@drmxrcy/tcg-lorcana-types 0.0.0-202602060544

package/src/abilities/effect-types/control-flow.ts

@@ -0,0 +1,317 @@
+/**
+ * Control Flow Effect Types
+ *
+ * Effects that control the flow of ability resolution:
+ * - Sequence (do A then B)
+ * - Choice (choose one of A or B)
+ * - Conditional (if X then A else B)
+ * - Optional (you may do A)
+ * - For-each (for each X, do A)
+ * - Repeat (do A X times)
+ */
+
+import type { Condition } from "../condition-types";
+import type { CharacterTarget, PlayerTarget } from "../target-types";
+import type { Amount, EffectDuration } from "./amount-types";
+
+// Forward reference - will be imported from combined-types at runtime
+// This avoids circular dependency during type checking
+import type { Effect } from "./combined-types";
+
+// ============================================================================
+// Control Flow Effects
+// ============================================================================
+
+/**
+ * Sequence of effects (executed in order)
+ *
+ * @example "Draw 2 cards, then choose and discard a card"
+ */
+export interface SequenceEffect {
+  type: "sequence";
+  /** Array of effects to execute in order (preferred name) */
+  steps?: Effect[];
+  /** Alias for steps - both are supported for parser compatibility */
+  effects?: Effect[];
+}
+
+/**
+ * Choose one of multiple effects
+ *
+ * @example "Choose one: Draw a card. Deal 2 damage to chosen character."
+ */
+export interface ChoiceEffect {
+  type: "choice";
+  /** Array of effect options (preferred name) */
+  options?: Effect[];
+  /** Alias for options - both are supported for parser compatibility */
+  choices?: Effect[];
+  /** Who makes the choice */
+  chooser?: PlayerTarget;
+  /** Who chooses (alternative field) */
+  chosenBy?: "you" | "opponent" | "TARGET";
+  /** Label/name for each option (for display) */
+  optionLabels?: string[];
+}
+
+/**
+ * Conditional effect (if/then/else)
+ *
+ * @example "If you have a character named Elsa, draw a card"
+ */
+export interface ConditionalEffect {
+  type: "conditional";
+  condition?: Condition;
+  /** Effect to execute if condition is true (preferred) */
+  then?: Effect;
+  /** Alternative field for then effect */
+  effect?: Effect;
+  /** Effect to execute if condition is false */
+  else?: Effect;
+  /** Alternative fields for if-true/if-false */
+  ifTrue?: Effect;
+  ifFalse?: Effect;
+}
+
+/**
+ * Optional effect ("you may")
+ *
+ * @example "You may draw a card"
+ */
+export interface OptionalEffect {
+  type: "optional";
+  effect?: Effect;
+  /** Who decides */
+  chooser?: PlayerTarget;
+}
+
+/**
+ * For-each effect (repeat for each X)
+ *
+ * @example "Gain 1 lore for each character you have in play"
+ */
+export interface ForEachEffect {
+  type: "for-each";
+  counter?: ForEachCounter;
+  effect?: Effect;
+  /** Maximum times to repeat (optional) */
+  maximum?: number;
+  /** Stat to modify (for static for-each effects) */
+  stat?: "strength" | "willpower" | "lore";
+  /** Modifier per count (for static for-each effects) */
+  modifier?: number;
+  /** Target for the effect */
+  target?: CharacterTarget;
+}
+
+/**
+ * What to count for for-each effects
+ */
+export type ForEachCounter =
+  | { type: "characters"; controller: "you" | "opponent" | "any" }
+  | { type: "damaged-characters"; controller: "you" | "opponent" | "any" }
+  | { type: "items"; controller: "you" | "opponent" }
+  | { type: "items-in-play"; controller: "you" | "opponent" }
+  | { type: "locations"; controller: "you" | "opponent" }
+  | { type: "cards-in-hand"; controller: "you" | "opponent" }
+  | { type: "cards-in-discard"; controller: "you" | "opponent" }
+  | { type: "damage-on-self" }
+  | { type: "damage-on-target" }
+  | { type: "cards-under-self" }
+  | { type: "characters-that-sang"; thisTurn: boolean };
+
+/**
+ * Repeat effect X times
+ */
+export interface RepeatEffect {
+  type: "repeat";
+  times: Amount;
+  effect: Effect;
+}
+
+// ============================================================================
+// Additional Effect Types for Parser Support
+// ============================================================================
+
+/**
+ * Cost-effect pattern - pay a cost to get an effect
+ *
+ * @example "Return chosen character to your hand to play another character"
+ * @example "Banish one of your items to draw 2 cards"
+ */
+export interface CostEffectEffect {
+  type: "cost-effect";
+  cost: Effect | { ink?: number; type?: string; target?: string };
+  effect: Effect;
+}
+
+/**
+ * Reveal and conditional effect - reveal cards and act based on what's revealed
+ *
+ * @example "Reveal the top card. If it's a character, play it for free."
+ */
+export interface RevealAndConditionalEffect {
+  type: "reveal-and-conditional";
+  reveal: {
+    source: "deck" | "hand" | "discard";
+    count: number;
+    position?: "top" | "bottom";
+  };
+  condition: {
+    type: "card-type" | "classification" | "name" | "cost";
+    cardType?: string;
+    classification?: string;
+    name?: string;
+    maxCost?: number;
+  };
+  ifTrue: Effect;
+  ifFalse?: Effect;
+}
+
+/**
+ * Grant keyword effect (for triggered/action effects, not static)
+ *
+ * @example "Your characters gain Evasive this turn"
+ */
+export interface GrantKeywordEffect {
+  type: "grant-keyword";
+  keyword: string;
+  value?: number;
+  target: CharacterTarget;
+  duration?: EffectDuration;
+}
+
+/**
+ * Grant multiple keywords at once
+ *
+ * @example "Chosen character gains Challenger +2 and Resist +2 this turn"
+ */
+export interface GrantKeywordsEffect {
+  type: "grant-keywords";
+  keywords: Array<{ keyword: string; value?: number }>;
+  target: CharacterTarget;
+  duration?: EffectDuration;
+}
+
+/**
+ * Delayed effect - effect that happens at a later time
+ *
+ * @example "At the end of the turn, banish them"
+ */
+export interface DelayedEffect {
+  type: "delayed";
+  timing: "end-of-turn" | "start-of-next-turn" | "end-of-next-turn";
+  effect: Effect;
+}
+
+/**
+ * Play for free effect
+ *
+ * @example "Play a character with cost 4 or less for free"
+ */
+export interface PlayForFreeEffect {
+  type: "play-for-free";
+  filter?: {
+    cardType?: string;
+    maxCost?: number | string;
+    classification?: string;
+  };
+  enterExerted?: boolean;
+}
+
+/**
+ * Put on deck effect
+ *
+ * @example "Put the rest on the bottom of your deck in any order"
+ */
+export interface PutOnDeckEffect {
+  type: "put-on-deck";
+  position?: "top" | "bottom" | "choice";
+  order?: "any" | "random";
+  options?: Array<{ position: "top" | "bottom" } | string>;
+  target?: string;
+}
+
+/**
+ * Look effect (for looking at cards)
+ *
+ * @example "Look at the top 3 cards of your deck"
+ */
+export interface LookEffect {
+  type: "look";
+  source?: "deck" | "hand" | "discard";
+  position?: "top" | "bottom";
+  count?: number;
+}
+
+/**
+ * Put into hand effect
+ *
+ * @example "You may put one into your hand"
+ */
+export interface PutIntoHandEffect {
+  type: "put-into-hand";
+  count: number;
+  source?: "revealed" | "deck" | "discard";
+}
+
+/**
+ * Compound effect (legacy - use sequence instead)
+ * @deprecated Use SequenceEffect instead
+ */
+export interface CompoundEffect {
+  type: "compound";
+  effects?: Effect[];
+}
+
+/**
+ * For each opponent effect
+ */
+export interface ForEachOpponentEffect {
+  type: "for-each-opponent";
+  effect: Effect;
+  condition?: Condition;
+}
+
+/**
+ * For each player effect
+ */
+export interface ForEachPlayerEffect {
+  type: "for-each-player";
+  effect: Effect;
+}
+
+/**
+ * Prevent damage effect
+ */
+export interface PreventDamageEffect {
+  type: "prevent-damage";
+  amount?: Amount | "all";
+  target?: CharacterTarget;
+  source?: "challenges" | "abilities" | "all" | "CHALLENGE";
+}
+
+/**
+ * Gain ability effect (for triggered effects)
+ */
+export interface GainAbilityEffect {
+  type: "gain-ability";
+  ability?: {
+    type: string;
+    [key: string]: unknown;
+  };
+  target?: CharacterTarget;
+  duration?: EffectDuration;
+}
+
+/**
+ * Redirect damage effect
+ */
+export interface RedirectDamageEffect {
+  type: "redirect-damage";
+  from?: CharacterTarget;
+  to?: CharacterTarget;
+  target?: CharacterTarget;
+  /** Amount of damage to redirect */
+  amount?: Amount | "all";
+}

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

