@pompidup/kingdomino-engine 3.3.0 → 3.5.0

package/dist/index.d.ts

@@ -1,8 +1,18 @@
+type Result<T> = Ok<T> | Err;
+interface Ok<T> {
+    readonly tag: "Ok";
+    readonly value: T;
+}
+interface Err {
+    readonly tag: "Err";
+    readonly error: string;
+}
+
 /**
  * All possible ground/terrain types in Kingdomino.
  * Each type can form contiguous properties for scoring.
  */
-declare const GROUND: readonly ["castle", "wheat", "forest", "sea", "plain", "swamp", "mine"];
+declare const GROUND: readonly ["castle", "wheat", "forest", "sea", "plain", "swamp", "mine", "grassland", "lake", "jungle", "quarry", "desert", "volcano"];
 /** Union type of all terrain types */
 type Ground = (typeof GROUND)[number];
 /** Special ground type for empty/unplaced tiles */
@@ -16,8 +26,16 @@ type Crown = number;
 type Tile = {
     /** The terrain type of this tile */
     type: Ground;
-    /** Number of crowns (0-3), multiplier for scoring */
+    /** Number of crowns (0-3), multiplier for scoring. In Origins, represents fire symbols. */
     crowns: Crown;
+    /** Whether this tile has a construction square for buildings (Queendomino) */
+    hasConstructionSquare?: boolean;
+    /** Number of volcanic craters on this tile (Origins, 1-3). Determines fire token type. */
+    volcanoCraters?: number;
+    /** Whether this tile has a giant icon (Age of Giants, letter dominos A-F) */
+    hasGiant?: boolean;
+    /** Whether this tile has footprint icons (Age of Giants, dominos 49-54) */
+    hasFootprint?: boolean;
 };
 /**
  * Represents an empty/unplaced tile on the kingdom grid.
@@ -37,8 +55,10 @@ type Domino = {
     left: Tile;
     /** The right tile of the domino */
     right: Tile;
-    /** Unique number identifying this domino (1-48 in Classic mode) */
+    /** Unique number identifying this domino (1-48 in Classic mode). Letter dominos use fractional numbers (A=0.01...F=0.06). */
     number: number;
+    /** Display letter for Age of Giants giant dominos (A-F). Undefined for numbered dominos. */
+    letter?: string;
 };
 /**
  * Represents a domino that has been revealed for player selection.
@@ -89,6 +109,65 @@ declare const GRIDSIZE = 9;
  */
 declare const MAX_KINGDOM_SIZE = 5;
 
