@drmxrcy/tcg-core 0.0.0-202602060542

package/src/targeting/target-definition.test.ts

@@ -0,0 +1,273 @@
+import { describe, expect, it } from "bun:test";
+import { createPlayerId, createZoneId } from "../types";
+import type { TargetDefinition, TargetRestriction } from "./target-definition";
+
+describe("Target Definition Types", () => {
+  describe("TargetDefinition", () => {
+    it("should define target with filter and count", () => {
+      const target: TargetDefinition = {
+        filter: { zone: createZoneId("play") },
+        count: 1,
+      };
+
+      expect(target.filter).toBeDefined();
+      expect(target.count).toBe(1);
+    });
+
+    it("should support optional targets with min/max count", () => {
+      const target: TargetDefinition = {
+        filter: { type: "creature" },
+        count: { min: 0, max: 3 },
+      };
+
+      expect(target.count).toEqual({ min: 0, max: 3 });
+    });
+
+    it("should support required targets with exact count", () => {
+      const target: TargetDefinition = {
+        filter: { zone: createZoneId("hand") },
+        count: 2,
+      };
+
+      expect(target.count).toBe(2);
+    });
+
+    it("should support targeting restrictions", () => {
+      const target: TargetDefinition = {
+        filter: { type: "creature" },
+        count: 1,
+        restrictions: ["not-self"],
+      };
+
+      expect(target.restrictions).toContain("not-self");
+    });
+
+    it("should support multiple restrictions", () => {
+      const target: TargetDefinition = {
+        filter: { zone: createZoneId("play") },
+        count: 2,
+        restrictions: ["not-self", "different-targets"],
+      };
+
+      expect(target.restrictions).toHaveLength(2);
+    });
+
+    it("should work without restrictions", () => {
+      const target: TargetDefinition = {
+        filter: { type: "land" },
+        count: 1,
+      };
+
+      expect(target.restrictions).toBeUndefined();
+    });
+  });
+
+  describe("TargetRestriction", () => {
+    it("should support 'not-self' restriction", () => {
+      const restriction: TargetRestriction = "not-self";
+      expect(restriction).toBe("not-self");
+    });
+
+    it("should support 'not-controller' restriction", () => {
+      const restriction: TargetRestriction = "not-controller";
+      expect(restriction).toBe("not-controller");
+    });
+
+    it("should support 'not-owner' restriction", () => {
+      const restriction: TargetRestriction = "not-owner";
+      expect(restriction).toBe("not-owner");
+    });
+
+    it("should support 'different-targets' restriction", () => {
+      const restriction: TargetRestriction = "different-targets";
+      expect(restriction).toBe("different-targets");
+    });
+  });
+
+  describe("Target Count Types", () => {
+    it("should support exact count as number", () => {
+      const count: number | { min: number; max: number } = 1;
+      expect(count).toBe(1);
+    });
+
+    it("should support range with min and max", () => {
+      const count: number | { min: number; max: number } = {
+        min: 1,
+        max: 3,
+      };
+      expect(count).toEqual({ min: 1, max: 3 });
+    });
+
+    it("should support optional targets with min 0", () => {
+      const count: number | { min: number; max: number } = {
+        min: 0,
+        max: 5,
+      };
+      expect(count.min).toBe(0);
+    });
+
+    it("should support unbounded max targets", () => {
+      const count: number | { min: number; max: number } = {
+        min: 1,
+        max: Number.POSITIVE_INFINITY,
+      };
+      expect(count.max).toBe(Number.POSITIVE_INFINITY);
+    });
+  });
+
+  describe("Multi-Target Definitions", () => {
+    it("should support multiple target groups", () => {
+      const targets: TargetDefinition[] = [
+        {
+          filter: { type: "creature" },
+          count: 1,
+        },
+        {
+          filter: { type: "player" },
+          count: 1,
+        },
+      ];
+
+      expect(targets).toHaveLength(2);
+      expect(targets[0].filter.type).toBe("creature");
+      expect(targets[1].filter.type).toBe("player");
+    });
+
+    it("should support optional and required targets together", () => {
+      const targets: TargetDefinition[] = [
+        {
+          filter: { type: "creature" },
+          count: 1,
+        },
+        {
+          filter: { type: "land" },
+          count: { min: 0, max: 2 },
+        },
+      ];
+
+      expect(typeof targets[0].count).toBe("number");
+      expect(typeof targets[1].count).toBe("object");
+    });
+  });
+
+  describe("Complex Target Definitions", () => {
+    it("should support targets with complex filters", () => {
+      const playZone = createZoneId("play");
+      const target: TargetDefinition = {
+        filter: {
+          zone: playZone,
+          type: "creature",
+          properties: {
+            basePower: { gte: 3 },
+          },
+          tapped: false,
+        },
+        count: { min: 1, max: 3 },
+        restrictions: ["not-self"],
+      };
+
+      expect(target.filter.zone).toBe(playZone);
+      expect(target.filter.type).toBe("creature");
+      expect(target.filter.properties?.basePower).toEqual({ gte: 3 });
+      expect(target.filter.tapped).toBe(false);
+      expect(target.count).toEqual({ min: 1, max: 3 });
+      expect(target.restrictions).toContain("not-self");
+    });
+
+    it("should support targets with composite filters", () => {
+      const target: TargetDefinition = {
+        filter: {
+          or: [{ type: "creature" }, { type: "artifact" }],
+        },
+        count: 2,
+        restrictions: ["different-targets"],
+      };
+
+      expect(target.filter.or).toBeDefined();
+      expect(target.filter.or).toHaveLength(2);
+      expect(target.restrictions).toContain("different-targets");
+    });
+  });
+
+  describe("Real-World Examples", () => {
+    it("should model Lightning Bolt (1 target, any creature or player)", () => {
+      const target: TargetDefinition = {
+        filter: {
+          or: [{ type: "creature" }, { type: "player" }],
+        },
+        count: 1,
+      };
+
+      expect(target.count).toBe(1);
+      expect(target.filter.or).toHaveLength(2);
+    });
+
+    it("should model Wrath of God (no targets)", () => {
+      const targets: TargetDefinition[] = [];
+
+      expect(targets).toHaveLength(0);
+    });
+
+    it("should model Fireball (1 required target, additional optional)", () => {
+      const targets: TargetDefinition[] = [
+        {
+          filter: {
+            or: [{ type: "creature" }, { type: "player" }],
+          },
+          count: 1,
+        },
+        {
+          filter: {
+            or: [{ type: "creature" }, { type: "player" }],
+          },
+          count: { min: 0, max: Number.POSITIVE_INFINITY },
+          restrictions: ["different-targets"],
+        },
+      ];
+
+      expect(targets).toHaveLength(2);
+      expect(targets[0].count).toBe(1);
+      expect(targets[1].count).toEqual({
+        min: 0,
+        max: Number.POSITIVE_INFINITY,
+      });
+    });
+
+    it("should model Pump spell (target creature you control)", () => {
+      const player = createPlayerId("player-1");
+      const target: TargetDefinition = {
+        filter: {
+          type: "creature",
+          controller: player,
+        },
+        count: 1,
+      };
+
+      expect(target.filter.controller).toBe(player);
+    });
+
+    it("should model Fight spell (2 creatures, can't target same)", () => {
+      const target: TargetDefinition = {
+        filter: { type: "creature" },
+        count: 2,
+        restrictions: ["different-targets"],
+      };
+
+      expect(target.count).toBe(2);
+      expect(target.restrictions).toContain("different-targets");
+    });
+
+    it("should model Act of Treason (opponent's creature)", () => {
+      const _player = createPlayerId("player-1");
+      const target: TargetDefinition = {
+        filter: {
+          type: "creature",
+        },
+        count: 1,
+        restrictions: ["not-controller"],
+      };
+
+      expect(target.restrictions).toContain("not-controller");
+    });
+  });
+});

