15 KiB
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.FilterOnUnitAttack.FilterOnUnitAbilityActivated.FilterOnUnitMPSpent.FilterOnDamagePrevented.FilterOnHealed.FilterBeforeUnitDeath.FilterBeforeDamageApplied.FilterOnUnitEnterBattlefield.FilterOnUnitLeaveBattlefield.FilterOnUnitDeath.FilterOnUnitSentToDiscard.FilterOnSpiritSacrificed.FilterOnTokenSummoned.FilterOnStatModified.FilterOnAbilityAdded.FilterOnAbilityRemoved.FilterOnGenusChanged.FilterOnUnitOccupyRuin.FilterOnTileAffinityChanged.FilterOnCardDrawn.FilterOnCardDiscarded.FilterOnCardReturnedToHand.FilterOnCardReturnedToDeck.FilterOnCardsRevealed.FilterOnTargetedByAbility.FilterOnEffectApplied.FilterOnEnterAuraRange.FilterOnLeaveAuraRange.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
FilterTypestring withFilterDraft[]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:
FixedRef(dynamic reference)
Builder compiles affinity effects as fixed only:
SetAffinitySetBaseAffinity1SetBaseAffinity2PushAffinityPushFinalAffinity
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
RandomtoPositionValues. - Ensure compile uses canonical casing expected by engine (
top|bottom|randomnormalization).
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:
RepositionUnitEffectsupportsDestinationTileFilters.
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.SourceFilterwith 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
- recommend
- After engine fix lands, document exact semantics in help.
Recommended implementation order
- High impact correctness: #1, #2, #3
- Model parity: #5, #6, #7, #8
- Low-risk UX/docs: #4, #9, #11
- 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:
- visual node/bubble drag-drop + connections,
- 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. ArchSpiritspecifics:MinChannelRange,MaxChannelRange,Tier.- If
Tier > 1:PreviousTierCardId(search/select prior tier card).
Spirit/ArchSpiritcombat/movement:AttackType(initially melee/ranged, extensible), range fields when ranged.- stats: damage/health/defense/movement type/points.
GenusTagswith 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.
- Spirit can include
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.ActivationConditionswith 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
OnEnterAuraRangeandOnLeaveAuraRangechecks. - On-leave policy configurable: remove immediately / persist / linger duration.
- Passive-like but range-scoped (
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:
BattlefieldHandDiscardDeck(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/XORrecursively. - 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 | XORitems:(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
minmax- optional LOS + shape flags (
requiresLos,linearOnly, extensible)
A7) FilterClause
fieldcomparatorvalue(ValueExpr)
A8) TargetSelector
scopetargetTypechooser(Self | Ally | Opponent | Random)count(N | All)filters(LogicGroup<FilterClause | TypedFilter>)
A9) TypedFilter
typeparams(strongly typed by filter kind; never type-only serialization)
A10) DurationPolicy
instantuntilEndOfTurnforTurns(n)whileSourceInPlayuntilCondition
A11) LeavePolicy (Aura/continuous cleanup)
removeImmediatelypersistlinger(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,OnUnitMPSpentOnDamageDealt,OnDamagePrevented,OnHealed,BeforeDamageApplied,BeforeUnitDeath- Common filters: actor ownership, unit filter, amount comparator
B3) Battlefield presence / status
OnUnitEnterBattlefield,OnUnitLeaveBattlefield,OnUnitDeath,OnUnitSentToDiscardOnSpiritSacrificed,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)
eventTypeactor(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)turnIndextimestamp
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
- Add shared DSL models in admin builder drafts (
LogicGroup,TypedFilter,TargetSelector,DurationPolicy). - Refactor trigger editors to event-family templates instead of per-event bespoke forms.
- Add JSON canonicalization tests to guarantee graph/form/English mode parity.
- Add migration shim for legacy type-only filters.