@drmxrcy/tcg-lorcana 0.0.0-202602060544

package/src/types/lorcana-state.ts

@@ -0,0 +1,260 @@
+/**
+ * Lorcana Game State Types
+ *
+ * Task 1.2: Define LorcanaState type extending base game state
+ *
+ * Complete type definition for Disney Lorcana game state following official rules:
+ * - Lore tracking for win condition (Rule 1.9.1.1 - win at 20 lore)
+ * - Ink management (total capacity and available per turn)
+ * - Character states (drying status, damage, exerted)
+ * - Turn metadata (cards played, characters questing, ink used)
+ * - Challenge state for combat resolution
+ * - Location and item states
+ *
+ * References:
+ * - Rule 3.1.4 (Lore starts at 0)
+ * - Rule 4.2.2.1 (Drying characters)
+ * - Rule 4.3.3 (Inkwell - once per turn)
+ * - Rule 4.3.6 (Challenge mechanics)
+ * - Rule 9 (Damage counters)
+ */
+
+import type { CardId, PlayerId } from "./branded-types";
+
+/**
+ * Lorcana Phase
+ *
+ * Three-phase turn structure (Rule 4.1.1):
+ * - beginning: Ready, Set, Draw steps
+ * - main: Player can take turn actions
+ * - end: End of turn cleanup
+ */
+export type LorcanaPhase = "beginning" | "main" | "end";
+
+/**
+ * Character State
+ *
+ * Runtime state for a character card in play.
+ * Tracks damage, exerted status, and "drying" state.
+ *
+ * Rule 4.2.2.1: Characters are "drying" the turn they're played
+ * Rule 6.1.4: Must be dry to quest, challenge, or exert
+ * Rule 9: Damage represented by counters
+ */
+export type CharacterState = {
+  /**
+   * "Drying" status - true if played this turn
+   *
+   * Characters that are "drying" cannot:
+   * - Quest (Rule 4.3.5)
+   * - Challenge (Rule 4.3.6.6)
+   * - Be exerted to pay costs (Rule 6.1.4)
+   *
+   * Becomes false at Set step of next turn (Rule 4.2.2.1)
+   */
+  playedThisTurn: boolean;
+
+  /**
+   * Damage counters on this character
+   *
+   * Rule 9.1: Each counter represents 1 damage
+   * Rule 1.9.1.3: Banished when damage >= Willpower
+   */
+  damage: number;
+
+  /**
+   * Exerted status - true if turned sideways
+   *
+   * Rule 5.1.2: Exerted cards turned sideways
+   * Rule 4.2.1.1: Readied at start of turn
+   */
+  exerted: boolean;
+};
+
+/**
+ * Permanent State
+ *
+ * Runtime state for locations and items in play.
+ * Currently only tracks damage (for locations).
+ */
+export type PermanentState = {
+  /**
+   * Damage counters (for locations)
+   *
+   * Rule 4.3.6.19-22: Locations can be challenged
+   * Rule 6.5: Locations have Willpower
+   */
+  damage: number;
+};
+
+/**
+ * Challenge State
+ *
+ * Temporary state during challenge resolution.
+ *
+ * Rule 4.3.6: Challenge mechanics
+ * - Attacker declared and exerted
+ * - Defender chosen
+ * - Damage calculated and dealt
+ * - Challenge ends
+ */
+export type ChallengeState = {
+  /**
+   * Attacking character
+   */
+  attacker: CardId;
+
+  /**
+   * Defending character or location
+   */
+  defender: CardId;
+
+  /**
+   * Calculated damage attacker will deal
+   *
+   * Rule 4.3.6.14: Based on Strength with modifiers
+   * Rule 10.3: Challenger +N applies
+   */
+  attackerDamage: number;
+
+  /**
+   * Calculated damage defender will deal
+   *
+   * Rule 4.3.6.14: Based on Strength with modifiers
+   * Rule 4.3.6.22: Locations deal no damage
+   */
+  defenderDamage: number;
+};
+
+/**
+ * Turn Metadata
+ *
+ * Tracks actions taken this turn for validation and cleanup.
+ * Reset at start of each turn.
+ */
+export type TurnMetadata = {
+  /**
+   * Cards played this turn
+   *
+   * Tracked for effects that reference "cards played this turn"
+   */
+  cardsPlayedThisTurn: CardId[];
+
+  /**
+   * Characters that quested this turn
+   *
+   * Rule 4.3.5: Each character can quest once per turn
+   * Tracked for effects that reference "whenever quests"
+   */
+  charactersQuesting: CardId[];
+
+  /**
+   * Whether player has put a card into inkwell this turn
+   *
+   * Rule 4.3.3: Limited to once per turn
+   */
+  inkedThisTurn: boolean;
+};
+
+/**
+ * Lorcana-specific Game State
+ *
+ * Complete game state for Disney Lorcana extending base game state structure.
+ * All Lorcana-specific data nested under `lorcana` property.
+ */
+export type LorcanaState = {
+  /**
+   * Players in the game
+   *
+   * Rule 2.1: Standard format is 2 players
+   */
+  players: PlayerId[];
+
+  /**
+   * Current player index (into players array)
+   *
+   * Rule 1.3: Active player takes their turn
+   */
+  currentPlayerIndex: number;
+
+  /**
+   * Turn number (starts at 1)
+   *
+   * Rule 3.1: First turn determined randomly
+   * Rule 4.2.3.2: Starting player skips draw on turn 1
+   */
+  turnNumber: number;
+
+  /**
+   * Current phase
+   *
+   * Rule 4.1: Three phases - Beginning, Main, End
+   */
+  phase: LorcanaPhase;
+
+  /**
+   * Lorcana-specific game state
+   */
+  lorcana: {
+    /**
+     * Lore totals for each player
+     *
+     * Rule 1.9.1.1: Win condition - first to 20 lore
+     * Rule 3.1.4: Starts at 0
+     * Rule 4.2.2.2: Gained from locations during Set step
+     * Rule 4.3.5.8: Gained from questing
+     */
+    lore: Record<PlayerId, number>;
+
+    /**
+     * Ink management
+     *
+     * Rule 4.3.3: Put card into inkwell once per turn
+     * Rule 8.5.1: Each ink card represents 1 ink
+     */
+    ink: {
+      /**
+       * Available ink this turn (can be spent)
+       *
+       * Replenished when cards readied at start of turn
+       */
+      available: Record<PlayerId, number>;
+
+      /**
+       * Total ink capacity (total cards in inkwell)
+       *
+       * Never decreases, only increases when inking
+       */
+      total: Record<PlayerId, number>;
+    };
+
+    /**
+     * Turn metadata - reset each turn
+     *
+     * Tracks what actions player has taken this turn
+     */
+    turnMetadata: TurnMetadata;
+
+    /**
+     * Character states
+     *
+     * Keyed by CardId, tracks runtime state of each character in play
+     */
+    characterStates: Record<CardId, CharacterState>;
+
+    /**
+     * Permanent states (locations and items)
+     *
+     * Keyed by CardId, tracks runtime state of non-character permanents
+     */
+    permanentStates: Record<CardId, PermanentState>;
+
+    /**
+     * Challenge state (only present during challenge)
+     *
+     * Rule 4.3.6: Challenge mechanics
+     * Optional - only set during challenge resolution
+     */
+    challengeState?: ChallengeState;
+  };
+};

