Files
sor/BuilderR2.md

13 KiB

BuilderR2

Purpose

Admin-side implementation plan for R2 New Card Flow + Ability Builder only.

Scope of this doc:

  • SOR.Admin UX + authoring data flow + validation process.
  • Canonical JSON authoring contract as consumed by engine.

Out of scope for this doc:

  • Engine runtime execution internals.
  • Client prompt transport/protocol implementation.

1) Product goals (Builder-only)

  • Build cards/abilities without manual JSON editing.
  • Mobile-first usability; desktop adds graph authoring.
  • Form mode, graph mode, and English mode all emit identical canonical JSON.
  • Prevent lossy save behavior (especially typed filter params).
  • Provide clear pre-save validation + preview so designers can trust outputs.

2) Builder architecture

2.1 Single canonical model in admin

Builder state should normalize into one canonical draft:

  • CardDefinitionDraftR2
  • AbilityDefinitionDraftR2

All UI surfaces are adapters:

  • Form editor ↔ Draft model
  • Graph editor ↔ Draft model
  • English parser draft → Draft model
  • Draft model → Canonical JSON

No mode-specific persisted format.

2.2 Authoring pipeline

  1. Input/edit in one of 3 modes.
  2. Normalize into draft model.
  3. Run validator pipeline (schema + semantic + flow checks).
  4. Show errors/warnings in a unified panel.
  5. Save canonical JSON only when passing required checks.

3) New Card Flow R2 (admin wizard)

3.1 Step plan

  1. Core
  • Name, CardType, Affinity, Description, art preview metadata, SP/ST cost.
  1. Type-specific
  • ArchSpirit: min/max channel range, tier, previous tier selector (if tier > 1).
  • Spirit/ArchSpirit: attack type/range, stats, movement, genus tags.
  1. Flags + constraints
  • Can booleans (attack/defend/move/etc.).
  • Type-gated booleans (e.g., spirit sacrifice).
  • LOS requirements where applicable.
  1. Abilities
  • Add/edit/reorder abilities.
  • Type gating by card type:
    • Spirit/ArchSpirit/SpiritToken/Ruin: Active/Triggered/Aura/Passive
    • Instinct/Repentance: Active/Triggered
  1. Review + validate + save
  • Human-readable summary + canonical JSON preview.
  • Blocking errors and non-blocking warnings.

3.2 UX notes

  • Mobile: progressive disclosure, chips/tags, sticky error summary.
  • Desktop: split pane with live JSON preview + structure outline.

4) Ability Builder R2 (form mode)

4.1 Common sections

  • Name, description, type
  • Activation conditions (LogicGroup with AND/OR/XOR)
  • Limits (per turn/game)
  • Animation/SFX

4.2 Type sections

  • Active: range/LOS/linear/uses per turn/cost groups
  • Triggered: event type + source zone gate + trigger filters + limits
  • Passive: continuous scope + recheck cadence + source-leave policy
  • Aura: min/max range + enter/leave hooks + leave policy

4.3 Action authoring

Per action:

  • Action group nesting (AND/OR/XOR)
  • Chooser authority (self/opponent/random/system)
  • Scope + target type + chooser + count
  • Typed parameterized filters (not type-only)
  • Action conditions
  • Effect chain with per-effect duration override

4.4 Cost authoring

  • Free or grouped costs
  • Group logic with alternatives
  • Interactive cost metadata fields where needed (pick mode, chooser, etc.)

5) Trigger authoring requirements (builder)

5.1 Source-zone gating (required)

Builder must allow trigger source to be active from:

  • Battlefield
  • Hand
  • Discard
  • Deck

UI control: multi-select sourceZoneGate[] with safe defaults by ability type.

5.2 Trigger matrix editor

Author by event family templates instead of fully bespoke screens:

  • Lifecycle
  • Unit combat/move/ability
  • Battlefield state
  • Ability mutation/targeting
  • Ruin/occupancy
  • Tile/affinity
  • Resource economy
  • Card movement/visibility
  • Aura boundary

Each family exposes only valid fields for that event.


6) Graph builder vision (desktop-first)

6.1 Node palette

  • Trigger
  • Condition Group
  • Cost Group
  • Target Selector
  • Action Group
  • Effect
  • Duration/Policy

6.2 Edge semantics

  • Typed input/output ports
  • Invalid connections blocked at UI level
  • Execution path preview (readable sequence)

