# 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. 2) **Type-specific** - ArchSpirit: min/max channel range, tier, previous tier selector (if tier > 1). - Spirit/ArchSpirit: attack type/range, stats, movement, genus tags. 3) **Flags + constraints** - Can booleans (attack/defend/move/etc.). - Type-gated booleans (e.g., spirit sacrifice). - LOS requirements where applicable. 4) **Abilities** - Add/edit/reorder abilities. - Type gating by card type: - Spirit/ArchSpirit/SpiritToken/Ruin: Active/Triggered/Aura/Passive - Instinct/Repentance: Active/Triggered 5) **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. 2) **Semantic validation** - CardType gating for ability types. - Trigger/event compatibility. - Filter parameter correctness. - Range/value bounds. - Source zone legality. 3) **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).