diff --git a/BuilderR2.md b/BuilderR2.md new file mode 100644 index 0000000..9e3459a --- /dev/null +++ b/BuilderR2.md @@ -0,0 +1,392 @@ +# 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).