6.3 Graph parity requirement

  • Graph decompile from existing canonical JSON must be possible.
  • Round-trip graph -> json -> graph should preserve semantics.

7) English -> Ability JSON authoring flow

7.1 Pipeline

  1. Designer writes plain-English intent.
  2. Parser/assistant produces structured draft + confidence + unresolved slots.
  3. Builder maps draft to canonical draft model.
  4. Designer resolves ambiguities in form/graph UI.
  5. Save only validated canonical JSON.

7.2 Safety constraints

  • Never persist raw parser output as final ability.
  • Ambiguous items must remain explicit TODO slots until resolved.
  • Show diff between generated draft and final saved JSON.

8) Validation system (admin-side)

8.1 Validation stages

  1. Schema validation
  • Shape/types/enums/required fields.
  1. Semantic validation
  • CardType gating for ability types.
  • Trigger/event compatibility.
  • Filter parameter correctness.
  • Range/value bounds.
  • Source zone legality.
  1. Flow validation
  • Action graph/group solvable.
  • Chooser/target requirements satisfiable.
  • Cost branches executable.

8.2 Output model

  • Error (blocks save)
  • Warning (save allowed)
  • Info (quality hints)

Each issue should include:

  • stable code
  • path to field/node
  • suggested fix text

8.3 Pre-save checks specifically for interactive mechanics

Builder should flag actions/effects that will require runtime prompts and ensure required metadata exists:

  • chooser authority
  • target selection mode
  • selection min/max
  • hidden-zone visibility policy
  • random/self/enemy pick modes

(Transport protocol stays out-of-scope here, but authoring completeness is validated.)


9) Builder simulator (admin tool)

Provide a lightweight simulation panel for author confidence:

  • load sample board/state fixture
  • fire selected trigger events
  • inspect condition pass/fail trace
  • inspect resolved target set and planned effects

This is a builder QA tool; not full runtime parity simulator.


10) Delivery plan (admin-only)

Phase A — Foundation

  • Draft models + canonical mapper
  • Unified validation framework
  • Error panel + field/node mapping

Phase B — Form parity

  • New card wizard upgrades
  • Full ability form for Active/Triggered/Aura/Passive
  • Typed filter editors + action/cost group editors

Phase C — Trigger + zone support

  • Trigger family template editors
  • Source zone gate controls (battlefield/hand/discard/deck)

Phase D — Graph mode

  • Node/edge authoring
  • graph <-> canonical draft compile/decompile
  • live preview and validation overlays

Phase E — English mode

  • Draft import + unresolved slot UX
  • normalization + explicit confirm flow

Phase F — Hardening

  • round-trip regression suite (form/graph/english)
  • legacy load/edit checks
  • UX polish for mobile

11) Acceptance criteria (BuilderR2)

  • Designer can author complete cards/abilities via mobile-friendly form.
  • Trigger source-zone gating supports battlefield/hand/discard/deck.
  • Filters persist with full parameters (no type-only loss).
  • Form/graph/english pathways produce equivalent canonical JSON.
  • Validation catches invalid gates/combinations before save.
  • Existing content can be loaded and edited without silent mutation.

12) Immediate next tasks

  1. Define CardDefinitionDraftR2 + AbilityDefinitionDraftR2 classes in admin.
  2. Implement unified validation result model and side panel UI.
  3. Build Trigger editor v2 with event family templates + sourceZoneGate.
  4. Replace all type-only filter save paths with typed param objects.
  5. Add canonical JSON preview + round-trip snapshot tests.

13) Coverage checklist from Jason long-form spec (exhaustiveness guard)

Use this as a builder completeness checklist so nothing from the spec is silently dropped.

13.1 Card fields and gates

  • Core fields: name, card type, affinity, description, art preview, SP cost, ST cost.
  • ArchSpirit-only:
    • min/max channel range
    • tier
    • previous-tier selector when tier > 1 (search tier-1 card)
  • Spirit + ArchSpirit:
    • attack type (melee/ranged/extensible)
    • if ranged: min/max attack range
    • stats: damage, health, defense
    • movement type + movement points
    • genus tags (autocomplete + create new)
    • boolean permissions: attack/defend/be attacked/be blocked/move/be obstructed/use ability/LOS behavior
  • Type-specific booleans:
    • Spirit: can be sacrificed
    • Repentance/Instinct: LOS requirement handling
  • Ability type gates by card type:
    • Spirit/ArchSpirit/SpiritToken/Ruin => Active/Triggered/Aura/Passive
    • Instinct/Repentance => Active/Triggered

