Files
sor/BuilderR3.md
T
8f3911e881 feat(ability): implement AbilityBuilderR3 + engine additions
Engine:
- AbilityDefinition: add SourceZoneGate (zone-restricted triggers) and TriggerLimitPerGame
- Effects: add StatModOperator (Add/Subtract/Multiply/Divide/Percent) on all stat mod effects; reversal stored as delta
- Action/CostEntry: add CostPickMode enum (Random/SelfPick/EnemySeePick/EnemyRandomPick/EnemyPick)
- PendingCostPick: new model for interactive cost pause/resume (mirrors PendingTriggeredTarget)
- GameState: PendingCostPick field
- GameMessages: CostPickRequestPush, GameCostPickRequest, GameCostPickResponse records
- AbilitySystem: FireTrigger scans Hand/Discard/Deck when SourceZoneGate set; per-game trigger limit tracking; ApplyStatOperator helper; PayCosts/ResumeCostPick for interactive cost flow
- GameCostPickHandler + ServiceRegistration wiring

Admin:
- AbilityBuilderR3.razor: full ability builder at /cards/ability-builder-r3 (39 triggers, 69 effects, 32 conditions, form/canvas/mermaid modes, compiles to engine-native $type JSON)
- AbilityBuilderR2-Draft.razor: fix switch expression no-best-type error

Docs:
- BuilderR3.md: master plan document

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
2026-04-18 20:15:13 -04:00

37 KiB
Raw Blame History

BuilderR3 — Master Plan: New Card Flow + Ability Builder

Synthesized from: BuilderR2.md · AbilityBuilderR2-Draft.razor assessment · long-form design spec
Scope: SOR.Admin UI authoring pipeline only. Engine runtime internals out of scope.
Date: 2026-04-16


0) Vision Statement

Design abilities the way you think about them — grab pieces, connect them, see the flow.
The canvas is the JSON. The English description is the JSON. The form is the JSON.
Three surfaces, one output, zero ambiguity.

The ideal experience:

  1. Fill in a card's core details (name, type, affinity, stats).
  2. Open the Ability Builder — a canvas of typed bubble nodes you drag, drop, and connect.
  3. Wire: Trigger → Condition Group → Cost Group → Action Group → Effects.
  4. The canvas re-renders in real time as a flowchart that is the ability.
  5. Hit Validate. Hit Save. The canonical JSON block is emitted — exactly what the AbilitySystem parses.

Mobile fallback: a progressive-disclosure form that maps one-to-one to the same canonical model.
Power user add-on: plain-English description → AI maps it to draft nodes → designer confirms.


1) Architecture

1.1 Three authoring surfaces, one model

Form Editor  ──┐
Visual Editor ──┼──► AbilityDefinitionDraftR3  ──► Canonical JSON  ──► AbilitySystem
English/AI ────┘        (single source of truth)

All three surfaces read from and write to AbilityDefinitionDraftR3.
No surface has its own persistence format.
Saving always goes through: Draft → Validate → Canonical JSON → DB.

1.2 Visual Editor ("Bubble Canvas")

The primary design goal for the ability builder is a node-and-wire canvas where:

  • Each structural piece (Trigger, Condition Group, Cost Group, Action Group, Effect) is a bubble node.
  • Nodes have typed output ports (e.g., a Trigger node has a → when active port).
  • Connecting a port to another node creates the structural relationship in the draft model.
  • Invalid connections are blocked at the UI level (port types don't match).
  • The rendered connection graph IS the ability flowchart — no separate diagram step needed.
  • Sidebar: selected node shows its property form.
  • Read-only JSON panel: always reflects current canonical output.

Visual mode is desktop-first. Mobile falls back to Form mode automatically.

1.3 Form Editor

Progressive-disclosure form, mobile-first:

  • Step 1: Common fields (Name, Description, Type, Limits, Presentation).
  • Step 2: Type section (Active / Triggered / Passive / Aura).
  • Step 3: Activation Conditions.
  • Step 4: Costs (Active only).
  • Step 5: Actions and Effects.
  • Step 6: Validate + Preview + Save.

Each step is collapsible. Errors are sticky at the bottom.

1.4 English / AI Surface

  1. Designer types plain-English intent.
  2. AI assistant produces a structured draft + confidence score + unresolved slots.
  3. Draft is loaded into Visual or Form editor for designer review.
  4. Unresolved slots are explicit TODO placeholders — never silently defaulted.
  5. Save is only available after all TODOs are resolved and validation passes.
  6. A diff panel shows AI-generated vs confirmed fields.

2) Canonical Data Model — AbilityDefinitionDraftR3

This is the single in-memory representation all surfaces write to.

