docs(ability): normalize trigger matrix and reusable schema blocks

This commit is contained in:
Shard
2026-04-16 15:39:21 +00:00
parent 6d1c01cdb2
commit 5ec62b9d42
+126
View File
@@ -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.