@drmxrcy/tcg-lorcana 0.0.0-202602060544

package/src/cards/README.md

@@ -0,0 +1,296 @@
+# Cards
+
+This directory contains card definitions, abilities, and card-related functionality for Lorcana.
+
+## Structure
+
+### Card Definitions
+
+- **`card-definitions/`** - Card data organized by set
+  - `set-001/` - The First Chapter cards
+  - `set-002/` - Rise of the Floodborn cards
+  - `set-003/` - Into the Inklands cards
+  - `index.ts` - Card registry aggregating all sets
+
+### Abilities
+
+- **`abilities/`** - Card ability definitions
+  - `keywords/` - Keyword abilities (Bodyguard, Challenger, Evasive, etc.)
+  - `triggered/` - Triggered abilities (When/Whenever)
+  - `activated/` - Activated abilities (tap to activate)
+  - `static/` - Static abilities (always active)
+  - `index.ts` - Ability registry
+
+### Card Types
+
+- **`card-types.ts`** - Lorcana-specific card type definitions
+- **`card-instance.ts`** - Runtime card instance management
+- **`card-queries.ts`** - Helper functions for querying cards
+- **`index.ts`** - Public exports
+
+## Purpose
+
+This directory defines all Lorcana cards and their abilities, structured to work with the `@drmxrcy/tcg-core` card system.
+
+## Card Definition Pattern
+
+Cards are defined declaratively:
+
+```typescript
+import type { CardDefinition } from "@drmxrcy/tcg-core";
+import type { LorcanaCard } from "../card-types";
+
+export const mickeyMouseTrueFriend: CardDefinition<LorcanaCard> = {
+  // Core properties
+  id: "001-001",
+  name: "Mickey Mouse - True Friend",
+  set: "001",
+  rarity: "legendary",
+  inkable: true,
+  
+  // Lorcana-specific properties
+  cost: 8,
+  inkCost: 8,
+  type: "character",
+  color: "amber",
+  
+  // Character properties
+  strength: 4,
+  willpower: 6,
+  loreValue: 3,
+  
+  // Abilities
+  abilities: [
+    {
+      type: "keyword",
+      keyword: "challenger",
+      value: 5,
+    },
+    {
+      type: "triggered",
+      trigger: "whenPlayed",
+      effect: "drawCards",
+      amount: 2,
+    },
+  ],
+  
+  // Flavor text
+  flavorText: "A friend in need is a friend indeed.",
+};
+```
+
+## Card Types
+
+Lorcana has several card types:
+
+```typescript
+export type LorcanaCardType = 
+  | "character"
+  | "action"
+  | "item"
+  | "location"
+  | "song";
+
+export type LorcanaCard = {
+  // Base card properties
+  id: CardId;
+  name: string;
+  type: LorcanaCardType;
+  cost: number;
+  inkCost: number;
+  color: LorcanaColor;
+  inkable: boolean;
+  rarity: LorcanaRarity;
+  set: string;
+  
+  // Character-specific
+  strength?: number;
+  willpower?: number;
+  loreValue?: number;
+  
+  // Abilities
+  abilities: LorcanaAbility[];
+  
+  // Text
+  text?: string;
+  flavorText?: string;
+};
+```
+
+## Keyword Abilities
+
+Keyword abilities are standardized mechanics:
+
+```typescript
+// Bodyguard - Must be challenged before other characters
+export const bodyguardAbility: KeywordAbility = {
+  keyword: "bodyguard",
+  
+  // Modify challenge validation
+  modifyValidation: (state, context) => {
+    // Implementation: prevent challenging other characters
+    // if a bodyguard is available
+  },
+};
+
+// Challenger +N - Gets +N strength when challenging
+export const challengerAbility: KeywordAbility = {
+  keyword: "challenger",
+  
+  // Modify challenge damage
+  modifyDamage: (state, cardId, baseValue) => {
+    const card = getCard(state, cardId);
+    const challengerBonus = getKeywordValue(card, "challenger");
+    return baseValue + challengerBonus;
+  },
+};
+```
+
+## Triggered Abilities
+
+Abilities that trigger on events:
+
+```typescript
+export type TriggeredAbility = {
+  type: "triggered";
+  trigger: TriggerTiming;
+  condition?: AbilityCondition;
+  effect: AbilityEffect;
+  target?: TargetDefinition;
+};
+
+// Example: "When you play this character, draw 2 cards"
+const drawOnPlayAbility: TriggeredAbility = {
+  type: "triggered",
+  trigger: "whenPlayed",
+  effect: {
+    type: "drawCards",
+    amount: 2,
+  },
+};
+```
+
+## Activated Abilities
+
+Abilities players can choose to activate:
+
+```typescript
+export type ActivatedAbility = {
+  type: "activated";
+  cost?: AbilityCost;
+  effect: AbilityEffect;
+  target?: TargetDefinition;
+  restrictions?: AbilityRestriction[];
+};
+
+// Example: "Exert - Draw a card"
+const exertToDrawAbility: ActivatedAbility = {
+  type: "activated",
+  cost: {
+    type: "exert",
+  },
+  effect: {
+    type: "drawCards",
+    amount: 1,
+  },
+};
+```
+
+## Card Registry
+
+All cards registered for lookup:
+
+```typescript
+// card-definitions/index.ts
+import * as set001 from "./set-001";
+import * as set002 from "./set-002";
+
+export const allCards = {
+  ...set001.cards,
+  ...set002.cards,
+};
+
+export const getCardDefinition = (cardId: CardId): CardDefinition => {
+  return allCards[cardId];
+};
+```
+
+## Card Instances vs Definitions
+
+- **CardDefinition**: The template (what the card does)
+- **CardInstance**: The runtime instance (current state)
+
+```typescript
+// Definition (static)
+const mickeyDefinition: CardDefinition = {
+  id: "001-001",
+  name: "Mickey Mouse",
+  strength: 4,
+  willpower: 6,
+};
+
+// Instance (dynamic)
+const mickeyInstance: CardInstance = {
+  definitionId: "001-001",
+  instanceId: "game1-card-123",
+  ownerId: "player1",
+  zone: "play",
+  
+  // Current state
+  damage: 2,
+  exerted: true,
+  playedThisTurn: true,
+};
+```
+
+## Card Queries
+
+Helper functions for common card operations:
+
+```typescript
+export const getCardsInZone = (
+  state: LorcanaState,
+  zone: ZoneId,
+  playerId: PlayerId
+): CardInstance[] => {
+  return state.zones[zone][playerId].map(
+    cardId => state.cards[cardId]
+  );
+};
+
+export const getReadyCharacters = (
+  state: LorcanaState,
+  playerId: PlayerId
+): CardInstance[] => {
+  return getCardsInZone(state, "play", playerId).filter(
+    card => card.type === "character" && !card.exerted
+  );
+};
+```
+
+## Testing Cards
+
+Card abilities are tested through integration tests:
+
+```typescript
+describe("Mickey Mouse - True Friend", () => {
+  it("draws 2 cards when played", () => {
+    const engine = createTestEngine();
+    const initialHandSize = getHandSize(engine.getState(), "player1");
+    
+    engine.executeMove("playCard", {
+      playerId: "player1",
+      params: { cardId: "mickey-true-friend" },
+    });
+    
+    const finalHandSize = getHandSize(engine.getState(), "player1");
+    expect(finalHandSize).toBe(initialHandSize + 2 - 1); // +2 draw, -1 played
+  });
+});
+```
+
+## References
+
+- See `@packages/core/src/cards/` for base card system
+- See `@packages/core/ENGINE_INTEGRATION.md` for card integration guide
+