sealed class AbilityDefinitionDraftR3
{
    // --- Common ---
    string Name;
    string Description;
    string Type;                    // Active | Triggered | Passive | Aura
    LimitsDraft Limits;
    PresentationDraft Presentation;
    LogicGroupDraft ActivationConditions;

    // --- Type sections (only one populated per ability) ---
    ActiveDraft?    Active;
    TriggeredDraft? Triggered;
    PassiveDraft?   Passive;
    AuraDraft?      Aura;

    // --- Costs (Active only; may appear on Triggered via spec extension) ---
    CostGroupDraft Costs;

    // --- Actions ---
    ActionGroupDraft Actions;
}

sealed class LimitsDraft
{
    int? PerTurn;
    int? PerGame;
}

sealed class PresentationDraft
{
    string? Animation;
    string? AnimationAsset;
    string? CastSfx;
    string? ImpactSfx;
}

2.1 Active section

sealed class ActiveDraft
{
    int  RangeMin;
    int  RangeMax;
    bool RequiresLos;
    bool LinearOnly;
    int? UsesPerTurn;
}

2.2 Triggered section

sealed class TriggeredDraft
{
    string   EventFamily;            // see §5 trigger catalog
    string   EventType;              // canonical event key
    string   LimitMode;             // Unlimited | PerTurn | PerGame
    int?     LimitAmount;
    List<string> SourceZoneGate;    // Battlefield | Hand | Discard | Deck (multi-select)
    string   OwnershipScope;        // Any | Self | Ally | Opponent
    string?  AmountComparator;      // > | == | < | != | <= | >=
    int?     Amount;
    List<TypedFilterDraft> Filters;
}

2.3 Passive section

sealed class PassiveDraft
{
    string ContinuousScope;     // Global | Battlefield | Zone | Self
    string RecheckCadence;      // OnAnyEvent | OnTurnStart | OnTurnEnd | Manual
    string SourceLeavePolicy;   // Remove | Linger | Keep
}

2.4 Aura section

sealed class AuraDraft
{
    int     RangeMin;
    int     RangeMax;
    string? EnterHook;          // ability key to trigger on enter
    string? LeaveHook;          // ability key to trigger on leave
    string  LeavePolicy;        // Remove | Linger
    int?    LingerDuration;
}

2.5 Logic group (conditions, nested)

sealed class LogicGroupDraft
{
    string Logic = "AND";       // AND | OR | XOR
    List<ConditionRuleDraft> Rules;
    List<LogicGroupDraft>    Groups;   // max depth: 3
}

sealed class ConditionRuleDraft
{
    string Domain;        // see §6 condition domains
    string Field;
    string Comparator;    // > | == | < | != | <= | >=
    string Value;
}

2.6 Cost group

sealed class CostGroupDraft
{
    string Logic = "AND";           // AND | OR (alternatives)
    List<CostDraft>      Costs;
    List<CostGroupDraft> Groups;
}

sealed class CostDraft
{
    string  Type;                   // see §7 cost catalog
    int?    Amount;
    string? PickMode;               // Random | SelfPick | EnemySeePick | EnemyRandomPick | EnemyPick
    string? Chooser;                // Self | Opponent | Random
}

2.7 Action group

sealed class ActionGroupDraft
{
    string Logic = "AND";               // AND | OR | XOR
    string? ChooserAuthority;           // Self | Opponent | Random | System (OR/XOR only)
    List<ActionDraft>      Actions;
    List<ActionGroupDraft> Groups;
}

sealed class ActionDraft
{
    string  Scope;              // see §8 scope catalog
    string  TargetType;
    string  Chooser;            // Self | Opponent | Random | System
    int?    Count;
    bool    All;
    List<TypedFilterDraft>  Filters;
    LogicGroupDraft         Conditions;
    List<EffectDraft>       Effects;
}

2.8 Typed filter

sealed class TypedFilterDraft
{
    string Type;            // filter category key
    string Field;           // specific field within type
    string Comparator;      // > | == | < | != | <= | >=
    string Value;
    string? ParameterKey;   // for parameterized filters
    string? ParameterValue;
}

2.9 Effect

sealed class EffectDraft
{
    string  Type;                   // canonical effect key — see §9 effect catalog
    int?    Amount;
    string? AmountSource;           // value expression: "Target.Damage", "Self.Health", etc.
    string? DurationMode;           // Permanent | Turns | UntilEndOfTurn | UntilNextTurn
    int?    DurationN;
    string? ParameterKey;
    string? ParameterValue;

    // Stat modification (for stat mod effects)
    string? StatModOperator;        // Add | Subtract | Multiply | Divide | Percent

    // Zone movement metadata
    string? ZonePosition;           // Top | Bottom | Random
    bool    ResetToDefinition;
}

