@drmxrcy/tcg-lorcana-types 0.0.0-202602060544

package/src/abilities/helpers/Conditions.ts

@@ -0,0 +1,266 @@
+/**
+ * Condition Helpers for Lorcana Abilities
+ *
+ * Provides a fluent API for building condition definitions.
+ * These helpers make it easy to construct common condition patterns.
+ *
+ * @example
+ * ```typescript
+ * const condition = Conditions.HasAnotherCharacter();
+ * const condition = Conditions.HasCharacterNamed("Elsa");
+ * const condition = Conditions.WhileDamaged();
+ * ```
+ */
+
+import type { Condition } from "../condition-types";
+
+export const Conditions = {
+  /**
+   * "If you have another character in play"
+   */
+  HasAnotherCharacter: (): Condition => ({
+    type: "has-another-character",
+  }),
+
+  /**
+   * "If you have a character named X"
+   */
+  HasCharacterNamed: (name: string): Condition => ({
+    type: "has-named-character",
+    name,
+    controller: "you",
+  }),
+
+  /**
+   * "If you have a character with classification X"
+   */
+  HasCharacterWithClassification: (classification: string): Condition => ({
+    type: "has-character-with-classification",
+    classification,
+    controller: "you",
+  }),
+
+  /**
+   * "If you have a character with keyword X"
+   */
+  HasCharacterWithKeyword: (keyword: string): Condition => ({
+    type: "has-character-with-keyword",
+    keyword,
+    controller: "you",
+  }),
+
+  /**
+   * "While this character has damage"
+   */
+  WhileDamaged: (): Condition => ({
+    type: "has-any-damage",
+  }),
+
+  /**
+   * "While this character has no damage"
+   */
+  WhileNoDamage: (): Condition => ({
+    type: "has-no-damage",
+  }),
+
+  /**
+   * "While this character is exerted"
+   */
+  WhileExerted: (): Condition => ({
+    type: "is-exerted",
+  }),
+
+  /**
+   * "While this character is ready"
+   */
+  WhileReady: (): Condition => ({
+    type: "is-ready",
+  }),
+
+  /**
+   * "While in a challenge"
+   */
+  InChallenge: (): Condition => ({
+    type: "in-challenge",
+  }),
+
+  /**
+   * "If you have X or more cards in hand"
+   */
+  HandSizeAtLeast: (amount: number): Condition => ({
+    type: "resource-count",
+    what: "cards-in-hand",
+    controller: "you",
+    comparison: "greater-or-equal",
+    value: amount,
+  }),
+
+  /**
+   * "If you have X or fewer cards in hand"
+   */
+  HandSizeAtMost: (amount: number): Condition => ({
+    type: "resource-count",
+    what: "cards-in-hand",
+    controller: "you",
+    comparison: "less-or-equal",
+    value: amount,
+  }),
+
+  /**
+   * "If you have no cards in hand"
+   */
+  HandIsEmpty: (): Condition => ({
+    type: "resource-count",
+    what: "cards-in-hand",
+    controller: "you",
+    comparison: "equal",
+    value: 0,
+  }),
+
+  /**
+   * "If you have X or more lore"
+   */
+  LoreAtLeast: (amount: number): Condition => ({
+    type: "lore-comparison",
+    comparison: "greater-or-equal",
+    value: amount,
+  }),
+
+  /**
+   * "If you have X or fewer lore"
+   */
+  LoreAtMost: (amount: number): Condition => ({
+    type: "lore-comparison",
+    comparison: "less-or-equal",
+    value: amount,
+  }),
+
+  /**
+   * "If you have a card under this character"
+   */
+  HasCardUnder: (): Condition => ({
+    type: "has-card-under",
+  }),
+
+  /**
+   * "If this is the first time this turn"
+   */
+  FirstTimeThisTurn: (): Condition => ({
+    type: "first-this-turn",
+    event: "action",
+  }),
+
+  /**
+   * "If you used Shift this turn"
+   */
+  UsedShiftThisTurn: (): Condition => ({
+    type: "used-shift",
+  }),
+
+  /**
+   * "If you have a character in play"
+   */
+  HaveCharacterInPlay: (): Condition => ({
+    type: "has-named-character",
+    controller: "you",
+  }),
+
+  /**
+   * "If you have an item in play"
+   */
+  HaveItemInPlay: (): Condition => ({
+    type: "has-named-item",
+    name: "",
+    controller: "you",
+  }),
+
+  /**
+   * "If you have a location in play"
+   */
+  HaveLocationInPlay: (): Condition => ({
+    type: "has-named-location",
+    name: "",
+    controller: "you",
+  }),
+
+  /**
+   * "If you have a card with classification X in play"
+   */
+  HaveClassificationInPlay: (classification: string): Condition => ({
+    type: "has-character-with-classification",
+    classification,
+    controller: "you",
+  }),
+
+  /**
+   * "If you have a card with keyword X in play"
+   */
+  HaveKeywordInPlay: (keyword: string): Condition => ({
+    type: "has-character-with-keyword",
+    keyword,
+    controller: "you",
+  }),
+
+  /**
+   * "If you have a card named X in play"
+   */
+  HaveNamedInPlay: (name: string): Condition => ({
+    type: "has-named-character",
+    name,
+    controller: "you",
+  }),
+
+  /**
+   * "If you have X or more characters in play"
+   */
+  CharacterCountAtLeast: (amount: number): Condition => ({
+    type: "has-character-count",
+    controller: "you",
+    comparison: "greater-or-equal",
+    count: amount,
+  }),
+
+  /**
+   * "If you have X or fewer characters in play"
+   */
+  CharacterCountAtMost: (amount: number): Condition => ({
+    type: "has-character-count",
+    controller: "you",
+    comparison: "less-or-equal",
+    count: amount,
+  }),
+
+  /**
+   * "If you have exactly X characters in play"
+   */
+  CharacterCountExactly: (amount: number): Condition => ({
+    type: "has-character-count",
+    controller: "you",
+    comparison: "equal",
+    count: amount,
+  }),
+
+  /**
+   * Logical AND - all conditions must be true
+   */
+  And: (...conditions: Condition[]): Condition => ({
+    type: "and",
+    conditions,
+  }),
+
+  /**
+   * Logical OR - any condition must be true
+   */
+  Or: (...conditions: Condition[]): Condition => ({
+    type: "or",
+    conditions,
+  }),
+
+  /**
+   * Logical NOT - negate a condition
+   */
+  Not: (condition: Condition): Condition => ({
+    type: "not",
+    condition,
+  }),
+};

