# Abilities This file is the canonical reference for the ability and effect system. The same model is used by: - Unit abilities (`ArchSpirit` and `Spirit`) - `Instinct` card effects - `Repentance` card effects The system is designed to be fully data-driven. Every ability, effect, condition, and target is expressible through the schema below — no additional programming required to create new content. --- ## 1) Ability Structure ``` AbilityDefinition { Type: Active | Passive | Aura | Triggered ActivationConditions: Condition[] // optional; if any unmet, ability cannot fire Actions: Action[] // Active only: Cost: CostEntry[]? // see §6.6 in gameplay.md for cost types Range: { Min, Max }? // targeting range from source unit, in tiles UsesPerTurn: N // default 1 // Aura only: AuraRange: { Min, Max } // Triggered only: TriggerEvent: TriggerEvent // see §8; specifies when the ability fires // ActivationConditions handles whether it fires } ``` --- ## 2) Ability Types ### 2.1 Active Manually activated by the controlling player. - Default: once per turn. May be increased or decreased by effects. - Optional **cost** — any supported cost type (see §6.6 in gameplay.md). - Optional **range** — min/max tile distance from source unit to valid targets. - Optional **activation conditions** — ability cannot be activated unless all conditions are met. - Supports N or more targets via the target selector on each action. ### 2.2 Aura Always active while the unit is in play and conditions are met. - Applies effects passively to all valid targets within `AuraRange` (min/max tiles from source). - Optional **activation conditions** — if any are unmet, the aura is fully suppressed. - No manual activation. No cost. - **Instant stat modifiers** (e.g. `ModifyDamage`, `ModifyMP`) apply when a unit enters range and are removed when the unit leaves range or the aura is suppressed. - **Per-turn effects** (e.g. `DealDamage`, `Heal`, `DOT`) apply once per turn to each unit currently in range, resolved during the start-of-turn triggers phase for the aura owner's turn. These effects also fire immediately when a unit enters range. - **On-exit effects** are not automatic — to fire effects when a unit leaves range, use a companion `Triggered` ability on `OnLeaveAuraRange` (§8.12). ### 2.3 Passive Always active while the unit is in play and conditions are met. - No range constraint. - Optional **activation conditions** — if any are unmet, the passive is fully suppressed. - No manual activation. No cost. ### 2.4 Triggered Automatically fires when the trigger condition is met. - Defined by a `TriggerEvent` from the catalog in §8, plus optional state conditions. - Fires once per trigger event unless modified by an effect. - Not manually activated. No cost. --- ## 3) Action Model All effect execution — whether from unit abilities, `Instinct` cards, or `Repentance` cards — uses the same Action model. An action is the atomic unit of targeting and effect delivery. An ability contains one or more actions that resolve in sequence. Each action may have its own target, conditions, and effects. ``` Action { Target: TargetSelector Conditions: Condition[] // optional; if any unmet, this action is skipped Effects: Effect[] Duration: DurationModel } ``` **Duration scope**: The `Duration` field applies to all effects within the action. If two effects in the same action need different durations, split them into separate actions targeting the same target. **Interrupt rule**: All actions within a single ability (or card play) resolve in full sequence before any interrupt window opens. Opponents cannot interrupt between individual actions of the same ability. **Instinct and Repentance**: The `Effects` field on these card types is an `Action[]` using this same model. **ChooseOne**: An ability or card may branch into mutually exclusive effect paths, with the controlling player selecting which branch to take at resolution time. ``` ChooseOne { Branches: [ { Label: string, Actions: Action[] }, ... ] } ``` `ChooseOne` may appear anywhere an `Action[]` can appear. When reached, the player controlling the source is presented with the branch labels and must select exactly one. Only the selected branch's actions resolve. Conditions on individual actions within a branch still apply normally. Example: "Discard a card from your hand OR pay 2 SP and channel it — all channeling rules apply." --- ## 4) Target Selector ``` TargetSelector { Scope: Hand | Deck | Discard | Battlefield | Player | AnyZone Type: Unit | ArchSpirit | Spirit | SpiritToken | Ruin | Tile | Card | Player Ownership: Self | Owner | Ally | Enemy | Any | Random Count: N | UpToN | All Filters: Filter[] } ``` - `Unit` — alias for `Spirit | ArchSpirit | SpiritToken`; use when targeting any unit type without restriction - `AnyZone` — target a card regardless of which zone it currently occupies - `Self` — the source unit itself (see §4.3) - `UpToN` — player may select between 0 and N valid targets; fewer than N is valid ### 4.1 Unit/Card Filters - `GenusContains(tag)` - `AffinityMatches(affinity)` - `HealthBelow(N)` / `HealthAbove(N)` - `DamageRange(min, max)` - `DefenseRange(min, max)` - `MPRange(min, max)` - `HasFlag(flag)` — e.g., `CanAttack`, `CanMove`, `CanBeSacrificed` - `TierIs(N)` — ArchSpirit only; matches a specific tier - `IsAdjacentToSource` — target must be adjacent to the source unit - `CardTypeIs(type)` - `CardSPCostRange(min, max)` - `CardSTCostRange(min, max)` - `WithinRange(min, max)` — from source unit, in tiles - `IsSelf` — matches only the specific unit or card that owns this ability ### 4.2 Tile Filters - `TileAffinityMatches(affinity)` - `TileIsOccupied(unitType?)` - `TileIsUnoccupied` - `TileWithinRange(min, max)` — from source unit, in tiles - `TileIsAdjacentToUnit(ownership, filter?)` — tile is adjacent to a unit matching the filter - `TileIsOnPlayerSide(ownership)` — tile falls within the starting side of the specified player - `TileIsInArchSpiritChannelRange(ownership)` — tile is within the channeling range of the specified player's active ArchSpirit ### 4.3 Ownership Values - `Self` — the specific unit using the ability (not just any unit the owner controls) - `Target` — the entity resolved as this action's target; used to reference the current target in conditions or subsequent chained actions - `Owner` — any unit/card controlled by the ability's owner - `Ally` — controlled by a teammate (distinct from owner in team modes) - `Enemy` — controlled by an opponent - `Any` — any player's units/cards - `Random` — random selection from valid pool after all other filters apply --- ### 4.4 Chained Targeting Some abilities need a second target defined relative to a first (e.g., "target an enemy Spirit, then target a tile adjacent to that Spirit"). This is expressed by referencing a prior action's resolved target in a subsequent action's filter. ``` Action 1: { Target: { Scope: Battlefield, Type: Spirit, Ownership: Enemy }, ... } Action 2: { Target: { Scope: Battlefield, Type: Tile, Filters: [TileIsAdjacentToUnit(ref: Action1.Target)] }, ... } ``` Actions reference prior resolved targets by index (`Action1.Target`, `Action2.Target`, etc.). --- ### 4.5 Dynamic Value References Filter parameters and effect amounts may reference runtime values instead of fixed constants: - `Action{N}.Target.{Property}` — a property of the Nth action's resolved target (e.g. `Action1.Target.Affinity`) - `Self.{Property}` — a property of the source unit (e.g. `Self.Damage`, `Self.Affinity`) - `Self.Owner.ArchSpirit.{Property}` — a property of the source unit's owner's active ArchSpirit (e.g. `Self.Owner.ArchSpirit.Affinity`) - `EventData.{Field}` — trigger payload values (see §6.0.2); available in `Triggered` abilities only Dynamic references resolve at the time the filter or effect is evaluated. They may be used in any parameter that accepts a numeric value, an affinity, or a unit/player reference. Example: `TileAffinityMatches(Action1.Target.Affinity)` — restrict tile selection to tiles that match the affinity of the spirit targeted in Action 1. Example: `SetAffinity(Self.Owner.ArchSpirit.Affinity)` — change the target unit's affinity to match the source unit's ArchSpirit. --- ## 5) Effect Types ### 5.1 Stat Modification Applies to `Spirit`, `ArchSpirit`, `SpiritToken`: - `ModifyHealth(amount, target: current | max)` — increase or decrease health - `ModifyDefense(amount, target: current | max)` — increase or decrease defense - `ModifyDamage(amount)` — increase or decrease damage - `ModifyMP(amount, target: current | max)` — increase or decrease movement points - `SetMovementType(type)` — change movement style (`Walk`, `Flight`, `Jump`, `Teleport`) - `SetAttackRange(min, max)` — change attack range - `ModifyCost(sp?, st?)` — change SP or ST cost - `SetAffinity(affinity)` — change the affinity of the target unit or card; accepts a fixed value or a dynamic reference (see §4.5) - `GrantAdditionalAttack(N)` — allow the unit to attack N additional times this turn; stacks with multiple applications - `SetStatModMultiplier(stat, multiplier)` — multiply any incoming stat modifications to the specified stat by the given value (e.g. `SetStatModMultiplier(Damage, 2.0)` doubles all Damage modifiers applied to this unit) --- ### 5.2 Flag Modification Applies to `Spirit`, `ArchSpirit`, `SpiritToken`, or `Player`: Unit flags: - `SetCanMove(bool)` - `SetCanAttack(bool)` - `SetCanDefend(bool)` — if false, incoming damage bypasses defense - `SetCanBeAttacked(bool)` - `SetCanBeBlocked(bool)` — if false, damage dealt ignores target defense - `SetCanBeObstructed(bool)` — if false, unit ignores movement obstruction - `SetCanUseAbility(bool)` - `SetCanBeSacrificed(bool)` — Spirit only Player flags: - `SetCanDrawCards(bool)` - `SetAccumulatesSP(bool)` - `SetCanChannelSpirit(bool)` - `SetCanSacrificeSpirit(bool)` - `SetCanAscendArchSpirit(bool)` - `SetCanTransitionArchSpirit(bool)` - `SetCanChannelRepentance(bool)` - `SetCanChannelInstinct(bool)` - `SetCanChannelRuin(bool)` - `SetCanChannelTerramorphaMono(bool)` - `SetCanChannelTerramorphaDi(bool)` - `SetCanChannelTerramorphaTri(bool)` --- ### 5.3 Ability Modification Applies to `Spirit`, `ArchSpirit`, `SpiritToken`: - `AddAbility(abilityDef)` — add a new ability to the unit - `RemoveAbility(abilityRef)` — permanently remove an ability - `EnableAbility(abilityRef)` — re-enable a disabled ability - `DisableAbility(abilityRef)` — disable without removing --- ### 5.4 Genus Modification Applies to `Spirit`, `ArchSpirit`, `SpiritToken`: - `AddGenus(tag)` - `RemoveGenus(tag)` --- ### 5.5 Player Resource Modification Applies to `Player`: - `ModifySP(amount)` — increase or decrease current SP - `ModifySPAccumulation(amount)` — increase or decrease SP gained per turn - `ModifyST(amount)` — increase or decrease current ST - `ModifyCardsDrawnPerTurn(amount)` — change per-turn draw count --- ### 5.6 Tile Modification Applies to `Tile`: - `SetBaseAffinity1(affinity)` — set Base1 affinity slot directly - `SetBaseAffinity2(affinity)` — set Base2 affinity slot directly - `PushAffinity(affinity)` — push basic affinity into Base2; Base2 shifts to Base1 - `PushFinalAffinity(affinity)` — set Base1/Base2 to the pair yielding the target final affinity --- ### 5.7 Zone and Card Operations - `DrawCards(N, player)` — target player draws N cards - `DiscardCards(N, player, filter?)` — discard N cards; optional filter or random selection - `ReturnToHand(card)` — move card from discard/battlefield to hand - `ReturnToDeck(card, position: top | bottom | random)` — move card to deck - `ReturnToBattlefield(card, controller?: Ownership, tileFilter?: TileFilter[])` — place card from discard/hand onto battlefield; `controller` overrides which player controls the unit (defaults to original owner); `tileFilter` restricts which tile the placing player may select - `SendToDiscard(card)` — move card from any zone to discard - `SearchDeck(filter, count?: N, thenAction)` — player searches deck for up to `count` cards matching filter (default 1); `thenAction` is applied once per found card with `SearchResult` referencing the current found card; deck is shuffled after the search - `ShuffleDeck(player)` — shuffle target player's deck - `RevealCards(N, toOwnership)` — reveal N hand cards to specified players - `PlaceOnDeck(card, position: top | bottom)` — place card on top or bottom of deck - `ChannelCard(card, payCost: bool, costMultiplier?: float)` — channel a card directly from hand or as referenced by `SearchResult`; `payCost: true` deducts normal SP/ST channel costs and all channeling rules apply; `costMultiplier` scales the cost (e.g. `2.0` = double, `0.5` = half); `payCost: false` overrides to no cost regardless of multiplier **`SearchResult`**: When used inside a `SearchDeck` `thenAction`, the keyword `SearchResult` refers to the currently found card. It may be used as the `card` argument in any §5.7 operation — `ReturnToHand(SearchResult)`, `SendToDiscard(SearchResult)`, `ChannelCard(SearchResult, ...)`, etc. --- ### 5.8 Combat and Damage - `DealDamage(amount, bypassDefense?: bool)` — deal damage to target; optionally bypass defense - `Heal(amount)` — restore health up to max - `DealDamageToSelf(amount, bypassDefense?: bool)` — source unit takes damage - `DOT(amount, duration, bypassDefense?: bool)` — damage over time; applies `amount` each turn tick - `HOT(amount, duration)` — heal over time; restores `amount` each turn tick --- ### 5.9 Displacement Moves a unit without spending that unit's MP. - `PushUnit(tiles, awayFromSource)` — move target N tiles away from the source - `PullUnit(tiles, towardSource)` — move target N tiles toward the source - `DisplaceUnit(tiles, direction)` — move target N tiles in a fixed cardinal/hex direction Rules: - Does not consume the displaced unit's MP. - Blocked if destination tile is occupied or invalid; unit stops at last valid tile. - Does not respect the displaced unit's own movement type or obstruction flags. --- ### 5.10 Control Effects Applies to `Spirit`, `ArchSpirit`, `SpiritToken`: - `TakeControl(duration)` — transfers control of the target unit to the ability owner for the specified duration; the unit acts as a friendly unit for that player until the effect expires, then returns to its original owner - `GrantMovementControl(N)` — the activating player may issue N move commands to the target unit this turn; each command uses the target unit's own MP, respects its `CanMove` flag, movement type, and obstruction rules; does not transfer ownership or affect any other flags - `SetFixedSacrificeReturn(stAmount)` — overrides the standard sacrifice formula for this unit; when sacrificed, the controller receives exactly `stAmount` ST instead of the formula result (see §6.15 in gameplay.md) --- ### 5.11 Token Summoning - `SummonToken(tokenDef, tileFilter?: TileFilter[])` — place a `SpiritToken` onto a player-selected tile meeting the filter; `tokenDef` references a token definition specifying the token's stats, abilities, and genus; follows normal occupancy rules for the tile --- ### 5.12 Deferred Effects - `ApplyOnEvent(trigger, effects)` — schedule effects to fire once the next time the specified trigger event occurs; the scheduled effects resolve as if originating from the same source unit; consumed after firing once; if the source unit leaves the battlefield before the event fires, the scheduled effect is cancelled Example: Channel a card for free, then `ApplyOnEvent(OnTurnEnd(Owner), [SendToDiscard(Self)])` ensures it leaves the battlefield at end of turn. --- ## 6) Condition Types Conditions can gate an entire ability or individual actions. If the condition group is not satisfied, the gated ability or action is skipped. ### 6.0 Logical Operators Conditions may be grouped with logical operators: - `AND` (default) — all conditions in the group must be met - `OR` — at least one condition in the group must be met - `XOR` — exactly one condition in the group must be met Groups may be nested to express compound logic: ``` OR [ AND [ SPAtLeast(2), UnitCountOnBattlefield(Enemy, Spirit, >=, 1) ] HandSizeAtLeast(3, subject: Target) ] ``` ### 6.0.1 Condition Subject Each condition evaluates against a **subject** — the entity whose state is checked: - `subject: Self` (default) — evaluates against the source unit or the ability owner - `subject: Target` — evaluates against the current action's resolved target Example: `UnitCountOnBattlefield(Owner, Spirit, >, 1, subject: Target)` checks whether *the targeted player* controls more than 1 Spirit, not the ability's owner. ### 6.0.2 EventData Reference `Triggered` ability actions have access to the payload of the triggering event via `EventData`. This allows effects to reference numeric values from the event rather than fixed constants. Available fields (availability depends on the triggering event): - `EventData.Amount` — the numeric magnitude of the event (e.g., HP gained, damage dealt, SP spent) - `EventData.Source` — the unit or player that caused the event - `EventData.Target` — the unit or player the event acted upon `EventData` fields may be used anywhere a numeric value or unit reference is accepted in an effect or condition within the same action sequence. Example: `OnHealed(Enemy, ArchSpirit)` → `DealDamage(EventData.Amount * 3)` — when an enemy ArchSpirit gains HP, deal 3× that amount as damage. ### 6.1 Unit Conditions - `HealthBelow(N)` / `HealthAbove(N)` - `DefenseIs(N)` - `HasGenus(tag)` - `HasAbility(abilityRef)` - `IsOnTileWithAffinity(affinity)` - `IsAdjacentTo(unitType, ownership)` - `WithinRangeOf(target, min, max)` - `MovementTypeIs(type)` ### 6.2 Player Conditions - `SPAtLeast(N)` / `SPAtMost(N)` - `STAtLeast(N)` / `STAtMost(N)` - `HandSizeAtLeast(N)` / `HandSizeAtMost(N)` - `DeckSizeAtLeast(N)` - `DiscardSizeAtLeast(N)` ### 6.3 Tile Conditions - `TileAffinityMatches(affinity)` - `TileIsOccupied(unitType?)` - `TileIsUnoccupied` ### 6.4 Turn/Timing Conditions - `IsOwnTurn` - `IsOpponentTurn` - `IsAllyTurn` - `IsActivePlayerTurn(ownership)` — scoped to a specific player ownership group ### 6.5 Battlefield Conditions - `UnitCountOnBattlefield(ownership, unitType, comparator, N)` — e.g. "ally Spirit count >= 3" - `CardInZone(cardRef, zone)` --- ## 7) Duration Model All effects support a duration. Reversible effects retain source and modifier context for rollback when duration ends. - `Instant` — one-time change, no ongoing state - `UntilEndOfTurn` - `UntilStartOfOwnerTurn` - `UntilStartOfSourceOwnerTurn` - `ForNTurns(N)` - `WhileCondition(condition)` - `PermanentInMatch` Duration anchors can be scoped to a specific player: - Until end of `X` player's turn - Until start of `X` player's turn Delayed timing: - Effect starts after `X` turns - Effect ends after `X` turns --- ## 8) Trigger Event Catalog All `Triggered` abilities specify a `TriggerEvent` from this catalog. Every event supports an **ownership scope** (`Owner | Ally | Enemy | Any`) applied to the acting unit, player, or card. Most events also accept an optional **filter** using the same filter types as §4. --- ### 8.1 Turn Phase - `OnTurnStart(player)` — start of the specified player's turn - `OnTurnEnd(player)` — end of the specified player's turn --- ### 8.2 Channeling Single event, parameterized by card type: - `OnChanneled(type, ownership, filter?)` — a card of the given type is channeled - `type`: `Spirit | Terramorpha | Repentance | Instinct | Ruin` --- ### 8.3 ArchSpirit Tier Actions - `OnAscend(ownership)` — an ArchSpirit is ascended to the next tier - `OnTransition(ownership)` — an ArchSpirit is transitioned out and replaced --- ### 8.4 Unit Actions - `OnUnitMove(ownership, filter?)` — a unit spends MP to move to a tile - `OnUnitAttack(ownership, filter?)` — a unit declares an attack - `OnUnitAbilityActivated(ownership, filter?)` — a unit activates an Active ability - `OnUnitMPSpent(ownership, filter?, amount?)` — a unit spends movement points --- ### 8.5 Damage and Healing - `OnDamageDealt(sourceOwnership, targetOwnership, type: HP | Defense | Any, amount?)` — damage lands on a unit - `OnDamagePrevented(targetOwnership, filter?)` — incoming damage is fully blocked by defense or an effect - `OnHealed(targetOwnership, filter?, amount?)` — a unit is restored health --- ### 8.6 Unit Lifecycle - `OnUnitEnterBattlefield(unitType, ownership, filter?)` — a unit is placed on the battlefield (any cause) - `OnUnitLeaveBattlefield(unitType, ownership, filter?)` — a unit leaves the battlefield (any cause) - `OnUnitDeath(unitType, ownership, filter?)` — a unit's HP reaches 0 - `OnUnitSentToDiscard(unitType, ownership, filter?, causedBy?)` — a unit is sent to the discard from the battlefield by any means other than death (e.g. used as a cost, forced removal) - `OnSpiritSacrificed(ownership, filter?)` — a Spirit is sacrificed (see §6.15 in gameplay.md) - `OnTokenSummoned(ownership, filter?)` — a SpiritToken enters the battlefield **`causedBy` parameter**: An optional ownership reference (`Self | Owner | Ally | Enemy | Any`) that filters events to only those caused by a specific unit or player. Applies to unit lifecycle events and unit action events where the acting entity can be identified. Example: `OnUnitSentToDiscard(Spirit, Any, causedBy: Self)` — fires only when this unit is the one that sent a spirit to the discard. --- ### 8.7 Unit State Changes - `OnStatModified(ownership, filter?, stat?)` — a mutable stat on a unit is changed - `OnAbilityAdded(ownership, filter?)` — an ability is added to a unit - `OnAbilityRemoved(ownership, filter?)` — an ability is removed from a unit - `OnGenusChanged(ownership, filter?)` — a unit's genus tags are modified --- ### 8.8 Ruin - `OnRuinActivation(ruinOwnership, occupantOwnership?)` — a Ruin fires one of its abilities - `OnUnitOccupyRuin(unitOwnership, filter?)` — a unit moves onto a tile containing a Ruin --- ### 8.9 Tile - `OnTileAffinityChanged(filter?)` — a tile's Base1 or Base2 affinity changes --- ### 8.10 Player Resources - `OnSPGained(player, amount?)` - `OnSPSpent(player, amount?)` - `OnSTGained(player, amount?)` - `OnSTSpent(player, amount?)` --- ### 8.11 Card Zone Events - `OnCardDrawn(player, filter?)` - `OnCardDiscarded(player, filter?, cause?: voluntary | forced)` — `cause` filters by whether the discard was player-initiated or forced by an effect - `OnCardReturnedToHand(player, filter?)` - `OnCardReturnedToDeck(player, filter?)` - `OnDeckShuffled(player)` - `OnCardsRevealed(player, filter?)` --- ### 8.12 Effect and Targeting Lifecycle - `OnTargetedByAbility(targetOwnership, sourceOwnership, filter?)` — a unit or player is selected as a target of an ability action (fires before effects resolve) - `OnEffectApplied(targetOwnership, sourceOwnership, filter?)` — an effect successfully resolves on a target (fires after resolution; distinct from targeting if action conditions blocked the effect) - `OnEnterAuraRange(auraOwnership, unitOwnership, filter?)` — a unit moves into the active range of an aura ability - `OnLeaveAuraRange(auraOwnership, unitOwnership, filter?)` — a unit moves out of the active range of an aura ability