# Ability-Issues-Solutions ## Scope reviewed - `Server/src/SOR.Admin/Components/Pages/Cards/AbilityBuilder.razor` (UI + Help + compile/parse) - `Server/src/SOR.Game/Abilities/Models/*` (engine schema) - `Server/src/SOR.Game/Abilities/AbilitySystem.cs` (runtime behavior) --- ## Key gaps (what is missing / mismatched) ## 1) Trigger filter support is incomplete in Ability Builder ### Issue Many trigger models support `Filter` (or `UnitFilter`) fields, but Builder UI only exposes: - `OnDamageDealt.SourceFilter` (limited type-only selector) Missing in Builder for trigger definitions: - `OnUnitMove.Filter` - `OnUnitAttack.Filter` - `OnUnitAbilityActivated.Filter` - `OnUnitMPSpent.Filter` - `OnDamagePrevented.Filter` - `OnHealed.Filter` - `BeforeUnitDeath.Filter` - `BeforeDamageApplied.Filter` - `OnUnitEnterBattlefield.Filter` - `OnUnitLeaveBattlefield.Filter` - `OnUnitDeath.Filter` - `OnUnitSentToDiscard.Filter` - `OnSpiritSacrificed.Filter` - `OnTokenSummoned.Filter` - `OnStatModified.Filter` - `OnAbilityAdded.Filter` - `OnAbilityRemoved.Filter` - `OnGenusChanged.Filter` - `OnUnitOccupyRuin.Filter` - `OnTileAffinityChanged.Filter` - `OnCardDrawn.Filter` - `OnCardDiscarded.Filter` - `OnCardReturnedToHand.Filter` - `OnCardReturnedToDeck.Filter` - `OnCardsRevealed.Filter` - `OnTargetedByAbility.Filter` - `OnEffectApplied.Filter` - `OnEnterAuraRange.Filter` - `OnLeaveAuraRange.Filter` ### Solution - Add a reusable Trigger Filter editor block in `RenderTriggerFields(...)`. - Support at least one fully-parameterized filter object initially, then expand to filter arrays. - Parse/compile these fields symmetrically. --- ## 2) Action target filter editor is type-only (no parameters) ### Issue Action target filtering currently stores only first filter `$type`: - Parse: first filter only - Compile: `{ "$type": action.FilterType }` This drops required filter args for many filters: - `WithinRange(min,max)`, `DamageRange(min,max)`, `CardSPCostRange(min,max)` - `HasFlag(flag)`, `TierIs(tier)` - `TileIsOccupied(unitType)` - `TileIsAdjacentToUnit(ownership, unitFilter)` - etc. ### Solution - Replace `FilterType` string with `FilterDraft[]` on action target. - Provide per-filter field editors (same pattern as effect/condition editors). - Compile full filter object(s), not type-only placeholders. --- ## 3) Affinity expressions are narrowed to fixed only in builder for effects ### Issue Engine supports `AffinityExpr` with: - `Fixed` - `Ref` (dynamic reference) Builder compiles affinity effects as fixed only: - `SetAffinity` - `SetBaseAffinity1` - `SetBaseAffinity2` - `PushAffinity` - `PushFinalAffinity` So dynamic affinity references (e.g. `Action1.Target.Affinity`, `Self.Owner.ArchSpirit.Affinity`) cannot be authored in Builder. ### Solution - Add AffinityExpr UI equivalent to ValueExpr: - mode: Fixed / Ref - ref picker options (self, event data where valid, prior action target refs) - Compile as `{ "Fixed": ... }` or `{ "Ref": ... }`. --- ## 4) `ReturnToDeck` / `PlaceOnDeck` missing `random` option ### Issue Model supports `Position` values including `random`. Builder options only expose: - `Top`, `Bottom` ### Solution - Add `Random` to `PositionValues`. - Ensure compile uses canonical casing expected by engine (`top|bottom|random` normalization). --- ## 5) `ChannelCard` effect missing `CostMultiplier` in Builder ### Issue Model: - `ChannelCardEffect { PayCost, CostMultiplier }` Builder currently only exposes/compiles `PayCost`. ### Solution - Add optional numeric field for `CostMultiplier`. - Parse/compile round-trip. --- ## 6) `RepositionUnit` missing destination tile filters in Builder ### Issue Model: - `RepositionUnitEffect` supports `DestinationTileFilters`. Builder exposes: - tiles count / adjacency options / relative target refs But cannot author `DestinationTileFilters`. ### Solution - Add tile filter editor subset for `DestinationTileFilters`. - Parse/compile full object(s). --- ## 7) `ReturnToBattlefield` missing `TileFilter` authoring in Builder ### Issue Model: - `ReturnToBattlefieldEffect { Controller?, TileFilter? }` Builder exposes only `Controller`. ### Solution - Add optional tile filter editor for `TileFilter`. - Parse/compile support. --- ## 8) `SearchDeck.ThenAction` cannot be authored in Builder ### Issue Model: - `SearchDeckEffect { Filters?, Count, ThenAction? }` Builder supports `N` only for SearchDeck and no editor for `ThenAction`. ### Solution - Add nested Action editor for `ThenAction` (single action draft). - Parse/compile including `SearchResult`-style targeting notes in help. --- ## 9) Trigger help/documentation in Builder omits advanced trigger filter capabilities ### Issue Help panel lists trigger names and ownership concepts, but does not document: - trigger-level filter support breadth - which triggers accept amount/stat/cause/causedBy/filter combos - serialization caveats ### Solution - Add a “Trigger Field Matrix” table in Help: - Trigger name - Supported properties - Whether filter is supported - Include examples for: `OnUnitSentToDiscard.CausedBy`, `OnDamageDealt.SourceFilter` with params. --- ## 10) Potential semantic mismatch to verify: `StatTarget` includes `Base` in Builder ### Issue Builder `StatTargetValues = ["Current", "Base", "Max"]`. Engine model `StatTarget` enum appears to define only `Current`, `Max`. If true at runtime, selecting `Base` in UI can serialize invalid enum value. ### Solution - Verify enum/runtime parser behavior. - If model truly lacks Base, remove Base from Builder options. - If Base is intended, add it to model + runtime handling. --- ## 11) Ruin trigger UX: builder does not warn about source-self retrigger hazard ### Issue From gameplay behavior review, `OnRuinActivation` may unintentionally retrigger additional abilities if source trigger handling is not constrained. Builder help has no warning/pattern guidance for safe Ruin trigger authoring. ### Solution - Add Help note under Ruin triggers: - recommend `TriggerLimitPerTurn` - recommend ownership/condition patterns to prevent accidental cascade - After engine fix lands, document exact semantics in help. --- ## Recommended implementation order 1. **High impact correctness**: #1, #2, #3 2. **Model parity**: #5, #6, #7, #8 3. **Low-risk UX/docs**: #4, #9, #11 4. **Schema consistency check**: #10 --- ## Acceptance criteria for completion - Builder can round-trip (parse + compile) all currently supported model fields without silent data loss. - No filter parameters are dropped when saving edited abilities. - Help panel accurately reflects trigger/effect/filter capabilities present in runtime. - Existing authored cards remain loadable and unchanged unless explicitly edited. --- ## 12) Product-direction recap (New Card Flow + Ability Builder v2) > Source: Jason recap (2026-04-16). Keep this as implementation intent unless superseded. ### Goals - Mobile-friendly authoring flow first; desktop can add richer visual UX. - Support two authoring modes: 1) visual node/bubble drag-drop + connections, 2) plain-English prompt mapped to canonical ability JSON. - Final persisted result is a deterministic JSON block consumed by `AbilitySystem`. - Prioritize robustness and clarity over minimal feature set (high ceiling, even if some complexity is rarely used). ### New Card flow (target fields) - Core: `Name`, `CardType`, `Affinity`, `Description`, art preview metadata, `SPCost`, `STCost`. - `ArchSpirit` specifics: - `MinChannelRange`, `MaxChannelRange`, `Tier`. - If `Tier > 1`: `PreviousTierCardId` (search/select prior tier card). - `Spirit`/`ArchSpirit` combat/movement: - `AttackType` (initially melee/ranged, extensible), range fields when ranged. - stats: damage/health/defense/movement type/points. - `GenusTags` with autocomplete + create-new. - bool flags (attack/defend/be attacked/be blocked/move/obstruct/use ability/LOS behaviors). - Additional type gates: - Spirit can include `CanBeSacrificed`. - Repentance/Instinct LOS requirements as applicable. ### Ability type eligibility by CardType - `Spirit | ArchSpirit | SpiritToken | Ruin` => `Active`, `Triggered`, `Aura`, `Passive`. - `Instinct | Repentance` => `Active`, `Triggered`. ### Ability common contract (all types) - `Name` (for Instinct/Repentance default to card name; others author-defined). - `Description`. - `ActivationConditions` with nested logical groups (`AND`/`OR`/`XOR`) and N clauses. - Per-ability animation/sound assignment hooks. ### Passive / Aura semantics (authoritative distinction) - **Passive** - Always active while source is on battlefield. - Applies to all valid targets in scope. - Re-validated/applied each turn. - Removal behavior configurable when source leaves play. - **Aura** - Passive-like but range-scoped (`AuraMinRange`, `AuraMaxRange`). - Must support `OnEnterAuraRange` and `OnLeaveAuraRange` checks. - On-leave policy configurable: remove immediately / persist / linger duration. ### Triggered ability direction - Broad trigger-event map with per-event ownership/source/unit/property filters. - Trigger limit policy required: - unlimited - N per turn - N per game - Include dedicated support for aura range boundary events (`OnEnterAuraRange`, `OnLeaveAuraRange`). - **Trigger source-zone support**: triggers must be authorable to function while source card is in: - `Battlefield` - `Hand` - `Discard` - `Deck` (with explicit zone gating in trigger definition). ### Conditions and logic system direction - Use a reusable expression/group model for: - Activation conditions - Action conditions - Target property constraints - Cost option constraints - Group composition supports `AND`/`OR`/`XOR` recursively. - Comparators include `>`, `>=`, `==`, `!=`, `<=`, `<`. ### Cost system direction - Active abilities can be free or have one/more cost groups. - Cost groups support alternatives and logic composition (AND/OR/XOR). - Special UI/handler needs for interactive costs: - `DiscardFromHand`: random / self pick / enemy visible pick / enemy random pick. - `SendSpiritFromBattlefieldToDiscard` / `DealDamageToOwnSpirit`: random / self pick / enemy pick. ### Action system direction - Each ability has N actions. - Action groups can be composed with AND/OR/XOR; chooser can vary (self/opponent/random). - Each action defines: - scope (hand/deck/discard/battlefield/player and combinations), - target type, - target chooser, - count (N/all), - filters (typed + parameterized, not type-only), - optional action conditions, - one or more effects with chaining. - Variable effect amounts may be literal or sourced from target/source/expression refs. ### UI architecture implications - Reusable editors for: - logical groups, - typed filters + params, - ownership/location/range selectors, - effect payloads by scope/target. - Mobile UX should prefer progressive disclosure and compact cards/chips over large static forms. - Desktop UX can add graph view (nodes/edges) mapping 1:1 to canonical JSON. ### Canonicalization requirement - All authoring surfaces (form, graph, plain-English assistant) must map to the same JSON schema. - Parser/renderer must round-trip without semantic loss. - Prevent duplicate divergent representations between UI modes. ### 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) - `sourceZone` (`Battlefield | Hand | Discard | Deck`) - `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.