package/src/abilities/helpers/Costs.ts

@@ -0,0 +1,83 @@
+/**
+ * Cost Helpers for Lorcana Abilities
+ *
+ * Provides a fluent API for building cost definitions.
+ * These helpers make it easy to construct common cost patterns.
+ *
+ * @example
+ * ```typescript
+ * const cost = Costs.Ink(2);
+ * const cost = Costs.Exert();
+ * const cost = Costs.Combined(Costs.Ink(1), Costs.Exert());
+ * ```
+ */
+
+import type { AbilityCost } from "../cost-types";
+
+export const Costs = {
+  /**
+   * "X ink cost"
+   */
+  Ink: (amount: number): AbilityCost => ({ ink: amount }),
+
+  /**
+   * "Exert this character"
+   */
+  Exert: (): AbilityCost => ({ exert: true }),
+
+  /**
+   * "Banish this character"
+   */
+  BanishSelf: (): AbilityCost => ({ banishSelf: true }),
+
+  /**
+   * "Discard a card"
+   */
+  Discard: (amount = 1): AbilityCost => ({
+    discardCards: amount,
+  }),
+
+  /**
+   * "Return this card to hand"
+   */
+  ReturnToHand: (): AbilityCost => ({ returnSelfToHand: true }),
+
+  /**
+   * "Damage this character X"
+   */
+  DamageSelf: (amount: number): AbilityCost => ({
+    damageSelf: amount,
+  }),
+
+  /**
+   * "X ink and exert"
+   */
+  InkAndExert: (amount: number): AbilityCost => ({
+    ink: amount,
+    exert: true,
+  }),
+
+  /**
+   * "X ink and banish"
+   */
+  InkAndBanish: (amount: number): AbilityCost => ({
+    ink: amount,
+    banishSelf: true,
+  }),
+
+  /**
+   * "X ink and discard"
+   */
+  InkAndDiscard: (amount: number, discardAmount = 1): AbilityCost => ({
+    ink: amount,
+    discardCards: discardAmount,
+  }),
+
+  /**
+   * "Exert and banish"
+   */
+  ExertAndBanish: (): AbilityCost => ({
+    exert: true,
+    banishSelf: true,
+  }),
+};

package/src/abilities/helpers/Effects.ts

