@pompidup/kingdomino-engine 3.3.0 → 3.5.0

package/README.md

@@ -7,585 +7,268 @@
 ![Statements](./badges/coverage-statements.svg)
 ![Coverage total](./badges/coverage-total.svg)
 
-A simple, lightweight TypeScript engine for the Kingdomino board game.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Requirements](#requirements)
-- [Features](#features)
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Basic Setup](#basic-setup)
-  - [Engine Options](#engine-options)
-  - [Adding Players](#adding-players)
-  - [Getting Available Game Modes](#getting-available-game-modes)
-  - [Getting Available Extra Rules](#getting-available-extra-rules)
-  - [Setting Up Extra Rules](#setting-up-extra-rules)
-  - [Starting the Game](#starting-the-game)
-  - [Player Actions](#player-actions)
-  - [Game Flow](#game-flow)
-  - [Scoring](#scoring)
-  - [Valid Placements](#valid-placements)
-  - [Serialization](#serialization)
-- [Complete Game Example](#complete-game-example)
-- [Extra Rules](#extra-rules)
-- [API Documentation](#api-documentation)
-  - [Key Types and Interfaces](#key-types-and-interfaces)
-  - [Methods](#methods)
-- [Development](#development)
-  - [Setup](#setup)
-  - [Testing](#testing)
-  - [Linting and Type Checking](#linting-and-type-checking)
-  - [Building](#building)
-- [Contributing](#contributing)
+A TypeScript engine for the Kingdomino board game and its expansions.
 
 ## Overview
 
-This is a simple and lightweight TypeScript engine designed to facilitate the gameplay of Kingdomino. It provides the core logic for managing game states, rules, and player interactions, making it easy to integrate into any application that requires a Kingdomino game engine.
-
-Kingdomino is a tile-placement game where players build kingdoms by connecting domino-like tiles with different terrains. This engine handles all the game logic, allowing you to focus on building the user interface and experience.
+This engine provides the core logic for Kingdomino: state management, rule enforcement, scoring, and turn flow. It is **not** a UI — consumers drive the game by calling engine methods and passing game state back in.
 
 The engine is **stateless**: each method takes the current game state as input and returns a new game state. It is your responsibility to persist the state between calls.
 
 ## Requirements
 
-- Node.js >= 18
-
-## Features
-
-- **Game State Management**: Efficiently manage game states, including player turns, game rules, and game progression.
-- **Rule Enforcement**: Automatically enforce game rules, ensuring a fair and consistent gameplay experience.
-- **Player Interaction**: Simplify player interactions, including drawing tiles, placing dominoes, and scoring.
-- **Extra Rules Support**: Implement and manage additional game rules for enhanced gameplay.
-- **Multiple Game Modes**: Support for different game modes, including Classic and potentially others.
-- **Scoring System**: Automatic calculation of scores based on kingdom layouts and rule sets.
-- **Valid Placement Detection**: Find all valid positions for a domino or check if any placement exists.
-- **Serialization**: Save and restore game state to/from JSON for persistence.
-- **TypeScript Support**: Full TypeScript support with comprehensive type definitions.
-- **Dependency Injection**: Custom shuffle, UUID, and logger implementations can be injected.
+- Node.js >= 20
 
 ## Installation
 
-To install the Kingdomino Engine, you can use npm, yarn or pnpm. Run one of the following commands in your terminal:
-
 ```bash
 npm install @pompidup/kingdomino-engine
-yarn add @pompidup/kingdomino-engine
-pnpm add @pompidup/kingdomino-engine
 ```
 
-## Usage
-
-The Kingdomino Engine is designed to be easy to use and integrate into any application. Below are examples of how you can use the engine to create a new game, add players, set rules, and manage gameplay.
-
-Each method returns an updated game state object, which contains the current state of the game, including the board, players, and dominoes. You will also receive the nextLord (the next player to play) and the nextAction (the next action to be performed by the next player).
-
-**It's your responsibility to save and pass the updated game state to the next method call.**
-
-### Basic Setup
-
-To start using the Kingdomino Engine, import it and initialize a new game instance:
-
-```typescript
-import { createGameEngine } from "@pompidup/kingdomino-engine";
-
-const engine = createGameEngine({});
-let gameState = engine.createGame({ mode: "Classic" });
-```
-
-### Engine Options
-
-You can pass options to the `createGameEngine` function to customize the engine's behavior:
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `logging` | `boolean` | `false` | Enable console logging for debugging |
-| `logger` | `Logger` | — | Custom logger instance (takes precedence over `logging`) |
-| `shuffleMethod` | `ShuffleMethod` | Fisher-Yates | Custom shuffle function for dominoes and lords |
-| `uuidMethod` | `UuidMethod` | `crypto.randomUUID()` | Custom UUID generator |
-
-```typescript
-import { createGameEngine, type EngineConfig } from "@pompidup/kingdomino-engine";
-
-// With logging enabled
-const engine = createGameEngine({ logging: true });
-
-// With custom logger
-const engine = createGameEngine({
-  logger: {
-    info: (msg) => console.log(msg),
-    error: (msg) => console.error(msg),
-  },
-});
-
-// With deterministic shuffle (useful for testing)
-const engine = createGameEngine({
-  shuffleMethod: (array) => array, // No shuffle
-});
-```
-
-### Adding Players
-
-Add players to the game by passing an array of player names (2-4 players, minimum 3 characters per name):
-
-```typescript
-gameState = engine.addPlayers({
-  game: gameState,
-  players: ["Alice", "Bob", "Carol"],
-});
-```
-
-### Getting Available Game Modes
-
-You can get available game modes and select one for the game:
-
-```typescript
-const modes = engine.getModes({});
-gameState = engine.createGame({ mode: modes[0].name });
-```
-
-### Getting Available Extra Rules
-
-You can get available extra rules for a specific game mode and number of players:
-
-```typescript
-const extraRules = engine.getExtraRules({ mode: "Classic", players: 2 });
-```
-
-### Setting Up Extra Rules
-
-You can add extra rules to the game to modify gameplay:
-
-```typescript
-gameState = engine.addExtraRules({
-  game: gameState,
-  extraRules: ["The middle Kingdom"],
-});
-```
-
-### Starting the Game
-
-After setting up players and rules, start the game. The engine will automatically set up the initial game state and determine the first player (lord) to play in `nextAction`.
-
-```typescript
-gameState = engine.startGame({ game: gameState });
-```
-
-### Player Actions
-
-Players can perform actions like picking a domino, placing a domino, and discarding a domino.
-
-**Pick a domino** from the currently revealed set:
-
-```typescript
-gameState = engine.chooseDomino({
-  game: gameState,
-  lordId: "lordId",
-  dominoPick: 12, // domino number
-});
-```
-
-**Place a domino** on the kingdom grid:
-
-```typescript
-gameState = engine.placeDomino({
-  game: gameState,
-  lordId: "lordId",
-  position: { x: 5, y: 4 },
-  rotation: 0, // 0, 90, 180, or 270
-});
-```
-
-**Discard a domino** when no valid placement exists:
-
-```typescript
-gameState = engine.discardDomino({
-  game: gameState,
-  lordId: "lordId",
-});
-```
-
-### Game Flow
-
-The game progresses through steps and actions. The `nextAction` property in the game state indicates what should happen next.
-
-**Steps** (setup and completion phases): `addPlayers` → `options` → `start` → `result`
-
-**Actions** (during gameplay): `pickDomino`, `placeDomino`, `pass`
-
-Use the provided type guards to determine the current state:
-
-```typescript
-import { isGameWithNextAction, isGameWithNextStep } from "@pompidup/kingdomino-engine";
-
-while (isGameWithNextAction(gameState)) {
-  const { nextLord, nextAction } = gameState.nextAction;
-  // Handle pickDomino, placeDomino, or pass
-}
-
-if (isGameWithNextStep(gameState)) {
-  // Game has ended, get results
-}
-```
-
-### Scoring
-
-When the last turn is played, the game transitions to the `result` step. Get final results with rankings:
-
-```typescript
-const gameWithResults = engine.getResults({ game: gameState });
-console.log(gameWithResults.result);
-// [{ playerId, playerName, details: { points, maxPropertiesSize, totalCrowns }, position }]
-```
-
-You can also calculate the score of any kingdom at any time:
-
-```typescript
-const score = engine.calculateScore({ kingdom: gameState.players[0].kingdom });
-// { points: 42, maxPropertiesSize: 5, totalCrowns: 8 }
-```
-
-### Valid Placements
-
-The engine provides helpers to determine where a domino can be placed:
-
-```typescript
-// Get all valid positions and rotations for a domino
-const placements = engine.getValidPlacements({
-  kingdom: player.kingdom,
-  domino: myDomino,
-});
-// [{ position: { x: 3, y: 4 }, rotation: 0 }, ...]
-
-// Quick check: can this domino be placed at all?
-const canPlace = engine.canPlaceDomino({
-  kingdom: player.kingdom,
-  domino: myDomino,
-});
-// true or false
-```
-
-### Serialization
-
-Save and restore game state for persistence:
-
-```typescript
-import {
-  serializeGame,
-  deserializeGame,
-  createSavePoint,
-  restoreFromSavePoint,
-} from "@pompidup/kingdomino-engine";
-
-// Serialize to JSON string
-const json = serializeGame(gameState);
-
-// Deserialize back (returns a Result type)
-const result = deserializeGame(json);
-
-// Or use save points with metadata
-const savePoint = createSavePoint(gameState);
-// { serialized, createdAt, gameId, turn }
-
-const restored = restoreFromSavePoint(savePoint);
-```
-
-The engine also provides `serialize` and `deserialize` methods on the engine instance:
-
-```typescript
-const json = engine.serialize({ game: gameState });
-const restored = engine.deserialize({ json });
-```
-
-## Complete Game Example
-
-Here's a complete example of how to simulate a game from start to finish:
+## Quick Start
 
 ```typescript
 import { createGameEngine, isGameWithNextAction } from "@pompidup/kingdomino-engine";
 
-// Create the game engine
 const engine = createGameEngine({});
 
-// Create a new game with Classic mode
+// Create and set up a game
 let game = engine.createGame({ mode: "Classic" });
-
-// Add players
 game = engine.addPlayers({ game, players: ["Alice", "Bob"] });
-
-// Optionally add extra rules
-game = engine.addExtraRules({ game, extraRules: ["The middle Kingdom", "Harmony"] });
-
-// Start the game
 game = engine.startGame({ game });
 
 // Game loop
 while (isGameWithNextAction(game)) {
-  const currentLordId = game.nextAction.nextLord;
-  const nextAction = game.nextAction.nextAction;
+  const { nextLord, nextAction } = game.nextAction;
 
   if (nextAction === "pickDomino") {
-    // Pick the first available domino
-    const availableDomino = game.currentDominoes.find((d) => !d.picked);
-    if (availableDomino) {
-      game = engine.chooseDomino({
-        game,
-        lordId: currentLordId,
-        dominoPick: availableDomino.domino.number,
-      });
+    const domino = game.currentDominoes.find((d) => !d.picked);
+    if (domino) {
+      game = engine.chooseDomino({ game, lordId: nextLord, dominoPick: domino.domino.number });
     }
   } else if (nextAction === "placeDomino") {
-    // Check if placement is possible
-    const lord = game.lords.find((l) => l.id === currentLordId);
+    const lord = game.lords.find((l) => l.id === nextLord);
     const player = game.players.find((p) => p.id === lord?.playerId);
-
     if (lord?.dominoPicked && player) {
-      const canPlace = engine.canPlaceDomino({
-        kingdom: player.kingdom,
-        domino: lord.dominoPicked,
-      });
-
-      if (canPlace) {
-        const placements = engine.getValidPlacements({
-          kingdom: player.kingdom,
-          domino: lord.dominoPicked,
-        });
-        game = engine.placeDomino({
-          game,
-          lordId: currentLordId,
-          position: placements[0].position,
-          rotation: placements[0].rotation,
-        });
+      const placements = engine.getValidPlacements({ kingdom: player.kingdom, domino: lord.dominoPicked });
+      if (placements.length > 0) {
+        game = engine.placeDomino({ game, lordId: nextLord, position: placements[0].position, rotation: placements[0].rotation });
       } else {
-        game = engine.discardDomino({ game, lordId: currentLordId });
+        game = engine.discardDomino({ game, lordId: nextLord });
       }
     }
   } else {
-    // pass action
-    game = engine.discardDomino({ game, lordId: currentLordId });
+    game = engine.discardDomino({ game, lordId: nextLord });
   }
 }
 
-// Get the final results
-const gameResult = engine.getResults({ game });
-console.log("Game results:", gameResult.result);
+const results = engine.getResults({ game });
+console.log(results.result);
 ```
 
-## Extra Rules
-
-The engine supports extra rules that can modify gameplay:
-
-- **The Middle Kingdom**: Gain 10 additional points if your castle is in the middle of the kingdom.
-- **Harmony**: Gain 5 additional points if your kingdom is complete (no discarded dominoes).
+## Game Modes
 
-You can get all available extra rules for a specific game mode and number of players:
+| Mode | Description |
+|------|-------------|
+| **Classic** | Original Kingdomino rules. 1-4 players, 5x5 kingdom, terrain-based scoring. |
+| **QueenDomino** | Full Queendomino expansion with buildings, coins, knights, the Queen and the Dragon. |
+| **KingdominoOrigins-Discovery** | Origins expansion — volcanoes, fire tokens, fire-based scoring. |
+| **KingdominoOrigins-Totem** | Origins — Discovery + wooden resources + totem majority tiles. |
+| **KingdominoOrigins-Tribe** | Origins — Discovery + resources + cave board + cavemen recruitment. |
+| **AgeOfGiants** | Age of Giants extension — giants, quest tiles, 5-player support, 12 new dominos on Classic. |
+| **AgeOfGiants-QueenDomino** | Age of Giants combined with QueenDomino. |
 
 ```typescript
-const extraRules = engine.getExtraRules({ mode: "Classic", players: 2 });
+let game = engine.createGame({ mode: "Classic" });
+let game = engine.createGame({ mode: "QueenDomino" });
+let game = engine.createGame({ mode: "KingdominoOrigins-Discovery" });
+let game = engine.createGame({ mode: "AgeOfGiants" });
 ```
 
-## API Documentation
-
-### Key Types and Interfaces
-
-#### GameEngine
+See [Game Modes](docs/game-modes.md) for rules, player counts, and extra rules details.
 
-The main interface for interacting with the Kingdomino engine.
+## Queendomino
 
-```typescript
-type GameEngine = {
-  getModes: (command: GetModesCommand) => GameMode[];
-  getExtraRules: (command: GetExtraRulesCommand) => ExtraRule[];
-  createGame: (command: CreateGameCommand) => GameWithNextStep;
-  addPlayers: (command: AddPlayersCommand) => GameWithNextStep;
-  addExtraRules: (command: AddExtraRulesCommand) => GameWithNextStep;
-  startGame: (command: StartGameCommand) => GameWithNextAction;
-  chooseDomino: (command: ChooseDominoCommand) => GameWithNextAction;
-  placeDomino: (command: PlaceDominoCommand) => GameState;
-  discardDomino: (command: DiscardDominoCommand) => GameState;
-  getResults: (command: GetResultCommand) => GameWithResults;
-  calculateScore: (command: CalculateScoreCommand) => Score;
-  getValidPlacements: (command: GetValidPlacementsCommand) => ValidPlacement[];
-  canPlaceDomino: (command: CanPlaceDominoCommand) => boolean;
-  serialize: (command: SerializeGameCommand) => string;
-  deserialize: (command: DeserializeGameCommand) => GameState;
-};
-```
+The QueenDomino mode adds significant new mechanics to the base game:
 
-#### Game
+- **Construction squares** on some domino tiles where buildings can be placed
+- **Coins** (7 starting) used to purchase buildings or use the Dragon
+- **Knights** (max 3) placed on dominos to collect tax from construction squares
+- **Buildings** (18 types) purchased from the Builders Board, granting crowns, towers, and end-game bonuses
+- **The Queen** goes to the player with the most towers, granting +1 crown to the best territory
+- **The Dragon** burns a building tile from the Builders Board
 
-Represents the current state of a Kingdomino game.
+The turn flow is extended with optional actions after placing a domino:
 
-```typescript
-type Game = {
-  id: string;
-  dominoes: Domino[];
-  currentDominoes: RevealsDomino[];
-  players: Player[];
-  lords: Lord[];
-  turn: number;
-  nextAction: NextAction | NextStep;
-  rules: SelectedRules;
-  mode: GameMode;
-};
 ```
-
-#### NextStep and NextAction
-
-Represent the next step or action in the game flow.
+placeDomino → placeKnight → constructBuilding → useDragon → pickDomino
+               (optional)      (optional)         (optional)
+```
 
 ```typescript
-type NextStep = {
-  type: "step";
-  step: "addPlayers" | "options" | "start" | "result";
-};
-
-type NextAction = {
-  type: "action";
-  nextLord: string;
-  nextAction: "pickDomino" | "placeDomino" | "pass";
-};
+// Handle QueenDomino optional actions in your game loop
+if (nextAction === "placeKnight" || nextAction === "constructBuilding" || nextAction === "useDragon") {
+  game = engine.skipOptionalAction({ game, lordId: nextLord });
+}
 ```
 
-#### Score
-
-Represents the score calculation for a kingdom.
+See [Queendomino Guide](docs/queendomino.md) for the complete rules, building list, and game loop example.
 
-```typescript
-type Score = {
-  points: number;
-  maxPropertiesSize: number;
-  totalCrowns: number;
-};
-```
+## Kingdomino Origins
 
-#### ExtraRule
+Origins introduces prehistoric terrains and fire-based scoring across three modes:
 
-Represents an additional rule that can be applied to the game.
+- **Discovery**: Volcanoes provide fire tokens. Scoring = region size × fire symbols.
+- **Totem**: Discovery + wooden resources + totem majority tiles for bonus points.
+- **Tribe**: Discovery + resources + cave board with 22 cavemen to recruit.
 
 ```typescript
-type ExtraRule = {
-  name: string;
-  description: string;
-  mode: GameMode[];
-  playersLimit?: number;
-};
+if (nextAction === "placeFireToken") {
+  game = engine.placeFireToken({ game, lordId: nextLord, position });
+}
+if (nextAction === "recruitCaveman") {
+  game = engine.recruitCaveman({ game, lordId: nextLord, cavemanId, position, resourcePositions });
+}
 ```
 
-#### ValidPlacement
-
-Represents a valid position and rotation for placing a domino.
+See [Origins Guide](docs/origins.md) for the complete rules and mechanics.
 
-```typescript
-type ValidPlacement = {
-  position: Position;
-  rotation: Rotation; // 0 | 90 | 180 | 270
-};
-```
+## Age of Giants
 
-#### Domain Errors
+Age of Giants extends Classic (or QueenDomino) with giants, quest tiles, and 5-player support:
 
-The engine throws typed `DomainException` errors with error codes for programmatic handling:
+- **60 dominos** (48 original + 12 new with giant/footprint symbols)
+- **Giants** cover crowns on your kingdom, reducing opponents' scores
+- **Quest tiles** (2 per game) provide end-game bonus scoring conditions
+- **5-player support** with 5 dominos revealed per turn
 
 ```typescript
-import { DomainException, ErrorCode } from "@pompidup/kingdomino-engine";
-
-try {
-  game = engine.placeDomino({ game, lordId, position, rotation });
-} catch (error) {
-  if (error instanceof DomainException) {
-    console.log(error.code);    // e.g. "INVALID_PLACEMENT"
-    console.log(error.message);  // Human-readable message
-    console.log(error.context);  // Optional debug context
-  }
+if (nextAction === "placeGiant") {
+  game = engine.placeGiant({ game, lordId: nextLord, position });
+}
+if (nextAction === "sendGiant") {
+  game = engine.sendGiant({ game, lordId: nextLord, giantIndex, targetPlayerId, targetCrownPosition });
 }
 ```
 
-### Methods
-
-| Method | Input | Output | Description |
-|--------|-------|--------|-------------|
-| `getModes` | `{}` | `GameMode[]` | Get available game modes |
-| `getExtraRules` | `{ mode, players }` | `ExtraRule[]` | Get extra rules for a mode/player count |
-| `createGame` | `{ mode }` | `GameWithNextStep` | Create a new game |
-| `addPlayers` | `{ game, players }` | `GameWithNextStep` | Add 2-4 players |
-| `addExtraRules` | `{ game, extraRules }` | `GameWithNextStep` | Add optional extra rules |
-| `startGame` | `{ game }` | `GameWithNextAction` | Start the game |
-| `chooseDomino` | `{ game, lordId, dominoPick }` | `GameWithNextAction` | Pick a domino |
-| `placeDomino` | `{ game, lordId, position, rotation }` | `GameState` | Place a domino on kingdom |
-| `discardDomino` | `{ game, lordId }` | `GameState` | Discard when no placement exists |
-| `getResults` | `{ game }` | `GameWithResults` | Get final rankings and scores |
-| `calculateScore` | `{ kingdom }` | `Score` | Calculate score for a kingdom |
-| `getValidPlacements` | `{ kingdom, domino }` | `ValidPlacement[]` | Find all valid placements |
-| `canPlaceDomino` | `{ kingdom, domino }` | `boolean` | Check if any placement exists |
-| `serialize` | `{ game }` | `string` | Serialize game state to JSON |
-| `deserialize` | `{ json }` | `GameState` | Restore game state from JSON |
-
-## Development
-
-### Setup
-
-To set up the project for development:
-
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/Pompidup/KDomino.git
-   cd KDomino
-   ```
-
-2. Install dependencies:
-   ```bash
-   pnpm install
-   ```
-
-### Testing
-
-The project uses Vitest for testing:
+See [Age of Giants Guide](docs/age-of-giants.md) for the complete rules and mechanics.
 
-```bash
-# Run tests in watch mode
-pnpm test
+## Extra Rules
 
-# Run tests once
-pnpm test -- --run
+| Rule | Description | Restriction |
+|------|-------------|-------------|
+| **The Middle Kingdom** | +10 points if castle is centered | — |
+| **Harmony** | +5 points if no dominos were discarded | — |
+| **The Mighty Duel** | All 48 dominos, 7x7 kingdom | 2 players only |
+| **Dynasty** | Play 3 games, highest total wins | — |
 
-# Run tests with coverage
-pnpm coverage
+```typescript
+game = engine.addExtraRules({ game, extraRules: ["The middle Kingdom", "Harmony"] });
 
-# Run a specific test file
-pnpm test -- src/tests/unit/useCases/calculateScore.test.ts --run
+// Dynasty: aggregate results from multiple games
+const dynastyResults = engine.getDynastyResults({ games: [game1, game2, game3] });
 ```
 
-### Linting and Type Checking
+See [Game Modes](docs/game-modes.md#extra-rules) for details.
 
-```bash
-# Lint with Biome
-pnpm lint
+## Engine Options
 
-# Type check with TypeScript
-pnpm typecheck
+```typescript
+const engine = createGameEngine({
+  logging: true,                          // Console logging
+  logger: { info: console.log, error: console.error },  // Custom logger
+  shuffleMethod: (arr) => arr,            // Custom shuffle (e.g. no-op for testing)
+  uuidMethod: () => "custom-uuid",        // Custom UUID generator
+  events: { onGameEnd: () => {} },        // Event callbacks
+  debug: true,                            // Debug mode
+});
 ```
 
-### Building
+## API Overview
+
+### Core Methods
+
+| Method | Description |
+|--------|-------------|
+| `getModes` | Get available game modes |
+| `createGame` | Create a new game |
+| `addPlayers` | Add 1-4 players |
+| `addExtraRules` | Add optional extra rules |
+| `startGame` | Start the game |
+| `chooseDomino` | Pick a domino from the revealed set |
+| `placeDomino` | Place a domino on the kingdom |
+| `discardDomino` | Discard when no valid placement exists |
+| `getResults` | Get final rankings and scores |
+| `calculateScore` | Calculate score for any kingdom |
+| `getValidPlacements` | Find all valid placements for a domino |
+| `canPlaceDomino` | Check if any placement exists |
+| `serialize` / `deserialize` | Save and restore game state |
+| `getDynastyResults` | Aggregate scores from multiple games |
+
+### Queendomino Methods
+
+| Method | Description |
+|--------|-------------|
+| `placeKnight` | Place a knight and collect tax |
+| `constructBuilding` | Buy and place a building |
+| `useDragon` | Destroy a building tile from the board |
+| `skipOptionalAction` | Skip the current optional action |
+
+### Origins Methods
+
+| Method | Description |
+|--------|-------------|
+| `placeFireToken` | Place a fire token after placing a volcano domino |
+| `recruitCaveman` | Recruit a caveman from the cave board (Tribe mode) |
+
+### Age of Giants Methods
+
+| Method | Description |
+|--------|-------------|
+| `placeGiant` | Place a giant on a crown in your kingdom |
+| `sendGiant` | Send a giant to an opponent's kingdom |
+
+See [API Reference](docs/api-reference.md) for complete method signatures, types, and error codes.
+
+## Additional Features
+
+- **Bot / AI**: 4 built-in strategies (`randomStrategy`, `greedyStrategy`, `advancedStrategy`, `expertStrategy`) with `playBotTurn()` helper
+- **Mixed games**: Human and bot players in the same game via `bot: { strategyName }` on player input
+- **Undo / Redo**: Snapshot-based history with `createGameHistory()`, `pushState()`, `undo()`, `redo()`
+- **Action Log**: Immutable log via `wrapWithActionLog(engine)` for replay with `replayActions()`
+- **Events**: Callbacks via `EngineConfig.events` (`onDominoPlaced`, `onGameEnd`, etc.)
+- **Debug Mode**: `wrapWithDebug(engine)` with 3 verbosity levels
+- **Seeded games**: Deterministic shuffle via `createGame({ mode, seed: "my-seed" })`
+- **Serialization**: `serializeGame()` / `deserializeGame()` and save points
+- **WASM Build**: `pnpm build:wasm` produces a WebAssembly module usable from any language
+
+## Documentation
+
+| Document | Content |
+|----------|---------|
+| [Game Modes](docs/game-modes.md) | Modes, rules by player count, extra rules, game flow |
+| [Queendomino Guide](docs/queendomino.md) | Complete Queendomino rules, mechanics, and examples |
+| [Origins Guide](docs/origins.md) | Kingdomino Origins rules, fire tokens, resources, cavemen |
+| [Age of Giants Guide](docs/age-of-giants.md) | Age of Giants rules, giants, quest tiles, 5-player support |
+| [API Reference](docs/api-reference.md) | All methods, types, error codes, and utilities |
+| [WASM Build](wasm/README.md) | Cross-language usage via WebAssembly |
 
-To build the project (ESM output to `dist/`):
+## Development
 
 ```bash
-pnpm build
+pnpm install          # Install dependencies
+pnpm test             # Run tests (watch mode)
+pnpm test -- --run    # Run tests once
+pnpm coverage         # Tests with coverage
+pnpm typecheck        # Type check (tsc)
+pnpm lint             # Lint (biome)
+pnpm build            # Build (ESM to dist/)
+pnpm build:wasm       # Build WASM module (requires javy)
 ```
 
 ## Contributing
 
-Contributions are welcome! Here's how you can contribute:
-
 1. Fork the repository
-2. Create a new branch (`git checkout -b feature/your-feature-name`)
-3. Make your changes
-4. Run tests to ensure everything works (`pnpm test -- --run`)
-5. Run type checking (`pnpm typecheck`)
-6. Commit your changes (`git commit -m 'Add some feature'`)
-7. Push to the branch (`git push origin feature/your-feature-name`)
-8. Open a Pull Request
-
-Please make sure your code follows the existing style and includes appropriate tests.
+2. Create a branch (`git checkout -b feature/your-feature`)
+3. Make changes with tests (`pnpm test -- --run && pnpm typecheck`)
+4. Open a Pull Request