13.2 Ability common + Active specifics

  • Ability fields: name, description, type.
  • Naming rule: Instinct/Repentance default ability name to card name.
  • Active-only fields:
    • range min/max
    • requires LOS
    • linear only
    • uses per turn
    • cost model (free vs grouped)
  • Cost groups support AND/OR/XOR and alternatives.
  • Interactive cost selectors required in builder metadata:
    • DiscardFromHand: Random / SelfPick / EnemySeePick / EnemyRandomPick
    • SendSpiritFromBattlefieldToDiscard: Random / SelfPick / EnemyPick
    • DealDamageToOwnSpirit: Random / SelfPick / EnemyPick

13.3 Conditions model completeness

  • Activation conditions for all ability types.
  • Action conditions per action.
  • Target property conditions.
  • All condition families must use nested group logic AND/OR/XOR.
  • Comparator support: >, ==, <, !=, <=, >=.
  • Condition domains to expose in UI:
    • turn/timing ownership
    • unit ownership/type/properties
    • this card properties
    • this card definition properties + count-in-zone rules
    • location scopes (deck/discard/hand/battlefield)
    • battlefield tile/surrounding tile properties
    • player properties (SP/ST/accumulation/hand/deck/discard metrics)

13.4 Trigger model completeness

  • Trigger event map must include the broad event set from spec (turn, channel, movement, combat, damage/heal, death, enter/leave battlefield, discard/sacrifice/token, stat/ability/genus, ruin occupancy/activation, tile affinity, resource gain/spend, card draw/discard/return/reveal/shuffle, targeted/effect applied, aura enter/leave).
  • Per-event filter capability must support:
    • ownership scopes (any/self/ally/opponent)
    • exact-card vs class vs filtered unit/card
    • comparator-based amount constraints where applicable
    • grouped property filters (AND/OR/XOR)
  • Trigger limits:
    • unlimited
    • N per turn
    • N per game
  • Source zone gating:
    • battlefield/hand/discard/deck

13.5 Action and targeting completeness

  • Ability has N actions.
  • Action grouping supports AND/OR/XOR.
  • Choice authority for action branching: self/opponent/random.
  • Action shape:
    • scope
    • target type
    • chooser
    • count (N/all)
    • filters
    • conditions
    • effects
  • Scope support:
    • hand, deck, discard, battlefield, player
    • combined scopes where needed
  • Target type support by scope:
    • zone cards by type
    • battlefield entities: tile, spirit, archspirit, spirit token, ruin
    • player targets: self/ally/opponent/all/random (with player-property filters)

13.6 Effect catalog coverage guard (builder)

Builder should expose effect families from spec (with params), including:

  • Zone movement ops (send to hand/deck/discard with top/bottom/random and optional reset-to-definition)
  • Channeling ops by card type with constraints (control, ignore cost/range/affinity/turn constraints)
  • Deck ops (search/shuffle/stack/put results)
  • Unit ops (heal/damage/dot/hot/prevent damage/death/push/pull/displace/toggle bools/stat mods/attack range mods/genus/affinity)
  • ArchSpirit ops (ascend/transition variants, channel range mods)
  • Spirit ops (clone token, take control variants, zone sends, sacrifice token return mod)
  • SpiritToken ops (destroy)
  • Ruin ops (relocate/disable/activate ability/send zones)
  • Tile ops (set/push affinities and resolve behavior)
  • Player ops (draw/discard/SP/ST modifications/skip turn/toggle player channel capabilities)
  • Token creation/channeling from existing card or custom token template

13.7 Validation guardrails explicitly requested by spec intent

  • If a feature is available in UI, compile/parsing must round-trip without dropping params.
  • All interactive choices must include authorable metadata for runtime prompting.
  • Builder should warn on high-risk trigger loops (e.g., ruin/self-retrigger) and recommend limits.
  • Canonical JSON preview required before save.

13.8 Definition of “nothing left out” for BuilderR2

For this doc, “nothing left out” means:

  • every major capability category from the long spec appears in at least one explicit checklist item,
  • and each category is mapped to a builder responsibility (field, editor, validation, or compile path).