package/src/targeting/target-definition.ts

@@ -0,0 +1,37 @@
+import type { CardFilter } from "../filtering/card-filter";
+
+/**
+ * Target restriction types
+ * Defines additional constraints on target selection beyond the filter
+ */
+export type TargetRestriction =
+  | "not-self" // Cannot target the source card itself
+  | "not-controller" // Cannot target cards controlled by the move's controller
+  | "not-owner" // Cannot target cards owned by the move's player
+  | "different-targets"; // All selected targets must be different cards
+
+/**
+ * Target count specification
+ * Can be an exact number or a range (min, max)
+ */
+export type TargetCount =
+  | number // Exact count (required)
+  | {
+      min: number; // Minimum number of targets (0 = optional)
+      max: number; // Maximum number of targets (can be Infinity)
+    };
+
+/**
+ * Target definition for a move
+ * Specifies what can be targeted and how many targets are needed
+ */
+export type TargetDefinition = {
+  /** Filter defining valid target cards/entities */
+  filter: CardFilter;
+
+  /** Number of targets required/allowed */
+  count: TargetCount;
+
+  /** Optional restrictions on target selection */
+  restrictions?: TargetRestriction[];
+};

package/src/targeting/target-dsl.ts

@@ -0,0 +1,279 @@
+/**
+ * Unified Target DSL - Core Types
+ *
+ * Game-agnostic targeting primitives that TCG engines can extend.
+ * This module provides the foundational DSL structure for expressing
+ * card and player targeting in a declarative, composable way.
+ *
+ * @module targeting/target-dsl
+ */
+
+import type { CardFilter } from "../filtering/card-filter";
+
+// ============================================================================
+// Selector: HOW targets are selected
+// ============================================================================
+
+/**
+ * Selector scope determines how targets are selected from valid options
+ *
+ * @example
+ * - "self": Target the source card itself
+ * - "chosen": Player actively selects from valid targets
+ * - "all": All matching cards are automatically targeted
+ * - "each": Semantic alias for "all" (used in effect descriptions)
+ * - "any": Single target, typically random or first-match
+ * - "random": Explicitly random selection
+ */
+export type SelectorScope =
+  | "self" // This card (the source of the ability)
+  | "chosen" // Player chooses from valid options
+  | "all" // All matching cards
+  | "each" // Each matching (semantic alias for effects)
+  | "any" // Any single matching card
+  | "random"; // Random selection from valid options
+
+// ============================================================================
+// Owner Scope: WHOSE cards can be selected
+// ============================================================================
+
+/**
+ * Owner scope determines which players' cards are valid targets
+ */
+export type OwnerScope =
+  | "you" // Controller of source card
+  | "opponent" // Opponent(s)
+  | "any"; // Any player's cards
+
+// ============================================================================
+// Target Count: HOW MANY to select
+// ============================================================================
+
+/**
+ * Target count specification with various semantics
+ *
+ * @example
+ * - `1`: Exactly 1 target (required)
+ * - `{ exactly: 2 }`: Exactly 2 targets
+ * - `{ upTo: 3 }`: 0 to 3 targets (player chooses how many)
+ * - `{ atLeast: 1 }`: 1 or more targets
+ * - `{ between: [2, 4] }`: 2 to 4 targets
+ * - `"all"`: All matching targets
+ */
+export type TargetCount =
+  | number // Exact count (required)
+  | { exactly: number } // Explicit exact count
+  | { upTo: number } // 0 to N (optional up to max)
+  | { atLeast: number } // N or more (minimum required)
+  | { between: [number, number] } // Range [min, max]
+  | "all"; // All matching
+
+// ============================================================================
+// Context References: Contextual card references
+// ============================================================================
+
+/**
+ * Base context for targeting - game engines extend this
+ *
+ * Provides references to cards based on the current game context,
+ * such as the trigger source, combat participants, etc.
+ */
+export interface BaseContext {
+  /** Reference the source card itself */
+  self?: boolean;
+}
+
+// ============================================================================
+// Core Target DSL Structure
+// ============================================================================
+
+/**
+ * Core Target DSL - The main targeting structure
+ *
+ * This generic type defines how targets are selected. Game-specific
+ * engines extend the filter and context type parameters.
+ *
+ * @typeParam TFilter - Type of filters (extends CardFilter or game-specific)
+ * @typeParam TContext - Type of context references
+ *
+ * @example Basic character targeting
+ * ```typescript
+ * const target: TargetDSL = {
+ *   selector: "chosen",
+ *   count: 1,
+ *   owner: "opponent",
+ *   zones: ["play"],
+ *   cardTypes: ["character"]
+ * };
+ * ```
+ *
+ * @example Targeting with filters
+ * ```typescript
+ * const target: TargetDSL = {
+ *   selector: "all",
+ *   owner: "any",
+ *   zones: ["play"],
+ *   filter: { type: "creature", tapped: true }
+ * };
+ * ```
+ */
+export interface TargetDSL<
+  TFilter = CardFilter,
+  TContext extends BaseContext = BaseContext,
+> {
+  /** How targets are selected (chosen, all, self, etc.) */
+  selector: SelectorScope;
+
+  /** How many targets to select */
+  count?: TargetCount;
+
+  /** Whose cards can be targeted */
+  owner?: OwnerScope;
+
+  /** Which zones to search for targets */
+  zones?: string[];
+
+  /** Card type restriction (game-specific type names) */
+  cardTypes?: string[];
+
+  /** Additional filter criteria (merged with base filter) */
+  filter?: TFilter;
+
+  /** Context references (self, trigger-source, etc.) */
+  context?: TContext;
+
+  /** Exclude the source card from valid targets */
+  excludeSelf?: boolean;
+
+  /** All selected targets must be different cards */
+  requireDifferentTargets?: boolean;
+}
+
+// ============================================================================
+// UI Hint Types
+// ============================================================================
+
+/**
+ * UI hints for target selection interfaces
+ *
+ * Games can use these to generate appropriate selection UI
+ */
+export interface TargetingUIHint {
+  /** Type of selection UI to show */
+  selectionType: "single" | "multiple" | "automatic" | "none";
+
+  /** Minimum number of selections required */
+  minSelections: number;
+
+  /** Maximum number of selections allowed */
+  maxSelections: number | "unlimited";
+
+  /** Human-readable prompt for the player */
+  prompt: string;
+
+  /** Whether selection is optional (can select 0) */
+  optional: boolean;
+
+  /** Zone(s) to highlight in the UI */
+  highlightZones: string[];
+}
+
+// ============================================================================
+// Player Targeting
+// ============================================================================
+
+/**
+ * Player target specification (separate from card targeting)
+ *
+ * Used when effects target players rather than cards.
+ *
+ * @example
+ * - "controller": The player who controls the source card
+ * - "opponent": A single opponent
+ * - "each-player": All players
+ * - "each-opponent": All opponents
+ * - "chosen-player": Player selects which player to target
+ */
+export type PlayerTargetDSL =
+  | "controller" // Player who controls the source
+  | "opponent" // Single opponent (or active opponent in 1v1)
+  | "each-player" // All players including controller
+  | "each-opponent" // All opponents
+  | "chosen-player"; // Controller chooses which player
+
+// ============================================================================
+// Type Utilities
+// ============================================================================
+
+/**
+ * Extract the minimum count from a TargetCount specification
+ */
+export function getMinCount(count: TargetCount | undefined): number {
+  if (count === undefined) return 1;
+  if (count === "all") return 0;
+  if (typeof count === "number") return count;
+  if ("exactly" in count) return count.exactly;
+  if ("upTo" in count) return 0;
+  if ("atLeast" in count) return count.atLeast;
+  if ("between" in count) return count.between[0];
+  return 0;
+}
+
+/**
+ * Extract the maximum count from a TargetCount specification
+ */
+export function getMaxCount(
+  count: TargetCount | undefined,
+): number | "unlimited" {
+  if (count === undefined) return 1;
+  if (count === "all") return "unlimited";
+  if (typeof count === "number") return count;
+  if ("exactly" in count) return count.exactly;
+  if ("upTo" in count) return count.upTo;
+  if ("atLeast" in count) return "unlimited";
+  if ("between" in count) return count.between[1];
+  return 1;
+}
+
+/**
+ * Check if a target count is optional (allows selecting 0)
+ */
+export function isOptionalCount(count: TargetCount | undefined): boolean {
+  return getMinCount(count) === 0;
+}
+
+/**
+ * Check if a selector requires player interaction
+ */
+export function requiresPlayerChoice(selector: SelectorScope): boolean {
+  return selector === "chosen";
+}
+
+/**
+ * Check if a selector targets multiple cards
+ */
+export function isMultipleTargetSelector(selector: SelectorScope): boolean {
+  return selector === "all" || selector === "each";
+}
+
+// ============================================================================
+// Default Values
+// ============================================================================
+
+/**
+ * Default target DSL for a single chosen card
+ */
+export const DEFAULT_SINGLE_TARGET: Partial<TargetDSL> = {
+  selector: "chosen",
+  count: 1,
+  owner: "any",
+};
+
+/**
+ * Default target DSL for self-targeting
+ */
+export const DEFAULT_SELF_TARGET: Partial<TargetDSL> = {
+  selector: "self",
+  count: 1,
+  context: { self: true },
+};