package/src/types/move-enumeration.ts

@@ -0,0 +1,126 @@
+/**
+ * Move Enumeration Types
+ *
+ * Type definitions for the move enumeration system that allows AI agents
+ * and UI components to discover available moves and their parameters.
+ */
+
+/**
+ * Parameter field schema
+ *
+ * Describes a single parameter field for a move, including its type,
+ * description, and valid values.
+ */
+export type ParamFieldSchema = {
+  /** Parameter name */
+  name: string;
+
+  /** Parameter type */
+  type: "cardId" | "playerId" | "number" | "boolean" | "object" | "string";
+
+  /** Human-readable description */
+  description: string;
+
+  /** For cardId/playerId type: valid IDs that can be used */
+  validValues?: string[];
+
+  /** For enum types: valid enum values */
+  enumValues?: string[];
+};
+
+/**
+ * Move parameter schema
+ *
+ * Defines the structure of parameters a move accepts, including
+ * required and optional fields.
+ */
+export type MoveParamSchema = {
+  /** Required parameters */
+  required: ParamFieldSchema[];
+
+  /** Optional parameters */
+  optional?: ParamFieldSchema[];
+};
+
+/**
+ * Available move information
+ *
+ * Metadata about a move that is available to execute, including
+ * display information and parameter schema.
+ */
+export type AvailableMoveInfo = {
+  /** Unique move identifier */
+  moveId: string;
+
+  /** Human-readable display name */
+  displayName: string;
+
+  /** Brief description of what the move does */
+  description: string;
+
+  /** Icon hint for UI (optional) */
+  icon?: string;
+
+  /** Parameter schema (undefined if move has no parameters) */
+  paramSchema?: MoveParamSchema;
+};
+
+/**
+ * Parameter information
+ *
+ * Detailed information about a specific parameter, including
+ * type, description, and constraints.
+ */
+export type ParameterInfo = {
+  /** Parameter type */
+  type: "cardId" | "playerId" | "number" | "boolean" | "object" | "string";
+
+  /** Human-readable description */
+  description: string;
+
+  /** Valid values for this parameter */
+  validValues?: any[];
+
+  /** Minimum value (for number types) */
+  min?: number;
+
+  /** Maximum value (for number types) */
+  max?: number;
+};
+
+/**
+ * Move parameter options
+ *
+ * All valid parameter combinations for a specific move, along with
+ * metadata about each parameter field.
+ */
+export type MoveParameterOptions = {
+  /** All valid parameter combinations for this move */
+  validCombinations: Record<string, any>[];
+
+  /** Information about each parameter */
+  parameterInfo: Record<string, ParameterInfo>;
+};
+
+/**
+ * Move validation error
+ *
+ * Detailed information about why a move cannot be executed,
+ * including error code, reason, context, and suggestions.
+ */
+export type MoveValidationError = {
+  /** Move that was attempted */
+  moveId: string;
+
+  /** Error code for programmatic handling */
+  errorCode: string;
+
+  /** Human-readable reason */
+  reason: string;
+
+  /** Additional error context */
+  context?: Record<string, any>;
+
+  /** Suggested actions to make the move valid */
+  suggestions?: string[];
+};

