@drmxrcy/tcg-core 0.0.0-202602060542

package/src/operations/game-operations.test.ts

@@ -0,0 +1,280 @@
+import { describe, expect, it } from "bun:test";
+import { createPlayerId } from "../types";
+import type { InternalState } from "../types/state";
+import { createGameOperations } from "./operations-impl";
+
+// Helper to create PlayerId for tests
+const playerId = createPlayerId;
+
+describe("GameOperations", () => {
+  const createTestState = (): InternalState => ({
+    zones: {},
+    cards: {},
+    cardMetas: {},
+    otp: undefined,
+    pendingMulligan: undefined,
+  });
+
+  describe("OTP Operations", () => {
+    it("should set OTP player", () => {
+      const state = createTestState();
+      const ops = createGameOperations(state);
+
+      ops.setOTP(playerId("player-1"));
+
+      expect(state.otp).toBe(playerId("player-1"));
+    });
+
+    it("should get OTP player", () => {
+      const state = createTestState();
+      state.otp = playerId("player-2");
+      const ops = createGameOperations(state);
+
+      const otp = ops.getOTP();
+
+      expect(otp).toBe(playerId("player-2"));
+    });
+
+    it("should return undefined when OTP not set", () => {
+      const state = createTestState();
+      const ops = createGameOperations(state);
+
+      const otp = ops.getOTP();
+
+      expect(otp).toBeUndefined();
+    });
+
+    it("should overwrite existing OTP", () => {
+      const state = createTestState();
+      state.otp = playerId("player-1");
+      const ops = createGameOperations(state);
+
+      ops.setOTP(playerId("player-2"));
+
+      expect(state.otp).toBe(playerId("player-2"));
+    });
+  });
+
+  describe("Pending Mulligan Operations", () => {
+    it("should set pending mulligan list", () => {
+      const state = createTestState();
+      const ops = createGameOperations(state);
+
+      ops.setPendingMulligan([playerId("player-1"), playerId("player-2")]);
+
+      expect(state.pendingMulligan).toEqual([
+        playerId("player-1"),
+        playerId("player-2"),
+      ]);
+    });
+
+    it("should get pending mulligan list", () => {
+      const state = createTestState();
+      state.pendingMulligan = [playerId("player-1"), playerId("player-2")];
+      const ops = createGameOperations(state);
+
+      const pending = ops.getPendingMulligan();
+
+      expect(pending).toEqual([playerId("player-1"), playerId("player-2")]);
+    });
+
+    it("should return copy of pending mulligan list to prevent mutation", () => {
+      const state = createTestState();
+      state.pendingMulligan = [playerId("player-1")];
+      const ops = createGameOperations(state);
+
+      const pending = ops.getPendingMulligan();
+      pending.push(playerId("player-2"));
+
+      expect(state.pendingMulligan).toEqual([playerId("player-1")]);
+    });
+
+    it("should return empty array when pending mulligan not set", () => {
+      const state = createTestState();
+      const ops = createGameOperations(state);
+
+      const pending = ops.getPendingMulligan();
+
+      expect(pending).toEqual([]);
+    });
+
+    it("should add player to pending mulligan list", () => {
+      const state = createTestState();
+      state.pendingMulligan = [playerId("player-1")];
+      const ops = createGameOperations(state);
+
+      ops.addPendingMulligan(playerId("player-2"));
+
+      expect(state.pendingMulligan).toEqual([
+        playerId("player-1"),
+        playerId("player-2"),
+      ]);
+    });
+
+    it("should not add duplicate player to pending mulligan list", () => {
+      const state = createTestState();
+      state.pendingMulligan = [playerId("player-1")];
+      const ops = createGameOperations(state);
+
+      ops.addPendingMulligan(playerId("player-1"));
+
+      expect(state.pendingMulligan).toEqual([playerId("player-1")]);
+    });
+
+    it("should initialize list when adding to undefined pending mulligan", () => {
+      const state = createTestState();
+      const ops = createGameOperations(state);
+
+      ops.addPendingMulligan(playerId("player-1"));
+
+      expect(state.pendingMulligan).toEqual([playerId("player-1")]);
+    });
+
+    it("should remove player from pending mulligan list", () => {
+      const state = createTestState();
+      state.pendingMulligan = [
+        playerId("player-1"),
+        playerId("player-2"),
+        playerId("player-3"),
+      ];
+      const ops = createGameOperations(state);
+
+      ops.removePendingMulligan(playerId("player-2"));
+
+      expect(state.pendingMulligan).toEqual([
+        playerId("player-1"),
+        playerId("player-3"),
+      ]);
+    });
+
+    it("should handle removing player not in list", () => {
+      const state = createTestState();
+      state.pendingMulligan = [playerId("player-1")];
+      const ops = createGameOperations(state);
+
+      ops.removePendingMulligan(playerId("player-2"));
+
+      expect(state.pendingMulligan).toEqual([playerId("player-1")]);
+    });
+
+    it("should handle removing from empty list", () => {
+      const state = createTestState();
+      state.pendingMulligan = [];
+      const ops = createGameOperations(state);
+
+      ops.removePendingMulligan(playerId("player-1"));
+
+      expect(state.pendingMulligan).toEqual([]);
+    });
+
+    it("should handle removing from undefined list", () => {
+      const state = createTestState();
+      const ops = createGameOperations(state);
+
+      ops.removePendingMulligan(playerId("player-1"));
+
+      expect(state.pendingMulligan).toBeUndefined();
+    });
+
+    it("should replace entire list with setPendingMulligan", () => {
+      const state = createTestState();
+      state.pendingMulligan = [playerId("player-1"), playerId("player-2")];
+      const ops = createGameOperations(state);
+
+      ops.setPendingMulligan([playerId("player-3"), playerId("player-4")]);
+
+      expect(state.pendingMulligan).toEqual([
+        playerId("player-3"),
+        playerId("player-4"),
+      ]);
+    });
+  });
+
+  describe("Choosing First Player Operations", () => {
+    it("should set choosing first player", () => {
+      const state = createTestState();
+      const ops = createGameOperations(state);
+
+      ops.setChoosingFirstPlayer(playerId("player-1"));
+
+      expect(state.choosingFirstPlayer).toBe(playerId("player-1"));
+    });
+
+    it("should get choosing first player", () => {
+      const state = createTestState();
+      state.choosingFirstPlayer = playerId("player-2");
+      const ops = createGameOperations(state);
+
+      const chooser = ops.getChoosingFirstPlayer();
+
+      expect(chooser).toBe(playerId("player-2"));
+    });
+
+    it("should return undefined when choosing first player not set", () => {
+      const state = createTestState();
+      const ops = createGameOperations(state);
+
+      const chooser = ops.getChoosingFirstPlayer();
+
+      expect(chooser).toBeUndefined();
+    });
+
+    it("should overwrite existing choosing first player", () => {
+      const state = createTestState();
+      state.choosingFirstPlayer = playerId("player-1");
+      const ops = createGameOperations(state);
+
+      ops.setChoosingFirstPlayer(playerId("player-2"));
+
+      expect(state.choosingFirstPlayer).toBe(playerId("player-2"));
+    });
+  });
+
+  describe("Integration", () => {
+    it("should handle typical game setup flow", () => {
+      const state = createTestState();
+      const ops = createGameOperations(state);
+
+      // Choose first player
+      ops.setOTP(playerId("player-1"));
+
+      // Set all players pending mulligan
+      ops.setPendingMulligan([playerId("player-1"), playerId("player-2")]);
+
+      // Verify state
+      expect(ops.getOTP()).toBe(playerId("player-1"));
+      expect(ops.getPendingMulligan()).toEqual([
+        playerId("player-1"),
+        playerId("player-2"),
+      ]);
+
+      // Player 1 decides to keep
+      ops.removePendingMulligan(playerId("player-1"));
+      expect(ops.getPendingMulligan()).toEqual([playerId("player-2")]);
+
+      // Player 2 decides to keep
+      ops.removePendingMulligan(playerId("player-2"));
+      expect(ops.getPendingMulligan()).toEqual([]);
+    });
+
+    it("should handle complete first player selection flow", () => {
+      const state = createTestState();
+      const ops = createGameOperations(state);
+
+      // 1. Randomly pick who gets to choose (simulated)
+      ops.setChoosingFirstPlayer(playerId("player-1"));
+      expect(ops.getChoosingFirstPlayer()).toBe(playerId("player-1"));
+
+      // 2. That player chooses who goes first
+      ops.setOTP(playerId("player-2"));
+      expect(ops.getOTP()).toBe(playerId("player-2"));
+
+      // 3. All players mulligan
+      ops.setPendingMulligan([playerId("player-1"), playerId("player-2")]);
+      expect(ops.getPendingMulligan()).toEqual([
+        playerId("player-1"),
+        playerId("player-2"),
+      ]);
+    });
+  });
+});

