@drmxrcy/tcg-lorcana-types 0.0.0-202602060544

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

@@ -0,0 +1,216 @@
+/**
+ * Movement Effect Types
+ *
+ * Effects that move cards between zones:
+ * - Return to hand
+ * - Put into inkwell
+ * - Shuffle into deck
+ * - Play cards from various zones
+ * - Move characters to locations
+ */
+
+import type { CardType } from "../../cards/card-types";
+import type {
+  CardTarget,
+  CharacterTarget,
+  ItemTarget,
+  LocationTarget,
+  PlayerTarget,
+} from "../target-types";
+import type { EffectDuration } from "./amount-types";
+
+// ============================================================================
+// Zone Movement Effects
+// ============================================================================
+
+/**
+ * Return to hand effect
+ *
+ * @example "Return chosen character to their player's hand"
+ */
+export interface ReturnToHandEffect {
+  type: "return-to-hand";
+  target?: CardTarget;
+  /** Filter for what can be returned */
+  filter?: {
+    cardType?: CardType | "song";
+    maxCost?: number;
+    classification?: string;
+    name?: string;
+  };
+  /** Amount of cards to return */
+  amount?: number;
+}
+
+/**
+ * Return from discard to hand
+ *
+ * @example "Return an action card from your discard to your hand"
+ */
+export interface ReturnFromDiscardEffect {
+  type: "return-from-discard";
+  cardType?: CardType | "song";
+  cardName?: string;
+  target?: PlayerTarget;
+  count?: number;
+  destination?: "hand" | "play" | "top-of-deck";
+}
+
+/**
+ * Put into inkwell effect
+ *
+ * @example "Put the top card of your deck into your inkwell facedown and exerted"
+ */
+export interface PutIntoInkwellEffect {
+  type: "put-into-inkwell";
+  source?:
+    | "top-of-deck"
+    | "hand"
+    | "chosen-card-in-play"
+    | "chosen-character"
+    | "this-card"
+    | "discard"
+    | "revealed"
+    | "deck"
+    | CardTarget;
+  target?: PlayerTarget | CharacterTarget | "SELF";
+  cardType?: CardType;
+  exerted?: boolean;
+  /** Whether the card is placed facedown in the inkwell */
+  facedown?: boolean;
+  /** Position in deck to take from */
+  position?: "top" | "bottom";
+  /** Who chooses the card */
+  chosenBy?: "you" | "opponent" | "TARGET";
+}
+
+/**
+ * Put card under another card (Boost mechanic)
+ */
+export interface PutUnderEffect {
+  type: "put-under";
+  source: "top-of-deck" | "hand" | "discard";
+  under: CharacterTarget | LocationTarget | "self";
+  cardType?: CardType;
+}
+
+/**
+ * Shuffle into deck effect
+ */
+export interface ShuffleIntoDeckEffect {
+  type: "shuffle-into-deck";
+  target?: CharacterTarget | ItemTarget | LocationTarget | CardTarget;
+  /** Whose deck to shuffle into */
+  intoDeck?: "owner" | "controller";
+}
+
+/**
+ * Put on bottom of deck
+ */
+export interface PutOnBottomEffect {
+  type: "put-on-bottom";
+  target: CharacterTarget | ItemTarget | LocationTarget;
+}
+
+// ============================================================================
+// Play Card Effects
+// ============================================================================
+
+/**
+ * Play a card effect
+ *
+ * @example "Play a character with cost 3 or less for free"
+ * @example "Play a character from your discard for free"
+ */
+export interface PlayCardEffect {
+  type: "play-card";
+  from?: "hand" | "discard" | "deck" | "under-self";
+  cardType?: CardType | "song" | "floodborn";
+  costRestriction?: { comparison: "less-or-equal" | "equal"; value: number };
+  cost?: "free" | "reduced";
+  reducedBy?: number;
+  /** Character enters play exerted */
+  entersExerted?: boolean;
+  /** Grants Rush for this turn */
+  grantsRush?: boolean;
+  /** Banish at end of turn */
+  banishAtEndOfTurn?: boolean;
+  /** Filter for what can be played */
+  filter?: {
+    cardType?: CardType | "song" | "floodborn";
+    maxCost?: number;
+    classification?: string;
+    name?: string;
+  };
+  /** Whether to play for free (alias for cost: "free") */
+  free?: boolean;
+  /** Target for the play effect */
+  target?: string;
+}
+
+/**
+ * Enable playing from under a card
+ */
+export interface EnablePlayFromUnderEffect {
+  type: "enable-play-from-under";
+  cardType?: CardType | "song" | "floodborn";
+  duration?: EffectDuration;
+}
+
+// ============================================================================
+// Location Movement Effects
+// ============================================================================
+
+/**
+ * Move character to location
+ *
+ * @example "Move a character of yours to a location for free"
+ */
+export interface MoveToLocationEffect {
+  type: "move-to-location";
+  character: CharacterTarget;
+  location?: LocationTarget;
+  cost?: "free" | "normal";
+}
+
+/**
+ * Move cost reduction effect for locations
+ *
+ * @example "Your characters named Robin Hood may move here for free"
+ * @example "Your Pirate characters may move here for free"
+ */
+export interface MoveCostReductionEffect {
+  type: "move-cost-reduction";
+  /** Filter for which characters get the reduction */
+  filter?: {
+    name?: string;
+    classification?: string;
+  };
+  /** How much to reduce the cost (0 = free) */
+  reduction: number | "free";
+  /** Target location (usually "here" for location abilities) */
+  location?: "here" | LocationTarget;
+}
+
+/**
+ * Grant abilities to characters while at this location
+ *
+ * @example "Characters gain Ward while here"
+ * @example "Characters gain Ward and activated ability while here"
+ */
+export interface GrantAbilitiesWhileHereEffect {
+  type: "grant-abilities-while-here";
+  abilities: Array<
+    | { type: "keyword"; keyword: string; value?: number }
+    | {
+        type: "activated";
+        cost: { exert?: boolean; ink?: number };
+        effect: {
+          type: string;
+          amount?: number;
+          target?: unknown;
+          [key: string]: unknown;
+        };
+      }
+  >;
+}

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

