docs(ability): normalize trigger matrix and reusable schema blocks
This commit is contained in:
@@ -332,3 +332,129 @@ Builder help has no warning/pattern guidance for safe Ruin trigger authoring.
|
||||
|
||||
### Cleanup task noted by Jason
|
||||
- De-duplicate overlapping items in this document and extract reusable structure blocks (shared condition/filter/action schemas).
|
||||
|
||||
---
|
||||
|
||||
## 13) Normalized reusable schema blocks + Trigger Event Matrix (dedupe pass)
|
||||
|
||||
### A. Reusable blocks (single source of truth)
|
||||
|
||||
#### A1) `LogicGroup<T>`
|
||||
- `op`: `AND | OR | XOR`
|
||||
- `items`: `(T | LogicGroup<T>)[]`
|
||||
|
||||
Use for:
|
||||
- Activation conditions
|
||||
- Action conditions
|
||||
- Cost option groups
|
||||
- Target/property filter groups
|
||||
|
||||
#### A2) `Comparator`
|
||||
- `> | >= | == | != | <= | <`
|
||||
|
||||
#### A3) `ValueExpr`
|
||||
- `fixed` (literal)
|
||||
- `ref` (path/expression reference)
|
||||
|
||||
#### A4) `OwnershipScope`
|
||||
- `Self | Ally | Opponent | Any`
|
||||
|
||||
#### A5) `LocationScope`
|
||||
- `Hand | Deck | Discard | Battlefield | Player`
|
||||
- Composite scopes supported via explicit list.
|
||||
|
||||
#### A6) `RangeSpec`
|
||||
- `min`
|
||||
- `max`
|
||||
- optional LOS + shape flags (`requiresLos`, `linearOnly`, extensible)
|
||||
|
||||
#### A7) `FilterClause`
|
||||
- `field`
|
||||
- `comparator`
|
||||
- `value` (`ValueExpr`)
|
||||
|
||||
#### A8) `TargetSelector`
|
||||
- `scope`
|
||||
- `targetType`
|
||||
- `chooser` (`Self | Ally | Opponent | Random`)
|
||||
- `count` (`N | All`)
|
||||
- `filters` (`LogicGroup<FilterClause | TypedFilter>`)
|
||||
|
||||
#### A9) `TypedFilter`
|
||||
- `type`
|
||||
- `params` (strongly typed by filter kind; never type-only serialization)
|
||||
|
||||
#### A10) `DurationPolicy`
|
||||
- `instant`
|
||||
- `untilEndOfTurn`
|
||||
- `forTurns(n)`
|
||||
- `whileSourceInPlay`
|
||||
- `untilCondition`
|
||||
|
||||
#### A11) `LeavePolicy` (Aura/continuous cleanup)
|
||||
- `removeImmediately`
|
||||
- `persist`
|
||||
- `linger(duration)`
|
||||
|
||||
### B. Trigger Event Matrix (normalized)
|
||||
|
||||
> Intention: collapse large event list into consistent event families + shared payload contract.
|
||||
|
||||
#### B1) Turn / lifecycle
|
||||
- `OnTurnStart`, `OnTurnEnd`, `OnAscend`, `OnTransition`, `OnChanneled`
|
||||
- Common filters: actor ownership, source card/unit, unit property filters
|
||||
|
||||
#### B2) Unit combat / movement / ability
|
||||
- `OnUnitMove`, `OnUnitAttack`, `OnUnitAbilityActivated`, `OnUnitMPSpent`
|
||||
- `OnDamageDealt`, `OnDamagePrevented`, `OnHealed`, `BeforeDamageApplied`, `BeforeUnitDeath`
|
||||
- Common filters: actor ownership, unit filter, amount comparator
|
||||
|
||||
#### B3) Battlefield presence / status
|
||||
- `OnUnitEnterBattlefield`, `OnUnitLeaveBattlefield`, `OnUnitDeath`, `OnUnitSentToDiscard`
|
||||
- `OnSpiritSacrificed`, `OnTokenSummoned`, `OnStatModified`, `OnGenusChanged`
|
||||
- Common filters: ownership + unit/property filter
|
||||
|
||||
#### B4) Ability mutation / targeting
|
||||
- `OnAbilityAdded`, `OnAbilityRemoved`, `OnTargetedByAbility`, `OnEffectApplied`
|
||||
- Common filters: source ownership, affected-unit filter, ability/effect metadata filters
|
||||
|
||||
#### B5) Ruin / occupancy
|
||||
- `OnRuinActivation`, `OnUnitOccupyRuin`
|
||||
- Common filters: ruin ownership/state, occupant filter
|
||||
|
||||
#### B6) Tile / affinity
|
||||
- `OnTileAffinityChanged`
|
||||
- Common filters: tile ownership zone, tile property filter, nearby occupancy filters
|
||||
|
||||
#### B7) Resource / hand economy
|
||||
- `OnSPGained`, `OnSPSpent`, `OnSTGained`, `OnSTSpent`
|
||||
- Common filters: player ownership, amount comparator
|
||||
|
||||
#### B8) Card movement / visibility
|
||||
- `OnCardDrawn`, `OnCardDiscarded`, `OnCardReturnedToHand`, `OnCardReturnedToDeck`, `OnDeckShuffled`, `OnCardsRevealed`
|
||||
- Common filters: card ownership/type/affinity/cost + amount/count comparators
|
||||
|
||||
#### B9) Aura boundary
|
||||
- `OnEnterAuraRange`, `OnLeaveAuraRange`
|
||||
- Common filters: aura source, entering/leaving unit filter, ownership
|
||||
|
||||
### C. Unified trigger payload contract (engine + builder)
|
||||
- `eventType`
|
||||
- `actor` (who caused event)
|
||||
- `subject` (primary unit/card/tile/player affected)
|
||||
- `source` (ability/card/effect source)
|
||||
- `amount?` (numeric payload for spend/damage/heal/etc.)
|
||||
- `context` (event-specific extras, e.g., occupant, causedBy, stat, affinity)
|
||||
- `turnIndex`
|
||||
- `timestamp`
|
||||
|
||||
This payload should be the basis for:
|
||||
- Trigger filter authoring
|
||||
- Plain-English prompt mapping
|
||||
- Debug/audit logs in admin/testing tools
|
||||
|
||||
### D. Near-term implementation split
|
||||
1. Add shared DSL models in admin builder drafts (`LogicGroup`, `TypedFilter`, `TargetSelector`, `DurationPolicy`).
|
||||
2. Refactor trigger editors to event-family templates instead of per-event bespoke forms.
|
||||
3. Add JSON canonicalization tests to guarantee graph/form/English mode parity.
|
||||
4. Add migration shim for legacy type-only filters.
|
||||
|
||||
Reference in New Issue
Block a user