+type ObjectValues<T> = T[keyof T];
+
+/**
+ * A giant placed on a player's kingdom, covering a crown.
+ * The covered crown does not count for scoring.
+ */
+type PlacedGiant = {
+    /** Position on the kingdom grid where the giant covers a crown */
+    position: Position;
+};
+/**
+ * All quest tile types available in Age of Giants.
+ */
+declare const questTypes: {
+    /** 5pts per matching terrain tile adjacent (8-dir) to castle */
+    readonly localTrade: "localTrade";
+    /** 5pts per matching terrain tile in the 4 corners of the kingdom */
+    readonly kingdomBorders: "kingdomBorders";
+    /** 5pts if kingdom is complete (no discarded dominos) */
+    readonly harmony: "harmony";
+    /** 10pts if castle is in the center of the kingdom */
+    readonly middleKingdom: "middleKingdom";
+    /** 20pts if castle is in one of the 4 corners of the kingdom */
+    readonly lostCorner: "lostCorner";
+    /** 10pts per alignment of 3+ tiles with crowns (H/V/diagonal) */
+    readonly megalomania: "megalomania";
+    /** 10pts per property of 5+ wheat/forest/sea/plain tiles with 0 crowns */
+    readonly austereKing: "austereKing";
+};
+type QuestType = ObjectValues<typeof questTypes>;
+/**
+ * A quest tile drawn at game start.
+ * Provides a specific end-of-game bonus scoring condition.
+ */
+type QuestTile = {
+    /** Unique identifier for the quest tile */
+    id: number;
+    /** Type of quest determining the scoring rule */
+    type: QuestType;
+    /** Display name of the quest */
+    name: string;
+    /** Description of the scoring condition */
+    description: string;
+    /** Points awarded per match (e.g., 5 for localTrade, 10 for megalomania) */
+    points: number;
+    /** Target terrain type (only for localTrade and kingdomBorders quests) */
+    terrain?: Ground;
+};
+/**
+ * Complete Age of Giants-specific game state.
+ * Stored as an optional field on Game and only present in AoG modes.
+ */
+type AgeOfGiantsState = {
+    /** Number of giant figurines remaining in the pool (starts at 6) */
+    giantPool: number;
+    /** The 2 quest tiles drawn for this game */
+    questTiles: QuestTile[];
+};
+
 /**
  * Represents a lord (player token) used for turn order and domino selection.
  * In games with 2 players, each player has 2 lords.
@@ -120,8 +199,241 @@ type GameMode = {
     description: string;
 };
 
-type ObjectValues<T> = T[keyof T];
+/**
+ * The three gameplay modes within Kingdomino Origins.
+ * Discovery is the base, Totem adds resources/totems, Tribe adds cavemen.
+ */
+declare const originsSubModes: {
+    readonly discovery: "Discovery";
+    readonly totem: "Totem";
+    readonly tribe: "Tribe";
+};
+type OriginsSubMode = ObjectValues<typeof originsSubModes>;
+/**
+ * Represents the pool of available fire tokens.
+ * Discovery Mode starts with: 5×1-fire, 4×2-fire, 1×3-fire = 10 total.
+ */
+type FireTokenPool = {
+    ones: number;
+    twos: number;
+    threes: number;
+};
+/**
+ * A fire token that has been placed on a player's kingdom.
+ */
+type PlacedFireToken = {
+    /** Number of fires on this token (1, 2, or 3) */
+    fires: 1 | 2 | 3;
+    /** Position on the kingdom grid */
+    position: Position;
+};
+/**
+ * Tracks which volcano granted the current pending fire token,
+ * so the placement validation knows the launch position.
+ */
+type PendingFireToken = {
+    /** Number of fires on the token to place */
+    fires: 1 | 2 | 3;
+    /** Position of the volcano that granted this token */
+    volcanoPosition: Position;
+};
+/**
+ * Types of wooden resources in Origins.
+ * Each maps to a specific terrain type.
+ */
+declare const resourceTypes: {
+    readonly mammoth: "mammoth";
+    readonly fish: "fish";
+    readonly mushroom: "mushroom";
+    readonly flint: "flint";
+};
+type ResourceType = ObjectValues<typeof resourceTypes>;
+/**
+ * A wooden resource placed on a player's kingdom tile.
+ */
+type Resource = {
+    /** Type of resource */
+    type: ResourceType;
+    /** Position on the kingdom grid */
+    position: Position;
+};
+/**
+ * Tracks which player holds each totem tile.
+ * null means no player currently holds that totem.
+ */
+type TotemState = Record<ResourceType, string | null>;
+/**
+ * Point values for each totem tile at end of game.
+ */
+type TotemBonus = Record<ResourceType, number>;
+/**
+ * The 7 kinds of hunter-gatherers.
+ * Each has a specific scoring rule based on surrounding resources.
+ */
+declare const hunterGathererKinds: {
+    /** Scores per mammoth adjacent */
+    readonly mammothHunter: "mammothHunter";
+    /** Scores per fish adjacent */
+    readonly fisherman: "fisherman";
+    /** Scores per mushroom adjacent */
+    readonly mushroomPicker: "mushroomPicker";
+    /** Scores per flint adjacent */
+    readonly flintCollector: "flintCollector";
+    /** Scores per unique resource type adjacent */
+    readonly trapper: "trapper";
+    /** Scores per total resource adjacent (any type) */
+    readonly gatherer: "gatherer";
+    /** Scores per fire symbol adjacent (Fire Lady) */
+    readonly fireLady: "fireLady";
+};
+type HunterGathererKind = ObjectValues<typeof hunterGathererKinds>;
+/**
+ * Warrior size categories with their power values.
+ */
+declare const warriorTypes: {
+    readonly small: "small";
+    readonly amazon: "amazon";
+    readonly oafish: "oafish";
+};
+type WarriorType = ObjectValues<typeof warriorTypes>;
+/**
+ * Power values for each warrior type.
+ */
+declare const WARRIOR_POWER: Record<WarriorType, number>;
+/**
+ * A hunter-gatherer caveman tile.
+ */
+type HunterGathererTile = {
+    kind: "hunterGatherer";
+    id: number;
+    /** Specific hunter-gatherer type determining scoring rule */
+    hunterType: HunterGathererKind;
+    /** Points per matching adjacent resource/symbol */
+    pointsPerMatch: number;
+};
+/**
+ * A warrior caveman tile.
+ */
+type WarriorTile = {
+    kind: "warrior";
+    id: number;
+    /** Warrior size category */
+    warriorType: WarriorType;
+    /** Combat power (1, 2, or 3) */
+    power: number;
+};
+/** Discriminated union of all caveman tile types. */
+type CavemanTile = HunterGathererTile | WarriorTile;
+/**
+ * A caveman tile placed on a player's kingdom.
+ */
+type PlacedCaveman = {
+    caveman: CavemanTile;
+    position: Position;
+};
+/**
+ * The Cave board used in Tribe mode.
+ * Shows 4 visible caveman tiles and a face-down draw pile.
+ */
+type CaveBoard = {
+    /** Up to 4 visible caveman tiles available for recruitment */
+    visible: CavemanTile[];
+    /** Face-down draw pile */
+    drawPile: CavemanTile[];
+};
+/**
+ * Complete Origins-specific game state.
+ * Stored as an optional field on Game and only present in Origins modes.
+ */
+type OriginsState = {
+    /** Which Origins sub-mode is being played */
+    subMode: OriginsSubMode;
+    /** Available fire tokens pool */
+    fireTokenPool: FireTokenPool;
+    /** Pending fire token to place (set after placing a volcano domino) */
+    pendingFireToken?: PendingFireToken;
+    /** Totem holder state (Totem mode only) */
+    totems?: TotemState;
+    /** Cave board state (Tribe mode only) */
+    caveBoard?: CaveBoard;
+};
+
+/**
+ * Types of immediate bonuses a building can grant when constructed.
+ */
+type ImmediateBonusType = "coins" | "tower" | "knight";
+/**
+ * Immediate bonus granted when a building is constructed.
+ */
+type ImmediateBonus = {
+    type: ImmediateBonusType;
+    amount: number;
+};
+/**
+ * Types of end-game scoring conditions for buildings.
+ */
+type EndGameScoringType = "perTerrain" | "perBuilding" | "perTower" | "perCrown" | "flat";
+/**
+ * End-game scoring rule for a building.
+ */
+type EndGameScoring = {
+    type: EndGameScoringType;
+    /** Terrain type (only for perTerrain) */
+    terrain?: string;
+    /** Points per matching element */
+    points: number;
+};
+/**
+ * Represents a building tile that can be purchased and placed on a construction square.
+ */
+type BuildingTile = {
+    /** Unique identifier */
+    id: number;
+    /** Display name */
+    name: string;
+    /** Cost in coins to purchase */
+    cost: number;
+    /** Immediate bonus when constructed (optional) */
+    immediateBonus?: ImmediateBonus;
+    /** Permanent crowns added to the territory */
+    crowns: number;
+    /** Towers granted by this building */
+    towers: number;
+    /** End-game scoring condition (optional) */
+    endGameScoring?: EndGameScoring;
+};
+/**
+ * A slot on the Builders Board that may hold a building tile.
+ */
+type BuildingSlot = BuildingTile | null;
+/**
+ * The Builders Board holding available building tiles for purchase.
+ */
+type BuildersBoard = {
+    /** Visible building tiles available for purchase (4 slots) */
+    slots: BuildingSlot[];
+    /** Remaining building tiles in the draw pile */
+    drawPile: BuildingTile[];
+};
+/**
+ * A building that has been placed on a player's kingdom.
+ */
+type PlacedBuilding = {
+    /** The building tile that was placed */
+    building: BuildingTile;
+    /** Position on the kingdom grid */
+    position: Position;
+};
 