package/src/types/move-params.ts

@@ -0,0 +1,216 @@
+/**
+ * Lorcana Move Parameter Types
+ *
+ * Type-safe move parameters using discriminated unions for better type safety.
+ * Each move has explicit parameter types that leverage TypeScript's type narrowing.
+ */
+
+import type { CardId, PlayerId } from "./branded-types";
+import type { LorcanaCardMeta } from "./game-state";
+
+/**
+ * Play Card Cost Types - Discriminated Union
+ *
+ * Uses discriminated unions for type-safe alternative costs.
+ * TypeScript can narrow types based on the `cost` discriminator.
+ */
+export type PlayCardCost =
+  | {
+      /** Standard ink cost payment */
+      cost: "standard";
+    }
+  | {
+      /** Shift cost - play over another character */
+      cost: "shift";
+      /** Character to shift onto (must share name) */
+      shiftTarget: CardId;
+    }
+  | {
+      /** Sing cost - exert a character to play a song */
+      cost: "sing";
+      /** Character exerting to sing the song */
+      singer: CardId;
+    }
+  | {
+      /** Sing Together cost - exert multiple characters */
+      cost: "singTogether";
+      /** Characters exerting to sing together */
+      singers: CardId[];
+    }
+  | {
+      /** Free play (for effects that play cards) */
+      cost: "free";
+    };
+
+/**
+ * Lorcana Move Parameters
+ *
+ * Exhaustive type definition for all Lorcana moves.
+ * Each move has explicit, well-typed parameters.
+ */
+export type LorcanaMoveParams = {
+  // ===== Setup Moves =====
+  /**
+   * Choose who goes first
+   *
+   * Rule 3.1.1: First player determined randomly
+   */
+  chooseWhoGoesFirstMove: { playerId: PlayerId };
+
+  /**
+   * Alter hand (mulligan)
+   *
+   * Rule 3.1.6: Players may mulligan by putting cards on bottom of deck
+   */
+  alterHand: {
+    playerId: PlayerId;
+    /** Cards to put on bottom of deck (empty array = keep all) */
+    cardsToMulligan: CardId[];
+  };
+
+  /**
+   * Draw cards (utility move for testing/effects)
+   */
+  drawCards: {
+    playerId: PlayerId;
+    count: number;
+  };
+
+  // ===== Resource Moves =====
+  /**
+   * Put a card into the inkwell
+   *
+   * Rule 4.3.3: Once per turn, put an inkable card into inkwell
+   */
+  putACardIntoTheInkwell: {
+    cardId: CardId;
+  };
+
+  // ===== Core Game Moves =====
+  /**
+   * Play a card from hand
+   *
+   * Rule 4.3.4: Pay cost and put card into play (or discard for actions)
+   * Rule 6.3.3: Songs can be sung as alternative cost
+   * Rule 10.18: Shift allows playing over same-named characters
+   */
+  playCard: {
+    cardId: CardId;
+  } & PlayCardCost;
+
+  /**
+   * Quest with a character
+   *
+   * Rule 4.3.5: Exert character to gain lore equal to its Lore value
+   */
+  quest: {
+    cardId: CardId;
+  };
+
+  /**
+   * Challenge with a character
+   *
+   * Rule 4.3.6: Attack another character or location
+   */
+  challenge: {
+    /** Attacking character */
+    attackerId: CardId;
+    /** Defending character or location */
+    defenderId: CardId;
+  };
+
+  /**
+   * Sing a song (legacy - prefer playCard with "sing" cost)
+   *
+   * Rule 6.3.3: Exert a character to play a song for free
+   */
+  sing: {
+    /** Character doing the singing */
+    singerId: CardId;
+    /** Song being sung */
+    songId: CardId;
+  };
+
+  /**
+   * Sing Together (legacy - prefer playCard with "singTogether" cost)
+   *
+   * Rule 10.10: Multiple characters exert to sing a song together
+   */
+  singTogether: {
+    /** Characters singing together */
+    singersIds: CardId[];
+    /** Song being sung */
+    songId: CardId;
+  };
+
+  /**
+   * Move a character to a location
+   *
+   * Rule 6.5: Characters can move to locations
+   */
+  moveCharacterToLocation: {
+    characterId: CardId;
+    locationId: CardId;
+  };
+
+  /**
+   * Activate an ability
+   *
+   * Rule 7: Abilities with costs can be activated
+   */
+  activateAbility: {
+    cardId: CardId;
+    /** Optional ability selection (if card has multiple) */
+    abilityIndex?: number;
+    /** Alternative identification by ability text */
+    abilityText?: string;
+    /** Alternative cost for ability (e.g., sing to activate) */
+    alternativeCost?: PlayCardCost;
+  };
+
+  // ===== Effect Resolution =====
+  /**
+   * Resolve an effect from the bag
+   *
+   * Rule 8.7: Bag system for triggered effects
+   */
+  resolveBag: {
+    bagId: string;
+    /** Parameters for the effect */
+    params: unknown;
+  };
+
+  /**
+   * Resolve an effect
+   */
+  resolveEffect: {
+    effectId: string;
+    /** Parameters for the effect */
+    params: unknown;
+  };
+
+  // ===== Manual Actions (Testing/Debug) =====
+  /**
+   * Manually exert a card (for testing)
+   */
+  manualExert: {
+    cardId: CardId;
+  };
+
+  // ===== Standard Moves =====
+  /**
+   * Pass turn to next player
+   *
+   * Rule 4.1.2: Player completes their turn
+   */
+  passTurn: Record<string, never>;
+
+  /**
+   * Concede the game
+   *
+   * Rule 1.9.1.2: Player can concede at any time
+   */
+  concede: Record<string, never>;
+};
+
+// LorcanaGameState is exported from game-state.ts - import from there

package/src/validators/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Lorcana Move Validators
+ *
+ * Public exports for composable validation functions
+ */
+
+export * from "./move-validators";