Files
sor/Ability-Issues-Solutions.md

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.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.

  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.