docs: add ability builder gaps and solutions

This commit is contained in:
Shard
2026-04-16 00:55:19 +00:00
parent ebf864b65d
commit 796fe0b4d1
+231
View File
@@ -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.