Kingdomino Engine

A TypeScript engine for the Kingdomino board game and its expansions.

Overview

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 >= 20

Installation

npm install @pompidup/kingdomino-engine

Quick Start

import { createGameEngine, isGameWithNextAction } from "@pompidup/kingdomino-engine";

const engine = createGameEngine({});

// Create and set up a game
let game = engine.createGame({ mode: "Classic" });
game = engine.addPlayers({ game, players: ["Alice", "Bob"] });
game = engine.startGame({ game });

// Game loop
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 });
    }
  } 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 });
      if (placements.length > 0) {
        game = engine.placeDomino({ game, lordId: nextLord, position: placements[0].position, rotation: placements[0].rotation });
      } else {
        game = engine.discardDomino({ game, lordId: nextLord });
      }
    }
  } else {
    game = engine.discardDomino({ game, lordId: nextLord });
  }
}

const results = engine.getResults({ game });
console.log(results.result);

Game Modes

| 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. |

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" });

See Game Modes for rules, player counts, and extra rules details.

Queendomino

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

The turn flow is extended with optional actions after placing a domino:

placeDomino → placeKnight → constructBuilding → useDragon → pickDomino
               (optional)      (optional)         (optional)

// Handle QueenDomino optional actions in your game loop
if (nextAction === "placeKnight" || nextAction === "constructBuilding" || nextAction === "useDragon") {
  game = engine.skipOptionalAction({ game, lordId: nextLord });
}

See Queendomino Guide for the complete rules, building list, and game loop example.

Kingdomino Origins

Origins introduces prehistoric terrains and fire-based scoring across three modes:

• 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.

if (nextAction === "placeFireToken") {
  game = engine.placeFireToken({ game, lordId: nextLord, position });
}
if (nextAction === "recruitCaveman") {
  game = engine.recruitCaveman({ game, lordId: nextLord, cavemanId, position, resourcePositions });
}

See Origins Guide for the complete rules and mechanics.

Age of Giants

Age of Giants extends Classic (or QueenDomino) with giants, quest tiles, and 5-player support:

• 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

if (nextAction === "placeGiant") {
  game = engine.placeGiant({ game, lordId: nextLord, position });
}
if (nextAction === "sendGiant") {
  game = engine.sendGiant({ game, lordId: nextLord, giantIndex, targetPlayerId, targetCrownPosition });
}

See Age of Giants Guide for the complete rules and mechanics.

Extra Rules

| 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 | — |

game = engine.addExtraRules({ game, extraRules: ["The middle Kingdom", "Harmony"] });

// Dynasty: aggregate results from multiple games
const dynastyResults = engine.getDynastyResults({ games: [game1, game2, game3] });

See Game Modes for details.

Engine Options

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
});

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 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 | Modes, rules by player count, extra rules, game flow | | Queendomino Guide | Complete Queendomino rules, mechanics, and examples | | Origins Guide | Kingdomino Origins rules, fire tokens, resources, cavemen | | Age of Giants Guide | Age of Giants rules, giants, quest tiles, 5-player support | | API Reference | All methods, types, error codes, and utilities | | WASM Build | Cross-language usage via WebAssembly |

Development

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

1. Fork the repository
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