diff --git a/Ability-Issues-Solutions.md b/Ability-Issues-Solutions.md new file mode 100644 index 0000000..482f90e --- /dev/null +++ b/Ability-Issues-Solutions.md @@ -0,0 +1,231 @@ +# 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.