abilities.md updates

This commit is contained in:
dingo
2026-02-23 13:07:13 -05:00
parent 80c5c0408a
commit 891f422afd
+42 -7
View File
@@ -26,7 +26,8 @@ AbilityDefinition {
AuraRange: { Min, Max }
// Triggered only:
TriggerCondition: Condition
TriggerEvent: TriggerEvent // see §8; specifies when the ability fires
// ActivationConditions handles whether it fires
}
```
@@ -52,7 +53,8 @@ Always active while the unit is in play and conditions are met.
- 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.
- **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
@@ -87,6 +89,8 @@ Action {
}
```
**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.
@@ -140,6 +144,7 @@ TargetSelector {
- `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
@@ -149,6 +154,7 @@ TargetSelector {
- `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
@@ -175,6 +181,23 @@ Actions reference prior resolved targets by index (`Action1.Target`, `Action2.Ta
---
### 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
@@ -188,6 +211,7 @@ Applies to `Spirit`, `ArchSpirit`, `SpiritToken`:
- `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)
@@ -271,13 +295,15 @@ Applies to `Tile`:
- `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)` — place card from discard/hand onto battlefield
- `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, thenAction)` — find card matching filter, then perform defined action
- `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)` — channel a card directly from hand (or as selected via filter); `payCost: true` deducts normal SP/ST channel costs and all channeling rules apply; `payCost: false` channels the card without cost
- `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.
---
@@ -311,13 +337,22 @@ Rules:
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, targetTile)` — place a `SpiritToken` onto the target tile; `tokenDef` references a token definition specifying the token's stats, abilities, and genus; follows normal occupancy rules for the tile
- `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.
---
@@ -520,7 +555,7 @@ Example: `OnUnitSentToDiscard(Spirit, Any, causedBy: Self)` — fires only when
### 8.11 Card Zone Events
- `OnCardDrawn(player, filter?)`
- `OnCardDiscarded(player, cause: voluntary | forced, 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)`