3) Card Creation Wizard — New Card Flow R3

3.1 Step overview

Step Name Content
1 Core Name, CardType, Affinity, Description, art preview, SP cost, ST cost
2 Type-Specific Stats, movement, genus tags, ArchSpirit channel/tier settings
3 Flags & Constraints Can-booleans, LOS requirements
4 Abilities Add/edit/reorder abilities (opens Ability Builder per ability)
5 Review + Save Human-readable summary, canonical JSON preview, validation panel

3.2 Step 1 — Core

  • Name (required)
  • CardType: Spirit | ArchSpirit | SpiritToken | Ruin | Instinct | Repentance | Terramorpha
  • Affinity: Fire | Water | Earth | Air | Void | Neutral (+ multi-affinity support)
  • Description (flavor/rules text)
  • Art preview (asset path or upload)
  • SP Cost (int ≥ 0)
  • ST Cost (int ≥ 0)

3.3 Step 2 — Type-Specific

Spirit and ArchSpirit additional fields:

Field Type Notes
Attack Type Melee | Ranged | Extensible
Attack Range Min int Ranged only
Attack Range Max int Ranged only
Damage int
Health int
Defense int
Movement Type string e.g. Walk, Fly, Burrow
Movement Points int
Genus Tags List<string> autocomplete + create-new

ArchSpirit additional fields:

Field Type Notes
Channel Range Min int
Channel Range Max int
Tier int 1–N
Previous Tier Card CardRef? required if Tier > 1 — search by name

3.4 Step 3 — Flags & Constraints

Universal booleans:

  • Can Attack
  • Can Defend
  • Can Be Attacked
  • Can Be Blocked
  • Can Move
  • Can Be Obstructed
  • Can Use Ability
  • Has LOS Requirement

Type-gated booleans:

  • Spirit: Can Be Sacrificed
  • Repentance / Instinct: LOS handling mode (selector, not just bool)

3.5 Step 4 — Abilities

  • Ability list with drag-to-reorder.
  • + Add Ability opens the Ability Builder (see §4).
  • Type gating enforced in the ability type selector:
    • Spirit / ArchSpirit / SpiritToken / Ruin → Active | Triggered | Aura | Passive
    • Instinct / Repentance → Active | Triggered only
  • Instinct / Repentance: default ability name to card name; designer may override.

3.6 Step 5 — Review + Validate + Save

  • Human-readable summary panel: "Spirit 'Emberveil' — 3 abilities — Tier 2 ArchSpirit…"
  • Canonical JSON accordion (collapsible per field group).
  • Validation panel (see §10).
  • Save disabled while blocking errors exist.
  • Non-blocking warnings shown with save-anyway option.

4) Ability Builder — Three-Mode UI

4.1 Common header (all modes)

  • Ability Name, Description, Type selector.
  • Limits: Per Turn / Per Game (optional ints).
  • Presentation: Animation key, Animation Asset, Cast SFX, Impact SFX.
  • Mode switcher: Form | Visual | English (tabs).

4.2 Form Mode — type section routing

After common fields, route to type-specific section:

Active:

  • Range Min / Max
  • Requires LOS (bool)
  • Linear Only (bool)
  • Uses Per Turn (optional int)
  • → then Activation Conditions → Costs → Actions

Triggered:

  • Trigger Event (family → event picker, see §5)
  • Source Zone Gate (multi-select: Battlefield / Hand / Discard / Deck)
  • Ownership Scope (Any / Self / Ally / Opponent)
  • Trigger Filters (typed, see §5 per-event filter schema)
  • Trigger Limits (Unlimited / N per turn / N per game)
  • → then Activation Conditions → Actions (no costs on triggered by default)

Passive:

  • Continuous Scope (Global / Battlefield / Zone / Self)
  • Recheck Cadence (OnAnyEvent / OnTurnStart / OnTurnEnd / Manual)
  • Source Leave Policy (Remove / Linger / Keep)
  • → then Activation Conditions → Actions

Aura:

  • Range Min / Max
  • Enter Hook (optional ability key)
  • Leave Hook (optional ability key)
  • Leave Policy (Remove / Linger)
  • Linger Duration (optional int, Linger only)
  • → then Activation Conditions → Actions

4.3 Visual Mode — Bubble Canvas

Node palette (left sidebar)

Node Type Color Ports
Trigger Purple → when active
Condition Group Blue ← from trigger/action; → to action/cost
Cost Group Orange ← from condition; → to action
Target Selector Teal ← from action; → effects
Action Group Green ← from cost/trigger; → effects
Effect Red ← from action
Duration/Policy Grey ← from effect

Canvas behaviors

  • Drag node from palette → drops onto canvas.
  • Drag from output port → hover over compatible input port → release to connect.
  • Incompatible port types: connection blocked with a red indicator.
  • Click node → property sidebar opens (right panel, replaces JSON view temporarily).
  • Connection line labels show logic type (AND / OR / XOR).
  • Delete node: Backspace or right-click menu.
  • Undo/redo: Ctrl+Z / Ctrl+Y.

Execution path preview

  • When a node is selected, the path from Trigger → Effect is highlighted on the canvas.
  • A readable sequence list appears beneath the canvas: "1. When [event] from [zone] → 2. If [condition] → 3. Pay [cost] → 4. Target [N] [type] → 5. Apply [effect]".

JSON sync

  • Every canvas edit immediately updates AbilityDefinitionDraftR3.
  • JSON panel (bottom-right) reflects current canonical output in real time.
  • "Decompile from JSON" button: paste existing JSON → re-renders as nodes.

4.4 English / AI Mode

  • Large textarea: "Describe what this ability does in plain English."
  • Submit → AI generates draft nodes (confidence 0–1 per slot).
  • Low-confidence slots marked yellow; unresolved (null) slots marked red as TODO.
  • Designer can accept, edit, or reject each slot inline.
  • Diff panel: shows AI-proposed values vs current model.
  • "Apply to Canvas" button loads confirmed slots into Visual mode for final wiring.
  • Save unavailable until all TODO slots resolved.

5) Trigger Event Catalog

5.1 Event families and events

Family Events
Lifecycle TurnStart, TurnEnd, GameStart, GameEnd, ChannelStart, ChannelEnd
Unit — Combat AttackDeclared, AttackResolved, BlockDeclared, DefendDeclared, DamageDelt, DamageReceived, HealReceived, DeathOccurred
Unit — Move/Ability MoveDeclared, MoveResolved, AbilityActivated, AbilityResolved, AbilityTargeted
Battlefield State SpiritEntersBattlefield, SpiritLeavesBattlefield, RuinActivated, RuinDeactivated, TileAffinityChanged, AuraEntered, AuraLeft
Resource Economy SpGained, SpSpent, StGained, StSpent
Card Movement CardDrawn, CardDiscarded, CardReturned, CardRevealed, CardShuffled, CardSentToZone
Stat / Ability Mutation StatModified, AbilityAdded, AbilityRemoved, GenusChanged, AffinityChanged
Ruin / Occupancy RuinOccupied, RuinVacated, RuinDestroyed
Token TokenCreated, TokenDestroyed, SpiritSacrificed

5.2 Per-event filter schema

Every trigger event exposes only the filters valid for that event. Example schemas:

DamageDelt / DamageReceived:

  • Ownership: Any | Self | Ally | Opponent
  • Source type: Any | Spirit | ArchSpirit | Ability | Ruin
  • Amount comparator + value

SpiritEntersBattlefield / SpiritLeavesBattlefield:

  • Ownership scope
  • Genus match (exact | contains)
  • Affinity match

CardDrawn / CardDiscarded / CardReturned:

  • Card type filter
  • Ownership scope
  • Zone source/destination

SpGained / SpSpent / StGained / StSpent:

  • Amount comparator + value
  • Who: Self | Opponent | Any

AbilityActivated / AbilityTargeted:

  • Ownership scope
  • Ability type filter
  • Target type filter

TileAffinityChanged:

  • Affinity before / after
  • Ownership of tile occupant

AuraEntered / AuraLeft:

  • Aura source ownership
  • Entity type entering/leaving

5.3 Trigger limits

  • Unlimited
  • N per turn (int input)
  • N per game (int input)

5.4 Source zone gate

Multi-select; at least one required for Triggered abilities.

Option Meaning
Battlefield Card must be deployed on the battlefield
Hand Card must be in owner's hand
Discard Card must be in discard pile
Deck Card must be in deck

Default for new Triggered abilities: [Battlefield].


6) Condition System

6.1 Logic structure

Conditions use nested LogicGroupDraft (AND / OR / XOR, max depth 3).
Conditions appear in three places:

  1. Activation conditions — on the ability itself (when is it legal to use/fire).
  2. Action conditions — per action (is this action branch taken).
  3. Target conditions — per filter (does this target qualify).

6.2 Condition domains

Domain Fields Available
Turn / Timing IsMyTurn, IsOpponentTurn, TurnNumber, PhaseType
Unit — Ownership Owner (Self/Ally/Opponent/Any), IsAlly, IsEnemy
Unit — Type CardType, Genus (contains/exact), Affinity
Unit — Properties Damage, Health, Defense, MovementPoints, CurrentHealth, AttackType
This Card Name (exact), SP cost, ST cost, HealthRemaining, IsChanneling
This Card Definition — Zone Count CountInZone (zone, comparator, amount)
Location — Zone Counts HandSize, DeckSize, DiscardSize, BattlefieldCount (by type)
Tile — Occupied IsOccupied, OccupantType, OccupantOwner, OccupantGenus
Tile — Surrounding AdjacentTileCount (by affinity/occupant), OccupiedNeighborCount
Tile — Affinity TileAffinity (matches/contains list)
Player — Resources SP, ST, AccumulatedSP, AccumulatedST
Player — Hand/Deck/Discard HandSize, DeckSize, DiscardSize, HasCardOfType
Player — Channel State HasChanneledThisTurn, ChannelCount

6.3 Comparators

> | == | < | != | <= | >=


7) Cost System

7.1 Cost group structure

CostGroupDraft is a recursive group with AND (all costs required) or OR (alternative cost paths).

7.2 Cost type catalog

Cost Key Description Required Metadata
PaySP Spend N spirit points Amount
PayST Spend N soul tokens Amount
DiscardFromHand Discard card(s) from hand Amount, PickMode
SendSpiritFromBattlefieldToDiscard Remove own spirit from battlefield Amount, PickMode
DealDamageToOwnSpirit Deal damage to own spirit Amount, PickMode
SacrificeSpirit Sacrifice a spirit permanently Amount, PickMode
SkipAction Forfeit an action this turn —
ExhaustSpirit Exhaust (tap) a spirit Amount, Chooser

7.3 Pick mode values

Required for all costs with PickMode:

Mode Description
Random System picks randomly
SelfPick Controlling player picks
EnemySeePick Opponent picks (sees options)
EnemyRandomPick Opponent picks (random from options)
EnemyPick Opponent picks (any method)

8) Action and Targeting System

8.1 Action group structure

ActionGroupDraft supports AND / OR / XOR.
OR / XOR require ChooserAuthority (Self / Opponent / Random / System).

8.2 Scope catalog

Scope Valid Target Types
Hand AnyCard, ByType, ByName
Deck AnyCard, ByType, ByName
Discard AnyCard, ByType, ByName
Battlefield Spirit, ArchSpirit, SpiritToken, Ruin, Tile
Player Self, Ally, Opponent, All, Random
Hand+Deck Combined search
Hand+Discard Combined search
Battlefield+Hand Combined send/recall

8.3 Chooser values

Self | Opponent | Random | System

8.4 Count options

  • Fixed N (int input)
  • All matching targets (All flag)

8.5 Target type details by scope

Battlefield targets:

Target Type Notes
Spirit Any spirit unit
ArchSpirit Any arch-spirit
SpiritToken Any spirit token
Ruin Any ruin structure
Tile Grid tile (position-based)

Player targets:

Target Notes
Self Controlling player
Ally Allied player (multiplayer)
Opponent Opposing player
All All players
Random Random player

Player targets support additional property filters (SP / ST / hand size / etc.).


9) Effect Catalog

Organized by scope. Each effect lists its required and optional parameters.

9.1 Hand / Deck / Discard operations

Effect Key Description Params
SendToHand Move target card(s) to hand —
SendToDeck Move target card(s) to deck ZonePosition (Top/Bottom/Random)
SendToDiscard Move target card(s) to discard —
ShuffleDeck Shuffle target player's deck —
SearchDeck Search deck for card matching filter FilterType, ZonePosition (where to put result)
StackDeck Place specific card on top of deck —
DrawCards Draw N cards Amount, AmountSource
DiscardCards Discard N cards from hand Amount, PickMode
RevealCard Reveal top N cards of deck Amount

9.2 Channeling operations

Effect Key Card Type Description Params
ChannelSpirit Spirit Channel target spirit card IgnoreCost, IgnoreRange, IgnoreAffinity, IgnoreTurnLimit
ChannelArchSpirit ArchSpirit Channel target arch-spirit same flags
ChannelInstinct Instinct Channel instinct card IgnoreCost
ChannelRepentance Repentance Channel repentance card IgnoreCost
ChannelRuin Ruin Place/activate ruin IgnoreCost, IgnoreRange
ChannelFromHand Any Channel any card from hand Type filter, IgnoreFlags
ChannelFromDeck Any Channel any card from top of deck Type filter, IgnoreFlags

9.3 Unit — health / damage operations

Effect Key Description Params
DealDamage Deal N damage to target Amount, AmountSource
HealDamage Heal N damage on target Amount, AmountSource
ApplyDot Apply damage-over-time Amount, DurationMode, DurationN
ApplyHot Apply heal-over-time Amount, DurationMode, DurationN
PreventDamage Prevent next N damage Amount, DurationMode
PreventDeath Prevent next death DurationMode

9.4 Unit — movement and positioning

Effect Key Description Params
PushUnit Push target N tiles in direction Amount, Direction (Away/Toward/Cardinal)
PullUnit Pull target N tiles toward caster Amount
DisplaceUnit Move unit to specific tile TargetTile (selector)
SwapPositions Swap two units —

9.5 Unit — stat modifications

Effect Key Description Params
ModifyStat Modify a numeric stat Stat (Damage/Health/Defense/MovementPoints/AttackRangeMin/AttackRangeMax), StatModOperator, Amount, AmountSource, DurationMode, DurationN
ToggleBool Toggle a boolean capability BoolKey (CanAttack/CanDefend/CanMove/CanUseAbility/etc.), Value (true/false), DurationMode

StatModOperator values: Add | Subtract | Multiply | Divide | Percent

9.6 Unit — genus / affinity / ability mutations

Effect Key Description Params
AddGenus Add genus tag to unit GenusTag
RemoveGenus Remove genus tag from unit GenusTag
ChangeAffinity Change unit affinity Affinity, DurationMode
AddAbility Grant an ability to target AbilityKey, DurationMode
RemoveAbility Remove an ability from target AbilityKey

9.7 ArchSpirit-specific operations

Effect Key Description Params
AscendArchSpirit Ascend arch-spirit to next tier IgnoreCost
TransitionVariant Transition to alternate form VariantKey
ModifyChannelRange Adjust channel range Min, Max, StatModOperator

9.8 Spirit-specific operations

Effect Key Description Params
CloneAsToken Create spirit token copy of target —
TakeControl Take control of target spirit DurationMode, DurationN
TakeControlTemporary Take control until end of turn —
ReturnToOwner Return controlled spirit to its owner —
ModifyTokenReturnPolicy Change what happens when token expires Policy

9.9 SpiritToken-specific operations

Effect Key Description Params
DestroyToken Destroy target spirit token —

9.10 Ruin-specific operations

Effect Key Description Params
RelocateRuin Move ruin to target tile TargetTile
DisableRuin Disable ruin ability DurationMode, DurationN
ActivateRuinAbility Force-activate a ruin's ability AbilityKey
SendRuinToZone Send ruin card to zone Zone

9.11 Tile operations

Effect Key Description Params
SetTileAffinity Set tile affinity Affinity
PushTileAffinity Push affinity to neighbors Affinity, Radius
ResolveTileEffect Force tile effect resolution —

9.12 Player resource operations

Effect Key Description Params
ModifySP Add/subtract SP Amount, AmountSource, StatModOperator
ModifyST Add/subtract ST Amount, AmountSource, StatModOperator
SkipTurn Force target to skip their next turn —
ToggleChannelCapability Enable/disable a channel type for player ChannelType, Value, DurationMode

9.13 Token creation

Effect Key Description Params
CreateTokenFromCard Create token copy of an existing card CardKey, OwnershipMode
CreateCustomToken Create token from inline template TokenTemplate (name/stats/abilities)
ChannelCreatedToken Immediately channel the created token IgnoreFlags

9.14 Value expressions (AmountSource)

Effect amounts can be sourced from runtime game state:

Expression Meaning
Target.Damage Target unit's current damage stat
Target.Health Target unit's current health
Target.Defense Target unit's current defense
Target.CurrentHealth Target unit's remaining health
Self.Damage Caster's damage stat
Self.Health Caster's health stat
Self.CurrentHealth Caster's remaining health
Self.SP Caster's current SP
Action0.Target.SpCost SP cost of first action's target
Trigger.Amount Amount from the trigger event (e.g., damage dealt)

10) Validation System

10.1 Three validation stages

Stage 1 — Schema

  • Required fields present and correctly typed.
  • Enums within valid value sets.
  • Range min ≤ range max.
  • Logic group depth ≤ 3.

Stage 2 — Semantic

  • Ability type gating: Passive/Aura not valid on Instinct/Repentance cards.
  • Trigger event compatible with selected family.
  • Source zone gate populated (Triggered abilities).
  • Filter parameters correct for event type.
  • Cost pick mode required when cost type demands it.
  • Effect parameters present and typed correctly.
  • Value expressions reference valid game state properties.

Stage 3 — Flow

  • Action group with OR/XOR has a ChooserAuthority.
  • All TODO slots resolved (English mode).
  • Target scope + target type combination is valid.
  • Effect type valid for selected scope.
  • Loop risk detection: Triggered ability that fires on events it can itself produce → Warning: recommend limits.

10.2 Validation issue model

record ValidationIssue(
    string Severity,      // Error | Warning | Info
    string Code,          // stable dot-notation key, e.g. "trigger.sourceZoneGate.empty"
    string Path,          // JSON path to field, e.g. "triggered.sourceZoneGate"
    string Message,       // human-readable
    string SuggestedFix   // actionable suggestion
);

10.3 Error panel UX

  • Sticky at bottom of builder (all modes).
  • Errors: red badge count in tab header.
  • Warnings: yellow badge.
  • Click issue → navigates to the relevant node (visual mode) or form field (form mode).
  • Mobile: collapsible error drawer.

10.4 Pre-save interactive metadata check

Before save, validate all interactive mechanics have required authoring metadata:

  • DiscardFromHand cost → PickMode required.
  • SendSpiritFromBattlefieldToDiscard cost → PickMode required.
  • DealDamageToOwnSpirit cost → PickMode required.
  • Any action with Chooser = Opponent → confirm intent with warning.
  • Action with All flag and Scope = Battlefield → performance warning.

11) Canonical JSON Contract

The compiled output is what the AbilitySystem parses. All three UI surfaces must produce identical JSON for the same logical ability.

{
  "name": "Ashwake Response",
  "description": "When an ally spirit enters the battlefield, heal it for 2.",
  "type": "Triggered",
  "limits": { "perTurn": 1 },
  "triggered": {
    "eventFamily": "BattlefieldState",
    "eventType": "SpiritEntersBattlefield",
    "sourceZoneGate": ["Battlefield"],
    "ownershipScope": "Ally",
    "limitMode": "PerTurn",
    "limitAmount": 1,
    "filters": []
  },
  "activationConditions": {
    "logic": "AND",
    "rules": [],
    "groups": []
  },
  "actions": {
    "logic": "AND",
    "actions": [
      {
        "scope": "Battlefield",
        "targetType": "Spirit",
        "chooser": "System",
        "count": 1,
        "filters": [
          {
            "type": "Ownership",
            "field": "Owner",
            "comparator": "==",
            "value": "TriggerSource"
          }
        ],
        "conditions": { "logic": "AND", "rules": [], "groups": [] },
        "effects": [
          {
            "type": "HealDamage",
            "amount": 2
          }
        ]
      }
    ],
    "groups": []
  }
}

11.1 Serialization rules

  • System.Text.Json with JsonIgnoreCondition.WhenWritingNull.
  • JsonNamingPolicy.CamelCase.
  • Enums as strings (not integers).
  • No mode-specific fields in output — all surfaces produce identical schema.
  • Round-trip guarantee: Parse(Compile(draft)) == draft (semantic equivalence, not string equality).

12) Gap Analysis — AbilityBuilderR2-Draft.razor vs R3

Area R2-Draft Status R3 Target
Data model ✅ Good structure Extend with value expressions, StatModOperator
Trigger events ⚠️ Placeholder simplified list Full 40+ event catalog per §5
Trigger filters ⚠️ Single OwnershipScope + Amount Per-event filter schema per §5.2
Source zone gate ✅ Present ✅ Carry forward
Condition system ✅ LogicGroup structure Add all domains per §6.2
Cost system ⚠️ Basic Cost types only Full catalog + PickMode per §7
Effect catalog ⚠️ 8 placeholder types Full 50+ catalog per §9
Action scope ⚠️ Basic scopes Full scope + combined scopes per §8
Value expressions ❌ Not present Add AmountSource expressions per §9.14
StatModOperator ❌ Not present Add per §9.5
Visual / Bubble canvas ❌ Not present Core R3 feature per §4.3
English / AI mode ❌ Not present Phase E (post-form parity)
Flowchart output ❌ JSON only Canvas IS the flowchart in visual mode
Mermaid read-only diagram ❌ Not present Phase B: read-only in form mode
Validation ✅ Basic coverage Add Stage 3 + loop detection
Card wizard ❌ Not wired Full wizard per §3

13) Delivery Phases

Phase A — Foundation (prerequisite)

  • Define AbilityDefinitionDraftR3 sealed class hierarchy (§2).
  • Define ValidationIssue record + validator pipeline shell (§10).
  • BuildCanonicalJson() with full serialization rules (§11).
  • ParseFromJson() for round-trip.
  • New standalone page AbilityBuilderR3-Draft.razor at /cards/ability-builder-r3-draft.
  • Validation error panel component (sticky, click-to-navigate).

Phase B — Form parity (full ability authoring via form)

  • Common fields: Name, Description, Type, Limits, Presentation.
  • Active section: Range, LOS, Linear, Uses/turn.
  • Triggered section: Full trigger event picker (families → events), source zone gate, per-event filters.
  • Passive section: Scope, Cadence, Leave policy.
  • Aura section: Range, hooks, leave policy.
  • Activation conditions: Full LogicGroupDraft nested editor (all domains per §6.2).
  • Cost group editor: All cost types + PickMode per §7.
  • Action group editor: All scopes + target types + typed filters.
  • Full effect editor: All effect types per §9 + value expressions + StatModOperator.
  • Read-only Mermaid.js flowchart rendering the compiled JSON.
  • Presets: sample Active + Triggered preloaded.

Phase C — Card wizard

  • 5-step wizard for new card creation (§3).
  • All card type fields and gates.
  • Ability list integration: add/edit/reorder with inline Ability Builder.
  • Review + validate + save step.

Phase D — Visual bubble canvas

  • Node palette + drag-drop onto canvas.
  • Port type system + connection validation.
  • Property sidebar per selected node.
  • Real-time JSON sync from canvas.
  • "Decompile from JSON" to re-render existing ability as nodes.
  • Execution path highlight on node selection.
  • Undo/redo.
  • Canvas ↔ Form mode parity (both surfaces edit same draft).

Phase E — English / AI mode

  • Textarea + AI submit.
  • Draft loader from AI response.
  • Confidence indicators + TODO slot UX.
  • Diff panel (AI proposed vs confirmed).
  • "Apply to Canvas" hand-off to visual mode.
  • Save gated on TODO resolution.

Phase F — Hardening

  • Round-trip regression suite: Form → JSON → Parse → Form (all ability types).
  • Visual → JSON → Visual (semantic equivalence).
  • Legacy JSON load: existing ability JSON loads cleanly into R3 draft.
  • Loop risk detection in validator.
  • Mobile UX polish: progressive disclosure, sticky errors, chip/tag inputs.
  • Performance: large action groups, deep condition nesting.

14) Acceptance Criteria

  • Designer authors a complete Active ability with cost, conditions, and effects via mobile form.
  • Designer authors a complete Triggered ability with full source-zone gating and per-event filters.
  • Visual canvas and form mode produce byte-equivalent canonical JSON for the same ability.
  • Validation catches: missing source zone gate, loop risk, missing pick mode, invalid effect params.
  • Existing saved ability JSON round-trips through R3 parser without mutation.
  • All effect families per §9 are authorable (no "coming soon" stubs in Phase B+).
  • Instinct/Repentance cards cannot add Passive or Aura ability types.
  • ArchSpirit-only card fields (tier, channel range) are hidden for non-ArchSpirit cards.
  • English mode draft loads into canvas with all TODO slots visible and resolvable.

15) Open Questions

# Question Default Assumption
1 Do Triggered abilities support costs, or is that Active-only? Active-only for now; Triggered costs via spec extension if needed
2 Max nesting depth for condition groups? 3
3 Max nesting depth for action groups? 2
4 Combined scopes (Hand+Deck) — are these first-class or derived? First-class scope keys
5 Token template authoring — inline in effect, or separate card editor flow? Inline for simple tokens; separate editor for complex
6 AI English mode — which model/API? Defer to Phase E; API call abstracted behind IAbilityAiDraftService
7 Undo/redo scope — within-session only, or persistent? Within-session only
8 Should read-only Mermaid diagram be in Form mode only, or also Visual mode? Form mode only; Visual canvas IS the diagram in Visual mode

Appendix A — Mermaid Flowchart Rendering Plan

Phase B adds a read-only Mermaid.js flowchart in the Form mode right panel.

Implementation:

  1. Load Mermaid.js from CDN (UMD build) via <script> tag in App.razor or page head.
  2. After BuildCanonicalJson() runs, also call BuildMermaidDiagram(draft) → mermaid syntax string.
  3. Use JSInterop.InvokeVoidAsync("mermaid.render", ...) to render into a <div> element.
  4. Re-render on any draft change (debounced 300ms).

Diagram structure (ability flowchart):

graph TD
  T([Trigger: SpiritEntersBattlefield]) --> C{Conditions}
  C -->|AND| A[Action: Target TriggerSource]
  A --> E1[Effect: HealDamage 2]

Node styling by type:

  • Trigger: rounded rectangle, purple fill.
  • Condition: diamond, blue fill.
  • Cost: hexagon, orange fill.
  • Action: rectangle, green fill.
  • Effect: stadium/pill, red fill.

Appendix B — Node Port Type System (Visual Mode)

Port Name Emitted By Accepted By
trigger_out Trigger Condition Group, Action Group
condition_out Condition Group Cost Group, Action Group
cost_out Cost Group Action Group
action_out Action Group Effect
effect_out Effect Duration/Policy
policy_in Duration/Policy (terminal)

Incompatible connections (e.g., Effect → Trigger) are blocked and show a red indicator with message: "Effects cannot connect back to triggers — use Triggered ability type instead."


End of BuilderR3.md