package/src/cards/abilities/index.ts

@@ -0,0 +1,175 @@
+/**
+ * Lorcana Ability System
+ *
+ * Provides a comprehensive, serializable type system for representing
+ * all Lorcana card abilities.
+ *
+ * ## Overview
+ *
+ * Lorcana abilities are composed of:
+ * - **Effects**: Atomic game actions (draw, damage, gain lore, etc.)
+ * - **Triggers**: Events that cause abilities to fire
+ * - **Conditions**: Requirements that must be met
+ * - **Costs**: What must be paid to activate abilities
+ * - **Targets**: Who/what is affected
+ *
+ * ## Ability Types
+ *
+ * - **Keyword**: Simple abilities like Rush, Ward, Challenger +X
+ * - **Triggered**: Fire when events occur (When/Whenever/At)
+ * - **Activated**: Player chooses to use by paying cost
+ * - **Static**: Always active, modify game state
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import {
+ *   Ability,
+ *   keyword,
+ *   triggered,
+ *   COMMON_TRIGGERS,
+ * } from "@lorcana/cards/abilities";
+ *
+ * // Simple keyword
+ * const rush: Ability = keyword("Rush");
+ *
+ * // Challenger +3
+ * const challengerAbility: Ability = challenger(3);
+ *
+ * // "When you play this character, draw 2 cards"
+ * const drawOnPlay: Ability = triggered(
+ *   COMMON_TRIGGERS.WHEN_PLAY_SELF,
+ *   { type: "draw", amount: 2, target: "CONTROLLER" }
+ * );
+ * ```
+ *
+ * ## Design Principles
+ *
+ * 1. **Serializable**: All types can be serialized to JSON
+ * 2. **Composable**: Effects combine into complex abilities
+ * 3. **Type-safe**: Discriminated unions with type guards
+ * 4. **Executable**: Structure is directly usable by game engine
+ *
+ * @module abilities
+ */
+
+// Re-export all types from lorcana-types
+export * from "@drmxrcy/tcg-lorcana-types/abilities";
+
+// ============================================================================
+// Version Info
+// ============================================================================
+
+/**
+ * Version of the ability type system
+ * Increment when making breaking changes
+ */
+export const ABILITY_TYPES_VERSION = "1.0.0";
+
+// ============================================================================
+// Quick Reference: Common Ability Patterns
+// ============================================================================
+
+/**
+ * Example abilities for reference and testing
+ */
+export const EXAMPLE_ABILITIES = {
+  /**
+   * Simple Rush keyword
+   */
+  rush: {
+    type: "keyword",
+    keyword: "Rush",
+  },
+
+  /**
+   * Challenger +3
+   */
+  challengerPlus3: {
+    type: "keyword",
+    keyword: "Challenger",
+    value: 3,
+  },
+
+  /**
+   * Resist +2
+   */
+  resistPlus2: {
+    type: "keyword",
+    keyword: "Resist",
+    value: 2,
+  },
+
+  /**
+   * Shift 5 (can Shift onto any matching character)
+   */
+  shift5: {
+    type: "keyword",
+    keyword: "Shift",
+    shiftCost: 5,
+  },
+
+  /**
+   * "When you play this character, draw 2 cards"
+   */
+  drawOnPlay: {
+    type: "triggered",
+    trigger: { event: "play", timing: "when", on: "SELF" },
+    effect: { type: "draw", amount: 2, target: "CONTROLLER" },
+  },
+
+  /**
+   * "Whenever this character quests, gain 1 lore"
+   */
+  gainLoreOnQuest: {
+    type: "triggered",
+    trigger: { event: "quest", timing: "whenever", on: "SELF" },
+    effect: { type: "gain-lore", amount: 1 },
+  },
+
+  /**
+   * "{E} - Draw a card"
+   */
+  exertToDraw: {
+    type: "activated",
+    cost: { exert: true },
+    effect: { type: "draw", amount: 1, target: "CONTROLLER" },
+  },
+
+  /**
+   * "{E}, 2 {I} - Deal 3 damage to chosen character"
+   */
+  exertInkToDamage: {
+    type: "activated",
+    cost: { exert: true, ink: 2 },
+    effect: { type: "deal-damage", amount: 3, target: "CHOSEN_CHARACTER" },
+  },
+
+  /**
+   * "Your characters gain Ward"
+   */
+  yourCharactersGainWard: {
+    type: "static",
+    effect: {
+      type: "gain-keyword",
+      keyword: "Ward",
+      target: "YOUR_CHARACTERS",
+      duration: "while-condition",
+    },
+  },
+
+  /**
+   * "While this character has no damage, he gets +2 Strength"
+   */
+  bonusWhileNoDamage: {
+    type: "static",
+    condition: { type: "no-damage" },
+    effect: {
+      type: "modify-stat",
+      stat: "strength",
+      modifier: 2,
+      target: "SELF",
+      duration: "while-condition",
+    },
+  },
+} as const;

