20 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:
TriggerCondition: Condition
}
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.
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
}
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 tiles
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 player
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.).
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 costGrantAdditionalAttack(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)— place card from discard/hand onto battlefieldSendToDiscard(card)— move card from any zone to discardSearchDeck(filter, thenAction)— find card matching filter, then perform defined actionShuffleDeck(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)— channel a card directly from hand (or as selected via filter);payCost: truededucts normal SP/ST channel costs and all channeling rules apply;payCost: falsechannels the card without cost
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 ownerSetFixedSacrificeReturn(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, targetTile)— place aSpiritTokenonto the target tile;tokenDefreferences a token definition specifying the token's stats, abilities, and genus; follows normal occupancy rules for the tile
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, cause: voluntary | forced, filter?)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 abilityOnLeaveAuraRange(auraOwnership, unitOwnership, filter?)— a unit moves out of the active range of an aura ability