# 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. ```csharp 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 ```csharp sealed class ActiveDraft { int RangeMin; int RangeMax; bool RequiresLos; bool LinearOnly; int? UsesPerTurn; } ``` ### 2.2 Triggered section ```csharp sealed class TriggeredDraft { string EventFamily; // see §5 trigger catalog string EventType; // canonical event key string LimitMode; // Unlimited | PerTurn | PerGame int? LimitAmount; List SourceZoneGate; // Battlefield | Hand | Discard | Deck (multi-select) string OwnershipScope; // Any | Self | Ally | Opponent string? AmountComparator; // > | == | < | != | <= | >= int? Amount; List Filters; } ``` ### 2.3 Passive section ```csharp sealed class PassiveDraft { string ContinuousScope; // Global | Battlefield | Zone | Self string RecheckCadence; // OnAnyEvent | OnTurnStart | OnTurnEnd | Manual string SourceLeavePolicy; // Remove | Linger | Keep } ``` ### 2.4 Aura section ```csharp 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) ```csharp sealed class LogicGroupDraft { string Logic = "AND"; // AND | OR | XOR List Rules; List Groups; // max depth: 3 } sealed class ConditionRuleDraft { string Domain; // see §6 condition domains string Field; string Comparator; // > | == | < | != | <= | >= string Value; } ``` ### 2.6 Cost group ```csharp sealed class CostGroupDraft { string Logic = "AND"; // AND | OR (alternatives) List Costs; List 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 ```csharp sealed class ActionGroupDraft { string Logic = "AND"; // AND | OR | XOR string? ChooserAuthority; // Self | Opponent | Random | System (OR/XOR only) List Actions; List Groups; } sealed class ActionDraft { string Scope; // see §8 scope catalog string TargetType; string Chooser; // Self | Opponent | Random | System int? Count; bool All; List Filters; LogicGroupDraft Conditions; List Effects; } ``` ### 2.8 Typed filter ```csharp 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 ```csharp 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\ | 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 ```csharp 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. ```json { "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 `