docs(builder): expand BuilderR2 with exhaustive spec coverage checklist
This commit is contained in:
+392
@@ -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).
|
||||
Reference in New Issue
Block a user