@@ -0,0 +1,136 @@
+/**
+ * Effect Types Index
+ *
+ * Re-exports all effect types and type guards from sub-modules.
+ * Import from this file for all effect-related types.
+ */
+
+// Shared types
+export type {
+  Amount,
+  AmountString,
+  EffectDuration,
+  ForEachCounterType,
+  VariableAmount,
+} from "./amount-types";
+export { isVariableAmount } from "./amount-types";
+
+// Basic effects
+export type {
+  BanishEffect,
+  DealDamageEffect,
+  DiscardEffect,
+  DrawEffect,
+  ExertEffect,
+  GainLoreEffect,
+  LoseLoreEffect,
+  MoveDamageEffect,
+  PutDamageEffect,
+  ReadyEffect,
+  RemoveDamageEffect,
+} from "./basic-effects";
+// Combined types and guards
+export type {
+  ChallengeReadyEffect,
+  Effect,
+  EntersPlayWithEffect,
+  GainKeywordsEffect,
+  ReplacementEffect,
+  StaticEffect,
+} from "./combined-types";
+export {
+  isControlFlowEffect,
+  isScryEffect,
+  targetsCharacters,
+} from "./combined-types";
+// Control flow effects
+export type {
+  ChoiceEffect,
+  CompoundEffect,
+  ConditionalEffect,
+  CostEffectEffect,
+  DelayedEffect,
+  ForEachCounter,
+  ForEachEffect,
+  ForEachOpponentEffect,
+  ForEachPlayerEffect,
+  GainAbilityEffect,
+  GrantKeywordEffect,
+  GrantKeywordsEffect,
+  LookEffect,
+  OptionalEffect,
+  PlayForFreeEffect,
+  PreventDamageEffect,
+  PutIntoHandEffect,
+  PutOnDeckEffect,
+  RedirectDamageEffect,
+  RepeatEffect,
+  RevealAndConditionalEffect,
+  SequenceEffect,
+} from "./control-flow";
+
+// Modifier effects
+export type {
+  CostReductionEffect,
+  DrawUntilHandSizeEffect,
+  EntersPlayEffect,
+  GainKeywordEffect,
+  GrantAbilityEffect,
+  LoseKeywordEffect,
+  ModifyStatEffect,
+  NameACardEffect,
+  PropertyModificationEffect,
+  PutOnTopEffect,
+  RestrictionEffect,
+  RevealHandEffect,
+  RevealTopCardEffect,
+  SearchDeckEffect,
+  SetStatEffect,
+  WinConditionEffect,
+} from "./modifier-effects";
+// Movement effects
+export type {
+  EnablePlayFromUnderEffect,
+  GrantAbilitiesWhileHereEffect,
+  MoveCostReductionEffect,
+  MoveToLocationEffect,
+  PlayCardEffect,
+  PutIntoInkwellEffect,
+  PutOnBottomEffect,
+  PutUnderEffect,
+  ReturnFromDiscardEffect,
+  ReturnToHandEffect,
+  ShuffleIntoDeckEffect,
+} from "./movement-effects";
+// Scry effects
+export type {
+  ScryAndFilter,
+  ScryCardFilter,
+  ScryCardOrdering,
+  ScryCardTypeFilter,
+  ScryClassificationFilter,
+  ScryCostComparisonFilter,
+  ScryDeckBottomDestination,
+  ScryDeckTopDestination,
+  ScryDestination,
+  ScryDiscardDestination,
+  ScryEffect,
+  ScryFloodbornFilter,
+  ScryHandDestination,
+  ScryInkwellDestination,
+  ScryKeywordFilter,
+  ScryNameFilter,
+  ScryNotFilter,
+  ScryOrFilter,
+  ScryPlayDestination,
+  ScrySongFilter,
+} from "./scry-effects";
+export {
+  isScryDeckBottomDestination,
+  isScryDeckTopDestination,
+  isScryDiscardDestination,
+  isScryHandDestination,
+  isScryInkwellDestination,
+  isScryPlayDestination,
+  isScryRemainderDestination,
+} from "./scry-effects";

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

