@drmxrcy/tcg-core 0.0.0-202602060542

package/src/moves/move-system.ts

@@ -0,0 +1,463 @@
+import type { Draft } from "immer";
+import type { HistoryOperations } from "../history/history-operations";
+import type { CardOperations } from "../operations/card-operations";
+import type { CardRegistry } from "../operations/card-registry";
+import type { CounterOperations } from "../operations/counter-operations";
+import type { GameOperations } from "../operations/game-operations";
+import type { ZoneOperations } from "../operations/zone-operations";
+import type { SeededRNG } from "../rng/seeded-rng";
+import type { CardId, PlayerId } from "../types";
+import type { MoveEnumerationContext } from "./move-enumeration";
+
+/**
+ * Helper type to normalize move parameters
+ *
+ * Converts void/undefined to empty object type for moves without parameters.
+ * This ensures consistent typing across all moves.
+ *
+ * @template T - Raw parameter type from TMoves
+ */
+export type NormalizeParams<T> = T extends void | undefined
+  ? Record<string, never>
+  : T;
+
+/**
+ * Move Context Input
+ *
+ * The context that callers provide when executing a move via engine.executeMove().
+ * This is a subset of MoveContext containing only the fields the caller provides.
+ * The engine fills in the remaining fields (rng, zones, cards, etc.).
+ *
+ * @template TParams - Move-specific parameter type (from TMoves[MoveName])
+ *
+ * @example
+ * ```typescript
+ * // Execute a move by providing only playerId and params
+ * engine.executeMove('playCard', {
+ *   playerId: 'p1',
+ *   params: { cardId: 'card-123' }
+ * });
+ * ```
+ */
+export type MoveContextInput<TParams = any> = {
+  /** Player performing this move */
+  playerId: PlayerId;
+
+  /**
+   * Move-specific parameters (fully typed)
+   *
+   * Type-safe parameters for this specific move.
+   * For moves without parameters (passTurn: void), this is an empty object {}.
+   */
+  params: TParams;
+
+  /** Source card for this move (e.g., card being played or ability source) */
+  sourceCardId?: CardId;
+
+  /** Selected targets (array of arrays for multi-target moves) */
+  targets?: string[][];
+
+  /** Timestamp when move was initiated (for deterministic ordering) */
+  timestamp?: number;
+};
+
+/**
+ * Context provided to move reducers and conditions
+ *
+ * Contains all information needed to execute a move:
+ * - Player performing the move
+ * - Move-specific parameters (fully typed)
+ * - Source card (if applicable)
+ * - Selected targets
+ * - Timestamp for deterministic ordering
+ * - RNG for deterministic randomness
+ * - Zone operations API (for framework-managed zones)
+ * - Card operations API (for framework-managed card metadata)
+ * - Card registry API (for static card definitions)
+ *
+ * @template TParams - Move-specific parameter type (from TMoves[MoveName])
+ * @template TCardMeta - Game-specific card metadata type
+ * @template TCardDefinition - Game-specific card definition type
+ */
+export type MoveContext<
+  TParams = any,
+  TCardMeta = any,
+  TCardDefinition = any,
+> = {
+  /** Player performing this move */
+  playerId: PlayerId;
+
+  /**
+   * Move-specific parameters (fully typed)
+   *
+   * Type-safe parameters for this specific move.
+   * For example, playCard receives { cardId: string; alternativeCost?: AlternativeCost }
+   *
+   * For moves without parameters (passTurn: void), this is an empty object {}.
+   */
+  params: TParams;
+
+  /** Source card for this move (e.g., card being played or ability source) */
+  sourceCardId?: CardId;
+
+  /** Selected targets (array of arrays for multi-target moves) */
+  targets?: string[][];
+
+  /** Timestamp when move was initiated (for deterministic ordering) */
+  timestamp?: number;
+
+  /** Seeded RNG for deterministic randomness (provided by engine) */
+  rng: SeededRNG;
+
+  /**
+   * Zone operations API (provided by RuleEngine)
+   *
+   * Provides methods to interact with the framework's zone management:
+   * - moveCard: Move cards between zones
+   * - getCardsInZone: Query cards in a zone
+   * - shuffleZone: Shuffle a zone
+   * - getCardZone: Find which zone contains a card
+   *
+   * This is the ONLY way moves can modify zone state.
+   * Always provided by RuleEngine when zones are configured.
+   */
+  zones: ZoneOperations;
+
+  /**
+   * Card operations API (provided by RuleEngine)
+   *
+   * Provides methods to interact with the framework's card metadata:
+   * - getCardMeta: Get dynamic card properties
+   * - updateCardMeta: Merge metadata updates
+   * - setCardMeta: Replace metadata completely
+   * - getCardOwner: Get card's owner
+   * - queryCards: Find cards by predicate
+   *
+   * This is the ONLY way moves can modify card metadata.
+   * Always provided by RuleEngine.
+   */
+  cards: CardOperations<TCardMeta>;
+
+  /**
+   * Game operations API (provided by RuleEngine)
+   *
+   * Provides methods to interact with game-level state:
+   * - setOTP: Mark player as on the play (goes first)
+   * - getOTP: Get the OTP player
+   * - setPendingMulligan: Set players pending mulligan
+   * - getPendingMulligan: Get players pending mulligan
+   * - addPendingMulligan: Add player to mulligan list
+   * - removePendingMulligan: Remove player from mulligan list
+   *
+   * These are universal TCG concepts that apply across all card games.
+   * This is the ONLY way moves can modify game-level internal state.
+   * Always provided by RuleEngine.
+   */
+  game: GameOperations;
+
+  /**
+   * History operations API (provided by RuleEngine)
+   *
+   * Provides methods to log custom history entries:
+   * - log: Add a history entry with custom messages and player-specific visibility
+   *
+   * Use this to add detailed logging for moves with private information
+   * (e.g., card draws, mulligans, hand reveals).
+   *
+   * Note: The engine automatically creates a base history entry for each move.
+   * Use this API to add additional context or player-specific details.
+   *
+   * Always provided by RuleEngine.
+   */
+  history: HistoryOperations;
+
+  /**
+   * Card registry API (provided by RuleEngine)
+   *
+   * Provides read-only access to static card definitions:
+   * - getCard: Get a card definition by ID
+   * - hasCard: Check if a card definition exists
+   * - getAllCards: Get all card definitions
+   * - queryCards: Find cards by predicate
+   * - getCardCount: Get total number of card definitions
+   *
+   * Use this to access static card properties (name, cost, abilities, etc).
+   * For dynamic card state (damage, tapped, etc), use the cards API.
+   *
+   * Optional for backward compatibility and testing. In production,
+   * this is always provided by RuleEngine when card definitions are configured.
+   */
+  registry?: CardRegistry<TCardDefinition>;
+
+  /**
+   * Flow state (provided by RuleEngine)
+   *
+   * Provides access to engine-managed flow state:
+   * - currentPhase: Current phase name (from flow definition)
+   * - currentSegment: Current segment name within phase (if applicable)
+   * - turn: Current turn number (1-indexed)
+   * - currentPlayer: Player ID of the active player
+   * - isFirstTurn: True if this is turn 1 of the game
+   * - endPhase: Trigger phase transition (deferred until after move completes)
+   * - endSegment: Trigger segment transition (deferred until after move completes)
+   * - endTurn: Trigger turn transition (deferred until after move completes)
+   *
+   * Games should NOT duplicate this state in their own game state.
+   * Access flow information via context.flow instead.
+   *
+   * Optional for backward compatibility. In production with flow configured,
+   * this is always provided by RuleEngine.
+   */
+  flow?: {
+    currentPhase?: string;
+    currentSegment?: string;
+    turn: number;
+    currentPlayer?: PlayerId;
+    isFirstTurn: boolean;
+    endPhase: (phaseName?: string) => void;
+    endSegment: () => void;
+    endTurn: () => void;
+    setCurrentPlayer?: (playerId?: PlayerId) => void;
+  };
+
+  /**
+   * End the game with a result
+   *
+   * Call this method to signal game completion. The engine will handle
+   * setting the game-ended state and preventing further moves.
+   *
+   * @param result - Game end result with winner and reason
+   *
+   * @example
+   * ```typescript
+   * // In a concede move:
+   * context.endGame({
+   *   winner: otherPlayerId,
+   *   reason: 'concede',
+   *   metadata: { concedeBy: context.playerId }
+   * });
+   * ```
+   */
+  endGame?: (result: {
+    winner?: PlayerId;
+    reason: string;
+    metadata?: Record<string, unknown>;
+  }) => void;
+
+  /**
+   * Tracker operations (provided by RuleEngine)
+   *
+   * Provides API for boolean flags that auto-reset at turn/phase boundaries.
+   * Eliminates boilerplate for "hasDrawnThisTurn", "hasPlayedResourceThisTurn", etc.
+   *
+   * Operations:
+   * - check(name, playerId?): Check if tracker is marked
+   * - mark(name, playerId?): Mark tracker as true
+   * - unmark(name, playerId?): Mark tracker as false
+   *
+   * Trackers auto-reset based on game definition config.
+   *
+   * Optional for backward compatibility. In production with trackers configured,
+   * this is always provided by RuleEngine.
+   *
+   * @example
+   * ```typescript
+   * // Check if player has drawn this turn
+   * if (!context.trackers.check('hasDrawn', context.playerId)) {
+   *   // Draw a card
+   *   context.trackers.mark('hasDrawn', context.playerId);
+   * }
+   * ```
+   */
+  trackers?: {
+    check(name: string, playerId?: PlayerId): boolean;
+    mark(name: string, playerId?: PlayerId): void;
+    unmark(name: string, playerId?: PlayerId): void;
+  };
+
+  /**
+   * Counter operations API (provided by RuleEngine)
+   *
+   * Provides methods to manage counters and flags on cards:
+   * - setFlag/getFlag: Boolean flags (exhausted, stunned, buffed)
+   * - addCounter/removeCounter/getCounter/clearCounter: Numeric counters (damage)
+   * - clearAllCounters: Reset all counters on a card
+   * - getCardsWithFlag/getCardsWithCounter: Query cards by counter state
+   *
+   * This is the recommended way to manage card counters/tokens.
+   * Always provided by RuleEngine.
+   *
+   * @example
+   * ```typescript
+   * // Mark card as exhausted
+   * context.counters.setFlag(cardId, 'exhausted', true);
+   *
+   * // Add damage to a card
+   * context.counters.addCounter(cardId, 'damage', 3);
+   *
+   * // Check if card is stunned
+   * if (context.counters.getFlag(cardId, 'stunned')) {
+   *   // Card is stunned
+   * }
+   * ```
+   */
+  counters: CounterOperations;
+};
+
+/**
+ * Move Reducer Function
+ *
+ * Pure function that updates game state in response to a move.
+ * Operates on Immer draft for immutable updates.
+ *
+ * @template TGameState - Game state type
+ * @template TParams - Move-specific parameter type (from TMoves[MoveName])
+ * @template TCardMeta - Card metadata type
+ * @template TCardDefinition - Card definition type
+ *
+ * @param draft - Immer draft of game state (mutable proxy)
+ * @param context - Move context with player, typed params, targets, etc.
+ *
+ * @example
+ * ```typescript
+ * type DrawCardParams = { count: number };
+ * const drawCardReducer: MoveReducer<GameState, DrawCardParams> = (draft, context) => {
+ *   const { count } = context.params; // ✅ Fully typed!
+ *   const player = draft.players[context.playerId];
+ *   for (let i = 0; i < count; i++) {
+ *     const card = draft.deck.pop();
+ *     if (card) player.hand.push(card);
+ *   }
+ * };
+ * ```
+ */
+export type MoveReducer<
+  TGameState,
+  TParams = any,
+  TCardMeta = any,
+  TCardDefinition = any,
+> = (
+  draft: Draft<TGameState>,
+  context: MoveContext<TParams, TCardMeta, TCardDefinition>,
+) => void;
+
+/**
+ * Condition Failure Result
+ *
+ * Detailed information about why a move condition failed.
+ * Returned by conditions to provide meaningful error messages to players.
+ *
+ * @example
+ * ```typescript
+ * // In a move condition:
+ * if (player.mana < card.cost) {
+ *   return {
+ *     reason: `Not enough mana. Required: ${card.cost}, Available: ${player.mana}`,
+ *     errorCode: "INSUFFICIENT_MANA",
+ *     context: { required: card.cost, available: player.mana },
+ *   };
+ * }
+ * ```
+ */
+export type ConditionFailure = {
+  /** Human-readable explanation of why the move failed */
+  reason: string;
+  /** Machine-readable error code for categorization */
+  errorCode: string;
+  /** Optional additional context for debugging/logging */
+  context?: Record<string, unknown>;
+};
+
+/**
+ * Move Condition Function
+ *
+ * Pure predicate that determines if a move is legal given current game state.
+ * Called BEFORE reducer execution to validate move.
+ *
+ * @template TGameState - Game state type
+ * @template TParams - Move-specific parameter type (from TMoves[MoveName])
+ * @template TCardMeta - Card metadata type
+ * @template TCardDefinition - Card definition type
+ *
+ * @param state - Current game state (readonly)
+ * @param context - Move context with player, typed params, targets, etc.
+ * @returns True if legal, false for generic failure, or ConditionFailure for detailed error
+ *
+ * @example
+ * ```typescript
+ * // Simple boolean validation (backward compatible)
+ * condition: (state, context) => {
+ *   return state.players[context.playerId].mana >= 5;
+ * }
+ *
+ * // Detailed failure information (recommended)
+ * condition: (state, context) => {
+ *   const player = state.players[context.playerId];
+ *   const cost = 5;
+ *
+ *   if (player.mana < cost) {
+ *     return {
+ *       reason: `Not enough mana. Required: ${cost}, Available: ${player.mana}`,
+ *       errorCode: "INSUFFICIENT_MANA",
+ *       context: { required: cost, available: player.mana },
+ *     };
+ *   }
+ *
+ *   return true;
+ * }
+ * ```
+ */
+export type MoveCondition<
+  TGameState,
+  TParams = any,
+  TCardMeta = any,
+  TCardDefinition = any,
+> = (
+  state: TGameState,
+  context: MoveContext<TParams, TCardMeta, TCardDefinition>,
+) => boolean | ConditionFailure;
+
+/**
+ * Move Result
+ *
+ * Result of attempting to execute a move.
+ * Either succeeds with new state, or fails with error information.
+ *
+ * @example
+ * ```typescript
+ * // Success
+ * const result: MoveResult<GameState> = {
+ *   success: true,
+ *   state: newGameState
+ * };
+ *
+ * // Failure
+ * const result: MoveResult<GameState> = {
+ *   success: false,
+ *   error: 'Not enough mana',
+ *   errorCode: 'INSUFFICIENT_RESOURCES',
+ *   errorContext: { required: 5, available: 3 }
+ * };
+ * ```
+ */
+export type MoveResult<TGameState> =
+  | {
+      /** Move executed successfully */
+      success: true;
+      /** New game state after move */
+      state: TGameState;
+      error?: never;
+      errorCode?: never;
+      errorContext?: never;
+    }
+  | {
+      /** Move failed validation or execution */
+      success: false;
+      /** Human-readable error message */
+      error: string;
+      /** Machine-readable error code */
+      errorCode?: string;
+      /** Additional error context for debugging */
+      errorContext?: Record<string, unknown>;
+      state?: never;
+    };

