@drmxrcy/tcg-core 0.0.0-202602060542

package/src/__tests__/riftbound-engine-definition.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "bun:test";
+import { createTestEngine } from "../testing/test-engine-builder";
+import { createTestPlayers } from "../testing/test-player-builder";
+import { createMockRiftboundGame } from "./createMockRiftboundGame";
+
+/**
+ * Riftbound Card Game - Engine Feature Tests
+ *
+ * Refactored to showcase:
+ * ✅ High-level zone utilities (createDeck, bulkMove, drawCards)
+ * ✅ Tracker system (hasDrawn)
+ * ✅ Standard moves (pass, concede)
+ * ✅ Flow context in phase hooks
+ * ✅ Massive simplification (10 fields → 4 fields)
+ */
+describe("Riftbound Game - Refactored Engine Features", () => {
+  it("should initialize game with ONLY game-specific state", () => {
+    const gameDefinition = createMockRiftboundGame();
+    const players = createTestPlayers(2);
+    const engine = createTestEngine(gameDefinition, players);
+
+    const state = engine.getState();
+
+    // ✅ NEW: Only game-specific data
+    expect(state.victoryPoints).toBeDefined();
+    expect(state.battlefieldControl).toBeDefined();
+    expect(state.runePools).toBeDefined();
+    expect(state.conqueredThisTurn).toBeDefined();
+
+    // ✅ REMOVED: No manual tracking
+    // @ts-expect-error
+    expect(state.phase).toBeUndefined();
+    // @ts-expect-error
+    expect(state.setupStep).toBeUndefined();
+    // @ts-expect-error
+    expect(state.turn).toBeUndefined();
+    // @ts-expect-error
+    expect(state.activePlayer).toBeUndefined();
+    // @ts-expect-error
+    expect(state.hasDrawnThisTurn).toBeUndefined();
+  });
+
+  it("should have proper zone configuration", () => {
+    const gameDefinition = createMockRiftboundGame();
+    const zones = gameDefinition.zones;
+
+    // Verify Riftbound zones
+    expect(zones?.mainDeck).toBeDefined();
+    expect(zones?.hand).toBeDefined();
+    expect(zones?.runeDeck).toBeDefined();
+    expect(zones?.runePool).toBeDefined();
+    expect(zones?.legendZone).toBeDefined();
+    expect(zones?.championZone).toBeDefined();
+    expect(zones?.battlefield).toBeDefined();
+    expect(zones?.battlefieldRow).toBeDefined();
+    expect(zones?.gearArea).toBeDefined();
+    expect(zones?.discard).toBeDefined();
+
+    expect(zones?.mainDeck?.maxSize).toBe(40);
+    expect(zones?.runeDeck?.maxSize).toBe(12);
+    expect(zones?.legendZone?.maxSize).toBe(1);
+    expect(zones?.championZone?.maxSize).toBe(1);
+    expect(zones?.battlefieldRow?.maxSize).toBe(3);
+  });
+
+  it("should use high-level zone utilities", () => {
+    // ✅ NEW: zones.createDeck() for dual deck system
+    // ✅ NEW: zones.bulkMove() for rune channeling
+    // ✅ NEW: zones.drawCards() for card drawing
+
+    const gameDefinition = createMockRiftboundGame();
+    expect(gameDefinition.moves.initializeDecks).toBeDefined();
+    expect(gameDefinition.moves.channelRunes).toBeDefined();
+    expect(gameDefinition.moves.drawCard).toBeDefined();
+    expect(gameDefinition.moves.drawInitialHand).toBeDefined();
+  });
+
+  it("should configure tracker system", () => {
+    const gameDefinition = createMockRiftboundGame();
+
+    expect(gameDefinition.trackers).toBeDefined();
+    expect(gameDefinition.trackers?.perTurn).toContain("hasDrawn");
+    expect(gameDefinition.trackers?.perPlayer).toBe(true);
+  });
+
+  it("should use tracker system for draw limitation", () => {
+    const gameDefinition = createMockRiftboundGame();
+
+    const drawCard = gameDefinition.moves.drawCard;
+    expect(drawCard.condition).toBeDefined();
+
+    // Uses context.trackers.check("hasDrawn")
+  });
+
+  it("should use flow context in phase hooks", () => {
+    const gameDefinition = createMockRiftboundGame();
+    const flow = gameDefinition.flow;
+
+    // ending phase uses context.getCurrentPlayer()
+    expect(flow).toBeDefined();
+    if (!(flow && "turn" in flow)) {
+      throw new Error("Expected simplified flow definition with turn property");
+    }
+    expect(flow.turn.phases?.ending).toBeDefined();
+  });
+
+  it("should use standard moves", () => {
+    const gameDefinition = createMockRiftboundGame();
+
+    expect(gameDefinition.moves.pass).toBeDefined();
+    expect(gameDefinition.moves.concede).toBeDefined();
+  });
+
+  it("should demonstrate boilerplate reduction", () => {
+    // State fields: 10 → 4 (-60%)
+    // 593 lines → 440 lines (-26%)
+
+    const gameDefinition = createMockRiftboundGame();
+    const players = createTestPlayers(2);
+    const state = gameDefinition.setup(players);
+
+    expect(Object.keys(state).length).toBe(4);
+  });
+});