@@ -0,0 +1,248 @@
+/**
+ * Modifier Effect Types
+ *
+ * Effects that modify game state or card properties:
+ * - Stat modifications (strength, willpower, lore)
+ * - Keyword granting/removal
+ * - Restrictions
+ * - Special state modifications
+ * - Reveal/Search effects
+ */
+
+import type { CardType } from "../../cards/card-types";
+import type { Condition } from "../condition-types";
+import type {
+  CardTarget,
+  CharacterTarget,
+  LocationTarget,
+  PlayerTarget,
+} from "../target-types";
+import type { Amount, EffectDuration } from "./amount-types";
+
+// ============================================================================
+// Stat Modification Effects
+// ============================================================================
+
+/**
+ * Modify stat effect (for "this turn" effects)
+ *
+ * @example "Chosen character gets +2 strength this turn"
+ * @example "Your characters get +1 lore this turn"
+ */
+export interface ModifyStatEffect {
+  type: "modify-stat";
+  stat?: "strength" | "willpower" | "lore";
+  modifier?: Amount;
+  target?: CharacterTarget | LocationTarget;
+  duration?: EffectDuration;
+  /** Alternative field for modifier value */
+  value?: Amount;
+}
+
+/**
+ * Set stat effect (absolute value)
+ */
+export interface SetStatEffect {
+  type: "set-stat";
+  stat: "strength" | "willpower" | "lore";
+  value: Amount;
+  target: CharacterTarget;
+  duration?: EffectDuration;
+}
+
+// ============================================================================
+// Keyword Effects
+// ============================================================================
+
+/**
+ * Grant keyword effect
+ *
+ * @example "Chosen character gains Rush this turn"
+ * @example "Your characters gain Resist +2 this turn"
+ */
+export interface GainKeywordEffect {
+  type: "gain-keyword";
+  keyword?:
+    | "Rush"
+    | "Ward"
+    | "Evasive"
+    | "Bodyguard"
+    | "Support"
+    | "Reckless"
+    | "Alert"
+    | "Challenger"
+    | "Resist"
+    | "Singer"
+    | "Sing Together"
+    | string; // Allow any keyword string for flexibility
+  /** For Challenger +X and Resist +X */
+  value?: number;
+  target?: CharacterTarget;
+  duration?: EffectDuration;
+}
+
+/**
+ * Lose keyword effect
+ */
+export interface LoseKeywordEffect {
+  type: "lose-keyword";
+  keyword: string;
+  target: CharacterTarget;
+  duration?: EffectDuration;
+}
+
+// ============================================================================
+// Restriction Effects
+// ============================================================================
+
+/**
+ * Apply restriction effect
+ *
+ * @example "Chosen character can't quest during their next turn"
+ * @example "Characters can't be challenged while here"
+ */
+export interface RestrictionEffect {
+  type: "restriction";
+  restriction?:
+    | "cant-quest"
+    | "cant-challenge"
+    | "cant-be-challenged"
+    | "cant-ready"
+    | "cant-quest-or-challenge"
+    | "cant-be-dealt-damage"
+    | "cant-sing"
+    | "cant-move"
+    | "enters-play-exerted"
+    | "skip-draw-step"
+    | "must-quest" // Forces character to quest if able
+    | "cant-play-actions" // Opponents can't play actions
+    | "cant-play-characters" // Opponents can't play characters
+    | "cant-play" // Generic can't play restriction
+    // Extended restrictions for card text coverage
+    | "doesnt-ready"; // Character doesn't ready (alias for cant-ready)
+  target?: CharacterTarget | PlayerTarget;
+  duration?: EffectDuration;
+  /** Condition for when the restriction applies */
+  condition?: Condition;
+}
+
+/**
+ * Grant ability effect (can challenge ready characters, etc.)
+ */
+export interface GrantAbilityEffect {
+  type: "grant-ability";
+  ability?:
+    | "can-challenge-ready"
+    | "takes-no-damage-from-challenges"
+    | "return-to-hand-when-banished"
+    | { type: string; [key: string]: unknown }; // Allow object-based abilities
+  target?: CharacterTarget;
+  duration?: EffectDuration;
+}
+
+/**
+ * Reduce cost effect
+ *
+ * @example "You pay 1 less to play this item"
+ */
+export interface CostReductionEffect {
+  type: "cost-reduction";
+  amount?: Amount | string;
+  /** Alternative field for reduction amount */
+  reduction?: { ink: number | string };
+  cardType?: CardType | "song";
+  target?: PlayerTarget; // Who gets the reduction (usually YOU)
+  duration?: EffectDuration;
+}
+
+// ============================================================================
+// Misc Effects
+// ============================================================================
+
+export interface NameACardEffect {
+  type: "name-a-card";
+}
+
+export interface RevealTopCardEffect {
+  type: "reveal-top-card";
+  target?: PlayerTarget; // Whose deck
+}
+
+export interface PutOnTopEffect {
+  type: "put-on-top";
+  source?: "revealed" | CardTarget;
+}
+
+export interface DrawUntilHandSizeEffect {
+  type: "draw-until-hand-size";
+  size: number;
+  target?: PlayerTarget;
+}
+
+// ============================================================================
+// Special State Modifications
+// ============================================================================
+
+/**
+ * Enters play modification effect
+ *
+ * @example "Enters play exerted"
+ * @example "Enters play with 2 damage"
+ */
+export interface EntersPlayEffect {
+  type: "enters-play-modification";
+  modification: "exerted" | "damaged";
+  amount?: number; // for damaged
+  target: CharacterTarget;
+}
+
+/**
+ * Win condition modification effect
+ *
+ * @example "Opponents need 25 lore to win"
+ */
+export interface WinConditionEffect {
+  type: "win-condition-modification";
+  loreRequired: number;
+  target: PlayerTarget;
+}
+
+/**
+ * Property modification effect
+ *
+ * @example "This character counts as being named 'Dalmatian Puppy'"
+ */
+export interface PropertyModificationEffect {
+  type: "property-modification";
+  property?: "name";
+  value?: string;
+  operation?: "add-alias";
+  target?: CharacterTarget;
+}
+
+// ============================================================================
+// Reveal/Search Effects
+// ============================================================================
+
+/**
+ * Reveal hand effect
+ */
+export interface RevealHandEffect {
+  type: "reveal-hand";
+  target: PlayerTarget;
+}
+
+/**
+ * Search deck effect
+ */
+export interface SearchDeckEffect {
+  type: "search-deck";
+  cardType?: CardType | "song" | "floodborn";
+  cardName?: string;
+  classification?: string;
+  putInto?: "hand" | "top-of-deck" | "play";
+  /** Alias for putInto: "top-of-deck" */
+  putOnTop?: boolean;
+  reveal?: boolean;
+  shuffle?: boolean;
+}