+/**
+ * Represents a knight placed on a player's kingdom (Queendomino).
+ */
+type Knight = {
+    /** ID of the player who owns this knight */
+    playerId: string;
+    /** Position on the kingdom grid where the knight is placed */
+    position: Position;
+};
 /**
  * Represents a player in the game.
  */
@@ -136,6 +448,22 @@ type Player = {
     bot?: {
         strategyName: string;
     };
+    /** Number of coins the player has (Queendomino) */
+    coins?: number;
+    /** Number of towers the player has (Queendomino) */
+    towers?: number;
+    /** Knights placed on the kingdom (Queendomino) */
+    knights?: Knight[];
+    /** Buildings placed on the kingdom (Queendomino) */
+    buildings?: PlacedBuilding[];
+    /** Fire tokens placed on the kingdom (Origins) */
+    fireTokens?: PlacedFireToken[];
+    /** Wooden resources on the kingdom (Origins Totem/Tribe) */
+    resources?: Resource[];
+    /** Cavemen placed on the kingdom (Origins Tribe) */
+    cavemen?: PlacedCaveman[];
+    /** Giants placed on the kingdom covering crowns (Age of Giants) */
+    giants?: PlacedGiant[];
 };
 /**
  * Payload for creating a new player.
@@ -158,10 +486,41 @@ declare const playerActions: {
     readonly pickDomino: "pickDomino";
     /** Pass/discard when no valid placement exists */
     readonly pass: "pass";
+    /** Place a knight on the just-placed domino (Queendomino, optional) */
+    readonly placeKnight: "placeKnight";
+    /** Construct a building on a construction square (Queendomino, optional) */
+    readonly constructBuilding: "constructBuilding";
+    /** Use the Dragon to burn a building tile (Queendomino, optional) */
+    readonly useDragon: "useDragon";
+    /** Skip the current optional action (Queendomino/Origins/AoG) */
+    readonly skipOptionalAction: "skipOptionalAction";
+    /** Place a giant on a crown after placing a giant domino (Age of Giants, mandatory) */
+    readonly placeGiant: "placeGiant";
+    /** Send a giant to an opponent after placing a footprint domino (Age of Giants, optional) */
+    readonly sendGiant: "sendGiant";
+    /** Place a fire token after placing a volcano domino (Origins, optional) */
+    readonly placeFireToken: "placeFireToken";
+    /** Recruit a caveman from the cave board (Origins Tribe, optional) */
+    readonly recruitCaveman: "recruitCaveman";
 };
 /** Union type of all player actions */
 type PlayerActions = ObjectValues<typeof playerActions>;
 
+/**
+ * Complete Queendomino-specific game state.
+ * This is stored as an optional field on Game and only present in QueenDomino mode.
+ */
+type QueenDominoState = {
+    /** The Builders Board with available building tiles */
+    buildersBoard: BuildersBoard;
+    /** ID of the player currently hosting the Queen, or null */
+    queenHolderId: string | null;
+    /** Whether the Dragon is available for use this round */
+    dragonAvailable: boolean;
+    /** Whether the Dragon has been used this round (resets each round) */
+    dragonUsedThisRound: boolean;
+};
+
 /**
  * Basic rules that vary based on player count.
  */
@@ -176,6 +535,8 @@ type BasicRules = {
     maxTurns: number;
     /** Maximum kingdom grid size (5 for standard, 7 for Mighty Duel) */
     maxKingdomSize: number;
+    /** Number of dominos discarded from each draw before selection (Age of Giants) */
+    dominoesDiscardedPerTurn?: number;
 };
 /**
  * Optional extra rules that modify gameplay and scoring.
@@ -196,6 +557,8 @@ type ExtraRule = {
 type Rules = {
     /** Basic rules indexed by player count (1-4) */
     basic: Record<number, BasicRules>;
