@drmxrcy/tcg-lorcana 0.0.0-202602060544

package/src/game-definition/flow/turn-flow.ts

@@ -0,0 +1,216 @@
+import { createPlayerId, type FlowDefinition } from "@drmxrcy/tcg-core";
+import type { LorcanaCardMeta, LorcanaGameState } from "../../types";
+
+/**
+ * Lorcana Turn Flow
+ *
+ * Defines the sequence of game segments and phases:
+ *
+ * Game Segments:
+ * 1. Starting a Game - Choose first player and mulligan
+ * 2. Main Game - Normal gameplay with turns
+ *
+ * Turn Phases (Main Game):
+ * 1. Beginning Phase - Start of turn, ready all cards
+ * 2. Main Phase - Play cards, quest, challenge
+ * 3. End Phase - End of turn cleanup
+ *
+ * The engine automatically handles phase transitions and turn management.
+ */
+export const lorcanaFlow: FlowDefinition<LorcanaGameState, LorcanaCardMeta> = {
+  initialGameSegment: "startingAGame",
+  gameSegments: {
+    /**
+     * Starting a Game Segment
+     *
+     * Rule 3.1: Starting a game
+     * - Choose who goes first (Rule 3.1.1)
+     * - Mulligan phase (Rule 3.1.6)
+     */
+    startingAGame: {
+      order: 0,
+      next: "mainGame",
+      turn: {
+        initialPhase: "chooseFirstPlayer",
+        onBegin: (context) => {
+          // Set currentPlayer to choosingFirstPlayer for priority
+          // During startingAGame, there is no "turn player" yet
+          // but there IS a priority player who can take actions
+          const chooser = context.game.getChoosingFirstPlayer();
+          if (chooser) {
+            context.setCurrentPlayer(String(chooser));
+          }
+        },
+        phases: {
+          /**
+           * Choose First Player Phase
+           *
+           * Rule 3.1.1: First player determined randomly
+           * In practice, decided by players (rock-paper-scissors, dice roll, etc.)
+           *
+           * Manual transition: The move itself will call context.flow.endPhase()
+           */
+          chooseFirstPlayer: {
+            order: 1,
+            next: "mulligan",
+            // Manual transition via move - always return false
+            // The move itself calls context.flow.endPhase()
+            endIf: (context) => context.game.getOTP() !== undefined,
+            onEnd: (context) => {
+              // After OTP is chosen, set currentPlayer to OTP for mulligan phase
+              const otp = context.game.getOTP();
+              if (otp) {
+                context.setCurrentPlayer(String(otp));
+              }
+            },
+          },
+
+          /**
+           * Mulligan Phase
+           *
+           * Rule 3.1.6: Players may mulligan by putting cards
+           * on bottom of deck and redrawing
+           */
+          mulligan: {
+            order: 2,
+            next: undefined, // Transitions to mainGame segment
+            onBegin: (context) => {
+              // Priority starts with OTP for mulligan
+              // Each player will mulligan in turn order
+              const otp = context.game.getOTP();
+              if (otp) {
+                context.setCurrentPlayer(String(otp));
+              }
+            },
+            // Advance when all players have completed mulligan
+            // The move itself will call context.flow.endPhase()
+            // So this always returns false to wait for manual transition
+            endIf: (context) => {
+              if (context.getCurrentPhase() === "mulligan") {
+                return context.game.getPendingMulligan().length === 0;
+              }
+
+              return false;
+            },
+            // When this phase ends, transition to mainGame segment
+            onEnd: (context) => {
+              context.endGameSegment("startingAGame");
+            },
+          },
+        },
+      },
+    },
+
+    /**
+     * Main Game Segment
+     *
+     * Normal gameplay with beginning, main, and end phases.
+     */
+    mainGame: {
+      order: 1,
+      // No next segment - game ends when this segment ends
+      turn: {
+        initialPhase: "beginning",
+        onBegin: (context) => {
+          // Switch to next player at start of each turn
+          // In a 2-player game, alternate between players
+          const currentPlayer = context.getCurrentPlayer();
+          const otp = context.game.getOTP();
+
+          if (currentPlayer && otp) {
+            // Alternate players (assumes 2-player game)
+            // TODO: Support N-player games with proper turn order
+            const playerIds = [String(otp)];
+            // Get the other player (not OTP)
+            // This is a simplification for 2-player games
+            // In production, you'd have a player list to iterate through
+            const otpStr = String(otp);
+
+            // For now, just toggle between two players based on turn number
+            // If turn is odd, OTP plays; if even, other player plays
+            const turnNum = context.getTurnNumber();
+            // This assumes OTP is player_one - needs improvement for robustness
+            context.setCurrentPlayer(
+              turnNum % 2 === 1
+                ? otpStr
+                : otpStr === "player_one"
+                  ? "player_two"
+                  : "player_one",
+            );
+          } else {
+            // First turn - set to OTP
+            if (otp) {
+              context.setCurrentPlayer(String(otp));
+            }
+          }
+        },
+        phases: {
+          /**
+           * Beginning Phase
+           * - Ready all exhausted cards
+           * - Draw a card (if not first turn)
+           * - Automatically advances to Main phase
+           */
+          beginning: {
+            order: 1,
+            next: "main",
+            onBegin: (context) => {
+              // Ready all cards for the current player
+              const currentPlayer = context.getCurrentPlayer();
+              if (!currentPlayer) return;
+
+              // Get all cards owned by current player
+              const playZone = context.zones.getCardsInZone(
+                "play" as any,
+                createPlayerId(currentPlayer),
+              );
+
+              // Ready each card (clear exerted status and summoning sickness)
+              for (const cardId of playZone) {
+                const meta = context.cards.getCardMeta(cardId);
+                if (meta) {
+                  context.cards.updateCardMeta(cardId, {
+                    state: "ready",
+                    isDrying: false, // Clear summoning sickness
+                  });
+                }
+              }
+
+              // TODO: Draw a card (if not first turn)
+              // This requires checking if it's turn 1 and drawing from deck
+            },
+            endIf: () => true, // Auto-advance
+          },
+
+          /**
+           * Main Phase
+           * - Player can take actions (play cards, quest, challenge)
+           * - Player manually ends phase by passing
+           */
+          main: {
+            order: 2,
+            next: "end",
+            onBegin: (_context) => {
+              // No automatic actions at start of main phase
+            },
+            // No endIf - player must manually pass to end phase
+          },
+
+          /**
+           * End Phase
+           * - Cleanup effects
+           * - Automatically advances to next turn (no next phase defined)
+           */
+          end: {
+            order: 3,
+            // No 'next' defined - FlowManager will call transitionToNextTurn()
+            onBegin: (_context) => {
+              // Cleanup logic could go here
+            },
+            endIf: () => true, // Auto-advance to next turn
+          },
+        },
+      },
+    },
+  },
+};

