@drmxrcy/tcg-core 0.0.0-202602060542

package/src/actions/action-timing.ts

@@ -0,0 +1,257 @@
+import type { CardDefinition } from "../cards/card-definition";
+import type { CardInstance } from "../cards/card-instance";
+import type { CardRegistry } from "../operations/card-registry";
+import {
+  type TargetContext,
+  validateTargetSelection,
+} from "../targeting/target-validation";
+import type {
+  ActionDefinition,
+  ActionInstance,
+  ActionValidationResult,
+} from "./action-definition";
+
+/**
+ * Game State Context for Timing Validation
+ *
+ * This is the minimal state information needed to validate action timing.
+ * Games using core-engine will have their full state here, but we only
+ * require the flow control properties.
+ */
+export type TimingContext = {
+  /** Current segment in the game flow */
+  currentSegment?: string | null;
+
+  /** Current phase within the segment */
+  currentPhase?: string | null;
+
+  /** Current step within the phase */
+  currentStep?: string | null;
+};
+
+/**
+ * Validate Action Timing
+ *
+ * Checks if an action can be performed based on current game flow state.
+ * This validates segments/phases/steps and custom timing predicates.
+ *
+ * Does NOT validate:
+ * - Costs (handled by core-engine's getConstraints)
+ * - Game-specific rules (handled by core-engine's getConstraints)
+ * - Complex state conditions (handled by core-engine's getConstraints)
+ *
+ * @param action - The action definition
+ * @param timingContext - Current game flow state (segment/phase/step)
+ * @param gameState - Full game state for custom timing predicates
+ * @returns True if timing is valid
+ */
+export function validateActionTiming<TGameState extends TimingContext>(
+  action: ActionDefinition<TGameState>,
+  timingContext: TimingContext,
+  gameState?: TGameState,
+): boolean {
+  const timing = action.timing;
+
+  // No timing restrictions means action is always valid (timing-wise)
+  if (!timing) {
+    return true;
+  }
+
+  // Check segment restrictions
+  if (timing.segments && timing.segments.length > 0) {
+    if (
+      !(
+        timingContext.currentSegment &&
+        timing.segments.includes(timingContext.currentSegment)
+      )
+    ) {
+      return false;
+    }
+  }
+
+  // Check phase restrictions
+  if (timing.phases && timing.phases.length > 0) {
+    if (
+      !(
+        timingContext.currentPhase &&
+        timing.phases.includes(timingContext.currentPhase)
+      )
+    ) {
+      return false;
+    }
+  }
+
+  // Check step restrictions
+  if (timing.steps && timing.steps.length > 0) {
+    if (
+      !(
+        timingContext.currentStep &&
+        timing.steps.includes(timingContext.currentStep)
+      )
+    ) {
+      return false;
+    }
+  }
+
+  // Check custom timing predicate
+  if (timing.custom && gameState) {
+    return timing.custom(gameState);
+  }
+
+  return true;
+}
+
+/**
+ * Validate Action Instance
+ *
+ * Validates both timing and target selection for an action instance.
+ * This bridges @drmxrcy/tcg-core's validation with core-engine's execution.
+ *
+ * @param instance - The action instance to validate
+ * @param definition - The action definition
+ * @param timingContext - Current game flow state
+ * @param state - Full game state with card information
+ * @param registry - Card definition registry for target validation
+ * @returns Validation result
+ */
+export function validateAction<
+  TCustomState = unknown,
+  TGameState extends TimingContext & {
+    cards: Record<string, CardInstance<TCustomState>>;
+  } = {
+    cards: Record<string, CardInstance<TCustomState>>;
+  } & TimingContext,
+>(
+  instance: ActionInstance,
+  definition: ActionDefinition<TGameState>,
+  timingContext: TimingContext,
+  state: TGameState,
+  registry: CardRegistry<CardDefinition>,
+): ActionValidationResult {
+  // Validate timing
+  const timingValid = validateActionTiming(definition, timingContext, state);
+  if (!timingValid) {
+    return {
+      valid: false,
+      error: "Action cannot be performed at this time",
+      reason: "timing",
+    };
+  }
+
+  // Validate targets if action requires them
+  if (definition.targets && definition.targets.length > 0) {
+    if (!instance.targets || instance.targets.length === 0) {
+      return {
+        valid: false,
+        error: "Action requires targets but none were provided",
+        reason: "targets",
+        invalidTargets: [],
+      };
+    }
+
+    // Validate each target group
+    for (let i = 0; i < definition.targets.length; i++) {
+      const targetDef = definition.targets[i];
+      const selectedTargets = instance.targets[i] || [];
+
+      // Convert target IDs to CardInstances
+      const targetCards = selectedTargets
+        .map((targetId) => state.cards[targetId])
+        .filter((card) => card !== undefined);
+
+      if (targetCards.length !== selectedTargets.length) {
+        return {
+          valid: false,
+          error: `Some target cards at index ${i} do not exist in game state`,
+          reason: "targets",
+          invalidTargets: [i],
+        };
+      }
+
+      // Create minimal target context for validation
+      // Note: We don't have a source card concept in actions, so we use the player
+      const context: Omit<TargetContext<TCustomState>, "previousTargets"> = {
+        sourceCard: {
+          id: "" as any,
+          owner: instance.playerId,
+          controller: instance.playerId,
+        } as any,
+        controller: instance.playerId,
+      };
+
+      // Validate target selection using @drmxrcy/tcg-core's targeting system
+      if (!targetDef) {
+        return {
+          valid: false,
+          error: `Target definition at index ${i} is undefined`,
+          reason: "targets",
+          invalidTargets: [i],
+        };
+      }
+
+      const validationResult = validateTargetSelection(
+        targetCards,
+        targetDef,
+        state,
+        registry,
+        context,
+      );
+
+      if (!validationResult.valid) {
+        return {
+          valid: false,
+          error: `Invalid targets at index ${i}: ${validationResult.error}`,
+          reason: "targets",
+          invalidTargets: [i],
+        };
+      }
+    }
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Get Available Actions
+ *
+ * Filters a list of action definitions to only those that are valid
+ * for the current timing context.
+ *
+ * This is useful for UI to show only valid actions, or for AI to
+ * enumerate possible actions.
+ *
+ * @param actions - All possible action definitions
+ * @param timingContext - Current game flow state
+ * @param gameState - Full game state for custom timing predicates
+ * @returns Array of actions that can be performed now (timing-wise)
+ */
+export function getAvailableActions<TGameState extends TimingContext>(
+  actions: ActionDefinition<TGameState>[],
+  timingContext: TimingContext,
+  gameState?: TGameState,
+): ActionDefinition<TGameState>[] {
+  return actions.filter((action) =>
+    validateActionTiming(action, timingContext, gameState),
+  );
+}
+
+/**
+ * Check if any action is available
+ *
+ * Quick check to see if the player has any valid actions.
+ * More efficient than getAvailableActions when you only need a boolean.
+ *
+ * @param actions - All possible action definitions
+ * @param timingContext - Current game flow state
+ * @param gameState - Full game state for custom timing predicates
+ * @returns True if at least one action can be performed
+ */
+export function hasAvailableActions<TGameState extends TimingContext>(
+  actions: ActionDefinition<TGameState>[],
+  timingContext: TimingContext,
+  gameState?: TGameState,
+): boolean {
+  return actions.some((action) =>
+    validateActionTiming(action, timingContext, gameState),
+  );
+}

package/src/cards/card-definition.test.ts

@@ -0,0 +1,268 @@
+import { describe, expect, it } from "bun:test";
+import { createCardRegistry } from "../operations/card-registry-impl";
+import type { CardDefinition } from "./card-definition";
+
+describe("Card Definition", () => {
+  describe("CardDefinition Type", () => {
+    it("should define static card data with all required fields", () => {
+      const definition: CardDefinition = {
+        id: "fire-bolt",
+        name: "Fire Bolt",
+        type: "instant",
+      };
+
+      expect(definition.id).toBe("fire-bolt");
+      expect(definition.name).toBe("Fire Bolt");
+      expect(definition.type).toBe("instant");
+    });
+
+    it("should support optional basePower field", () => {
+      const definition: CardDefinition = {
+        id: "grizzly-bears",
+        name: "Grizzly Bears",
+        type: "creature",
+        basePower: 2,
+      };
+
+      expect(definition.basePower).toBe(2);
+    });
+
+    it("should support optional baseToughness field", () => {
+      const definition: CardDefinition = {
+        id: "grizzly-bears",
+        name: "Grizzly Bears",
+        type: "creature",
+        baseToughness: 2,
+      };
+
+      expect(definition.baseToughness).toBe(2);
+    });
+
+    it("should support optional baseCost field", () => {
+      const definition: CardDefinition = {
+        id: "fire-bolt",
+        name: "Fire Bolt",
+        type: "instant",
+        baseCost: 1,
+      };
+
+      expect(definition.baseCost).toBe(1);
+    });
+
+    it("should support abilities array", () => {
+      const definition: CardDefinition = {
+        id: "serra-angel",
+        name: "Serra Angel",
+        type: "creature",
+        abilities: ["flying", "vigilance"],
+      };
+
+      expect(definition.abilities).toHaveLength(2);
+      expect(definition.abilities).toContain("flying");
+      expect(definition.abilities).toContain("vigilance");
+    });
+
+    it("should work with empty abilities array", () => {
+      const definition: CardDefinition = {
+        id: "vanilla-creature",
+        name: "Vanilla Creature",
+        type: "creature",
+        abilities: [],
+      };
+
+      expect(definition.abilities).toHaveLength(0);
+    });
+
+    it("should support all fields together", () => {
+      const definition: CardDefinition = {
+        id: "lightning-dragon",
+        name: "Lightning Dragon",
+        type: "creature",
+        basePower: 4,
+        baseToughness: 4,
+        baseCost: 4,
+        abilities: ["flying", "haste"],
+      };
+
+      expect(definition.id).toBe("lightning-dragon");
+      expect(definition.name).toBe("Lightning Dragon");
+      expect(definition.type).toBe("creature");
+      expect(definition.basePower).toBe(4);
+      expect(definition.baseToughness).toBe(4);
+      expect(definition.baseCost).toBe(4);
+      expect(definition.abilities).toHaveLength(2);
+    });
+  });
+
+  describe("Card Registry", () => {
+    it("should create empty registry", () => {
+      const registry = createCardRegistry<CardDefinition>([]);
+      expect(registry).toBeDefined();
+      expect(registry.getCardCount()).toBe(0);
+    });
+
+    it("should register single card definition", () => {
+      const definition: CardDefinition = {
+        id: "fire-bolt",
+        name: "Fire Bolt",
+        type: "instant",
+        baseCost: 1,
+        abilities: [],
+      };
+
+      const registry = createCardRegistry([definition]);
+      const retrieved = registry.getCard("fire-bolt");
+
+      expect(retrieved).toBeDefined();
+      expect(retrieved?.id).toBe("fire-bolt");
+      expect(retrieved?.name).toBe("Fire Bolt");
+    });
+
+    it("should register multiple card definitions", () => {
+      const definitions: CardDefinition[] = [
+        {
+          id: "fire-bolt",
+          name: "Fire Bolt",
+          type: "instant",
+          baseCost: 1,
+          abilities: [],
+        },
+        {
+          id: "grizzly-bears",
+          name: "Grizzly Bears",
+          type: "creature",
+          basePower: 2,
+          baseToughness: 2,
+          baseCost: 2,
+          abilities: [],
+        },
+      ];
+
+      const registry = createCardRegistry(definitions);
+
+      const fireBolt = registry.getCard("fire-bolt");
+      const bears = registry.getCard("grizzly-bears");
+
+      expect(fireBolt?.name).toBe("Fire Bolt");
+      expect(bears?.name).toBe("Grizzly Bears");
+    });
+
+    it("should return undefined for non-existent definition", () => {
+      const registry = createCardRegistry<CardDefinition>([]);
+      const retrieved = registry.getCard("non-existent");
+
+      expect(retrieved).toBeUndefined();
+    });
+
+    it("should overwrite duplicate definitions with last one", () => {
+      const definitions: CardDefinition[] = [
+        {
+          id: "fire-bolt",
+          name: "Fire Bolt V1",
+          type: "instant",
+          baseCost: 1,
+          abilities: [],
+        },
+        {
+          id: "fire-bolt",
+          name: "Fire Bolt V2",
+          type: "instant",
+          baseCost: 2,
+          abilities: [],
+        },
+      ];
+
+      const registry = createCardRegistry(definitions);
+      const retrieved = registry.getCard("fire-bolt");
+
+      expect(retrieved?.name).toBe("Fire Bolt V2");
+      expect(retrieved?.baseCost).toBe(2);
+    });
+  });
+
+  describe("CardRegistry.getCard", () => {
+    it("should retrieve definition by id", () => {
+      const definition: CardDefinition = {
+        id: "test-card",
+        name: "Test Card",
+        type: "creature",
+        abilities: [],
+      };
+
+      const registry = createCardRegistry([definition]);
+      const retrieved = registry.getCard("test-card");
+
+      expect(retrieved).toEqual(definition);
+    });
+
+    it("should be case-sensitive for ids", () => {
+      const definition: CardDefinition = {
+        id: "TestCard",
+        name: "Test Card",
+        type: "creature",
+        abilities: [],
+      };
+
+      const registry = createCardRegistry([definition]);
+
+      expect(registry.getCard("TestCard")).toBeDefined();
+      expect(registry.getCard("testcard")).toBeUndefined();
+    });
+
+    it("should handle definitions with zero values", () => {
+      const definition: CardDefinition = {
+        id: "zero-cost",
+        name: "Zero Cost Card",
+        type: "instant",
+        baseCost: 0,
+        abilities: [],
+      };
+
+      const registry = createCardRegistry([definition]);
+      const retrieved = registry.getCard("zero-cost");
+
+      expect(retrieved?.baseCost).toBe(0);
+    });
+  });
+
+  describe("CardRegistry additional methods", () => {
+    it("should check if card exists with hasCard", () => {
+      const registry = createCardRegistry([
+        { id: "card1", name: "Card 1", type: "creature" },
+      ]);
+
+      expect(registry.hasCard("card1")).toBe(true);
+      expect(registry.hasCard("nonexistent")).toBe(false);
+    });
+
+    it("should get all cards with getAllCards", () => {
+      const registry = createCardRegistry([
+        { id: "card1", name: "Card 1", type: "creature" },
+        { id: "card2", name: "Card 2", type: "instant" },
+      ]);
+
+      const allCards = registry.getAllCards();
+      expect(allCards).toHaveLength(2);
+    });
+
+    it("should query cards with predicate", () => {
+      const registry = createCardRegistry([
+        { id: "card1", name: "Card 1", type: "creature" },
+        { id: "card2", name: "Card 2", type: "instant" },
+        { id: "card3", name: "Card 3", type: "creature" },
+      ]);
+
+      const creatures = registry.queryCards((card) => card.type === "creature");
+      expect(creatures).toHaveLength(2);
+    });
+
+    it("should return card count", () => {
+      const registry = createCardRegistry([
+        { id: "card1", name: "Card 1", type: "creature" },
+        { id: "card2", name: "Card 2", type: "instant" },
+      ]);
+
+      expect(registry.getCardCount()).toBe(2);
+    });
+  });
+});

package/src/cards/card-definition.ts

@@ -0,0 +1,27 @@
+/**
+ * Card Definition - Static, immutable data for a card type
+ * This represents the "blueprint" of a card, not an instance in play.
+ * All instances of the same card share the same definition.
+ */
+export type CardDefinition = {
+  /** Unique identifier for this card definition */
+  id: string;
+
+  /** Display name of the card */
+  name: string;
+
+  /** Card type (e.g., 'creature', 'instant', 'sorcery', 'enchantment') */
+  type: string;
+
+  /** Base power value (for creatures) */
+  basePower?: number;
+
+  /** Base toughness/health value (for creatures) */
+  baseToughness?: number;
+
+  /** Base mana/resource cost to play the card */
+  baseCost?: number;
+
+  /** Static abilities this card has */
+  abilities?: string[];
+};