+    /** Age of Giants basic rules indexed by player count (2-5) */
+    aogBasic?: Record<number, BasicRules>;
     /** Available extra rules */
     extraRules: ExtraRule[];
 };
@@ -209,16 +572,6 @@ type SelectedRules = {
     extra: ExtraRule[];
 };
 
-type Result<T> = Ok<T> | Err;
-interface Ok<T> {
-    readonly tag: "Ok";
-    readonly value: T;
-}
-interface Err {
-    readonly tag: "Err";
-    readonly error: string;
-}
-
 /**
  * Represents the complete state of a Kingdomino game.
  * This is the main aggregate containing all game data.
@@ -244,6 +597,12 @@ type Game = {
     mode: GameMode;
     /** Optional seed for deterministic shuffle (replays, sharing) */
     seed?: string;
+    /** Queendomino-specific state (only present in QueenDomino mode) */
+    queendomino?: QueenDominoState;
+    /** Origins-specific state (only present in KingdominoOrigins modes) */
+    origins?: OriginsState;
+    /** Age of Giants-specific state (only present in AgeOfGiants modes) */
+    ageOfGiants?: AgeOfGiantsState;
 };
 /**
  * Available game steps representing phases of game setup and completion.
@@ -340,6 +699,29 @@ type GameWithResults = Game & {
     result: FinalResult[];
 };
 
+type AddExtraRulesCommand = {
+    game: GameState;
+    extraRules: string[];
+};
+
+/**
+ * Input for a single player: either a name string (human) or an object with bot config.
+ */
+type PlayerInput = string | {
+    name: string;
+    bot?: {
+        strategyName: string;
+    };
+};
+type AddPlayersCommand = {
+    game: GameState;
+    players: PlayerInput[];
+};
+
+type CalculateScoreCommand = {
+    kingdom: Kingdom;
+};
+
 /**
  * Severity level for a validation issue.
  * - "error": The state is corrupted and cannot be used safely.
@@ -360,39 +742,16 @@ type ValidationIssue = {
     severity: ValidationSeverity;
 };
 
-type GetModesCommand = Record<string, never>;
-
-type GetExtraRulesCommand = {
-    mode: GameMode["name"];
-    players: number;
-};
-
-type CreateGameCommand = {
-    mode: string;
-    seed?: string;
-};
-
 /**
- * Input for a single player: either a name string (human) or an object with bot config.
+ * Command to check if a domino can be placed anywhere on a kingdom.
  */