package/src/moves/standard-moves.ts

@@ -0,0 +1,231 @@
+import type { Draft } from "immer";
+import type { GameMoveDefinitions } from "../game-definition/move-definitions";
+import type { PlayerId, ZoneId } from "../types/branded";
+import type { MoveContext } from "./move-system";
+
+/**
+ * Options for configuring standard moves
+ */
+export type StandardMoveOptions = {
+  /** Which standard moves to include */
+  include?: StandardMoveName[];
+  /** Custom zone names for draw/shuffle operations */
+  zones?: {
+    deck?: ZoneId;
+    hand?: ZoneId;
+    discard?: ZoneId;
+  };
+  /** Custom game-over handling for concede */
+  onConcede?: (playerId: PlayerId, context: MoveContext) => void;
+};
+
+/**
+ * Available standard move names
+ */
+export type StandardMoveName =
+  | "pass"
+  | "concede"
+  | "draw"
+  | "shuffle"
+  | "mulligan";
+
+/**
+ * Type definition for standard moves
+ */
+export type StandardMoves = {
+  pass: { playerId: PlayerId };
+  concede: { playerId: PlayerId };
+  draw: { playerId: PlayerId; count?: number };
+  shuffle: { playerId: PlayerId };
+  mulligan: { playerId: PlayerId; keepCards?: string[] };
+};
+
+/**
+ * Create a library of standard TCG moves that games can opt into.
+ * Eliminates boilerplate for common operations like pass, concede, draw, shuffle, etc.
+ *
+ * @example
+ * ```typescript
+ * const gameDefinition = {
+ *   moves: {
+ *     ...standardMoves({ include: ["pass", "concede", "draw"] }),
+ *     // Custom game-specific moves
+ *     playCard: { ... }
+ *   }
+ * }
+ * ```
+ *
+ * @param options - Configuration for which moves to include and custom settings
+ * @returns A GameMoveDefinitions object with the requested standard moves
+ */
+export function standardMoves<TState>(
+  options: StandardMoveOptions = {},
+): Partial<GameMoveDefinitions<TState, StandardMoves>> {
+  const { include = ["pass", "concede"], zones = {} } = options;
+  const moves: Partial<GameMoveDefinitions<TState, StandardMoves>> = {};
+
+  const deckZone = zones.deck ?? ("deck" as ZoneId);
+  const handZone = zones.hand ?? ("hand" as ZoneId);
+  const discardZone = zones.discard ?? ("discard" as ZoneId);
+
+  // Pass move - do nothing, just advance turn
+  if (include.includes("pass")) {
+    moves.pass = {
+      condition: (_state: TState, _context: MoveContext) => {
+        // Can always pass (unless game has ended)
+        return true;
+      },
+      reducer: (_draft: Draft<TState>, _context: MoveContext) => {
+        // No state changes - this is just a signal to advance flow
+      },
+    };
+  }
+
+  // Concede move - player forfeits the game
+  if (include.includes("concede")) {
+    moves.concede = {
+      condition: () => true, // Can always concede
+      reducer: (_draft: Draft<TState>, context: MoveContext) => {
+        if (options.onConcede) {
+          options.onConcede(context.playerId, context);
+        } else if (context.endGame) {
+          // Determine winner (opponent of conceeding player)
+          const winner = (
+            context.flow?.currentPlayer !== context.playerId
+              ? context.flow?.currentPlayer
+              : undefined
+          ) as PlayerId | undefined;
+          context.endGame({
+            winner,
+            reason: "concede",
+            metadata: { conceedingPlayer: context.playerId },
+          });
+        }
+      },
+    };
+  }
+
+  // Draw move - draw N cards from deck to hand
+  if (include.includes("draw")) {
+    moves.draw = {
+      condition: (_state: TState, context: MoveContext) => {
+        const count = context.params?.count ?? 1;
+        const deckCards = context.zones.getCardsInZone(
+          deckZone,
+          context.playerId,
+        );
+        return deckCards.length >= count;
+      },
+      reducer: (_draft: Draft<TState>, context: MoveContext) => {
+        const count = context.params?.count ?? 1;
+        context.zones.drawCards({
+          from: deckZone,
+          to: handZone,
+          count,
+          playerId: context.playerId,
+        });
+      },
+    };
+  }
+
+  // Shuffle move - shuffle player's deck
+  if (include.includes("shuffle")) {
+    moves.shuffle = {
+      condition: () => true,
+      reducer: (_draft: Draft<TState>, context: MoveContext) => {
+        context.zones.shuffleZone(deckZone, context.playerId);
+      },
+    };
+  }
+
+  // Mulligan move - return hand to deck, shuffle, and redraw
+  if (include.includes("mulligan")) {
+    moves.mulligan = {
+      condition: (_state: TState, context: MoveContext) => {
+        // Typically only allowed on first turn or during setup
+        return context.flow?.isFirstTurn ?? true;
+      },
+      reducer: (_draft: Draft<TState>, context: MoveContext) => {
+        const keepCards = context.params?.keepCards ?? [];
+        const handCards = context.zones.getCardsInZone(
+          handZone,
+          context.playerId,
+        );
+
+        // Return non-kept cards to deck
+        const cardsToReturn = handCards.filter(
+          (cardId: string) => !keepCards.includes(cardId),
+        );
+        for (const cardId of cardsToReturn) {
+          context.zones.moveCard({
+            cardId,
+            targetZoneId: deckZone,
+            position: "bottom",
+          });
+        }
+
+        // Shuffle deck
+        context.zones.shuffleZone(deckZone, context.playerId);
+
+        // Draw the same number of cards we returned
+        const drawCount = cardsToReturn.length;
+        if (drawCount > 0) {
+          context.zones.drawCards({
+            from: deckZone,
+            to: handZone,
+            count: drawCount,
+            playerId: context.playerId,
+          });
+        }
+      },
+    };
+  }
+
+  return moves;
+}
+
+/**
+ * Helper to create a "discard" standard move
+ * This is separate because it requires card selection parameters
+ */
+export function createDiscardMove<TState>(): GameMoveDefinitions<
+  TState,
+  { discard: { playerId: PlayerId; cardIds: string[] } }
+>["discard"] {
+  return {
+    condition: (_state: TState, context: MoveContext) => {
+      // Must have cards to discard
+      const cardIds = context.params?.cardIds ?? [];
+      return cardIds.length > 0;
+    },
+    reducer: (_draft: Draft<TState>, context: MoveContext) => {
+      const cardIds = context.params?.cardIds ?? [];
+      for (const cardId of cardIds) {
+        context.zones.moveCard({
+          cardId,
+          targetZoneId: "discard" as ZoneId,
+        });
+      }
+    },
+  };
+}
+
+/**
+ * Helper to create an "endTurn" standard move
+ * This is separate because it interacts with flow management
+ */
+export function createEndTurnMove<TState>(): GameMoveDefinitions<
+  TState,
+  { endTurn: { playerId: PlayerId } }
+>["endTurn"] {
+  return {
+    condition: (_state: TState, context: MoveContext) => {
+      // Only current player can end their turn
+      return context.flow?.currentPlayer === context.playerId;
+    },
+    reducer: (_draft: Draft<TState>, _context: MoveContext) => {
+      // The actual turn transition is handled by FlowManager
+      // This move just signals that the player is done
+    },
+  };
+}