@pompidup/kingdomino-engine 3.5.1 → 3.7.0

package/README.md

@@ -42,15 +42,19 @@ while (isGameWithNextAction(game)) {
   const { nextLord, nextAction } = game.nextAction;
 
   if (nextAction === "pickDomino") {
-    const domino = game.currentDominoes.find((d) => !d.picked);
-    if (domino) {
-      game = engine.chooseDomino({ game, lordId: nextLord, dominoPick: domino.domino.number });
-    }
+    const [dominoPick] = engine.getValidDominoPicks({ game });
+    game = engine.chooseDomino({ game, lordId: nextLord, dominoPick });
   } else if (nextAction === "placeDomino") {
     const lord = game.lords.find((l) => l.id === nextLord);
     const player = game.players.find((p) => p.id === lord?.playerId);
     if (lord?.dominoPicked && player) {
-      const placements = engine.getValidPlacements({ kingdom: player.kingdom, domino: lord.dominoPicked });
+      // maxKingdomSize: 5, or 7 for a 7x7 kingdom (The Mighty Duel, Neolithic,
+      // QueenDomino and AgeOfGiants-QueenDomino at 2 players)
+      const placements = engine.getValidPlacements({
+        kingdom: player.kingdom,
+        domino: lord.dominoPicked,
+        maxKingdomSize: game.rules.basic.maxKingdomSize,
+      });
       if (placements.length > 0) {
         game = engine.placeDomino({ game, lordId: nextLord, position: placements[0].position, rotation: placements[0].rotation });
       } else {
@@ -71,12 +75,12 @@ console.log(results.result);
 | 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. |
+| **QueenDomino** | Full Queendomino expansion with buildings, coins, knights, the Queen and the Dragon. 2-4 players (7x7 kingdom with the 48 dominoes at 2 players). |
 | **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. |
+| **AgeOfGiants-QueenDomino** | Age of Giants combined with QueenDomino (7x7 kingdom with the 60 dominoes at 2 players). |
 
 ```typescript
 let game = engine.createGame({ mode: "Classic" });
@@ -92,11 +96,12 @@ See [Game Modes](docs/game-modes.md) for rules, player counts, and extra rules d
 The QueenDomino mode adds significant new mechanics to the base 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
+- **Coins** (7 starting) used to purchase buildings or bribe the Dragon; 1 point per 3 unused coins at the end of the game
+- **Knights** (1 at the start, more from building bonuses) placed on the domino just placed, up to 2 per turn, collecting 1 coin per square of the territory
+- **Buildings** purchased from the 6-spot Builders Board (spots costing 5 to 0 coins), granting crowns, towers, and end-game bonuses
+- **The Queen** hosted by the player who reaches the most towers (even on a tie): -1 coin on her host's constructions, +1 crown on their largest territory at the end
+- **The Dragon** burns a building tile from the Builders Board for 1 coin
+- **2 players**: 7x7 kingdoms with all 48 dominoes (official rule)
 
 The turn flow is extended with optional actions after placing a domino:
 
@@ -147,10 +152,13 @@ if (nextAction === "placeGiant") {
   game = engine.placeGiant({ game, lordId: nextLord, position });
 }
 if (nextAction === "sendGiant") {
-  game = engine.sendGiant({ game, lordId: nextLord, giantIndex, targetPlayerId, targetCrownPosition });
+  // The targeted opponent chooses the crown the giant covers
+  game = engine.sendGiant({ game, lordId: nextLord, giantIndex, targetPlayerId });
 }
 ```
 
+After `sendGiant`, a single free crown of the opponent is covered automatically. With several free crowns, `game.ageOfGiants.pendingGiant` is set and the game waits for a `placeGiant` played by a lord of the **targeted** player (`getValidGiantPositions` lists its crowns). `targetCrownPosition` is still accepted for backward compatibility.
+
 See [Age of Giants Guide](docs/age-of-giants.md) for the complete rules and mechanics.
 
 ## Extra Rules
@@ -159,13 +167,16 @@ See [Age of Giants Guide](docs/age-of-giants.md) for the complete rules and mech
 |------|-------------|-------------|
 | **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 |
+| **The Mighty Duel** | All 48 dominos, 7x7 kingdom | 2 players only (QueenDomino already plays 7x7 at 2 players: accepted, without further effect) |
 | **Dynasty** | Play 3 games, highest total wins | — |
 
+Origins has its own equivalents: **Empire of Fire**, **Homo Habilis**, **Neolithic** (2 players, 7x7, and the first pick of each line takes the dominoes 1 & 4 or 2 & 3 — see [Origins Guide](docs/origins.md#neolithic-2-players)) and **Dynasty**.
+
 ```typescript
 game = engine.addExtraRules({ game, extraRules: ["The middle Kingdom", "Harmony"] });
 
-// Dynasty: aggregate results from multiple games
+// Dynasty: aggregate results from multiple games (grouped by player id: pass
+// the same stable ids to addPlayers in every game, e.g. { id: "alice", name: "Alice" })
 const dynastyResults = engine.getDynastyResults({ games: [game1, game2, game3] });
 ```
 
@@ -202,6 +213,8 @@ const engine = createGameEngine({
 | `calculateScore` | Calculate score for any kingdom |
 | `getValidPlacements` | Find all valid placements for a domino |
 | `canPlaceDomino` | Check if any placement exists |
+| `getValidDominoPicks` | Dominoes the lord to play may pick (Neolithic reservations included) |
+| `calculatePlayerScore` | Mode-aware live (or final) score of one player, with its breakdown |
 | `serialize` / `deserialize` | Save and restore game state |
 | `getDynastyResults` | Aggregate scores from multiple games |
 
@@ -211,7 +224,7 @@ const engine = createGameEngine({
 |--------|-------------|
 | `placeKnight` | Place a knight and collect tax |
 | `constructBuilding` | Buy and place a building |
-| `useDragon` | Destroy a building tile from the board |
+| `useDragon` | Destroy a building tile from the board (1 coin) |
 | `skipOptionalAction` | Skip the current optional action |
 
 ### Origins Methods
@@ -228,14 +241,18 @@ const engine = createGameEngine({
 | `placeGiant` | Place a giant on a crown in your kingdom |
 | `sendGiant` | Send a giant to an opponent's kingdom |
 
+### Valid targets
+
+`getValidFireTokenPositions`, `getValidKnightPositions`, `getValidBuildingPositions`, `getAffordableBuildings`, `getValidDragonTargets`, `getValidCavemanPlacements`, `getValidGiantPositions`, `getValidGiantTargets` and `canSkipOptionalAction` list what the extension actions accept, with the same checks as the actions (see [Valid targets](docs/api-reference.md#valid-targets-for-extension-actions)).
+
 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
+- **Bot / AI**: 4 built-in strategies (`randomStrategy`, `greedyStrategy`, `advancedStrategy`, `expertStrategy`) with `playBotTurn()` helper; mode-aware (they evaluate with the mode-aware score and play the Queendomino, Origins and Age of Giants actions — see [Bot Strategies](docs/api-reference.md#bot-strategies))
 - **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()`
+- **Action Log**: Immutable log via `wrapWithActionLog(engine)` for replay with `replayActions()`; format v2 records the seed and the game, player and lord ids, so a replay gives a strictly identical state (v1 logs remain replayable)
 - **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" })`