@@ -0,0 +1,182 @@
+/**
+ * Effect Helpers for Lorcana Abilities
+ *
+ * Provides a fluent API for building effect definitions.
+ * These helpers make it easy to construct common effect patterns.
+ *
+ * @example
+ * ```typescript
+ * const effect = Effects.Draw({ amount: 2 });
+ * const effect = Effects.Banish({ target: Targets.ChallengedCharacter(), optional: true });
+ * const effect = Effects.RemoveDamage({ amount: 2, target: Targets.Self() });
+ * ```
+ */
+
+import type { Effect, OptionalEffect } from "../effect-types";
+import type {
+  CardTarget,
+  CharacterTarget,
+  PlayerTarget,
+} from "../target-types";
+
+export const Effects = {
+  /**
+   * "Draw X cards"
+   */
+  Draw: (params: { amount: number }): Effect => ({
+    type: "draw",
+    amount: params.amount,
+  }),
+
+  /**
+   * "Banish chosen character" or "You may banish chosen character"
+   */
+  Banish: (params: { target: CharacterTarget; optional?: boolean }): Effect => {
+    const banishEffect: Effect = {
+      type: "banish",
+      target: params.target,
+    };
+
+    return params.optional
+      ? { type: "optional", effect: banishEffect }
+      : banishEffect;
+  },
+
+  /**
+   * "Remove up to X damage from target"
+   */
+  RemoveDamage: (params: {
+    amount: number;
+    target: CharacterTarget;
+    upTo?: boolean;
+  }): Effect => ({
+    type: "remove-damage",
+    amount: params.amount,
+    target: params.target,
+    upTo: params.upTo,
+  }),
+
+  /**
+   * "Target gains keyword"
+   */
+  GainKeyword: (params: {
+    keyword: string;
+    target?: CharacterTarget;
+  }): Effect => ({
+    type: "gain-keyword",
+    keyword: params.keyword,
+    target: params.target ?? "SELF",
+  }),
+
+  /**
+   * "Sequence of effects"
+   */
+  Sequence: (effects: Effect[]): Effect => ({
+    type: "sequence",
+    effects,
+  }),
+
+  /**
+   * "You may [effect]"
+   */
+  Optional: (effect: Effect): OptionalEffect => ({
+    type: "optional",
+    effect,
+  }),
+
+  /**
+   * "Deal X damage to target"
+   */
+  DealDamage: (params: {
+    amount: number;
+    target: CharacterTarget;
+  }): Effect => ({
+    type: "deal-damage",
+    amount: params.amount,
+    target: params.target,
+  }),
+
+  /**
+   * "Gain X lore"
+   */
+  GainLore: (params: { amount: number }): Effect => ({
+    type: "gain-lore",
+    amount: params.amount,
+  }),
+
+  /**
+   * "Lose X lore"
+   */
+  LoseLore: (params: { amount: number }): Effect => ({
+    type: "lose-lore",
+    amount: params.amount,
+  }),
+
+  /**
+   * "Exert target"
+   */
+  Exert: (params?: { target?: CharacterTarget }): Effect => ({
+    type: "exert",
+    target: params?.target ?? "SELF",
+  }),
+
+  /**
+   * "Ready target"
+   */
+  Ready: (params?: { target?: CharacterTarget }): Effect => ({
+    type: "ready",
+    target: params?.target ?? "SELF",
+  }),
+
+  /**
+   * "Return target to hand"
+   */
+  ReturnToHand: (params: { target: CharacterTarget }): Effect => ({
+    type: "return-to-hand",
+    target: params.target,
+  }),
+
+  /**
+   * "Discard target"
+   */
+  Discard: (params?: { target?: CharacterTarget }): Effect => ({
+    type: "discard",
+  }),
+
+  /**
+   * "Put target into inkwell"
+   */
+  PutIntoInkwell: (params?: { target?: CharacterTarget }): Effect => ({
+    type: "put-into-inkwell",
+  }),
+
+  /**
+   * "Search deck for card and put into hand"
+   */
+  SearchDeck: (): Effect => ({
+    type: "search-deck",
+  }),
+
+  /**
+   * "Shuffle target into deck"
+   */
+  ShuffleIntoDeck: (params: { target: CharacterTarget }): Effect => ({
+    type: "shuffle-into-deck",
+    target: params.target,
+  }),
+
+  /**
+   * "Put target on top of deck"
+   */
+  PutOnTop: (params: { target: CharacterTarget }): Effect => ({
+    type: "put-on-top",
+  }),
+
+  /**
+   * "Put target on bottom of deck"
+   */
+  PutOnBottom: (params: { target: CharacterTarget }): Effect => ({
+    type: "put-on-bottom",
+    target: params.target,
+  }),
+};

package/src/abilities/helpers/Targets.ts

