docs(ability): add v2 builder/card-flow product direction recap

This commit is contained in:
Shard
2026-04-16 15:38:36 +00:00
parent 796fe0b4d1
commit 6d1c01cdb2
+103
View File
@@ -229,3 +229,106 @@ Builder help has no warning/pattern guidance for safe Ruin trigger authoring.
- No filter parameters are dropped when saving edited abilities.
- Help panel accurately reflects trigger/effect/filter capabilities present in runtime.
- Existing authored cards remain loadable and unchanged unless explicitly edited.
---
## 12) Product-direction recap (New Card Flow + Ability Builder v2)
> Source: Jason recap (2026-04-16). Keep this as implementation intent unless superseded.
### Goals
- Mobile-friendly authoring flow first; desktop can add richer visual UX.
- Support two authoring modes:
1) visual node/bubble drag-drop + connections,
2) plain-English prompt mapped to canonical ability JSON.
- Final persisted result is a deterministic JSON block consumed by `AbilitySystem`.
- Prioritize robustness and clarity over minimal feature set (high ceiling, even if some complexity is rarely used).
### New Card flow (target fields)
- Core: `Name`, `CardType`, `Affinity`, `Description`, art preview metadata, `SPCost`, `STCost`.
- `ArchSpirit` specifics:
- `MinChannelRange`, `MaxChannelRange`, `Tier`.
- If `Tier > 1`: `PreviousTierCardId` (search/select prior tier card).
- `Spirit`/`ArchSpirit` combat/movement:
- `AttackType` (initially melee/ranged, extensible), range fields when ranged.
- stats: damage/health/defense/movement type/points.
- `GenusTags` with autocomplete + create-new.
- bool flags (attack/defend/be attacked/be blocked/move/obstruct/use ability/LOS behaviors).
- Additional type gates:
- Spirit can include `CanBeSacrificed`.
- Repentance/Instinct LOS requirements as applicable.
### Ability type eligibility by CardType
- `Spirit | ArchSpirit | SpiritToken | Ruin` => `Active`, `Triggered`, `Aura`, `Passive`.
- `Instinct | Repentance` => `Active`, `Triggered`.
### Ability common contract (all types)
- `Name` (for Instinct/Repentance default to card name; others author-defined).
- `Description`.
- `ActivationConditions` with nested logical groups (`AND`/`OR`/`XOR`) and N clauses.
- Per-ability animation/sound assignment hooks.
### Passive / Aura semantics (authoritative distinction)
- **Passive**
- Always active while source is on battlefield.
- Applies to all valid targets in scope.
- Re-validated/applied each turn.
- Removal behavior configurable when source leaves play.
- **Aura**
- Passive-like but range-scoped (`AuraMinRange`, `AuraMaxRange`).
- Must support `OnEnterAuraRange` and `OnLeaveAuraRange` checks.
- On-leave policy configurable: remove immediately / persist / linger duration.
### Triggered ability direction
- Broad trigger-event map with per-event ownership/source/unit/property filters.
- Trigger limit policy required:
- unlimited
- N per turn
- N per game
- Include dedicated support for aura range boundary events (`OnEnterAuraRange`, `OnLeaveAuraRange`).
### Conditions and logic system direction
- Use a reusable expression/group model for:
- Activation conditions
- Action conditions
- Target property constraints
- Cost option constraints
- Group composition supports `AND`/`OR`/`XOR` recursively.
- Comparators include `>`, `>=`, `==`, `!=`, `<=`, `<`.
### Cost system direction
- Active abilities can be free or have one/more cost groups.
- Cost groups support alternatives and logic composition (AND/OR/XOR).
- Special UI/handler needs for interactive costs:
- `DiscardFromHand`: random / self pick / enemy visible pick / enemy random pick.
- `SendSpiritFromBattlefieldToDiscard` / `DealDamageToOwnSpirit`: random / self pick / enemy pick.
### Action system direction
- Each ability has N actions.
- Action groups can be composed with AND/OR/XOR; chooser can vary (self/opponent/random).
- Each action defines:
- scope (hand/deck/discard/battlefield/player and combinations),
- target type,
- target chooser,
- count (N/all),
- filters (typed + parameterized, not type-only),
- optional action conditions,
- one or more effects with chaining.
- Variable effect amounts may be literal or sourced from target/source/expression refs.
### UI architecture implications
- Reusable editors for:
- logical groups,
- typed filters + params,
- ownership/location/range selectors,
- effect payloads by scope/target.
- Mobile UX should prefer progressive disclosure and compact cards/chips over large static forms.
- Desktop UX can add graph view (nodes/edges) mapping 1:1 to canonical JSON.
### Canonicalization requirement
- All authoring surfaces (form, graph, plain-English assistant) must map to the same JSON schema.
- Parser/renderer must round-trip without semantic loss.
- Prevent duplicate divergent representations between UI modes.
### Cleanup task noted by Jason
- De-duplicate overlapping items in this document and extract reusable structure blocks (shared condition/filter/action schemas).