18 KiB
SOR Ability System — Detailed Readable Guide
This document explains how the current ability system works in practice, based on:
SOR/Server/src/SOR.Game/Abilities/AbilitySystem.csSOR/Server/src/SOR.Admin/Components/Pages/Cards/AbilityBuilder.razor
The goal is to bridge three viewpoints at once:
- designers who want to understand what kinds of abilities are possible
- implementers who want to know how the engine actually resolves them
- content authors using the admin Ability Builder
1. High-level model
The ability system is data-driven.
Abilities are stored as JSON and parsed into engine models. The engine then:
- validates whether an ability can fire
- resolves targets
- pays costs if necessary
- executes one or more actions
- each action applies one or more effects
- durations are tracked so temporary effects can expire or reverse later
That means abilities are not hardcoded one-by-one. They are built from a structured rules language.
2. The four ability types
The admin builder exposes four top-level ability types, and the engine recognizes them.
2.1 Active
An Active ability is manually activated by the player.
Typical properties:
- range
- uses per turn
- costs
- activation conditions
- actions/effects
- optional duration override
The engine enforces:
- source unit must exist
- source unit must not be exhausted
- source unit must be allowed to use abilities
- ability index must be valid
- ability type must be
Active - named ability must not be disabled
- uses per turn must not be exhausted
- activation conditions must pass
- costs must be payable
Then the actions resolve.
2.2 Passive
Passive abilities are always-on while the source unit is on the battlefield.
The engine applies passive abilities by:
- finding passive definitions on a source unit
- executing their actions
- tracking them with
WhileSourceOnBattlefieldby default if no explicit duration is given
When the source leaves play, passive effects from that source are revoked.
Important consequence:
- passive buffs are not “just descriptive text”
- they are actual tracked applied effects that can be reversed
2.3 Aura
Auras are continuous-range relationships.
An Aura ability defines an AuraRange, and the engine watches:
- when units enter aura range
- when units leave aura range
- when a unit with an aura enters play
- when a unit with an aura moves
- when a target unit moves
- when a unit with an aura leaves play
So auras are not resolved once; they are part of an event system.
2.4 Triggered
Triggered abilities fire automatically when a matching event occurs.
Examples:
- turn start
- card drawn
- unit death
- unit enters battlefield
- SP gained/spent
- ruin activation
- entering aura range
- etc.
The engine scans battlefield units for triggered abilities and fires any that match the trigger occurrence and pass activation conditions.
3. Abilities vs EffectsJson card effects
There are two relevant ways non-unit cards can do things.
3.1 EffectsJson
Cards like Repentance / Instinct / Ruin can carry a flat action list in EffectsJson.
The engine parses that and executes it immediately on play.
3.2 AbilitiesJson on cards
The engine also supports Active-style ability definitions on non-unit cards, especially for targeted Repentance / Instinct behavior.
There is even a compatibility fallback:
- if
AbilitiesJsonhas no active entries - the engine may try parsing active abilities out of
EffectsJson
So the engine is tolerant of older or mixed content pipelines.
4. Core execution pipeline
At a high level, ability execution looks like this:
- parse the ability JSON
- validate source-side conditions
- pay costs
- resolve action targets
- apply target-side conditions
- execute effects
- track reversals / durations if needed
That same action/effect model is reused across active, passive, triggered, and card-fired effects.
5. Ability structure
An ability definition can contain:
TypeNameDescriptionRangeorAuraRangeUsesPerTurnCostTriggerEventActivationConditionsActionsDuration- optional animation metadata
The important thing is that an ability typically contains one or more Actions, and each Action contains:
- a target selector
- optional action conditions
- one or more effects
So the action is the real “resolution block.”
6. Targeting model
The target selector has several parts.
6.1 Scope
Scope tells the engine where to search:
BattlefieldHandDeckDiscardPlayerAnyZone
6.2 Target type
Examples include:
UnitArchSpiritSpiritSpiritTokenRuinTileCardPlayer
6.3 Ownership
Ownership narrows the candidate pool:
SelfExactSelfOwnerAllyEnemyAnyRandomTarget
Important distinctions:
Selfmeans same controller’s entitiesExactSelfmeans the exact instance using the abilityTargetis for chained actions that reuse a previous resolution context
6.4 Count
The selector can choose:
- one target
- N targets
- all targets
- up-to-N targets depending on config
If required targets are missing, the engine can fail with INSUFFICIENT_TARGETS.
6.5 Client-selected vs auto-selected
For actions that require explicit client selection, if the client does not provide targets, the engine may fail. For self/automatic selectors, the engine can auto-resolve.
7. Range checking
Active abilities may define range. The engine checks:
- min range
- max range
- optional
LinearOnly - optional
RequiresLos
Current engine details:
- range uses Manhattan distance in this part of the ability system
- linear-only allows same row / column / diagonal line
- LOS uses board line-of-sight helpers
For tile targets and field-card targets, out-of-range explicit client selections can produce:
TARGET_OUT_OF_RANGE
8. Conditions
Conditions can exist at two levels.
8.1 Ability activation conditions
These gate whether the whole ability can activate/fire.
8.2 Action conditions
These gate one specific action.
There is also a Subject distinction:
SelfTarget
Meaning:
- some conditions evaluate the source
- some evaluate each resolved target
Examples supported by the engine
Logical:
AndOrXor
Unit-state:
HealthBelowHealthAboveDefenseIsHasGenusHasAbilityIsOnTileWithAffinityMovementTypeIs
Player-state:
SPAtLeastSPAtMostSTAtLeastSTAtMostHandSizeAtLeastHandSizeAtMostDeckSizeAtLeastDiscardSizeAtLeast
Turn-state:
IsOwnTurnIsOpponentTurnIsAllyTurnIsActivePlayerTurn
Battlefield aggregate:
UnitCountOnBattlefield
A very important implemented one is:
IsOnTileWithAffinityCondition
That makes terrain-conditional design first-class.
9. Costs
The engine supports these cost types:
SpiritPointsSacrificeTokensDiscardFromHandMillTopOfDeckMillBottomOfDeckDealDamageToOwnArchSpiritDealDamageToOwnSpiritSendSpiritFromBattlefieldToDiscard
If a cost cannot be paid, activation fails.
Examples of failure codes include:
INSUFFICIENT_SPINSUFFICIENT_STINSUFFICIENT_CARDS_TO_DISCARDNO_VALID_SPIRIT_FOR_COST
So costs are fully part of resolution legality, not cosmetic metadata.
10. Trigger system
Triggered abilities listen for TriggerOccurrences produced by the engine.
The code currently supports matching triggers such as:
OnTurnStartOnTurnEndOnUnitDeathOnDamageDealtOnUnitEnterBattlefieldOnUnitLeaveBattlefieldOnSPGainedOnSPSpentOnSTGainedOnSTSpentOnCardDrawnOnUnitMoveOnUnitAttackOnSpiritSacrificedOnAscendOnTransitionOnChanneledOnEnterAuraRangeOnLeaveAuraRangeOnRuinActivationOnUnitOccupyRuin
The admin UI lists even more trigger templates, some of which may be ahead of fully-matched engine support. So for content authoring, the safe rule is:
the code is the final authority on what actually fires today.
11. Effects: what abilities can actually do
This is the meat of the system.
The engine supports a large effect vocabulary.
11.1 Stat modification
These mutate unit stats:
ModifyHealthModifyDefenseModifyDamageModifyMPSetMovementTypeSetAttackRangeModifyCostSetAffinityGrantAdditionalAttack
Most temporary stat modifications are tracked with reversal effects so they can expire cleanly.
11.2 Unit flags
These toggle combat/action flags on units:
SetCanMoveSetCanAttackSetCanDefendSetCanBeAttackedSetCanBeBlockedSetCanBeObstructedSetCanUseAbilitySetCanBeSacrificed
This is a huge part of what makes the game feel expressive.
11.3 Player flags
These toggle player-level permissions:
SetCanDrawCardsSetAccumulatesSPSetCanChannelSpiritSetCanSacrificeSpiritSetCanAscendArchSpiritSetCanTransitionArchSpiritSetCanChannelRepentanceSetCanChannelInstinctSetCanChannelRuinSetCanChannelTerramorphaMonoSetCanChannelTerramorphaDiSetCanChannelTerramorphaTri
So the game supports hard lockouts or permissions at player scope.
11.4 Ability modification
Abilities themselves can be changed mid-match:
AddAbilityRemoveAbilityEnableAbilityDisableAbility
That means cards can grant temporary or persistent new abilities, or suppress existing ones.
11.5 Genus changes
The engine supports:
AddGenusRemoveGenus
This matters because many conditions/filters can key off genus tags.
11.6 Player resource effects
These can modify:
- current SP
- SP accumulation bonus
- current ST
- cards drawn per turn bonus
Examples:
ModifySPModifySPAccumulationModifySTModifyCardsDrawnPerTurn
11.7 Tile modification
These are crucial for terrain gameplay:
SetBaseAffinity1SetBaseAffinity2PushAffinityPushFinalAffinity
Important distinction
PushAffinityuses the normal shift rule (Base1 = old Base2; Base2 = new)PushFinalAffinitydirectly overrides the newer slot to force the tile toward a final target identity
These are some of the most strategically important effect types in the entire game.
11.8 Zone and card operations
The system supports a rich set of zone moves:
DrawCardsDiscardCardsReturnToHandReturnToDeckReturnToBattlefieldSendToDiscardSearchDeckShuffleDeckRevealCardsPlaceOnDeck
This means tutors, bounce, recursion, deck manipulation, and graveyard loops are all supported structurally.
11.9 Damage and healing
Combat-adjacent effects include:
DealDamageHealDealDamageToSelfDOTHOT
Damage normally respects defense first unless the effect says BypassDefense.
DOT/HOT are tracked as turn-ticking active effects.
11.10 Displacement
Movement-by-effect includes:
PushUnitPullUnitDisplaceUnit
These are distinct from normal movement and can reposition units directly if the destination is valid.
11.11 Control effects
The engine can do things like:
TakeControlGrantMovementControlSetFixedSacrificeReturn
So temporary stealing or sacrifice rewrites are supported.
11.12 Token summoning
The engine supports:
SummonToken
The token is built from JSON, turned into a SpiritToken, placed on the battlefield, and then normal enter-battlefield / aura / passive hooks are processed.
That means tokens are not fake visual markers; they are real battlefield objects.
11.13 Deferred effects
The engine supports:
ApplyOnEvent
This stores a pending deferred effect tied to:
- a trigger
- a target reference
- a source
- an owner
Later, when the trigger occurs, the deferred effect executes.
That gives the system delayed punishments, marks, future riders, etc.
12. Filters
Filters are used to narrow target pools or cost candidates.
Implemented examples include:
GenusContainsCardTypeIsAffinityMatchesHasFlagTierIsIsSelfIsExactSelfHealthBelowHealthAboveIsAdjacentToSourceWithinRange
This is a big part of what makes one generic effect system produce lots of specific card behavior.
13. Value expressions
One of the strongest parts of the system is that effect values can be dynamic.
A value can be:
- fixed
- or a reference expression
Examples supported by the admin builder / engine:
Self.DamageSelf.HealthSelf.DefenseSelf.MPSelf.SpCostSelf.StCostTarget.DamageTarget.DefenseTarget.HealthTarget.MPTarget.SpCostTarget.StCostEventData.AmountAction0.Target.*Action1.Target.*
That means later actions in an ability can depend on what earlier actions targeted.
Example idea
- Action 1: target a Spirit and return it to hand
- Action 2: refund its SP cost to its owner
That sort of chained design is absolutely supported by the model.
14. Durations and reversibility
Temporary effects are tracked in ActiveEffects along with duration metadata.
Supported duration types in code/admin include:
InstantUntilEndOfTurnUntilStartOfOwnerTurnUntilStartOfSourceOwnerTurnForNTurnsWhileSourceOnBattlefieldWhileConditionPermanentInMatch
The system stores reversal effects for many temporary modifiers. When the duration expires, the reversal effect is executed.
This is a very robust design choice.
Example
If an ability gives:
+2 Damage until end of turn
The engine tracks the inverse effect:
-2 Damage
Then applies that inverse later when the duration expires.
15. Tick effects
For ongoing effects like DOT/HOT:
- the engine stores them as active effects with
IsTick = true - at turn boundaries, it ticks them
- when duration runs out, the active effect is removed
So DOT/HOT are not handled as one-off hacks.
16. Ruin activation
At the start of each turn, for each friendly occupied Ruin tile:
- the engine checks triggered abilities on the Ruin
- it selects exactly one eligible
OnRuinActivationability at random - executes it
- then emits a RuinActivation trigger for observers
This is an important subtlety:
a Ruin can have multiple possible activation abilities, but only one fires each activation.
That gives Ruins controlled randomness.
17. Passive application and revocation
The passive system is more sophisticated than a lot of card engines.
When a passive source appears
The engine:
- applies passive effects from that source to valid battlefield targets
- tracks them as
WhileSourceOnBattlefield
When a new unit enters
The engine:
- applies all existing passives from older sources onto the new unit
When a passive source leaves
The engine:
- revokes all
WhileSourceOnBattlefieldeffects sourced from that unit
Conditional passives
The engine can fully re-evaluate conditional passives after state changes.
This matters for things like:
- “while this is on Marsh…”
- “while you have 3+ Spirits…”
- “while this source remains in play…”
18. Aura transitions
Aura-related triggers are evaluated when:
- units move
- units enter battlefield
- units leave battlefield
The engine checks both directions:
- did the moving unit enter somebody else’s aura?
- did somebody else enter/leave the moving unit’s own aura?
That means aura triggers are symmetrical and spatially reactive.
19. Admin Ability Builder: what it’s really doing
The admin UI is not just a fancy text box. It is a structured front-end for creating the JSON the engine expects.
It exposes:
- ability type
- range / aura range
- uses per turn
- costs
- activation conditions
- trigger event selection
- actions
- targets
- effects
- durations
- animation metadata
It also includes help text for:
- scope
- ownership
- filters
- value expressions
- durations
- conditions
- trigger events
So it is effectively a content-authoring layer on top of the engine model.
20. Important implementation realities / caveats
20.1 Code beats builder help
The builder help is useful, but the engine code is final. If there is a mismatch, trust the server code.
20.2 Some builder options may be ahead of full engine support
The builder lists a broad trigger/effect vocabulary. Some of that is aspirational or broader than what’s fully wired today. So practical validation is still necessary.
20.3 Passive and aura content should be designed carefully
Because passives and aura transitions can reapply/revoke dynamically, sloppy content can become noisy or expensive. The system is powerful, but wants disciplined design.
20.4 Range and movement are not identical concepts
Ability range checking in this system is not the same as path-based movement legality. That matters a lot for designing blink / push / pull / support abilities.
21. Best mental model
If you want the shortest useful description:
The SOR ability system is a structured action/effect engine where cards define who they can target, when they are allowed to fire, what they do, and how long the result lasts — with enough reversibility and event support to handle passives, auras, triggers, terrain manipulation, tokens, and delayed effects cleanly.
That’s why it’s such a strong foundation.
22. Practical authoring advice
If I were using this system to author real cards, my rules of thumb would be:
-
Start simple
- one action
- one target
- one effect
-
Only add cross-action references when they truly add value
- they’re powerful, but complexity climbs fast
-
Use conditions instead of bespoke special-case text whenever possible
- especially tile-affinity and turn-state conditions
-
Respect reversibility
- temporary buffs/debuffs are safest when expressed in standard reversible effect types
-
Test trigger ownership carefully
Owner,Enemy,Any, andExactSelfmatter a lot
-
Be deliberate with terrain conditions
- terrain-aware content is one of SOR’s best unique strengths
-
For Ruins, think in random eligible packages
- one activation picks one eligible effect, not all of them
23. Final read
This is already a pretty serious system.
It supports:
- active tactical abilities
- passive board shaping
- aura gameplay
- triggered event gameplay
- player-state manipulation
- terrain mutation
- card-zone operations
- token creation
- delayed triggers
- reversible temporary changes
So from a card-design perspective, there’s a lot of room to make cards feel distinct without needing custom engine code for every idea.