package/src/cards/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Cards Module
+ *
+ * Card definitions, abilities, and card-related functionality for Lorcana.
+ *
+ * @module cards
+ */
+
+// Export ability types and utilities
+export * from "./abilities";

package/src/deck-validation.ts

@@ -0,0 +1,175 @@
+/**
+ * Deck Validation (Rule 2.1)
+ *
+ * Validates a deck against Lorcana deck building rules:
+ * - Minimum 60 cards (Rule 2.1.1.1)
+ * - Maximum 2 ink types (Rule 2.1.1.2)
+ * - Maximum 4 copies per full name (Rule 2.1.1.3)
+ */
+
+import type {
+  DeckStats,
+  DeckValidationError,
+  DeckValidationResult,
+  InkType,
+  LorcanaCardDefinition,
+} from "@drmxrcy/tcg-lorcana-types";
+import {
+  getFullName,
+  getInkTypes,
+  MAX_COPIES_PER_CARD,
+  MAX_INK_TYPES,
+  MIN_DECK_SIZE,
+} from "@drmxrcy/tcg-lorcana-types";
+
+/**
+ * Validate a deck against Lorcana rules
+ *
+ * @param cards - Array of card definitions in the deck
+ * @returns Validation result with any errors
+ */
+export function validateDeck(
+  cards: LorcanaCardDefinition[],
+): DeckValidationResult {
+  const errors: DeckValidationError[] = [];
+
+  // Rule 2.1.1.1: Minimum 60 cards
+  if (cards.length < MIN_DECK_SIZE) {
+    errors.push({
+      type: "TOO_FEW_CARDS",
+      count: cards.length,
+      minimum: MIN_DECK_SIZE,
+    });
+  }
+
+  // Rule 2.1.1.2: Maximum 2 ink types
+  const inkTypes = getUniqueInkTypes(cards);
+  if (inkTypes.length > MAX_INK_TYPES) {
+    errors.push({
+      type: "TOO_MANY_INK_TYPES",
+      inkTypes,
+      maximum: MAX_INK_TYPES,
+    });
+  }
+
+  // Rule 2.1.1.3: Maximum copies per full name (default 4, can be overridden)
+  const cardCounts = getCardCounts(cards);
+  const copyLimits = getCardCopyLimits(cards);
+
+  for (const [fullName, count] of cardCounts.entries()) {
+    const limit = copyLimits.get(fullName);
+
+    // Skip validation for cards with no limit
+    if (limit === "no-limit") {
+      continue;
+    }
+
+    const maxCopies = limit ?? MAX_COPIES_PER_CARD;
+    if (count > maxCopies) {
+      errors.push({
+        type: "TOO_MANY_COPIES",
+        fullName,
+        count,
+        maximum: maxCopies,
+      });
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Get all unique ink types in a deck
+ */
+export function getUniqueInkTypes(cards: LorcanaCardDefinition[]): InkType[] {
+  const inkSet = new Set<InkType>();
+  for (const card of cards) {
+    for (const ink of getInkTypes(card)) {
+      inkSet.add(ink);
+    }
+  }
+  return Array.from(inkSet);
+}
+
+/**
+ * Count cards by full name
+ */
+export function getCardCounts(
+  cards: LorcanaCardDefinition[],
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const card of cards) {
+    const fullName = getFullName(card);
+    counts.set(fullName, (counts.get(fullName) ?? 0) + 1);
+  }
+  return counts;
+}
+
+/**
+ * Get card copy limits by full name
+ * Returns undefined for default limit (4), number for custom limit, or "no-limit" for unlimited
+ */
+export function getCardCopyLimits(
+  cards: LorcanaCardDefinition[],
+): Map<string, number | "no-limit" | undefined> {
+  const limits = new Map<string, number | "no-limit" | undefined>();
+  for (const card of cards) {
+    const fullName = getFullName(card);
+    if (card.cardCopyLimit !== undefined && !limits.has(fullName)) {
+      limits.set(fullName, card.cardCopyLimit);
+    }
+  }
+  return limits;
+}
+
+/**
+ * Calculate deck statistics
+ */
+export function getDeckStats(cards: LorcanaCardDefinition[]): DeckStats {
+  const cardCounts = getCardCounts(cards);
+  const inkTypes = getUniqueInkTypes(cards);
+
+  const cardTypeBreakdown = {
+    characters: 0,
+    actions: 0,
+    items: 0,
+    locations: 0,
+  };
+
+  let inkableCards = 0;
+  let totalCost = 0;
+
+  for (const card of cards) {
+    switch (card.cardType) {
+      case "character":
+        cardTypeBreakdown.characters++;
+        break;
+      case "action":
+        cardTypeBreakdown.actions++;
+        break;
+      case "item":
+        cardTypeBreakdown.items++;
+        break;
+      case "location":
+        cardTypeBreakdown.locations++;
+        break;
+    }
+
+    if (card.inkable) {
+      inkableCards++;
+    }
+    totalCost += card.cost;
+  }
+
+  return {
+    totalCards: cards.length,
+    inkTypes,
+    cardCounts,
+    cardTypeBreakdown,
+    inkableCards,
+    averageCost: cards.length > 0 ? totalCost / cards.length : 0,
+  };
+}