package/src/game-definition/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Lorcana Game Definition
+ *
+ * Public exports for game definition components
+ */
+
+// Main game definition
+export { lorcanaGameDefinition } from "./definition";
+export { lorcanaFlow } from "./flow/turn-flow";
+export { lorcanaMoves } from "./moves";
+export { setupLorcanaGame } from "./setup/game-setup";
+export { trackerConfig } from "./trackers/tracker-config";
+export { checkLoreVictory } from "./win-conditions/lore-victory";
+// Legacy exports (for backward compatibility)
+export * from "./zone-operations";
+export type {
+  LorcanaZoneConfig,
+  LorcanaZoneId,
+  LorcanaZoneVisibility,
+} from "./zones";
+export {
+  getZoneConfig,
+  isFacedownZone,
+  isLorcanaZoneId,
+  isOrderedZone,
+  isPrivateZone,
+  isPublicZone,
+  lorcanaZones as legacyLorcanaZones,
+} from "./zones";
+// Modular components (for testing and advanced use)
+export { lorcanaZones } from "./zones/zone-configs";

package/src/game-definition/moves/abilities/activate-ability.ts

@@ -0,0 +1,51 @@
+import { createMove } from "@drmxrcy/tcg-core";
+import type {
+  LorcanaCardMeta,
+  LorcanaGameState,
+  LorcanaMoveParams,
+} from "../../../types";
+import { and, isMainPhase } from "../../../validators";
+
+/**
+ * Activate Ability
+ *
+ * Rule 7: Abilities with costs can be activated
+ *
+ * Process:
+ * 1. Look up the ability from card definition using context.registry.getCard()
+ * 2. Verify ability requirements are met (via conditions)
+ * 3. Pay the cost (exert, discard, etc.) using operations
+ * 4. Execute the effect
+ *
+ * TODO: Full implementation requires:
+ * - Ability definition system: Need to define abilities with costs and effects in card definitions
+ * - Cost payment system: Extend LorcanaOperations with ability cost payment (exert, discard, ink)
+ * - Effect execution system: Framework for executing ability effects with proper timing
+ * - Targeting system: Allow players to select targets for abilities
+ * - Validation: Ensure ability can be activated (not already used this turn, costs can be paid, etc.)
+ *
+ * Example usage once implemented:
+ * ```
+ * const card = context.registry.getCard(cardId);
+ * const ability = card.abilities?.find(a => a.id === abilityId);
+ * if (ability) {
+ *   ops.payCost(ability.cost);
+ *   executeEffect(ability.effect, ability.targets);
+ * }
+ * ```
+ */
+export const activateAbility = createMove<
+  LorcanaGameState,
+  LorcanaMoveParams,
+  "activateAbility",
+  LorcanaCardMeta
+>({
+  condition: and(isMainPhase()),
+  reducer: (_draft, _context) => {
+    // TODO: Implement ability activation logic
+    // This would require:
+    // 1. Looking up the ability from card definition
+    // 2. Paying the cost
+    // 3. Executing the effect
+  },
+});