@@ -0,0 +1,193 @@
+/**
+ * Target Helpers for Lorcana Abilities
+ *
+ * Provides a fluent API for building target definitions.
+ * These helpers make it easy to construct common target patterns.
+ *
+ * @example
+ * ```typescript
+ * const target = Targets.Self();
+ * const target = Targets.ChallengedCharacter();
+ * const target = Targets.YourCharacters();
+ * ```
+ */
+
+import type {
+  CardTarget,
+  CharacterTarget,
+  PlayerTarget,
+} from "../target-types";
+
+export const Targets = {
+  // ========================================================================
+  // Self/Controller Targets
+  // ========================================================================
+
+  /**
+   * "This character" or "this card"
+   */
+  Self: (): CardTarget => "SELF",
+
+  /**
+   * "You" (for player-targeted effects)
+   */
+  Controller: (): PlayerTarget => "CONTROLLER",
+
+  /**
+   * "Your opponent"
+   */
+  Opponent: (): PlayerTarget => "OPPONENT",
+
+  // ========================================================================
+  // Character Targets
+  // ========================================================================
+
+  /**
+   * "Chosen character"
+   */
+  ChosenCharacter: (): CharacterTarget => "CHOSEN_CHARACTER",
+
+  /**
+   * "Challenged character"
+   */
+  ChallengedCharacter: (): CharacterTarget => "CHALLENGED_CHARACTER",
+
+  /**
+   * "Challenging character"
+   */
+  ChallengingCharacter: (): CharacterTarget => "CHALLENGING_CHARACTER",
+
+  // ========================================================================
+  // Your Characters
+  // ========================================================================
+
+  /**
+   * "Your characters"
+   */
+  YourCharacters: (): CharacterTarget => "YOUR_CHARACTERS",
+
+  /**
+   * "Your other characters"
+   */
+  YourOtherCharacters: (): CharacterTarget => "YOUR_OTHER_CHARACTERS",
+
+  // ========================================================================
+  // Opponent Characters
+  // ========================================================================
+
+  /**
+   * "Opponent's characters"
+   */
+  OpponentCharacters: (): CharacterTarget => "ALL_OPPOSING_CHARACTERS",
+
+  /**
+   * "Opposing characters"
+   */
+  OpposingCharacters: (): CharacterTarget => "OPPOSING_CHARACTERS",
+
+  // ========================================================================
+  // Classification-based Targets
+  // ========================================================================
+
+  /**
+   * "Your Musketeer characters"
+   */
+  YourMusketeers: (): CharacterTarget => "YOUR_MUSKETEER_CHARACTERS",
+
+  /**
+   * "Your Villain characters"
+   */
+  YourVillains: (): CharacterTarget => "YOUR_VILLAIN_CHARACTERS",
+
+  /**
+   * "Your Broom characters"
+   */
+  YourBrooms: (): CharacterTarget => "YOUR_BROOM_CHARACTERS",
+
+  /**
+   * "Your other Steel characters"
+   */
+  YourOtherSteelCharacters: (): CharacterTarget =>
+    "YOUR_OTHER_STEEL_CHARACTERS",
+
+  /**
+   * "Your other Amethyst characters"
+   */
+  YourOtherAmethystCharacters: (): CharacterTarget =>
+    "YOUR_OTHER_AMETHYST_CHARACTERS",
+
+  // ========================================================================
+  // Zone-based Targets
+  // ========================================================================
+
+  /**
+   * "Character from discard"
+   */
+  CharacterFromDiscard: (): CharacterTarget => "CHOSEN_CHARACTER_IN_DISCARD",
+
+  /**
+   * "Characters at this location"
+   */
+  CharactersHere: (): CharacterTarget => "CHARACTERS_HERE",
+
+  // ========================================================================
+  // All/Each Targets
+  // ========================================================================
+
+  /**
+   * "All characters"
+   */
+  AllCharacters: (): CharacterTarget => "ALL_CHARACTERS",
+
+  /**
+   * "All your characters"
+   */
+  AllYourCharacters: (): CharacterTarget => "YOUR_CHARACTERS",
+
+  /**
+   * "All opponent characters"
+   */
+  AllOpponentCharacters: (): CharacterTarget => "ALL_OPPOSING_CHARACTERS",
+
+  // ========================================================================
+  // Item Targets
+  // ========================================================================
+
+  /**
+   * "Your items"
+   */
+  YourItems: (): CardTarget => "YOUR_ITEMS",
+
+  /**
+   * "Chosen item"
+   */
+  ChosenItem: (): CardTarget => "CHOSEN_ITEM",
+
+  // ========================================================================
+  // Location Targets
+  // ========================================================================
+
+  /**
+   * "Your locations"
+   */
+  YourLocations: (): CardTarget => "YOUR_LOCATIONS",
+
+  /**
+   * "Chosen location"
+   */
+  ChosenLocation: (): CardTarget => "CHOSEN_LOCATION",
+
+  // ========================================================================
+  // Generic Targets
+  // ========================================================================
+
+  /**
+   * "Any character"
+   */
+  AnyCharacter: (): CharacterTarget => "ALL_CHARACTERS",
+
+  /**
+   * "All characters"
+   */
+  AllCharactersTarget: (): CharacterTarget => "ALL_CHARACTERS",
+};