Files
cardgen/references/ability_system_detailed_readable.md

18 KiB
Raw Permalink Blame History

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.cs
  • SOR/Server/src/SOR.Admin/Components/Pages/Cards/AbilityBuilder.razor

The goal is to bridge three viewpoints at once:

  1. designers who want to understand what kinds of abilities are possible
  2. implementers who want to know how the engine actually resolves them
  3. 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 WhileSourceOnBattlefield by 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 AbilitiesJson has 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:

  1. parse the ability JSON
  2. validate source-side conditions
  3. pay costs
  4. resolve action targets
  5. apply target-side conditions
  6. execute effects
  7. 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:

  • Type
  • Name
  • Description
  • Range or AuraRange
  • UsesPerTurn
  • Cost
  • TriggerEvent
  • ActivationConditions
  • Actions
  • Duration
  • 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:

  • Battlefield
  • Hand
  • Deck
  • Discard
  • Player
  • AnyZone

6.2 Target type

Examples include:

  • Unit
  • ArchSpirit
  • Spirit
  • SpiritToken
  • Ruin
  • Tile
  • Card
  • Player

6.3 Ownership

Ownership narrows the candidate pool:

  • Self
  • ExactSelf
  • Owner
  • Ally
  • Enemy
  • Any
  • Random
  • Target

Important distinctions:

  • Self means same controller’s entities
  • ExactSelf means the exact instance using the ability
  • Target is 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:

  • Self
  • Target

Meaning:

  • some conditions evaluate the source
  • some evaluate each resolved target

Examples supported by the engine

Logical:

  • And
  • Or
  • Xor

Unit-state:

  • HealthBelow
  • HealthAbove
  • DefenseIs
  • HasGenus
  • HasAbility
  • IsOnTileWithAffinity
  • MovementTypeIs

Player-state:

  • SPAtLeast
  • SPAtMost
  • STAtLeast
  • STAtMost
  • HandSizeAtLeast
  • HandSizeAtMost
  • DeckSizeAtLeast
  • DiscardSizeAtLeast

Turn-state:

  • IsOwnTurn
  • IsOpponentTurn
  • IsAllyTurn
  • IsActivePlayerTurn

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:

  • SpiritPoints
  • SacrificeTokens
  • DiscardFromHand
  • MillTopOfDeck
  • MillBottomOfDeck
  • DealDamageToOwnArchSpirit
  • DealDamageToOwnSpirit
  • SendSpiritFromBattlefieldToDiscard

If a cost cannot be paid, activation fails.

Examples of failure codes include:

  • INSUFFICIENT_SP
  • INSUFFICIENT_ST
  • INSUFFICIENT_CARDS_TO_DISCARD
  • NO_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:

  • OnTurnStart
  • OnTurnEnd
  • OnUnitDeath
  • OnDamageDealt
  • OnUnitEnterBattlefield
  • OnUnitLeaveBattlefield
  • OnSPGained
  • OnSPSpent
  • OnSTGained
  • OnSTSpent
  • OnCardDrawn
  • OnUnitMove
  • OnUnitAttack
  • OnSpiritSacrificed
  • OnAscend
  • OnTransition
  • OnChanneled
  • OnEnterAuraRange
  • OnLeaveAuraRange
  • OnRuinActivation
  • OnUnitOccupyRuin

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:

  • ModifyHealth
  • ModifyDefense
  • ModifyDamage
  • ModifyMP
  • SetMovementType
  • SetAttackRange
  • ModifyCost
  • SetAffinity
  • GrantAdditionalAttack

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:

  • SetCanMove
  • SetCanAttack
  • SetCanDefend
  • SetCanBeAttacked
  • SetCanBeBlocked
  • SetCanBeObstructed
  • SetCanUseAbility
  • SetCanBeSacrificed

This is a huge part of what makes the game feel expressive.


11.3 Player flags

These toggle player-level permissions:

  • SetCanDrawCards
  • SetAccumulatesSP
  • SetCanChannelSpirit
  • SetCanSacrificeSpirit
  • SetCanAscendArchSpirit
  • SetCanTransitionArchSpirit
  • SetCanChannelRepentance
  • SetCanChannelInstinct
  • SetCanChannelRuin
  • SetCanChannelTerramorphaMono
  • SetCanChannelTerramorphaDi
  • SetCanChannelTerramorphaTri

So the game supports hard lockouts or permissions at player scope.


11.4 Ability modification

Abilities themselves can be changed mid-match:

  • AddAbility
  • RemoveAbility
  • EnableAbility
  • DisableAbility

That means cards can grant temporary or persistent new abilities, or suppress existing ones.


11.5 Genus changes

The engine supports:

  • AddGenus
  • RemoveGenus

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:

  • ModifySP
  • ModifySPAccumulation
  • ModifyST
  • ModifyCardsDrawnPerTurn

11.7 Tile modification

These are crucial for terrain gameplay:

  • SetBaseAffinity1
  • SetBaseAffinity2
  • PushAffinity
  • PushFinalAffinity

Important distinction

  • PushAffinity uses the normal shift rule (Base1 = old Base2; Base2 = new)
  • PushFinalAffinity directly 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:

  • DrawCards
  • DiscardCards
  • ReturnToHand
  • ReturnToDeck
  • ReturnToBattlefield
  • SendToDiscard
  • SearchDeck
  • ShuffleDeck
  • RevealCards
  • PlaceOnDeck

This means tutors, bounce, recursion, deck manipulation, and graveyard loops are all supported structurally.


11.9 Damage and healing

Combat-adjacent effects include:

  • DealDamage
  • Heal
  • DealDamageToSelf
  • DOT
  • HOT

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:

  • PushUnit
  • PullUnit
  • DisplaceUnit

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:

  • TakeControl
  • GrantMovementControl
  • SetFixedSacrificeReturn

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:

  • GenusContains
  • CardTypeIs
  • AffinityMatches
  • HasFlag
  • TierIs
  • IsSelf
  • IsExactSelf
  • HealthBelow
  • HealthAbove
  • IsAdjacentToSource
  • WithinRange

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.Damage
  • Self.Health
  • Self.Defense
  • Self.MP
  • Self.SpCost
  • Self.StCost
  • Target.Damage
  • Target.Defense
  • Target.Health
  • Target.MP
  • Target.SpCost
  • Target.StCost
  • EventData.Amount
  • Action0.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:

  • Instant
  • UntilEndOfTurn
  • UntilStartOfOwnerTurn
  • UntilStartOfSourceOwnerTurn
  • ForNTurns
  • WhileSourceOnBattlefield
  • WhileCondition
  • PermanentInMatch

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 OnRuinActivation ability 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 WhileSourceOnBattlefield effects 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:

  1. Start simple

    • one action
    • one target
    • one effect
  2. Only add cross-action references when they truly add value

    • they’re powerful, but complexity climbs fast
  3. Use conditions instead of bespoke special-case text whenever possible

    • especially tile-affinity and turn-state conditions
  4. Respect reversibility

    • temporary buffs/debuffs are safest when expressed in standard reversible effect types
  5. Test trigger ownership carefully

    • Owner, Enemy, Any, and ExactSelf matter a lot
  6. Be deliberate with terrain conditions

    • terrain-aware content is one of SOR’s best unique strengths
  7. 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.