From 6d1c01cdb24f0e7e062b138fd08a5d7da1840c14 Mon Sep 17 00:00:00 2001 From: Shard Date: Thu, 16 Apr 2026 15:38:36 +0000 Subject: [PATCH] docs(ability): add v2 builder/card-flow product direction recap --- Ability-Issues-Solutions.md | 103 ++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/Ability-Issues-Solutions.md b/Ability-Issues-Solutions.md index 482f90e..5a288fa 100644 --- a/Ability-Issues-Solutions.md +++ b/Ability-Issues-Solutions.md @@ -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).