23 KiB
Abilities
This file is the canonical reference for the ability and effect system. The same model is used by:
- Unit abilities (
ArchSpiritandSpirit) Instinctcard effectsRepentancecard 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
Triggeredability onOnLeaveAuraRange(§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
TriggerEventfrom 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 forSpirit | ArchSpirit | SpiritToken; use when targeting any unit type without restrictionAnyZone— target a card regardless of which zone it currently occupiesSelf— 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,CanBeSacrificedTierIs(N)— ArchSpirit only; matches a specific tierIsAdjacentToSource— target must be adjacent to the source unitCardTypeIs(type)CardSPCostRange(min, max)CardSTCostRange(min, max)WithinRange(min, max)— from source unit, in tilesIsSelf— matches only the specific unit or card that owns this ability
4.2 Tile Filters
TileAffinityMatches(affinity)TileIsOccupied(unitType?)TileIsUnoccupiedTileWithinRange(min, max)— from source unit, in tilesTileIsAdjacentToUnit(ownership, filter?)— tile is adjacent to a unit matching the filterTileIsOnPlayerSide(ownership)— tile falls within the starting side of the specified playerTileIsInArchSpiritChannelRange(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 actionsOwner— any unit/card controlled by the ability's ownerAlly— controlled by a teammate (distinct from owner in team modes)Enemy— controlled by an opponentAny— any player's units/cardsRandom— 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 inTriggeredabilities 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 healthModifyDefense(amount, target: current | max)— increase or decrease defenseModifyDamage(amount)— increase or decrease damageModifyMP(amount, target: current | max)— increase or decrease movement pointsSetMovementType(type)— change movement style (Walk,Flight,Jump,Teleport)SetAttackRange(min, max)— change attack rangeModifyCost(sp?, st?)— change SP or ST costSetAffinity(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 applicationsSetStatModMultiplier(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 defenseSetCanBeAttacked(bool)SetCanBeBlocked(bool)— if false, damage dealt ignores target defenseSetCanBeObstructed(bool)— if false, unit ignores movement obstructionSetCanUseAbility(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 unitRemoveAbility(abilityRef)— permanently remove an abilityEnableAbility(abilityRef)— re-enable a disabled abilityDisableAbility(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 SPModifySPAccumulation(amount)— increase or decrease SP gained per turnModifyST(amount)— increase or decrease current STModifyCardsDrawnPerTurn(amount)— change per-turn draw count
5.6 Tile Modification
Applies to Tile:
SetBaseAffinity1(affinity)— set Base1 affinity slot directlySetBaseAffinity2(affinity)— set Base2 affinity slot directlyPushAffinity(affinity)— push basic affinity into Base2; Base2 shifts to Base1PushFinalAffinity(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 cardsDiscardCards(N, player, filter?)— discard N cards; optional filter or random selectionReturnToHand(card)— move card from discard/battlefield to handReturnToDeck(card, position: top | bottom | random)— move card to deckReturnToBattlefield(card, controller?: Ownership, tileFilter?: TileFilter[])— place card from discard/hand onto battlefield;controlleroverrides which player controls the unit (defaults to original owner);tileFilterrestricts which tile the placing player may selectSendToDiscard(card)— move card from any zone to discardSearchDeck(filter, count?: N, thenAction)— player searches deck for up tocountcards matching filter (default 1);thenActionis applied once per found card withSearchResultreferencing the current found card; deck is shuffled after the searchShuffleDeck(player)— shuffle target player's deckRevealCards(N, toOwnership)— reveal N hand cards to specified playersPlaceOnDeck(card, position: top | bottom)— place card on top or bottom of deckChannelCard(card, payCost: bool, costMultiplier?: float)— channel a card directly from hand or as referenced bySearchResult;payCost: truededucts normal SP/ST channel costs and all channeling rules apply;costMultiplierscales the cost (e.g.2.0= double,0.5= half);payCost: falseoverrides 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 defenseHeal(amount)— restore health up to maxDealDamageToSelf(amount, bypassDefense?: bool)— source unit takes damageDOT(amount, duration, bypassDefense?: bool)— damage over time; appliesamounteach turn tickHOT(amount, duration)— heal over time; restoresamounteach turn tick
5.9 Displacement
Moves a unit without spending that unit's MP.
PushUnit(tiles, awayFromSource)— move target N tiles away from the sourcePullUnit(tiles, towardSource)— move target N tiles toward the sourceDisplaceUnit(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 ownerGrantMovementControl(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 itsCanMoveflag, movement type, and obstruction rules; does not transfer ownership or affect any other flagsSetFixedSacrificeReturn(stAmount)— overrides the standard sacrifice formula for this unit; when sacrificed, the controller receives exactlystAmountST instead of the formula result (see §6.15 in gameplay.md)
5.11 Token Summoning
SummonToken(tokenDef, tileFilter?: TileFilter[])— place aSpiritTokenonto a player-selected tile meeting the filter;tokenDefreferences 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 metOR— at least one condition in the group must be metXOR— 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 ownersubject: 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 eventEventData.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
IsOwnTurnIsOpponentTurnIsAllyTurnIsActivePlayerTurn(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 stateUntilEndOfTurnUntilStartOfOwnerTurnUntilStartOfSourceOwnerTurnForNTurns(N)WhileCondition(condition)PermanentInMatch
Duration anchors can be scoped to a specific player:
- Until end of
Xplayer's turn - Until start of
Xplayer's turn
Delayed timing:
- Effect starts after
Xturns - Effect ends after
Xturns
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 turnOnTurnEnd(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 channeledtype:Spirit | Terramorpha | Repentance | Instinct | Ruin
8.3 ArchSpirit Tier Actions
OnAscend(ownership)— an ArchSpirit is ascended to the next tierOnTransition(ownership)— an ArchSpirit is transitioned out and replaced
8.4 Unit Actions
OnUnitMove(ownership, filter?)— a unit spends MP to move to a tileOnUnitAttack(ownership, filter?)— a unit declares an attackOnUnitAbilityActivated(ownership, filter?)— a unit activates an Active abilityOnUnitMPSpent(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 unitOnDamagePrevented(targetOwnership, filter?)— incoming damage is fully blocked by defense or an effectOnHealed(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 0OnUnitSentToDiscard(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 changedOnAbilityAdded(ownership, filter?)— an ability is added to a unitOnAbilityRemoved(ownership, filter?)— an ability is removed from a unitOnGenusChanged(ownership, filter?)— a unit's genus tags are modified
8.8 Ruin
OnRuinActivation(ruinOwnership, occupantOwnership?)— a Ruin fires one of its abilitiesOnUnitOccupyRuin(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)—causefilters by whether the discard was player-initiated or forced by an effectOnCardReturnedToHand(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 abilityOnLeaveAuraRange(auraOwnership, unitOwnership, filter?)— a unit moves out of the active range of an aura ability