468 lines
15 KiB
Markdown
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.
|