expanded basic game features

docs/server.md

@@ -0,0 +1,88 @@
+# Server (`server.py`)
+
+## What it is
+
+`server.py` is a FastAPI development server that:
+
+- Maintains an in-memory lobby (`lobby`)
+- Starts games when all lobby players are ready
+- Stores active games in-memory (`games`)
+- Exposes REST endpoints for lobby operations and game actions
+- Serves a simple HTML test client at `/`
+
+This server is intended for development/testing, not production.
+
+## In-memory state
+
+The server keeps three top-level collections:
+
+- `lobby`: list of `LobbyMember` (players waiting to start a game)
+- `games`: dict of `game_id -> Game`
+- `gamers`: list of `GameMember` (player_id/name/game_id records for in-game players)
+
+There is no persistence; restarting the server resets everything.
+
+## Lobby flow
+
+High-level flow:
+
+- `POST /api/lobby/join`: creates a `LobbyMember` with a `shortuuid` `player_id`
+- `POST /api/lobby/ready`: marks the player ready; when all lobby players are ready (and there are at least 2), it starts a game:
+  - generates a new `game_id` (uuid4)
+  - moves ready lobby members into `gamers` for that `game_id`
+  - calls `load_game_data(game_id, "base1", game_gamers)` and constructs `Game(game_state)`
+- `GET /api/lobby/status`: returns lobby members + whether the requesting player is already in a game
+
+Lobby cleanup:
+
+- `GET /api/lobby/status` prunes lobby members inactive for > 60 seconds
+
+## Game API
+
+- `GET /api/game/{game_id}/state`: returns the current game state encoded using `GameObjectEncoder` (from `game.py`)
+- `POST /api/game/{game_id}/action`: performs a game action and returns the updated game state
+
+Supported `action_type` values currently include:
+
+- `hire_citizen`
+- `buy_domain`
+- `slay_monster`
+- `take_resource`
+- `harvest_card`
+- `act_on_required_action` (sequential, single-player follow-ups)
+- `submit_concurrent_action` (non-ordered, multi-player prompts; see below)
+- `roll_phase`
+- `harvest_phase`
+- `play_turn`
+
+### `submit_concurrent_action`
+
+Used to respond to a `concurrent_action` gate (see `docs/game.md`). The
+serialized game state exposes a `concurrent_action` object with `kind`,
+`pending`, and `completed` lists; while `pending` is non-empty no other
+turn-based action will succeed. Request body:
+
+```
+{
+  "player_id": "<pid>",
+  "action_type": "submit_concurrent_action",
+  "kind": "choose_duke",          // optional sanity check
+  "response": "<opaque string>"   // handler-specific payload
+}
+```
+
+The server validates that the player is in `pending` and that `kind`
+(if provided) matches the active gate. Players may submit in any order;
+when the last pending player submits, the engine auto-advances out of
+the setup gate.
+
+## Game cleanup
+
+On startup, a background task deletes games inactive for > 180 seconds and prunes the corresponding `gamers` entries.
+
+## Dev HTML client
+
+The root route `/` serves a simple HTML page that calls the lobby endpoints and can fetch a game state.
+
+For run instructions, see `docs/README_SERVER.md`.
+