docs(builder): expand BuilderR2 with exhaustive spec coverage checklist

This commit is contained in:
Shard
2026-04-16 16:10:10 +00:00
parent 9598db0582
commit 26fa4c810d
+392
View File
@@ -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).