package/src/actions/action-definition.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it } from "bun:test";
+import { createPlayerId } from "../types";
+import type {
+  ActionDefinition,
+  ActionInstance,
+  ActionMetadata,
+  ActionTiming,
+} from "./action-definition";
+
+describe("Action Definition Types", () => {
+  describe("ActionTiming", () => {
+    it("should define timing constraints with segments", () => {
+      const timing: ActionTiming = {
+        segments: ["gameplay"],
+        phases: ["mainPhase"],
+      };
+
+      expect(timing.segments).toEqual(["gameplay"]);
+      expect(timing.phases).toEqual(["mainPhase"]);
+    });
+
+    it("should support custom timing predicates", () => {
+      type GameState = { turnCount: number };
+      const timing: ActionTiming<GameState> = {
+        custom: (state) => state.turnCount > 5,
+      };
+
+      expect(timing.custom?.({ turnCount: 6 })).toBe(true);
+      expect(timing.custom?.({ turnCount: 3 })).toBe(false);
+    });
+
+    it("should support multiple phases and steps", () => {
+      const timing: ActionTiming = {
+        segments: ["gameplay"],
+        phases: ["mainPhase", "combatPhase"],
+        steps: ["attackStep", "blockStep"],
+      };
+
+      expect(timing.phases).toHaveLength(2);
+      expect(timing.steps).toHaveLength(2);
+    });
+  });
+
+  describe("ActionMetadata", () => {
+    it("should define metadata for categorization", () => {
+      const metadata: ActionMetadata = {
+        category: "card-play",
+        subcategory: "creature",
+        tags: ["costs-resources", "requires-target"],
+        priorityHint: 10,
+      };
+
+      expect(metadata.category).toBe("card-play");
+      expect(metadata.tags).toContain("costs-resources");
+      expect(metadata.priorityHint).toBe(10);
+    });
+
+    it("should support hidden actions", () => {
+      const metadata: ActionMetadata = {
+        hidden: true,
+        category: "internal",
+      };
+
+      expect(metadata.hidden).toBe(true);
+    });
+  });
+
+  describe("ActionDefinition", () => {
+    it("should define minimal action with just id and name", () => {
+      const action: ActionDefinition = {
+        id: "pass",
+        name: "Pass Priority",
+      };
+
+      expect(action.id).toBe("pass");
+      expect(action.name).toBe("Pass Priority");
+    });
+
+    it("should define action with timing constraints", () => {
+      const action: ActionDefinition = {
+        id: "play-creature",
+        name: "Play Creature",
+        description: "Play a creature card from your hand",
+        timing: {
+          segments: ["gameplay"],
+          phases: ["mainPhase"],
+        },
+      };
+
+      expect(action.timing?.segments).toEqual(["gameplay"]);
+      expect(action.timing?.phases).toEqual(["mainPhase"]);
+    });
+
+    it("should define action with target requirements", () => {
+      const action: ActionDefinition = {
+        id: "lightning-bolt",
+        name: "Lightning Bolt",
+        targets: [
+          {
+            filter: { type: "creature" },
+            count: 1,
+          },
+        ],
+      };
+
+      expect(action.targets).toHaveLength(1);
+      expect(action.targets?.[0].count).toBe(1);
+    });
+
+    it("should define action with metadata", () => {
+      const action: ActionDefinition = {
+        id: "attack",
+        name: "Attack",
+        metadata: {
+          category: "combat",
+          tags: ["combat-action"],
+          priorityHint: 8,
+        },
+      };
+
+      expect(action.metadata?.category).toBe("combat");
+      expect(action.metadata?.priorityHint).toBe(8);
+    });
+
+    it("should support game-specific state types", () => {
+      type LorcanaState = { turnPhase: string; inkPool: number };
+
+      const action: ActionDefinition<LorcanaState> = {
+        id: "quest",
+        name: "Quest with Character",
+        timing: {
+          custom: (state) => state.turnPhase === "main" && state.inkPool >= 0,
+        },
+      };
+
+      expect(action.timing?.custom?.({ turnPhase: "main", inkPool: 3 })).toBe(
+        true,
+      );
+      expect(action.timing?.custom?.({ turnPhase: "draw", inkPool: 3 })).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("ActionInstance", () => {
+    it("should create action instance without targets", () => {
+      const player1 = createPlayerId("player1");
+      const instance: ActionInstance = {
+        actionId: "pass",
+        playerId: player1,
+      };
+
+      expect(instance.actionId).toBe("pass");
+      expect(instance.playerId).toBe(player1);
+    });
+
+    it("should create action instance with targets", () => {
+      const player1 = createPlayerId("player1");
+      const instance: ActionInstance = {
+        actionId: "lightning-bolt",
+        playerId: player1,
+        targets: [["card1"]],
+      };
+
+      expect(instance.targets).toHaveLength(1);
+      expect(instance.targets?.[0]).toEqual(["card1"]);
+    });
+
+    it("should create action instance with custom parameters", () => {
+      const player1 = createPlayerId("player1");
+      const instance: ActionInstance = {
+        actionId: "choose-option",
+        playerId: player1,
+        params: {
+          optionIndex: 2,
+          cardId: "card1",
+        },
+        timestamp: Date.now(),
+      };
+
+      expect(instance.params?.optionIndex).toBe(2);
+      expect(instance.timestamp).toBeDefined();
+    });
+
+    it("should support multi-target actions", () => {
+      const player1 = createPlayerId("player1");
+      const instance: ActionInstance = {
+        actionId: "distribute-damage",
+        playerId: player1,
+        targets: [
+          ["creature1", "creature2"], // First target group
+          ["player1"], // Second target group
+        ],
+      };
+
+      expect(instance.targets).toHaveLength(2);
+      expect(instance.targets?.[0]).toHaveLength(2);
+      expect(instance.targets?.[1]).toHaveLength(1);
+    });
+  });
+});

package/src/actions/action-definition.ts

@@ -0,0 +1,122 @@
+import type { TargetDefinition } from "../targeting/target-definition";
+import type { PlayerId } from "../types";
+
+/**
+ * Action Timing Constraint
+ * Specifies when an action can be performed in terms of game flow.
+ *
+ * This is a thin layer over core-engine's phase/segment/step system,
+ * providing a way to validate timing without duplicating core-engine logic.
+ */
+export type ActionTiming<TGameState = unknown> = {
+  /** Segments where this action is allowed (e.g., "setup", "gameplay") */
+  segments?: string[];
+
+  /** Phases where this action is allowed (e.g., "mainPhase", "combatPhase") */
+  phases?: string[];
+
+  /** Steps where this action is allowed (e.g., "drawStep", "playStep") */
+  steps?: string[];
+
+  /** Custom timing predicate for complex game-specific timing rules */
+  custom?: (state: TGameState) => boolean;
+};
+
+/**
+ * Action Metadata
+ * Provides categorization and UI/logging information for actions.
+ * Games can define their own category taxonomies.
+ */
+export type ActionMetadata = {
+  /** Category for UI grouping (game-defined, e.g., "card-play", "combat", "special") */
+  category?: string;
+
+  /** Subcategory for finer-grained grouping */
+  subcategory?: string;
+
+  /** Tags for flexible categorization (e.g., ["instant-speed", "costs-resources"]) */
+  tags?: string[];
+
+  /** Priority hint for AI/automation (higher = more important) */
+  priorityHint?: number;
+
+  /** Whether this action is hidden from normal UI (for automatic/internal actions) */
+  hidden?: boolean;
+};
+
+/**
+ * Action Definition
+ *
+ * A minimal, game-agnostic definition of a player action.
+ * This complements core-engine's EnumerableMove by providing:
+ * - Timing validation (segments/phases/steps)
+ * - Metadata for UI/logging/categorization
+ * - Target specifications using @drmxrcy/tcg-core's targeting system
+ *
+ * The actual execution logic, game-specific constraints, and cost validation
+ * are handled by core-engine's EnumerableMove.getConstraints() and execute().
+ */
+export type ActionDefinition<TGameState = unknown> = {
+  /** Unique identifier for this action */
+  id: string;
+
+  /** Human-readable name for UI display */
+  name: string;
+
+  /** Optional description for tooltips/help */
+  description?: string;
+
+  /** When this action can be performed */
+  timing?: ActionTiming<TGameState>;
+
+  /** Target requirements using @drmxrcy/tcg-core's targeting system */
+  targets?: TargetDefinition[];
+
+  /** Metadata for categorization and UI */
+  metadata?: ActionMetadata;
+};
+
+/**
+ * Action Instance
+ *
+ * Represents a specific action being performed by a player.
+ * This is the bridge between @drmxrcy/tcg-core's action definitions and
+ * core-engine's move execution system.
+ */
+export type ActionInstance = {
+  /** The action being performed */
+  actionId: string;
+
+  /** Player performing the action */
+  playerId: PlayerId;
+
+  /** Selected targets (array of arrays for multi-target actions) */
+  targets?: string[][];
+
+  /** Additional action-specific parameters */
+  params?: Record<string, unknown>;
+
+  /** Timestamp when action was initiated */
+  timestamp?: number;
+};
+
+/**
+ * Action Validation Result
+ *
+ * Result of validating whether an action can be performed.
+ * Focused on timing and target validation - cost validation
+ * is handled by core-engine's constraint system.
+ */
+export type ActionValidationResult = {
+  /** Whether the action is valid */
+  valid: boolean;
+
+  /** Human-readable error message if invalid */
+  error?: string;
+
+  /** Specific reason code for programmatic handling */
+  reason?: "timing" | "targets" | "precondition";
+
+  /** Invalid target indices (if reason is "targets") */
+  invalidTargets?: number[];
+};