docs: add ability builder gaps and solutions
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user