package/src/game-definition/moves/core/__tests__/move-parameter-enumeration.test.ts

@@ -0,0 +1,316 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import { createPlayerId } from "@drmxrcy/tcg-core";
+import {
+  LorcanaTestEngine,
+  PLAYER_ONE,
+  PLAYER_TWO,
+} from "../../../../testing/lorcana-test-engine";
+
+describe("Core Move Parameter Enumeration", () => {
+  describe("playCard Parameter Enumeration", () => {
+    let testEngine: LorcanaTestEngine;
+
+    beforeEach(() => {
+      // Start in main phase with cards in hand
+      testEngine = new LorcanaTestEngine(
+        { hand: 3, deck: 10 },
+        { hand: 3, deck: 10 },
+        { skipPreGame: true },
+      );
+    });
+
+    it.todo("should enumerate cards in hand as valid playCard targets", () => {
+      const params = testEngine.enumerateMoveParameters("playCard", PLAYER_ONE);
+
+      expect(params).not.toBeNull();
+      expect(params?.validCombinations).toBeDefined();
+      expect(params?.validCombinations.length).toBeGreaterThan(0);
+    });
+
+    it.todo("should include cardId in parameter info", () => {
+      const params = testEngine.enumerateMoveParameters("playCard", PLAYER_ONE);
+
+      expect(params?.parameterInfo.cardId).toBeDefined();
+      expect(params?.parameterInfo.cardId.type).toBe("cardId");
+      expect(params?.parameterInfo.cardId.validValues).toBeDefined();
+    });
+
+    it("should return empty when no cards in hand", () => {
+      // Remove all cards from hand
+      const hand = testEngine.getZone("hand", PLAYER_ONE);
+      for (const cardId of hand || []) {
+        testEngine.moveCard(cardId, "discard", PLAYER_ONE);
+      }
+
+      const params = testEngine.enumerateMoveParameters("playCard", PLAYER_ONE);
+
+      if (params) {
+        expect(params.validCombinations).toHaveLength(0);
+      }
+    });
+
+    it("should return null when move not available", () => {
+      // Try during opponent's turn or wrong phase
+      const params = testEngine.enumerateMoveParameters(
+        "playCard",
+        PLAYER_TWO, // Not active player
+      );
+
+      // May return null or empty combinations depending on phase/turn rules
+      if (params === null) {
+        expect(params).toBeNull();
+      } else {
+        expect(params.validCombinations).toBeDefined();
+      }
+    });
+  });
+
+  describe("quest Parameter Enumeration", () => {
+    let testEngine: LorcanaTestEngine;
+
+    beforeEach(() => {
+      testEngine = new LorcanaTestEngine(
+        { hand: 0, deck: 10 },
+        { hand: 0, deck: 10 },
+        { skipPreGame: true },
+      );
+    });
+
+    it.todo("should enumerate ready characters as valid quest targets", () => {
+      const params = testEngine.enumerateMoveParameters("quest", PLAYER_ONE);
+
+      expect(params).toBeDefined();
+      expect(params?.parameterInfo.cardId).toBeDefined();
+      expect(params?.parameterInfo.cardId.type).toBe("cardId");
+    });
+
+    it("should exclude exerted characters", () => {
+      // This test would require characters in play
+      // For now, verify the structure
+      const params = testEngine.enumerateMoveParameters("quest", PLAYER_ONE);
+
+      if (params) {
+        expect(params.validCombinations).toBeDefined();
+        expect(Array.isArray(params.validCombinations)).toBe(true);
+      }
+    });
+
+    it("should return empty when no ready characters", () => {
+      const params = testEngine.enumerateMoveParameters("quest", PLAYER_ONE);
+
+      // With no characters in play, should have no valid combinations
+      if (params) {
+        expect(params.validCombinations).toHaveLength(0);
+      }
+    });
+  });
+
+  describe("challenge Parameter Enumeration", () => {
+    let testEngine: LorcanaTestEngine;
+
+    beforeEach(() => {
+      testEngine = new LorcanaTestEngine(
+        { hand: 0, deck: 10 },
+        { hand: 0, deck: 10 },
+        { skipPreGame: true },
+      );
+    });
+
+    it("should enumerate attacker-defender pairs", () => {
+      const params = testEngine.enumerateMoveParameters(
+        "challenge",
+        PLAYER_ONE,
+      );
+
+      expect(params).toBeDefined();
+      if (params) {
+        expect(params.parameterInfo.attackerId).toBeDefined();
+        expect(params.parameterInfo.defenderId).toBeDefined();
+      }
+    });
+
+    it("should have attackerId and defenderId in parameter info", () => {
+      const params = testEngine.enumerateMoveParameters(
+        "challenge",
+        PLAYER_ONE,
+      );
+
+      if (params) {
+        expect(params.parameterInfo.attackerId.type).toBe("cardId");
+        expect(params.parameterInfo.defenderId.type).toBe("cardId");
+      }
+    });
+
+    it("should return empty when no valid attackers or defenders", () => {
+      const params = testEngine.enumerateMoveParameters(
+        "challenge",
+        PLAYER_ONE,
+      );
+
+      // With no characters in play, should have no valid combinations
+      if (params) {
+        expect(params.validCombinations).toHaveLength(0);
+      }
+    });
+  });
+
+  describe("alterHand Parameter Enumeration", () => {
+    let testEngine: LorcanaTestEngine;
+
+    beforeEach(() => {
+      testEngine = new LorcanaTestEngine(
+        { hand: 7, deck: 10 },
+        { hand: 7, deck: 10 },
+        { skipPreGame: false },
+      );
+
+      // Execute choose first player to get to mulligan phase
+      const choosingPlayer = testEngine.getCtx().choosingFirstPlayer;
+      testEngine.changeActivePlayer(choosingPlayer || PLAYER_ONE);
+      testEngine.chooseWhoGoesFirst(PLAYER_ONE);
+    });
+
+    it.todo("should enumerate cards in hand as mulligan options", () => {
+      const params = testEngine.enumerateMoveParameters(
+        "alterHand",
+        PLAYER_ONE,
+      );
+
+      expect(params).not.toBeNull();
+      if (params) {
+        expect(params.parameterInfo.cardsToMulligan).toBeDefined();
+      }
+    });
+
+    it("should allow mulliganing 0 cards (keep all)", () => {
+      const params = testEngine.enumerateMoveParameters(
+        "alterHand",
+        PLAYER_ONE,
+      );
+
+      if (params) {
+        // Should include option to mulligan no cards
+        const keepAllOption = params.validCombinations.find(
+          (c: any) =>
+            Array.isArray(c.cardsToMulligan) && c.cardsToMulligan.length === 0,
+        );
+        expect(keepAllOption).toBeDefined();
+      }
+    });
+
+    it("should allow mulliganing all cards", () => {
+      const params = testEngine.enumerateMoveParameters(
+        "alterHand",
+        PLAYER_ONE,
+      );
+
+      if (params) {
+        const hand = testEngine.getZone("hand", PLAYER_ONE);
+        const handSize = hand?.length || 0;
+
+        // Should include option to mulligan all cards
+        const mulliganAllOption = params.validCombinations.find(
+          (c: any) =>
+            Array.isArray(c.cardsToMulligan) &&
+            c.cardsToMulligan.length === handSize,
+        );
+        expect(mulliganAllOption).toBeDefined();
+      }
+    });
+  });
+
+  describe("putACardIntoTheInkwell Parameter Enumeration", () => {
+    let testEngine: LorcanaTestEngine;
+
+    beforeEach(() => {
+      testEngine = new LorcanaTestEngine(
+        { hand: 5, deck: 10 },
+        { hand: 5, deck: 10 },
+        { skipPreGame: true },
+      );
+    });
+
+    it("should enumerate inkable cards in hand", () => {
+      const params = testEngine.enumerateMoveParameters(
+        "putACardIntoTheInkwell",
+        PLAYER_ONE,
+      );
+
+      expect(params).toBeDefined();
+      if (params) {
+        expect(params.parameterInfo.cardId).toBeDefined();
+        expect(params.parameterInfo.cardId.type).toBe("cardId");
+      }
+    });
+
+    it("should only include cards with inkable property", () => {
+      const params = testEngine.enumerateMoveParameters(
+        "putACardIntoTheInkwell",
+        PLAYER_ONE,
+      );
+
+      // All returned cards should be inkable (this would be validated by move condition)
+      if (params) {
+        expect(Array.isArray(params.validCombinations)).toBe(true);
+      }
+    });
+
+    it("should return null if already inked this turn", () => {
+      // Execute ink move once using the public helper
+      const hand = testEngine.getZone("hand", PLAYER_ONE);
+      if (hand && hand.length > 0) {
+        testEngine.putCardInInkwell(hand[0]);
+      }
+
+      // Try to enumerate again - should return null (move not available)
+      const params = testEngine.enumerateMoveParameters(
+        "putACardIntoTheInkwell",
+        PLAYER_ONE,
+      );
+
+      // Move should no longer be available after using once per turn
+      expect(params).toBeNull();
+    });
+  });
+
+  describe("Cross-Move Integration", () => {
+    let testEngine: LorcanaTestEngine;
+
+    beforeEach(() => {
+      testEngine = new LorcanaTestEngine(
+        { hand: 5, deck: 10 },
+        { hand: 5, deck: 10 },
+        { skipPreGame: true },
+      );
+    });
+
+    it("should enumerate parameters for multiple moves simultaneously", () => {
+      const playCardParams = testEngine.enumerateMoveParameters(
+        "playCard",
+        PLAYER_ONE,
+      );
+      const inkwellParams = testEngine.enumerateMoveParameters(
+        "putACardIntoTheInkwell",
+        PLAYER_ONE,
+      );
+
+      // Both should be available during main phase
+      expect(playCardParams).toBeDefined();
+      expect(inkwellParams).toBeDefined();
+    });
+
+    it("should return consistent results across multiple calls", () => {
+      const params1 = testEngine.enumerateMoveParameters(
+        "playCard",
+        PLAYER_ONE,
+      );
+      const params2 = testEngine.enumerateMoveParameters(
+        "playCard",
+        PLAYER_ONE,
+      );
+
+      // Should be identical
+      expect(params1).toEqual(params2);
+    });
+  });
+});