@@ -0,0 +1,269 @@
+/**
+ * Scry Effect Types
+ *
+ * Defines the "look at top X cards" effect system with declarative destinations.
+ * Used for effects like "Look at the top 4 cards of your deck..."
+ */
+
+import type { CardType } from "../../cards/card-types";
+import type { PlayerTarget } from "../target-types";
+import type { Amount, VariableAmount } from "./amount-types";
+
+// ============================================================================
+// Scry Effect
+// ============================================================================
+
+/**
+ * Scry effect - Look at top cards and distribute to destinations
+ *
+ * Replaces the old LookAtCardsEffect with a declarative destinations array.
+ *
+ * Design principles:
+ * 1. Declarative: Describes WHAT happens, not HOW
+ * 2. Composable: Multiple independent selections from same pool
+ * 3. Parser-friendly: Can be constructed from natural language
+ *
+ * @example "Look at top 4, reveal a character, put into hand, rest on bottom"
+ * @example "Look at top 5, reveal up to 1 Madrigal AND up to 1 song, put in hand"
+ */
+export interface ScryEffect {
+  type: "scry";
+  /** Number of cards to look at from top of deck */
+  amount?: Amount;
+  /** Whose deck to look at (default: CONTROLLER) */
+  target?: PlayerTarget;
+  /** Destinations for the looked-at cards, processed in order */
+  destinations?: ScryDestination[];
+  /** Whether all looked-at cards should be revealed to opponent */
+  revealAll?: boolean;
+}
+
+// ============================================================================
+// Scry Destinations (Discriminated Union)
+// ============================================================================
+
+/**
+ * A destination describes where cards can go and constraints on the selection.
+ * Uses discriminated union on 'zone' property for type safety.
+ */
+export type ScryDestination =
+  | ScryHandDestination
+  | ScryDeckTopDestination
+  | ScryDeckBottomDestination
+  | ScryInkwellDestination
+  | ScryPlayDestination
+  | ScryDiscardDestination;
+
+/**
+ * Base properties shared by all scry destinations
+ */
+interface ScryBaseDestination {
+  /** Minimum cards that MUST go to this destination (default: 0) */
+  min?: number;
+  /** Maximum cards that CAN go to this destination */
+  max?: number;
+  /** Filter for which cards can go to this destination */
+  filter?: ScryCardFilter | ScryCardFilter[];
+  /** Whether cards going here must be revealed to opponent */
+  reveal?: boolean;
+  /** Mark as remainder destination - receives all unselected cards */
+  remainder?: boolean;
+  /** Destinations in the same exclusiveGroup are mutually exclusive */
+  exclusiveGroup?: string;
+  /** Label for UI display (e.g., "up to 1 Madrigal character") */
+  label?: string;
+}
+
+/** Put cards into hand */
+export interface ScryHandDestination extends ScryBaseDestination {
+  zone: "hand";
+}
+
+/** Put cards on top of deck */
+export interface ScryDeckTopDestination extends ScryBaseDestination {
+  zone: "deck-top";
+  /** How cards are ordered when placed on top */
+  ordering?: ScryCardOrdering;
+}
+
+/** Put cards on bottom of deck */
+export interface ScryDeckBottomDestination extends ScryBaseDestination {
+  zone: "deck-bottom";
+  /** How cards are ordered when placed on bottom */
+  ordering?: ScryCardOrdering;
+}
+
+/** Put cards into inkwell */
+export interface ScryInkwellDestination extends ScryBaseDestination {
+  zone: "inkwell";
+  /** Whether ink enters exerted (default: true) */
+  exerted?: boolean;
+  /** Whether card is facedown (default: true) */
+  facedown?: boolean;
+}
+
+/** Put cards into play (for "play for free" effects) */
+export interface ScryPlayDestination extends ScryBaseDestination {
+  zone: "play";
+  /** Cost modification when playing */
+  cost?: "free" | "reduced";
+  /** Amount to reduce cost by (when cost is "reduced") */
+  reducedBy?: number;
+  /** Additional filter for cost restriction (beyond selection filter) */
+  playFilter?: ScryCardFilter | ScryCardFilter[];
+  /** Character enters play exerted */
+  entersExerted?: boolean;
+  /** Grants Rush for this turn */
+  grantsRush?: boolean;
+  /** Banish at end of turn */
+  banishAtEndOfTurn?: boolean;
+}
+
+/** Put cards into discard */
+export interface ScryDiscardDestination extends ScryBaseDestination {
+  zone: "discard";
+}
+
+/** How cards are ordered when placed on deck */
+export type ScryCardOrdering =
+  | "player-choice" // Player decides order
+  | "original-order" // Keep original order from look
+  | "random"; // Shuffle before placing
+
+// ============================================================================
+// Scry Card Filters
+// ============================================================================
+
+/** Filters for selecting cards during scry */
+export type ScryCardFilter =
+  // Card Type Filters
+  | ScryCardTypeFilter
+  | ScrySongFilter
+  | ScryFloodbornFilter
+  // Property Filters
+  | ScryClassificationFilter
+  | ScryNameFilter
+  | ScryKeywordFilter
+  // Cost Filters
+  | ScryCostComparisonFilter
+  // Composite Filters
+  | ScryAndFilter
+  | ScryOrFilter
+  | ScryNotFilter;
+
+/** Filter by card type (character, item, action, location) */
+export interface ScryCardTypeFilter {
+  type: "card-type";
+  cardType: CardType;
+}
+
+/** Filter for songs specifically (action with song subtype) */
+export interface ScrySongFilter {
+  type: "song";
+}
+
+/** Filter for floodborn characters */
+export interface ScryFloodbornFilter {
+  type: "floodborn";
+}
+
+/** Filter by classification (e.g., "Madrigal", "Puppy", "Princess") */
+export interface ScryClassificationFilter {
+  type: "classification";
+  classification: string;
+}
+
+/** Filter by card name */
+export interface ScryNameFilter {
+  type: "name";
+  name: string;
+  /** Match mode: exact or contains */
+  match?: "exact" | "contains";
+}
+
+/** Filter by keyword (e.g., "Bodyguard", "Evasive") */
+export interface ScryKeywordFilter {
+  type: "keyword";
+  keyword: string;
+}
+
+/** Filter by cost comparison */
+export interface ScryCostComparisonFilter {
+  type: "cost-comparison";
+  comparison:
+    | "less-or-equal"
+    | "equal"
+    | "greater-or-equal"
+    | "less"
+    | "greater";
+  value: number | VariableAmount;
+}
+
+/** AND filter - all sub-filters must match */
+export interface ScryAndFilter {
+  type: "and";
+  filters: ScryCardFilter[];
+}
+
+/** OR filter - any sub-filter can match */
+export interface ScryOrFilter {
+  type: "or";
+  filters: ScryCardFilter[];
+}
+
+/** NOT filter - inverts the sub-filter */
+export interface ScryNotFilter {
+  type: "not";
+  filter: ScryCardFilter;
+}
+
+// ============================================================================
+// Scry Type Guards
+// ============================================================================
+
+/** Check if destination is a hand destination */
+export function isScryHandDestination(
+  dest: ScryDestination,
+): dest is ScryHandDestination {
+  return dest.zone === "hand";
+}
+
+/** Check if destination is a deck-top destination */
+export function isScryDeckTopDestination(
+  dest: ScryDestination,
+): dest is ScryDeckTopDestination {
+  return dest.zone === "deck-top";
+}
+
+/** Check if destination is a deck-bottom destination */
+export function isScryDeckBottomDestination(
+  dest: ScryDestination,
+): dest is ScryDeckBottomDestination {
+  return dest.zone === "deck-bottom";
+}
+
+/** Check if destination is an inkwell destination */
+export function isScryInkwellDestination(
+  dest: ScryDestination,
+): dest is ScryInkwellDestination {
+  return dest.zone === "inkwell";
+}
+
+/** Check if destination is a play destination */
+export function isScryPlayDestination(
+  dest: ScryDestination,
+): dest is ScryPlayDestination {
+  return dest.zone === "play";
+}
+
+/** Check if destination is a discard destination */
+export function isScryDiscardDestination(
+  dest: ScryDestination,
+): dest is ScryDiscardDestination {
+  return dest.zone === "discard";
+}
+
+/** Check if destination is a remainder destination */
+export function isScryRemainderDestination(dest: ScryDestination): boolean {
+  return dest.remainder === true;
+}

