Merge pull request #250 from oskarrough/experimental-api

Experimental API

Author: oskarrough

DOCUMENTATION.md

@@ -4,12 +4,12 @@ Throughout the project I've attempted to document and leave comments. Go ahead a
 
 In the root of this project you'll find configuration files as well as three folders:
 
-- [src →](src/) The web root. 
+- [src](src/) The web root. 
   - [content](src/content) contains cards, dungeons, encounters and monsters etc.
   - [game](src/game) contains the core game logic
   - [ui](src/ui) is the example web interface to actually play the game
-- [public →](public/) Copied to the web root as-is
-- [tests →](tests/) Contains all tests for the game engine. Nothing for the UI. Run `npm test`.
+- [public](public/) Copied to the web root as-is, used for static images 
+- [tests](tests/) Contains tests for the game. There are no tests for the UI.
 
 ### Game
 

EXPERIMENT.md

@@ -0,0 +1,60 @@
+# Slay the web API design
+
+## Core architecture (current)
+
+- State-based: Actions are pure functions `(state, props) => newState`
+- Queue system: Actions enqueued and processed sequentially
+- Turn-based: Perfect for command pattern with clear state transitions
+
+```js
+// Core pattern
+game.enqueue({type: 'playCard', card})
+game.dequeue()
+
+// Queue enables
+// - Undo/redo
+// - Action history
+// - Save states
+// - Debugging
+```
+
+## API style options
+
+All styles would wrap the same core engine:
+
+1. Current (Raw Actions) - Explicit and debuggable but verbose
+   ```js
+   game.enqueue({type: 'playCard', card: strike})
+   game.dequeue()
+   ```
+
+2. Fluent/Chainable - Readable sequences
+   ```js
+   game.drawCards(5).playCard(strike, 'enemy0').endTurn()
+   ```
+
+3. Command Strings - Console-like for debugging
+   ```js
+   game.do('/play strike enemy0')
+   ```
+
+4. Domain-Specific - Organized by game concepts
+   ```js
+   game.combat.play(strike).on('enemy0')
+   game.deck.draw(5)
+   ```
+
+5. Builder Pattern - Step-by-step construction
+   ```js
+   game.command.play(strike).target('enemy0').run()
+   ```
+
+## Implementation considerations
+
+1. All wrappers map to core state transforms
+2. Actions remain composable
+3. Type safety for parameters
+
+## Conclusion
+
+The state-based core architecture is powerful, flexible, and should be preserved. Thin wrapper APIs can provide more ergonomic interfaces for common operations while maintaining the underlying strengths of the system.

README.md

@@ -24,7 +24,6 @@ TLDR;
 1. Clone the repository
 2. Run `npm install` followed by `npm run dev` to open a local development server.
 
-
 ## Documentation
 
 If you're interested in contributing to the game or merely curious how it works: