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>
37 KiB
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:
- Fill in a card's core details (name, type, affinity, stats).
- Open the Ability Builder — a canvas of typed bubble nodes you drag, drop, and connect.
- Wire:
Trigger→Condition Group→Cost Group→Action Group→Effects. - The canvas re-renders in real time as a flowchart that is the ability.
- 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 activeport). - 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
- Designer types plain-English intent.
- AI assistant produces a structured draft + confidence score + unresolved slots.
- Draft is loaded into Visual or Form editor for designer review.
- Unresolved slots are explicit
TODOplaceholders — never silently defaulted. - Save is only available after all TODOs are resolved and validation passes.
- 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 Abilityopens 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:
Backspaceor 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:
- Activation conditions — on the ability itself (when is it legal to use/fire).
- Action conditions — per action (is this action branch taken).
- 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 (
Allflag)
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:
DiscardFromHandcost → PickMode required.SendSpiritFromBattlefieldToDiscardcost → PickMode required.DealDamageToOwnSpiritcost → PickMode required.- Any action with
Chooser = Opponent→ confirm intent with warning. - Action with
Allflag andScope = 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.JsonwithJsonIgnoreCondition.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
AbilityDefinitionDraftR3sealed class hierarchy (§2). - Define
ValidationIssuerecord + validator pipeline shell (§10). BuildCanonicalJson()with full serialization rules (§11).ParseFromJson()for round-trip.- New standalone page
AbilityBuilderR3-Draft.razorat/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
LogicGroupDraftnested 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:
- Load Mermaid.js from CDN (UMD build) via
<script>tag inApp.razoror page head. - After
BuildCanonicalJson()runs, also callBuildMermaidDiagram(draft)→ mermaid syntax string. - Use
JSInterop.InvokeVoidAsync("mermaid.render", ...)to render into a<div>element. - 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