package/src/operations/game-operations.ts

@@ -0,0 +1,140 @@
+import type { PlayerId } from "../types";
+
+/**
+ * Game Operations
+ *
+ * Provides controlled access to game-level internal state:
+ * - OTP (On The Play): The player who goes first
+ * - Pending Mulligan: Players who need to decide on mulligan
+ *
+ * These are universal TCG concepts that apply across all card games.
+ */
+export type GameOperations = {
+  /**
+   * Set the player who is "on the play" (goes first)
+   *
+   * This is a universal TCG concept. The player marked as OTP
+   * typically goes first and may have different rules apply
+   * (e.g., no card draw on first turn in some games).
+   *
+   * @param playerId - Player to mark as on the play
+   *
+   * @example
+   * ```typescript
+   * // In a choose first player move:
+   * context.game.setOTP('player-1');
+   * ```
+   */
+  setOTP(playerId: PlayerId): void;
+
+  /**
+   * Get the player who is on the play
+   *
+   * @returns Player ID of OTP, or undefined if not yet set
+   *
+   * @example
+   * ```typescript
+   * const firstPlayer = context.game.getOTP();
+   * if (firstPlayer === context.playerId) {
+   *   // Current player goes first
+   * }
+   * ```
+   */
+  getOTP(): PlayerId | undefined;
+
+  /**
+   * Set the player who gets to choose the first player
+   *
+   * In games like Lorcana, one player is randomly designated to choose
+   * who will be the starting player (OTP). This is distinct from OTP itself.
+   *
+   * @param playerId - Player designated to make the choice
+   *
+   * @example
+   * ```typescript
+   * // In game setup, randomly choose who gets to pick:
+   * const chooser = context.rng.choice(['player-1', 'player-2']);
+   * context.game.setChoosingFirstPlayer(chooser);
+   * ```
+   */
+  setChoosingFirstPlayer(playerId: PlayerId): void;
+
+  /**
+   * Get the player designated to choose the first player
+   *
+   * @returns Player ID of chooser, or undefined if not yet set
+   *
+   * @example
+   * ```typescript
+   * // In chooseFirstPlayer move condition:
+   * const chooser = context.game.getChoosingFirstPlayer();
+   * if (context.playerId !== chooser) {
+   *   return { reason: "Only the designated player can choose", errorCode: "NOT_CHOOSER" };
+   * }
+   * ```
+   */
+  getChoosingFirstPlayer(): PlayerId | undefined;
+
+  /**
+   * Set the list of players who need to decide on mulligan
+   *
+   * Replaces the entire pending mulligan list.
+   * Typically called during game setup to initialize the list.
+   *
+   * @param playerIds - Array of player IDs pending mulligan
+   *
+   * @example
+   * ```typescript
+   * // After choosing first player, all players can mulligan:
+   * context.game.setPendingMulligan(['player-1', 'player-2']);
+   * ```
+   */
+  setPendingMulligan(playerIds: PlayerId[]): void;
+
+  /**
+   * Get the list of players pending mulligan
+   *
+   * @returns Array of player IDs (copy to prevent mutation)
+   *
+   * @example
+   * ```typescript
+   * const pending = context.game.getPendingMulligan();
+   * if (pending.includes(context.playerId)) {
+   *   // Current player can still mulligan
+   * }
+   * ```
+   */
+  getPendingMulligan(): PlayerId[];
+
+  /**
+   * Add a player to the pending mulligan list
+   *
+   * Use this to mark a player as needing to decide on mulligan.
+   * Has no effect if player is already in the list.
+   *
+   * @param playerId - Player to add to mulligan list
+   *
+   * @example
+   * ```typescript
+   * // Allow a player to mulligan again (game-specific rule):
+   * context.game.addPendingMulligan('player-1');
+   * ```
+   */
+  addPendingMulligan(playerId: PlayerId): void;
+
+  /**
+   * Remove a player from the pending mulligan list
+   *
+   * Use this when a player completes their mulligan decision.
+   * Has no effect if player is not in the list.
+   *
+   * @param playerId - Player to remove from mulligan list
+   *
+   * @example
+   * ```typescript
+   * // After player decides to keep or mulligan:
+   * context.game.removePendingMulligan(context.playerId);
+   * ```
+   */
+  removePendingMulligan(playerId: PlayerId): void;
+};

package/src/operations/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Operations API
+ *
+ * Provides controlled access to internal game state through specialized operations interfaces:
+ * - ZoneOperations: Manage card zones and card movement
+ * - CardOperations: Manage card metadata and state
+ * - GameOperations: Manage game-level state (OTP, mulligan)
+ * - CounterOperations: Manage counters and flags on cards
+ * - CardRegistry: Access static card definitions
+ */
+
+export type { CardOperations } from "./card-operations";
+export type { CardRegistry } from "./card-registry";
+export { createCardRegistry } from "./card-registry-impl";
+export type { CounterOperations } from "./counter-operations";
+export type { GameOperations } from "./game-operations";
+
+export {
+  createCardOperations,
+  createCounterOperations,
+  createGameOperations,
+  createZoneOperations,
+} from "./operations-impl";
+export type { ZoneOperations } from "./zone-operations";