@drmxrcy/tcg-lorcana-types 0.0.0-202602060544

package/src/abilities/cost-types.ts

@@ -0,0 +1,344 @@
+/**
+ * Cost Types for Lorcana Abilities
+ *
+ * Defines the costs required to activate abilities in Lorcana.
+ * Activated abilities use the format: "{cost} - {effect}"
+ *
+ * Common costs:
+ * - {E} = Exert this card
+ * - {d} {I} = Pay ink (where d is a number)
+ * - Banish this card/item
+ * - Discard cards
+ *
+ * @example "{E} - Draw a card" (exert cost)
+ * @example "{E}, 2 {I} - Deal 3 damage" (exert + ink cost)
+ * @example "Banish this item - Gain 3 lore" (banish self cost)
+ */
+
+import type { CardType } from "../cards/card-types";
+
+// ============================================================================
+// Individual Cost Components
+// ============================================================================
+
+/**
+ * Exert cost - tap/exhaust this card
+ */
+export interface ExertCost {
+  type: "exert";
+  /** What to exert (defaults to self) */
+  target?: "self" | "another-character" | "item";
+}
+
+/**
+ * Ink cost - pay from inkwell
+ */
+export interface InkCost {
+  type: "ink";
+  amount: number;
+}
+
+/**
+ * Banish cost - sacrifice a card
+ */
+export type BanishCost =
+  | {
+      type: "banish";
+      /** Simple banish targets */
+      target: "self" | "item" | "character";
+    }
+  | {
+      type: "banish";
+      /** Banish a specific card type/name */
+      target: "specific";
+      /** For "specific" target - card type or name required */
+      cardType?: CardType;
+      /** For "specific" target - card name required */
+      cardName?: string;
+    };
+
+/**
+ * Discard cost - discard cards from hand
+ */
+export interface DiscardCost {
+  type: "discard";
+  /** How many cards to discard */
+  amount: number;
+  /** Whether the player chooses which cards (vs random) */
+  chosen?: boolean;
+  /** Specific card type required */
+  cardType?: CardType | "song";
+  /** Specific card name required */
+  cardName?: string;
+}
+
+/**
+ * Deal damage to self cost
+ */
+export interface DamageSelfCost {
+  type: "damage-self";
+  amount: number;
+}
+
+/**
+ * Return card to hand cost
+ */
+export interface ReturnToHandCost {
+  type: "return-to-hand";
+  /** What to return */
+  target:
+    | "self" // Return this card
+    | "another-character" // Return another of your characters
+    | "item"; // Return one of your items
+}
+
+/**
+ * Put card under another card cost
+ */
+export interface PutUnderCost {
+  type: "put-under";
+  /** What goes under */
+  source: "card-from-hand" | "top-of-deck";
+  /** Card type requirement */
+  cardType?: CardType;
+}
+
+/**
+ * Exert another card cost (not self)
+ */
+export interface ExertOtherCost {
+  type: "exert-other";
+  /** What to exert */
+  target: "character" | "item";
+  /** How many to exert */
+  amount?: number;
+}
+
+// ============================================================================
+// Combined Cost
+// ============================================================================
+
+/**
+ * Individual cost component
+ */
+export type CostComponent =
+  | ExertCost
+  | InkCost
+  | BanishCost
+  | DiscardCost
+  | DamageSelfCost
+  | ReturnToHandCost
+  | PutUnderCost
+  | ExertOtherCost;
+
+/**
+ * Complete ability cost - can have multiple components
+ *
+ * @example "{E}" - just exert
+ * ```typescript
+ * { exert: true }
+ * ```
+ *
+ * @example "{E}, 2 {I}" - exert and pay 2 ink
+ * ```typescript
+ * { exert: true, ink: 2 }
+ * ```
+ *
+ * @example "{E}, Banish this item" - exert and banish self
+ * ```typescript
+ * { exert: true, banishSelf: true }
+ * ```
+ *
+ * @example "Choose and discard a card" - discard cost
+ * ```typescript
+ * { discardCards: 1, discardChosen: true }
+ * ```
+ *
+ * @remarks
+ * **Valid Cost Combinations:**
+ * - `exert` can be combined with any other cost
+ * - `ink` must be a positive number (omit if no ink cost)
+ * - Banish costs (`banishSelf`, `banishItem`, `banishCharacter`) are mutually exclusive
+ * - `discardChosen` requires `discardCards` to also be set
+ * - `discardCardType`/`discardCardName` require `discardCards` to also be set
+ * - Use `components` for complex costs not covered by simple fields
+ *
+ * @todo Consider refactoring to discriminated unions for better type safety in a future major version
+ */
+export interface AbilityCost {
+  /** Whether to exert this card */
+  exert?: boolean;
+
+  /** Ink to pay from inkwell (must be positive if present) */
+  ink?: number;
+
+  /** Banish this card (mutually exclusive with banishItem/banishCharacter) */
+  banishSelf?: boolean;
+
+  /** Banish one of your items (mutually exclusive with banishSelf/banishCharacter) */
+  banishItem?: boolean;
+
+  /** Banish one of your characters (mutually exclusive with banishSelf/banishItem) */
+  banishCharacter?: boolean;
+
+  /** Banish another card (generic) */
+  banishOther?: boolean;
+
+  /** Number of cards to discard from hand */
+  discardCards?: number;
+
+  /** Alias for discardCards (singular form) */
+  discardCard?: number;
+
+  /** Whether discarded cards are chosen (requires discardCards) */
+  discardChosen?: boolean;
+
+  /** Specific card type required for discard (requires discardCards) */
+  discardCardType?: CardType | "song";
+
+  /** Specific card name required for discard (requires discardCards) */
+  discardCardName?: string;
+
+  /** Damage to deal to this character */
+  damageSelf?: number;
+
+  /** Return this card to hand */
+  returnSelfToHand?: boolean;
+
+  /** Return another character to hand */
+  returnCharacterToHand?: boolean;
+
+  /** Number of items to exert (other than self) */
+  exertItems?: number;
+
+  /** Number of characters to exert (other than self) */
+  exertCharacters?: number;
+
+  /** Exert a single character (singular form) */
+  exertCharacter?: boolean;
+
+  /** Exert another card (generic) */
+  exertOther?: boolean;
+
+  /** Target for cost (e.g., which character to exert) */
+  target?: string;
+
+  /**
+   * Discard cost as an object (alternative format)
+   * Used by parser for complex discard costs
+   */
+  discard?: {
+    cardType?: CardType | "song" | "character";
+    amount?: number;
+  };
+
+  /**
+   * Complex cost components (for less common costs)
+   * Used when the simple fields above don't suffice
+   */
+  components?: CostComponent[];
+}
+
+// ============================================================================
+// Cost Builders (convenience)
+// ============================================================================
+
+/**
+ * Create an exert-only cost
+ */
+export function exertCost(): AbilityCost {
+  return { exert: true };
+}
+
+/**
+ * Create an exert + ink cost
+ */
+export function exertAndInkCost(ink: number): AbilityCost {
+  return { exert: true, ink };
+}
+
+/**
+ * Create a banish-self cost
+ */
+export function banishSelfCost(): AbilityCost {
+  return { banishSelf: true };
+}
+
+/**
+ * Create an exert + banish item cost
+ */
+export function exertAndBanishItemCost(): AbilityCost {
+  return { exert: true, banishItem: true };
+}
+
+/**
+ * Create a discard cost
+ */
+export function discardCost(amount: number, chosen = true): AbilityCost {
+  return { discardCards: amount, discardChosen: chosen };
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Check if a cost requires exerting
+ */
+export function requiresExert(cost: AbilityCost): boolean {
+  return cost.exert === true;
+}
+
+/**
+ * Check if a cost requires paying ink
+ */
+export function requiresInk(cost: AbilityCost): boolean {
+  return (cost.ink ?? 0) > 0;
+}
+
+/**
+ * Check if a cost requires banishing something
+ */
+export function requiresBanish(cost: AbilityCost): boolean {
+  return (
+    cost.banishSelf === true ||
+    cost.banishItem === true ||
+    cost.banishCharacter === true
+  );
+}
+
+/**
+ * Check if a cost requires discarding cards
+ */
+export function requiresDiscard(cost: AbilityCost): boolean {
+  return (cost.discardCards ?? 0) > 0;
+}
+
+/**
+ * Get total ink cost
+ */
+export function getInkCost(cost: AbilityCost): number {
+  return cost.ink ?? 0;
+}
+
+/**
+ * Check if cost is "free" (no cost)
+ */
+export function isFreeCost(cost: AbilityCost): boolean {
+  return (
+    !(
+      cost.exert ||
+      cost.ink ||
+      cost.banishSelf ||
+      cost.banishItem ||
+      cost.banishCharacter ||
+      cost.discardCards ||
+      cost.damageSelf ||
+      cost.returnSelfToHand ||
+      cost.returnCharacterToHand ||
+      cost.exertItems ||
+      cost.exertCharacters
+    ) &&
+    (!cost.components || cost.components.length === 0)
+  );
+}

package/src/abilities/effect-types/amount-types.ts

@@ -0,0 +1,115 @@
+/**
+ * Shared Types for Effects
+ *
+ * Defines primitive types used across multiple effect modules:
+ * - Amount types (fixed or variable)
+ * - Effect duration types
+ */
+
+import type { CardTarget, CharacterTarget } from "../target-types";
+
+// ============================================================================
+// Amount Types
+// ============================================================================
+
+/**
+ * Amount can be a fixed number, variable based on game state, or a string reference
+ */
+export type Amount = number | VariableAmount | AmountString;
+
+/**
+ * String-based amount references
+ */
+export type AmountString =
+  | "all" // All damage, all cards, etc.
+  | "DISCARDED_COUNT" // Number of cards discarded
+  | "DISCARDED_CARD_LORE" // Lore value of discarded card
+  | "RETURNED_CARD_COST" // Cost of returned card
+  | "DAMAGE_DEALT" // Amount of damage dealt
+  | "OPPONENTS_DAMAGED_CHARACTER_COUNT" // Number of opponent's damaged characters
+  | "X" // Variable amount (determined at resolution)
+  // Extended amount references for card text coverage
+  | "DAMAGE_REMOVED" // Amount of damage removed
+  | "HAND" // Number of cards in hand
+  | "TARGET_COST" // Cost of target card
+  | "TARGET_STRENGTH" // Strength of target character
+  | "TARGET_WILLPOWER"; // Willpower of target character
+
+/**
+ * Counter types for for-each amounts
+ */
+export type ForEachCounterType =
+  | "characters"
+  | "damaged-characters"
+  | "items"
+  | "locations"
+  | "cards-in-hand"
+  | "cards-in-discard"
+  | "damage-on-self"
+  | "damage-on-target"
+  | "cards-under-self";
+
+/**
+ * Variable amount calculated from game state
+ */
+export type VariableAmount =
+  | { type: "damage-on-target" }
+  | { type: "damage-on-self" }
+  | {
+      type: "cards-in-hand";
+      controller: "you" | "opponent" | "opponents";
+      modifier?: number;
+    }
+  | { type: "characters-in-play"; controller: "you" | "opponent" | "opponents" }
+  | { type: "items-in-play"; controller: "you" | "opponent" }
+  | { type: "cards-in-discard"; controller: "you" | "opponent" }
+  | { type: "lore"; controller: "you" | "opponent" }
+  | { type: "strength-of"; target: CharacterTarget }
+  | { type: "willpower-of"; target: CharacterTarget }
+  | { type: "lore-value-of"; target: CharacterTarget }
+  | { type: "cost-of"; target: CardTarget }
+  | { type: "cards-under-self" }
+  | {
+      type: "classification-character-count";
+      classification: string;
+      controller: "you" | "opponent";
+    }
+  | { type: "locations-in-play"; controller: "you" | "opponent" }
+  // For-each based amounts
+  | {
+      type: "for-each";
+      counter: ForEachCounterType | { type: string; controller?: string };
+      count?: number | VariableAmount;
+      modifier?: number;
+    }
+  // Additional variable amounts
+  | { type: "count"; what?: string; controller?: string; of?: string }
+  | { type: "VARIABLE" } // Generic variable amount
+  | { type: "lore-lost" } // Amount of lore lost
+  | { type: "stat"; stat?: string; target?: string }; // Stat value
+
+/**
+ * Check if amount is variable (vs fixed number)
+ */
+export function isVariableAmount(amount: Amount): amount is VariableAmount {
+  return typeof amount === "object";
+}
+
+// ============================================================================
+// Effect Duration Types
+// ============================================================================
+
+/**
+ * How long an effect lasts
+ */
+export type EffectDuration =
+  | "this-turn"
+  | "until-start-of-next-turn"
+  | "until-end-of-turn"
+  | "permanent"
+  | "while-condition"
+  | "next-play-this-turn" // Used with static abilities
+  | "next-turn" // Until the start/end of their next turn
+  | "their-next-turn" // Until the opponent's next turn
+  | "while-in-play" // While the card is in play
+  | { type: string }; // Allow object-based durations for flexibility

package/src/abilities/effect-types/basic-effects.ts

@@ -0,0 +1,200 @@
+/**
+ * Basic Effect Types
+ *
+ * Core effect types for common game actions:
+ * - Draw/Discard cards
+ * - Deal/Remove damage
+ * - Gain/Lose lore
+ * - Exert/Ready/Banish cards
+ */
+
+import type {
+  CharacterTarget,
+  ItemTarget,
+  LocationTarget,
+  PlayerTarget,
+  TargetZone,
+} from "../target-types";
+import type { Amount } from "./amount-types";
+
+// ============================================================================
+// Draw/Discard Effects
+// ============================================================================
+
+/**
+ * Draw cards effect
+ *
+ * @example "Draw 2 cards"
+ * @example "Each player draws a card"
+ */
+export interface DrawEffect {
+  type: "draw";
+  amount?: Amount;
+  target?: PlayerTarget;
+}
+
+/**
+ * Discard cards effect
+ *
+ * @example "Choose and discard a card"
+ * @example "Each opponent discards a card at random"
+ */
+export interface DiscardEffect {
+  type: "discard";
+  amount?: Amount;
+  target?: PlayerTarget;
+  /** Whether the affected player chooses which cards */
+  chosen?: boolean;
+  /** Who chooses (alternative to chosen) */
+  chosenBy?: "you" | "opponent" | "TARGET";
+  /** If not chosen, discard is random */
+  random?: boolean;
+  /** Discard from specific zone (default: hand) */
+  from?: TargetZone;
+  /** Filter for what can be discarded */
+  filter?: {
+    cardType?: string;
+    maxCost?: number;
+    classification?: string;
+  };
+}
+
+// ============================================================================
+// Damage Effects
+// ============================================================================
+
+/**
+ * Deal damage effect
+ *
+ * @example "Deal 3 damage to chosen character"
+ * @example "Deal 2 damage to each opposing character"
+ */
+export interface DealDamageEffect {
+  type: "deal-damage";
+  amount?: Amount;
+  target?: CharacterTarget | LocationTarget;
+}
+
+/**
+ * Put damage counters (different from "deal" - doesn't trigger "when dealt damage")
+ */
+export interface PutDamageEffect {
+  type: "put-damage";
+  amount: Amount;
+  target: CharacterTarget | LocationTarget;
+}
+
+/**
+ * Remove damage effect
+ *
+ * @example "Remove up to 3 damage from chosen character"
+ */
+export interface RemoveDamageEffect {
+  type: "remove-damage";
+  amount?: Amount;
+  target?: CharacterTarget | LocationTarget;
+  /** "up to" allows removing less than max */
+  upTo?: boolean;
+}
+
+/**
+ * Move damage counters effect
+ *
+ * @example "Move 2 damage from chosen character to another"
+ */
+export interface MoveDamageEffect {
+  type: "move-damage";
+  amount?: Amount;
+  from?: CharacterTarget;
+  to?: CharacterTarget;
+}
+
+// ============================================================================
+// Lore Effects
+// ============================================================================
+
+/**
+ * Gain lore effect
+ *
+ * @example "Gain 2 lore"
+ */
+export interface GainLoreEffect {
+  type: "gain-lore";
+  amount?: Amount;
+  target?: PlayerTarget;
+}
+
+/**
+ * Lose lore effect
+ *
+ * @example "Each opponent loses 1 lore"
+ */
+export interface LoseLoreEffect {
+  type: "lose-lore";
+  amount: Amount;
+  target?: PlayerTarget;
+}
+
+// ============================================================================
+// Card State Effects
+// ============================================================================
+
+/**
+ * Exert effect
+ *
+ * @example "Exert chosen character"
+ */
+export interface ExertEffect {
+  type: "exert";
+  target?: CharacterTarget | ItemTarget | LocationTarget;
+}
+
+/**
+ * Ready effect
+ *
+ * @example "Ready chosen character"
+ */
+export interface ReadyEffect {
+  type: "ready";
+  target?: CharacterTarget | ItemTarget | LocationTarget;
+  /** Restriction after readying */
+  restriction?: "cant-quest" | "cant-challenge" | "cant-quest-or-challenge";
+}
+
+/**
+ * Banish effect
+ *
+ * @example "Banish chosen character"
+ * @example "Banish all opposing items"
+ */
+export interface BanishEffect {
+  type: "banish";
+  target?: CharacterTarget | ItemTarget | LocationTarget;
+}
+
+// ============================================================================
+// Look At / Reveal Effects
+// ============================================================================
+
+/**
+ * Look at cards effect
+ *
+ * @example "Look at the top 3 cards of your deck"
+ */
+export interface LookAtCardsEffect {
+  type: "look-at-cards";
+  amount: Amount;
+  source: "deck" | "hand" | "discard";
+  target: PlayerTarget;
+}
+
+/**
+ * Put card into hand effect
+ *
+ * @example "Put a card into your hand"
+ */
+export interface PutInHandEffect {
+  type: "put-in-hand";
+  source: "deck" | "discard" | "revealed";
+  target: PlayerTarget;
+}