package/src/abilities/helpers/Abilities.ts

@@ -0,0 +1,172 @@
+/**
+ * Ability Helpers for Lorcana Abilities
+ *
+ * Provides a fluent API for building ability definitions.
+ * These helpers make it easy to construct all ability types.
+ *
+ * @example
+ * ```typescript
+ * const ability = Abilities.Keyword("Rush");
+ * const ability = Abilities.Triggered({
+ *   trigger: Triggers.WhenYouPlay(),
+ *   effect: Effects.Draw({ amount: 2 })
+ * });
+ * const ability = Abilities.Action(Effects.Draw({ amount: 2 }));
+ * ```
+ */
+
+import type {
+  ActionAbility,
+  ActivatedAbility,
+  KeywordAbility,
+  ParameterizedKeywordType,
+  ShiftKeywordAbility,
+  SimpleKeywordType,
+  StaticAbility,
+  TriggeredAbility,
+  ValueKeywordType,
+} from "../ability-types";
+import type { Effect, StaticEffect } from "../effect-types";
+import type { AbilityCost, Condition } from "../index";
+import type { Trigger } from "../trigger-types";
+
+export const Abilities = {
+  /**
+   * Simple keyword ability (no parameters)
+   *
+   * @example Abilities.Keyword("Rush")
+   * @example Abilities.Keyword("Ward")
+   */
+  Keyword: (keyword: SimpleKeywordType): KeywordAbility => ({
+    type: "keyword",
+    keyword,
+  }),
+
+  /**
+   * Value-based keyword ability (Singer, SingTogether, Boost)
+   *
+   * @example Abilities.Keyword("Singer", { value: 5 })
+   */
+  KeywordWithValue: (
+    keyword: ValueKeywordType,
+    params: { value: number },
+  ): KeywordAbility => ({
+    type: "keyword",
+    keyword,
+    value: params.value,
+  }),
+
+  /**
+   * Parameterized keyword ability (Challenger, Resist)
+   *
+   * @example Abilities.Keyword("Challenger", { value: 3 })
+   * @example Abilities.Keyword("Resist", { value: 2, condition: Conditions.WhileDamaged() })
+   */
+  KeywordParameterized: (
+    keyword: ParameterizedKeywordType,
+    params: { value: number; condition?: Condition },
+  ): KeywordAbility => ({
+    type: "keyword",
+    keyword,
+    value: params.value,
+    ...(params.condition && { condition: params.condition }),
+  }),
+
+  /**
+   * Shift keyword ability
+   *
+   * @example Abilities.Shift({ cost: { ink: 5 } })
+   * @example Abilities.Shift({ cost: { ink: 3 }, shiftTarget: "Elsa" })
+   */
+  Shift: (params: {
+    cost: AbilityCost;
+    shiftTarget?: string;
+  }): ShiftKeywordAbility => ({
+    type: "keyword",
+    keyword: "Shift",
+    cost: params.cost,
+    ...(params.shiftTarget && { shiftTarget: params.shiftTarget }),
+  }),
+
+  /**
+   * Triggered ability - fires when conditions are met
+   *
+   * @example
+   * ```typescript
+   * Abilities.Triggered({
+   *   trigger: Triggers.WhenYouPlay(),
+   *   effect: Effects.Draw({ amount: 2 })
+   * })
+   * ```
+   */
+  Triggered: (params: {
+    name?: string;
+    trigger: Trigger;
+    effect: Effect;
+    condition?: Condition;
+  }): TriggeredAbility => ({
+    type: "triggered",
+    ...(params.name && { name: params.name }),
+    trigger: params.trigger,
+    effect: params.effect,
+    ...(params.condition && { condition: params.condition }),
+  }),
+
+  /**
+   * Activated ability - player chooses to use by paying cost
+   *
+   * @example
+   * ```typescript
+   * Abilities.Activated({
+   *   cost: Costs.Ink(2),
+   *   effect: Effects.Draw({ amount: 1 })
+   * })
+   * ```
+   */
+  Activated: (params: {
+    name?: string;
+    cost: AbilityCost;
+    effect: Effect;
+    condition?: Condition;
+  }): ActivatedAbility => ({
+    type: "activated",
+    ...(params.name && { name: params.name }),
+    cost: params.cost,
+    effect: params.effect,
+    ...(params.condition && { condition: params.condition }),
+  }),
+
+  /**
+   * Static ability - always active effect
+   *
+   * @example
+   * ```typescript
+   * Abilities.Static({
+   *   effect: Effects.GainKeyword({ keyword: "Ward" })
+   * })
+   * ```
+   */
+  Static: (params: {
+    name?: string;
+    effect: StaticEffect;
+    condition?: Condition;
+  }): StaticAbility => ({
+    type: "static",
+    ...(params.name && { name: params.name }),
+    effect: params.effect,
+    ...(params.condition && { condition: params.condition }),
+  }),
+
+  /**
+   * Action ability - standalone effect on action cards
+   *
+   * @example
+   * ```typescript
+   * Abilities.Action(Effects.Draw({ amount: 2 }))
+   * ```
+   */
+  Action: (effect: Effect): ActionAbility => ({
+    type: "action",
+    effect,
+  }),
+};