-type PlayerInput = string | {
-    name: string;
-    bot?: {
-        strategyName: string;
-    };
-};
-type AddPlayersCommand = {
-    game: GameState;
-    players: PlayerInput[];
-};
-
-type AddExtraRulesCommand = {
-    game: GameState;
-    extraRules: string[];
-};
-
-type StartGameCommand = {
-    game: GameState;
+type CanPlaceDominoCommand = {
+    /** The kingdom grid to check */
+    kingdom: Kingdom;
+    /** The domino to check placement for */
+    domino: Domino;
+    /** Maximum kingdom size (default: 5, use 7 for Mighty Duel) */
+    maxKingdomSize?: number;
 };
 
 type ChooseDominoCommand = {
@@ -401,11 +760,16 @@ type ChooseDominoCommand = {
     lordId: string;
 };
 
-type PlaceDominoCommand = {
-    game: GameState;
+type ConstructBuildingCommand = {
+    game: GameWithNextAction;
     lordId: string;
+    buildingId: number;
     position: Position;
-    rotation: Rotation;
+};
+
+type CreateGameCommand = {
+    mode: string;
+    seed?: string;
 };
 
 type DiscardDominoCommand = {
@@ -413,12 +777,19 @@ type DiscardDominoCommand = {
     lordId: string;
 };
 
-type GetResultCommand = {
-    game: GameState;
+type GetDynastyResultCommand = {
+    games: GameWithResults[];
 };
 
-type CalculateScoreCommand = {
-    kingdom: Kingdom;
+type GetExtraRulesCommand = {
+    mode: GameMode["name"];
+    players: number;
+};
+
+type GetModesCommand = Record<string, never>;
+
+type GetResultCommand = {
+    game: GameState;
 };
 
 /**
@@ -433,16 +804,51 @@ type GetValidPlacementsCommand = {
     maxKingdomSize?: number;
 };
 
-/**
- * Command to check if a domino can be placed anywhere on a kingdom.
- */
-type CanPlaceDominoCommand = {
-    /** The kingdom grid to check */
-    kingdom: Kingdom;
-    /** The domino to check placement for */
-    domino: Domino;
-    /** Maximum kingdom size (default: 5, use 7 for Mighty Duel) */
-    maxKingdomSize?: number;
+type PlaceDominoCommand = {
+    game: GameState;
+    lordId: string;
+    position: Position;
+    rotation: Rotation;
+};
+
+type PlaceFireTokenCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    position: Position;
+};
+
+type PlaceGiantCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    position: Position;
+};
+
+type PlaceKnightCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    position: Position;
+};
+
+type RecruitCavemanCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    /** ID of the caveman tile to recruit */
+    cavemanId: number;
+    /** Position on the kingdom to place the caveman */
+    position: Position;
+    /** Positions of resources to spend as payment */
+    resourcePositions: Position[];
+};
+
+type SendGiantCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    /** Index of the giant to send from the current player's giants array */
+    giantIndex: number;
+    /** ID of the opponent player to receive the giant */
+    targetPlayerId: string;
+    /** Position on the opponent's kingdom where the giant will cover a crown */
+    targetCrownPosition: Position;
 };
 
 /**
@@ -460,16 +866,19 @@ type DeserializeGameCommand = {
     json: string;
 };
 
-type GetDynastyResultCommand = {
-    games: GameWithResults[];
+type SkipOptionalActionCommand = {
+    game: GameWithNextAction;
+    lordId: string;
 };
 
-/**
- * Represents a valid placement position with rotation.
- */
-type ValidPlacement = {
-    position: Position;
-    rotation: Rotation;
+type StartGameCommand = {
+    game: GameState;
+};
+
+type UseDragonCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    buildingId: number;
 };
 
 type DynastyResult = {
@@ -480,6 +889,14 @@ type DynastyResult = {
     position: number;
 };
 
+/**
+ * Represents a valid placement position with rotation.
+ */
+type ValidPlacement = {
+    position: Position;
+    rotation: Rotation;
+};
+
 /**
  * The main interface for interacting with the Kingdomino game engine.
  *
@@ -613,6 +1030,56 @@ type GameEngine = {
      * @returns Ranked dynasty results per player
      */
     getDynastyResults: (command: GetDynastyResultCommand) => DynastyResult[];
+    /**
+     * Places a giant on a crown in the lord's kingdom (Age of Giants).
+     * Mandatory after placing a giant domino (A-F). The giant covers the crown for scoring.
+     * @param command - Contains game state, lord ID, and crown position
+     * @returns Updated game state with next action
+     */
+    placeGiant: (command: PlaceGiantCommand) => GameState;
+    /**
+     * Sends a giant from the lord's kingdom to an opponent's kingdom (Age of Giants).
+     * Optional after placing a footprint domino (49-54). The opponent chooses which crown is covered.
+     * @param command - Contains game state, lord ID, giant index, target player ID, and target crown position
+     * @returns Updated game state with next action
+     */
+    sendGiant: (command: SendGiantCommand) => GameState;
+    /**
+     * Places a knight on the lord's kingdom at the specified position (Queendomino).
+     * @param command - Contains game state, lord ID, and position
+     * @returns Updated game state with next action
+     */
+    placeKnight: (command: PlaceKnightCommand) => GameState;
+    /**
+     * Constructs a building on the lord's kingdom (Queendomino).
+     * @param command - Contains game state, lord ID, building ID, and position
+     * @returns Updated game state with next action
+     */
+    constructBuilding: (command: ConstructBuildingCommand) => GameState;
+    /**
+     * Uses the dragon to destroy a building on the builders board (Queendomino).
+     * @param command - Contains game state, lord ID, and building ID
+     * @returns Updated game state with next action
+     */
+    useDragon: (command: UseDragonCommand) => GameState;
+    /**
+     * Places a fire token on the lord's kingdom after placing a volcano domino (Origins).
+     * @param command - Contains game state, lord ID, and target position
+     * @returns Updated game state with next action
+     */
+    placeFireToken: (command: PlaceFireTokenCommand) => GameState;
+    /**
+     * Recruits a caveman from the cave board and places it on the lord's kingdom (Origins).
+     * @param command - Contains game state, lord ID, caveman ID, position, and resource positions to spend
+     * @returns Updated game state with next action
+     */
+    recruitCaveman: (command: RecruitCavemanCommand) => GameState;
+    /**
+     * Skips the current optional action (Queendomino/Origins).
+     * @param command - Contains game state and lord ID
+     * @returns Updated game state with next action
+     */
+    skipOptionalAction: (command: SkipOptionalActionCommand) => GameState;
 };
 
 /**
@@ -641,6 +1108,27 @@ declare const ErrorCode: {
     readonly DOMINO_ALREADY_PICKED: "DOMINO_ALREADY_PICKED";
     readonly UNDO_UNAVAILABLE: "UNDO_UNAVAILABLE";
     readonly REDO_UNAVAILABLE: "REDO_UNAVAILABLE";
+    readonly CANNOT_PLACE_KNIGHT: "CANNOT_PLACE_KNIGHT";
+    readonly MAX_KNIGHTS_REACHED: "MAX_KNIGHTS_REACHED";
+    readonly KNIGHT_TERRITORY_OCCUPIED: "KNIGHT_TERRITORY_OCCUPIED";
+    readonly CANNOT_AFFORD_BUILDING: "CANNOT_AFFORD_BUILDING";
+    readonly NO_CONSTRUCTION_SQUARE: "NO_CONSTRUCTION_SQUARE";
+    readonly DRAGON_UNAVAILABLE: "DRAGON_UNAVAILABLE";
+    readonly QUEEN_HOLDER_CANNOT_USE_DRAGON: "QUEEN_HOLDER_CANNOT_USE_DRAGON";
+    readonly BUILDING_NOT_FOUND: "BUILDING_NOT_FOUND";
+    readonly INVALID_OPTIONAL_ACTION: "INVALID_OPTIONAL_ACTION";
+    readonly GIANT_POOL_EMPTY: "GIANT_POOL_EMPTY";
+    readonly GIANT_NOT_FOUND: "GIANT_NOT_FOUND";
+    readonly INVALID_GIANT_PLACEMENT: "INVALID_GIANT_PLACEMENT";
+    readonly NOT_AOG_MODE: "NOT_AOG_MODE";
+    readonly FIRE_TOKEN_POOL_EMPTY: "FIRE_TOKEN_POOL_EMPTY";
+    readonly FIRE_TOKEN_INVALID_POSITION: "FIRE_TOKEN_INVALID_POSITION";
+    readonly NO_PENDING_FIRE_TOKEN: "NO_PENDING_FIRE_TOKEN";
+    readonly CANNOT_RECRUIT_CAVEMAN: "CANNOT_RECRUIT_CAVEMAN";
+    readonly INSUFFICIENT_RESOURCES: "INSUFFICIENT_RESOURCES";
+    readonly INVALID_CAVEMAN_PLACEMENT: "INVALID_CAVEMAN_PLACEMENT";
+    readonly CAVEMAN_NOT_FOUND: "CAVEMAN_NOT_FOUND";
+    readonly NOT_TRIBE_MODE: "NOT_TRIBE_MODE";
 };
 type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
 /**
@@ -752,6 +1240,27 @@ declare const TranslationKey: {
     readonly ACTION_PICK_DOMINO: "action.pickDomino";
     readonly ACTION_PLACE_DOMINO: "action.placeDomino";
     readonly ACTION_PASS: "action.pass";
+    readonly ERROR_CANNOT_PLACE_KNIGHT: "error.cannotPlaceKnight";
+    readonly ERROR_MAX_KNIGHTS_REACHED: "error.maxKnightsReached";
+    readonly ERROR_KNIGHT_TERRITORY_OCCUPIED: "error.knightTerritoryOccupied";
+    readonly ERROR_CANNOT_AFFORD_BUILDING: "error.cannotAffordBuilding";
+    readonly ERROR_NO_CONSTRUCTION_SQUARE: "error.noConstructionSquare";
+    readonly ERROR_DRAGON_UNAVAILABLE: "error.dragonUnavailable";
+    readonly ERROR_QUEEN_HOLDER_CANNOT_USE_DRAGON: "error.queenHolderCannotUseDragon";
+    readonly ERROR_BUILDING_NOT_FOUND: "error.buildingNotFound";
+    readonly ERROR_INVALID_OPTIONAL_ACTION: "error.invalidOptionalAction";
+    readonly ERROR_GIANT_POOL_EMPTY: "error.giantPoolEmpty";
+    readonly ERROR_GIANT_NOT_FOUND: "error.giantNotFound";
+    readonly ERROR_INVALID_GIANT_PLACEMENT: "error.invalidGiantPlacement";
+    readonly ERROR_NOT_AOG_MODE: "error.notAogMode";
+    readonly ERROR_FIRE_TOKEN_POOL_EMPTY: "error.fireTokenPoolEmpty";
+    readonly ERROR_FIRE_TOKEN_INVALID_POSITION: "error.fireTokenInvalidPosition";
+    readonly ERROR_NO_PENDING_FIRE_TOKEN: "error.noPendingFireToken";
+    readonly ERROR_CANNOT_RECRUIT_CAVEMAN: "error.cannotRecruitCaveman";
+    readonly ERROR_INSUFFICIENT_RESOURCES: "error.insufficientResources";
+    readonly ERROR_INVALID_CAVEMAN_PLACEMENT: "error.invalidCavemanPlacement";
+    readonly ERROR_CAVEMAN_NOT_FOUND: "error.cavemanNotFound";
+    readonly ERROR_NOT_TRIBE_MODE: "error.notTribeMode";
 };
 type TranslationKeyType = (typeof TranslationKey)[keyof typeof TranslationKey];
 /**
@@ -934,6 +1443,45 @@ type GameEventCallbacks = {
     onGameEnd?: (event: {
         game: GameState;
     }) => void;
+    /** Called after a lord places a knight on their kingdom (QueenDomino) */
+    onKnightPlaced?: (event: {
+        game: GameState;
+        lordId: string;
+    }) => void;
+    /** Called after a lord constructs a building (QueenDomino) */
+    onBuildingConstructed?: (event: {
+        game: GameState;
+        lordId: string;
+        buildingId: number;
+    }) => void;
+    /** Called after a lord uses the dragon to destroy a building (QueenDomino) */
+    onDragonUsed?: (event: {
+        game: GameState;
+        lordId: string;
+        buildingId: number;
+    }) => void;
+    /** Called after a lord places a fire token on their kingdom (Origins) */
+    onFireTokenPlaced?: (event: {
+        game: GameState;
+        lordId: string;
+    }) => void;
+    /** Called after a lord recruits a caveman from the cave board (Origins Tribe) */
+    onCavemanRecruited?: (event: {
+        game: GameState;
+        lordId: string;
+        cavemanId: number;
+    }) => void;
+    /** Called after a lord places a giant on a crown in their kingdom */
+    onGiantPlaced?: (event: {
+        game: GameState;
+        lordId: string;
+    }) => void;
+    /** Called after a lord sends a giant to an opponent's kingdom */
+    onGiantSent?: (event: {
+        game: GameState;
+        lordId: string;
+        targetPlayerId: string;
+    }) => void;
 };
 /**
  * Wraps a GameEngine to emit event callbacks after each state-changing method.
@@ -988,6 +1536,14 @@ type EngineConfig = {
  */
 declare const validateGameState: (game: Game) => ValidationIssue[];
 
+type BuildingsRepository = {
+    getAll: () => BuildingTile[];
+};
+
+type CavemenRepository = {
+    getAll: () => CavemanTile[];
+};
+
 type DominoesRepository = {
     getForMode: (mode: GameMode) => Domino[] | [];
 };
@@ -996,6 +1552,10 @@ type ModeRepository = {
     getAvailables: () => GameMode[];
 };
 
+type QuestTilesRepository = {
+    getAll: () => QuestTile[];
+};
+
 type RuleRepository = {
     getAll: () => Rules;
     getAllExtra: () => ExtraRule[];
@@ -1093,10 +1653,12 @@ declare const getStrategy: (name: string, custom?: Record<string, BotStrategy>)
  */
 declare const getStrategyNames: () => string[];
 
+type ConstructBuildingUseCase = (game: GameWithNextAction, lordId: string, buildingId: number, position: Position) => GameStateResult;
+
 /**
  * The types of state-changing actions that can be recorded.
  */
-type ActionType = "createGame" | "addPlayers" | "addExtraRules" | "startGame" | "chooseDomino" | "placeDomino" | "discardDomino";
+type ActionType = "createGame" | "addPlayers" | "addExtraRules" | "startGame" | "chooseDomino" | "placeDomino" | "discardDomino" | "placeGiant" | "sendGiant";
 /**
  * Payload types for each action, containing only the command parameters
  * (excluding the game state, which is too large to store).
@@ -1125,6 +1687,16 @@ type ActionPayloadMap = {
     discardDomino: {
         lordId: string;
     };
+    placeGiant: {
+        lordId: string;
+        position: Position;
+    };
+    sendGiant: {
+        lordId: string;
+        giantIndex: number;
+        targetPlayerId: string;
+        targetCrownPosition: Position;
+    };
 };
 /**
  * A single recorded action in the game log.
@@ -1290,6 +1862,16 @@ declare const getHistorySize: (history: GameHistory) => {
     future: number;
 };
 
+type PlaceFireTokenUseCase = (game: GameWithNextAction, lordId: string, position: Position) => GameStateResult;
+
+type PlaceGiantUseCase = (game: GameWithNextAction, lordId: string, position: Position) => GameStateResult;
+
+type PlaceKnightUseCase = (game: GameWithNextAction, lordId: string, position: Position) => GameStateResult;
+
+type RecruitCavemanUseCase = (game: GameWithNextAction, lordId: string, cavemanId: number, position: Position, resourcePositions: Position[]) => GameStateResult;
+
+type SendGiantUseCase = (game: GameWithNextAction, lordId: string, giantIndex: number, targetPlayerId: string, targetCrownPosition: Position) => GameStateResult;
+
 /**
  * Serializes a game state to a JSON string.
  * The serialized string includes version information for future compatibility.
@@ -1335,6 +1917,10 @@ declare const createSavePoint: (game: GameState) => GameSavePoint;
  */
 declare const restoreFromSavePoint: (savePoint: GameSavePoint) => Result<GameState>;
 
+type SkipOptionalActionUseCase = (game: GameWithNextAction, lordId: string) => GameStateResult;
+
+type UseDragonUseCase = (game: GameWithNextAction, lordId: string, buildingId: number) => GameStateResult;
+
 /**
  * Creates a new Kingdomino game engine instance.
  *
@@ -1360,4 +1946,4 @@ declare const restoreFromSavePoint: (savePoint: GameSavePoint) => Result<GameSta
  */
 declare const createGameEngine: (config: Partial<EngineConfig>) => GameEngine;
 
-export { type ActionEntry, ActionExecutionError, type ActionPayloadMap, type ActionType, type AddExtraRulesCommand, type AddPlayersCommand, type BasicRules, type BotStrategy, type CalculateScoreCommand, type CanPlaceDominoCommand, type ChooseDominoCommand, type CreateGameCommand, type Crown, type DebugLogEntry, type DebugLogLevel, type DebugLogger, type DebugOptions, type DeserializeGameCommand, type DiscardDominoCommand, type DomainError, DomainException, type Domino, type DominoesRepository, type DynastyResult, type EmptyGround, type EmptyTile, type EngineConfig, ErrorCode, type ErrorCodeType, type ExtraRule, type FinalResult, GRIDSIZE, GROUND, type Game, type GameActionLog, type GameEngine, type GameEventCallbacks, type GameHistory, type GameMode, type GameSavePoint, type GameState, type GameStateResult, type GameStateSummary, type GameSteps, type GameWithNextAction, type GameWithNextStep, type GameWithResults, type GetDynastyResultCommand, type GetExtraRulesCommand, type GetModesCommand, type GetResultCommand, type GetValidPlacementsCommand, type Ground, InvalidStepError, type Kingdom, type Logger, type Lord, MAX_KINGDOM_SIZE, type ModeRepository, type NextAction, type NextStep, NotFoundError, type ObjectValues, type PickContext, type PlaceContext, type PlaceDominoCommand, type Player, type PlayerActions, type PlayerInput, type PlayerPayload, type Players, type PlayersPayload, type Position, RedoError, type RevealsDomino, type Rotation, type RuleRepository, type Rules, type Score, type ScoreResult, type SelectedRules, type SerializeGameCommand, type ShuffleMethod, type StartGameCommand, StepExecutionError, type StrategyName, type Tile, TranslationKey, type TranslationKeyType, type Translator, UndoError, type UuidMethod, type ValidPlacement, ValidationError, type ValidationIssue, type ValidationSeverity, advancedStrategy, appendAction, canRedo, canUndo, clearHistory, createActionLog, createDomainError, createGameEngine, createGameHistory, createSavePoint, createTranslator, defaultTranslations, defaultTranslator, deserializeGame, errorCodeToTranslationKey, expertStrategy, gameSteps, getActions, getActionsByTurn, getActionsByType, getHistorySize, getStrategy, getStrategyNames, greedyStrategy, isBotTurn, isGameWithNextAction, isGameWithNextStep, playBotTurn, playBotTurns, playerActions, pushState, randomStrategy, redo, replayActions, restoreFromSavePoint, serializeGame, summarizeGameState, translateErrorCode, undo, validateGameState, wrapWithActionLog, wrapWithDebug, wrapWithEvents };
+export { type ActionEntry, ActionExecutionError, type ActionPayloadMap, type ActionType, type AddExtraRulesCommand, type AddPlayersCommand, type AgeOfGiantsState, type BasicRules, type BotStrategy, type BuildersBoard, type BuildingSlot, type BuildingTile, type BuildingsRepository, type CalculateScoreCommand, type CanPlaceDominoCommand, type CaveBoard, type CavemanTile, type CavemenRepository, type ChooseDominoCommand, type ConstructBuildingCommand, type ConstructBuildingUseCase, type CreateGameCommand, type Crown, type DebugLogEntry, type DebugLogLevel, type DebugLogger, type DebugOptions, type DeserializeGameCommand, type DiscardDominoCommand, type DomainError, DomainException, type Domino, type DominoesRepository, type DynastyResult, type EmptyGround, type EmptyTile, type EndGameScoring, type EndGameScoringType, type EngineConfig, ErrorCode, type ErrorCodeType, type ExtraRule, type FinalResult, type FireTokenPool, GRIDSIZE, GROUND, type Game, type GameActionLog, type GameEngine, type GameEventCallbacks, type GameHistory, type GameMode, type GameSavePoint, type GameState, type GameStateResult, type GameStateSummary, type GameSteps, type GameWithNextAction, type GameWithNextStep, type GameWithResults, type GetDynastyResultCommand, type GetExtraRulesCommand, type GetModesCommand, type GetResultCommand, type GetValidPlacementsCommand, type Ground, type HunterGathererKind, type HunterGathererTile, type ImmediateBonus, type ImmediateBonusType, InvalidStepError, type Kingdom, type Knight, type Logger, type Lord, MAX_KINGDOM_SIZE, type ModeRepository, type NextAction, type NextStep, NotFoundError, type ObjectValues, type OriginsState, type OriginsSubMode, type PendingFireToken, type PickContext, type PlaceContext, type PlaceDominoCommand, type PlaceFireTokenCommand, type PlaceFireTokenUseCase, type PlaceGiantCommand, type PlaceGiantUseCase, type PlaceKnightCommand, type PlaceKnightUseCase, type PlacedBuilding, type PlacedCaveman, type PlacedFireToken, type PlacedGiant, type Player, type PlayerActions, type PlayerInput, type PlayerPayload, type Players, type PlayersPayload, type Position, type QueenDominoState, type QuestTile, type QuestTilesRepository, type QuestType, type RecruitCavemanCommand, type RecruitCavemanUseCase, RedoError, type Resource, type ResourceType, type RevealsDomino, type Rotation, type RuleRepository, type Rules, type Score, type ScoreResult, type SelectedRules, type SendGiantCommand, type SendGiantUseCase, type SerializeGameCommand, type ShuffleMethod, type SkipOptionalActionCommand, type SkipOptionalActionUseCase, type StartGameCommand, StepExecutionError, type StrategyName, type Tile, type TotemBonus, type TotemState, TranslationKey, type TranslationKeyType, type Translator, UndoError, type UseDragonCommand, type UseDragonUseCase, type UuidMethod, type ValidPlacement, ValidationError, type ValidationIssue, type ValidationSeverity, WARRIOR_POWER, type WarriorTile, type WarriorType, advancedStrategy, appendAction, canRedo, canUndo, clearHistory, createActionLog, createDomainError, createGameEngine, createGameHistory, createSavePoint, createTranslator, defaultTranslations, defaultTranslator, deserializeGame, errorCodeToTranslationKey, expertStrategy, gameSteps, getActions, getActionsByTurn, getActionsByType, getHistorySize, getStrategy, getStrategyNames, greedyStrategy, hunterGathererKinds, isBotTurn, isGameWithNextAction, isGameWithNextStep, originsSubModes, playBotTurn, playBotTurns, playerActions, pushState, questTypes, randomStrategy, redo, replayActions, resourceTypes, restoreFromSavePoint, serializeGame, summarizeGameState, translateErrorCode, undo, validateGameState, warriorTypes, wrapWithActionLog, wrapWithDebug, wrapWithEvents };