@pompidup/kingdomino-engine 3.2.0 → 3.4.0

package/dist/index.d.ts

@@ -18,6 +18,8 @@ type Tile = {
     type: Ground;
     /** Number of crowns (0-3), multiplier for scoring */
     crowns: Crown;
+    /** Whether this tile has a construction square for buildings (Queendomino) */
+    hasConstructionSquare?: boolean;
 };
 /**
  * Represents an empty/unplaced tile on the kingdom grid.
@@ -89,6 +91,83 @@ declare const GRIDSIZE = 9;
  */
 declare const MAX_KINGDOM_SIZE = 5;
 
+/**
+ * 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;
+};
+
+type Result<T> = Ok<T> | Err;
+interface Ok<T> {
+    readonly tag: "Ok";
+    readonly value: T;
+}
+interface Err {
+    readonly tag: "Err";
+    readonly error: string;
+}
+
 /**
  * Represents a lord (player token) used for turn order and domino selection.
  * In games with 2 players, each player has 2 lords.
@@ -122,6 +201,15 @@ type GameMode = {
 
 type ObjectValues<T> = T[keyof T];
 
+/**
+ * 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 +224,14 @@ 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[];
 };
 /**
  * Payload for creating a new player.
@@ -158,10 +254,33 @@ 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) */
+    readonly skipOptionalAction: "skipOptionalAction";
 };
 /** 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.
  */
@@ -209,16 +328,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 +353,8 @@ type Game = {
     mode: GameMode;
     /** Optional seed for deterministic shuffle (replays, sharing) */
     seed?: string;
+    /** Queendomino-specific state (only present in QueenDomino mode) */
+    queendomino?: QueenDominoState;
 };
 /**
  * Available game steps representing phases of game setup and completion.
@@ -464,6 +575,30 @@ type GetDynastyResultCommand = {
     games: GameWithResults[];
 };
 
+type PlaceKnightCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    position: Position;
+};
+
+type ConstructBuildingCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    buildingId: number;
+    position: Position;
+};
+
+type UseDragonCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    buildingId: number;
+};
+
+type SkipOptionalActionCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+};
+
 /**
  * Represents a valid placement position with rotation.
  */
@@ -613,6 +748,30 @@ type GameEngine = {
      * @returns Ranked dynasty results per player
      */
     getDynastyResults: (command: GetDynastyResultCommand) => DynastyResult[];
+    /**
+     * 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;
+    /**
+     * Skips the current optional action (Queendomino).
+     * @param command - Contains game state and lord ID
+     * @returns Updated game state with next action
+     */
+    skipOptionalAction: (command: SkipOptionalActionCommand) => GameState;
 };
 
 /**
@@ -641,6 +800,15 @@ 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";
 };
 type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
 /**
@@ -752,6 +920,15 @@ 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";
 };
 type TranslationKeyType = (typeof TranslationKey)[keyof typeof TranslationKey];
 /**
@@ -988,6 +1165,10 @@ type EngineConfig = {
  */
 declare const validateGameState: (game: Game) => ValidationIssue[];
 
+type BuildingsRepository = {
+    getAll: () => BuildingTile[];
+};
+
 type DominoesRepository = {
     getForMode: (mode: GameMode) => Domino[] | [];
 };
@@ -1290,6 +1471,14 @@ declare const getHistorySize: (history: GameHistory) => {
     future: number;
 };
 
+type PlaceKnightUseCase = (game: GameWithNextAction, lordId: string, position: Position) => GameStateResult;
+
+type ConstructBuildingUseCase = (game: GameWithNextAction, lordId: string, buildingId: number, position: Position) => GameStateResult;
+
+type UseDragonUseCase = (game: GameWithNextAction, lordId: string, buildingId: number) => GameStateResult;
+
+type SkipOptionalActionUseCase = (game: GameWithNextAction, lordId: string) => GameStateResult;
+
 /**
  * Serializes a game state to a JSON string.
  * The serialized string includes version information for future compatibility.
@@ -1360,4 +1549,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 BasicRules, type BotStrategy, type BuildersBoard, type BuildingSlot, type BuildingTile, type BuildingsRepository, type CalculateScoreCommand, type CanPlaceDominoCommand, 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, 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 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 PickContext, type PlaceContext, type PlaceDominoCommand, type PlaceKnightCommand, type PlaceKnightUseCase, type PlacedBuilding, type Player, type PlayerActions, type PlayerInput, type PlayerPayload, type Players, type PlayersPayload, type Position, type QueenDominoState, RedoError, type RevealsDomino, type Rotation, type RuleRepository, type Rules, type Score, type ScoreResult, type SelectedRules, type SerializeGameCommand, type ShuffleMethod, type SkipOptionalActionCommand, type SkipOptionalActionUseCase, type StartGameCommand, StepExecutionError, type StrategyName, type Tile, TranslationKey, type TranslationKeyType, type Translator, UndoError, type UseDragonCommand, type UseDragonUseCase, 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 };