diff --git a/Ability-Issues-Solutions.md b/Ability-Issues-Solutions.md index 5a288fa..2fe4e03 100644 --- a/Ability-Issues-Solutions.md +++ b/Ability-Issues-Solutions.md @@ -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` +- `op`: `AND | OR | XOR` +- `items`: `(T | LogicGroup)[]` + +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`) + +#### 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.