Files
sor/Shared/context-files/abilities.md
T
2026-02-23 13:07:13 -05:00

23 KiB
Raw Blame History

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