diff --git a/Shared/context-files/abilities.md b/Shared/context-files/abilities.md index 7cad41a..0bb30ff 100644 --- a/Shared/context-files/abilities.md +++ b/Shared/context-files/abilities.md @@ -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)`