Files
sor/Ability-Issues-Solutions.md

468 lines
15 KiB
Markdown

# 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<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)
- `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.