393 lines
13 KiB
Markdown
393 lines
13 KiB
Markdown
# 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).
|