diff --git a/NewCard-AbilityChange.md b/NewCard-AbilityChange.md index deb1535..692c870 100644 --- a/NewCard-AbilityChange.md +++ b/NewCard-AbilityChange.md @@ -1,505 +1,721 @@ -# NewCard + Ability System Revamp — Implementation Plan +# NewCard + Ability System Revamp -- Implementation Plan -> **Status:** Planning -> **Target branch:** `feature/newcard-ability-revamp` -> **Files to delete before starting:** `AbilityBuilderR2-Draft.razor`, `AbilityBuilderR3.razor` +> Status: Planning +> Target branch: feature/newcard-ability-revamp +> Files to delete before starting: AbilityBuilderR2-Draft.razor, AbilityBuilderR3.razor --- ## Overview -Three parallel workstreams that feed into each other: +Three workstreams that feed into each other: -1. **Ability Model Expansion** — fill gaps in C# domain models and JSON schema so the engine can represent every ability described in the spec. -2. **Card Editor Revamp** — replace the current tabbed form with a mobile-friendly, type-contextual wizard. -3. **Visual Ability Builder** — replace the raw-JSON / form-based `AbilityBuilder.razor` with a drag-and-drop node canvas. +1. Ability Model Expansion -- fill gaps in C# domain models so the engine can represent every ability in the spec. +2. Card Editor Revamp -- replace the current tabbed form with a mobile-friendly, type-contextual flow. +3. Visual Ability Builder -- replace the raw-JSON AbilityBuilder.razor with a drag-and-drop node canvas. Database migrations sit between 1 and 2/3 and must land first. --- -## Phase 0 — Cleanup - -| # | Task | File(s) | -|---|------|---------| -| 0.1 | Delete draft razor pages | `AbilityBuilderR2-Draft.razor`, `AbilityBuilderR3.razor` | -| 0.2 | Verify no router references remain to deleted pages | `NavMenu.razor`, routing scan | -| 0.3 | Create feature branch `feature/newcard-ability-revamp` | git | - ---- - -## Phase 1 — Ability Model Expansion (C# + JSON Schema) - -### 1.1 — Cost Groups (AND / OR / XOR) - -**Current state:** `AbilityDefinition.Cost` is `CostEntry[]` — all entries are paid simultaneously (implicit AND). - -**Gap:** The spec requires OR/XOR cost groups so players can choose between payment options (e.g. *pay 2 SP + discard 3 cards* **OR** *pay 6 SP + 1 ST*). - -**Changes to `Action.cs`:** -``` -CostGroup { - LogicOp: And | Or | Xor - Entries: CostEntry[] // leaf costs - Groups: CostGroup[] // nested groups - // For Or/Xor: ChooserRole Self | Opponent | Random - ChooserRole: string = "Self" -} -``` -Replace `AbilityDefinition.Cost: CostEntry[]?` → `AbilityDefinition.CostGroup: CostGroup?` -Keep `CostEntry[]` as the leaf node inside `CostGroup`. -`CostEntry` gains no changes (already has `PickMode` for interactive pick). - -### 1.2 — Condition Additions - -**Gap vs spec (new conditions to add to `Conditions.cs`):** - -| New Condition | Purpose | -|---|---| -| `UnitTypeIsCondition` | `Spirit \| ArchSpirit \| SpiritToken` | -| `OwnershipIsCondition` | Is unit owned by Self / Ally / Opponent? | -| `IsThisCardCondition` | Subject == the source card instance (ExactSelf already partially covered by `TargetOwnership.ExactSelf` but needed as a standalone Condition) | -| `UnitPropertyCompareCondition` | Generic: `PropertyName` + `Comparator` + `ValueExpr` — covers Damage/Defense/HP/MP comparisons not covered by existing typed conditions | -| `PlayerPropertyCompareCondition` | Generic player resource compare: SP, ST, SPAccumulation, HandSize, DeckSize, DiscardSize + `Comparator` + `ValueExpr` | -| `HandContainsCountCondition` | N cards of type/affinity in hand ≥/≤/=/etc | -| `CardDefinitionCountInZoneCondition` | X copies of this definition in Battlefield/Hand/Deck/Discard of Any/Ally/Opponent/Self | -| `IsInRangeOfUnitCondition` | Source is within [Min,Max] of a unit matching `UnitType` + `Ownership` + optional property filters | -| `TileOccupantCondition` | Tile (subject is tile) occupied by unit matching type, ownership, properties | -| `SurroundingTileCondition` | At least N surrounding tiles within [Min,Max] match affinity/occupancy filters | -| `SPAccumulationCompareCondition` | Compares SP-accumulation-per-turn against value | -| `CostOfCardsInHandCondition` | Aggregate cost (by type, affinity) in hand meets comparator | - -**Existing composites (AND/OR/XOR/NOT) already exist — no change needed.** - -### 1.3 — Trigger Event Additions / Enrichments - -Most trigger types already exist. The following enrichments are needed: - -| Trigger | Gap | Fix | -|---|---|---| -| All unit-event triggers (`OnUnitMove`, `OnUnitAttack`, etc.) | Subject filter only does ownership string; spec requires "unit with N properties ≥/≤/= Y" | Add `Filter[]? UnitFilters` to each (already present on some) | -| `OnChanneledTrigger` | Missing `DefinitionId` (specific card) filter | Add `Guid? CardDefinitionId` optional field | -| `OnRuinActivationTrigger` | Missing occupant filter | Add `Filter[]? OccupantFilters` | -| `OnUnitOccupyRuinTrigger` | Missing occupant filter | Add `Filter[]? OccupantFilters` | -| `OnCardReturnedToDeckTrigger` | Missing `ResetStatsToDefinition` observation flag | Add `bool? ResetStats` (for UI display only) | -| `OnDamageDealtTrigger` / `OnHealedTrigger` / etc. | Already have amount compare via event data; verify `AmountComparator` & `Amount` fields present | Audit & add if missing | - -### 1.4 — Effect Additions - -**New effects to add to `Effects.cs`:** - -| Effect | Category | Notes | -|---|---|---| -| `CloneSpiritAsTokenEffect` | §5.11 Token | Clone source Spirit to SpiritToken; `DestinationScope` = NeighborTile \| RandomInChannelRange \| TargetTile | -| `AscendFromZoneEffect` | §5.1 ArchSpirit | `Zone`: Hand \| Deck \| Discard; `IgnoreCost: bool` — unified replacement for future AscendFrom* variants | -| `TransitionFromZoneEffect` | §5.1 ArchSpirit | Same pattern as Ascend | -| `ModifyChannelRangeEffect` | §5.1 ArchSpirit | Min/Max delta (replaces missing `ModChannelRange`) | -| `RelocateRuinEffect` | §5.13 Ruin | Move Ruin to target tile | -| `ActivateRuinAbilityEffect` | §5.13 Ruin | `AbilityRef` or `Random: bool`; `ChooseAllTargets: bool` | -| `DisableRuinForDurationEffect` | §5.13 Ruin | `Duration: DurationModel` | -| `ChannelCardFromZoneEffect` | §5.7 Zone | Unified ChannelCard with `Zone`, `UnderControlOf`, `IgnoreChannelCost`, `IgnoreTurnConstraint`, `IgnoreChannelRange`, `IgnoreAffinity`, `KeepInZone`, `TargetTile`, `InOwnChannelRange`, `InTargetChannelRange` flags | -| `ModifySacrificeTokenReturnEffect` | §5.10 Control | Override ST returned on Spirit sacrifice | -| `DestroyTokenEffect` | §5.11 Token | Destroy a SpiritToken | -| `SkipTurnEffect` | §5.5 Player | Target player skips their next turn | -| `ModifyCardsDrawnThisTurnEffect` | §5.5 Player | Delta for current-turn draw; complements existing `ModifyCardsDrawnPerTurnEffect` | -| `StackDeckEffect` | §5.7 Zone | Reorder top N cards of deck | -| `SearchAndPlaceEffect` | §5.7 Zone | Composite search → put cards into Hand/Deck/Discard with shuffle option | -| `ChangeAttackTypeEffect` | §5.9 Unit | Change Melee↔Ranged etc. | -| `ObstructMovementTypeEffect` | §5.9 Unit | Act as obstacle for given movement type | -| `PreventNextDamageEffect` | already exists — needs `Times` field | Add `int Times = 1` | -| `PreventDeathEffect` | already exists — needs `DamageTakenSetToHP` + `DamageIgnored` | Add opt fields | - -**Consolidation note:** `ChannelCardEffect` in current `Effects.cs` is minimal. `ChannelCardFromZoneEffect` will supersede it; the old type stays for backwards compatibility but is marked `[Obsolete]` and the builder will not emit it. - -### 1.5 — Filter Additions (`Filters.cs` audit) - -Review `Filters.cs` to ensure these filter types exist (add if missing): - -- `CardTypeFilter` — filter Hand/Deck/Discard cards by `CardType` -- `AffinityFilter` — filter by card affinity -- `CostRangeFilter` — filter by SP/ST cost range -- `GenusFilter` — filter by genus tag -- `OwnershipFilter` — filter by unit ownership -- `UnitPropertyFilter` — generic property comparator on a unit -- `TileAffinityFilter` — filter tiles by Base1, Base2, Resolved affinity -- `TileOccupancyFilter` — filter tiles by occupant type/ownership/properties -- `RangeFilter` — target must be within [Min,Max] tiles of source -- `OccupancyTypeFilter` — tile occupied by Spirit/ArchSpirit/SpiritToken/Ruin - -### 1.6 — `AbilityDefinition` additions - -```csharp -// Passive / Aura -public string? Name { get; set; } // already exists ✓ -public string? Description { get; set; } // already exists ✓ - -// Aura -// AuraRange, ClearOnLeave, LingerDuration already exist ✓ -// Add: OnEnterActions / OnLeaveActions for per-unit aura entry/exit effects -public Action[]? OnEnterAuraActions { get; set; } -public Action[]? OnLeaveAuraActions { get; set; } - -// Triggered -// TriggerLimitPerTurn, TriggerLimitPerGame, SourceZoneGate already exist ✓ - -// Active — cost group (replaces Cost array) -public CostGroup? CostGroup { get; set; } // NEW — replaces Cost -// Keep Cost for migration read; mark [Obsolete()] + reader falls back on parse -``` - ---- - -## Phase 2 — Database Migration - -| # | Migration | Notes | -|---|---|---| -| 2.1 | Add `CardType.SpiritToken` enum value | EF migration + Postgres enum value. Deck-build validator and collection-grant endpoint must reject SpiritToken cards. | -| 2.2 | **Hard cutover: `EffectsJson` → `AbilitiesJson`** | Write a migration tool (C# console or SQL script) that reads every card where `effects_json IS NOT NULL AND abilities_json IS NULL`, deserializes the old `Action[]` format, wraps it in a minimal `AbilityDefinition[]` envelope (type: Active/Triggered as applicable), and writes to `abilities_json`. After verification: `ALTER TABLE card_definitions DROP COLUMN effects_json`. Remove all `EffectsJson` references from `CardDefinition.cs`, `CardEditor.razor`, and `AbilitySystem.cs`. No dual-read shim. | -| 2.3 | `RequiresLos` for Repentance/Instinct | Field exists on `CardDefinition`. No DB change. Engine change: for non-battlefield card types, LOS source = controlling player's active ArchSpirit (see Resolved Decision #6). UI change: show checkbox in Phase 3. | -| 2.4 | `OtherCostsJson` audit | Verify column is unused / redundant with ability `CostGroup`. If confirmed unused: drop column in this migration. If used, document the distinction before touching. | - -**Migration tool:** `SOR.Tools/Migrations/EffectsJsonCutover.cs` — standalone console app, idempotent, logs every card converted and any parse failures for manual review. -**Schema version**: `DefinitionVersion` trigger covers all card updates automatically. -**EF migration file**: `Migrations/20260420_AbilityRevamp.cs` - ---- - -## Phase 3 — Card Editor Revamp (`CardEditor.razor`) - -### Design Principles -- Mobile-first: single-column by default, two-column on md+ -- Type-contextual: sections and fields appear/disappear based on `CardType` -- Progressive disclosure: collapse optional sections, expand on demand -- No separate "Stats" tab for non-unit cards (Repentance/Instinct only show what they need) - -### 3.1 — Step 1: Core Info (all card types) - -Fields always shown: -- Name -- Card Type (select) — changing type rerenders the rest of the form reactively -- Affinity -- Description (art description textarea) -- SP Cost / ST Cost - -### 3.2 — Step 2: Type-Specific Stats - -**If `CardType == ArchSpirit`:** -- Min/Max Channel Range -- Tier (1–5) -- Previous Tier search autocomplete (ArchSpirit 1 tier lower) — already implemented, keep - -**If `CardType` is `ArchSpirit | Spirit | SpiritToken`:** - -*Combat section:* -- Attack Type (None / Melee / Ranged) - - If Ranged: Min/Max Attack Range -- Damage, Health Points, Defense - -*Movement section:* -- Movement Type (None / Walk / Fly / …) -- Movement Points - -*Capability flags (checkbox grid):* -- CanAttack / CanDefend / CanBeAttacked / CanBeBlocked -- CanMove / CanBeObstructed / CanUseAbility / RequiresLOS -- CanBeSacrificed (Spirit + SpiritToken only) - -*Genus Tags:* -- Typeahead + free create, already implemented — keep - -**If `CardType == Terramorpha`:** -- TerramorphaMode - -**If `CardType == Repentance | Instinct`:** -- RequiresLOS checkbox (currently missing from UI for these types) - -### 3.3 — Step 3: Abilities - -See Phase 4. The "Abilities" tab becomes the visual builder embedded in the same page. - -Rules per CardType: -| CardType | Allowed Ability Types | -|---|---| -| Spirit, ArchSpirit, SpiritToken, Ruin | Active, Triggered, Aura, Passive | -| Instinct, Repentance | Active, Triggered | -| Terramorpha | Active, Triggered | - -Auto-name rule: if `CardType == Repentance | Instinct`, the first ability's Name is locked to the card Name. - -### 3.4 — Step 4: Assets - -No change from current implementation. Already well-structured. - -### 3.5 — Implementation Notes - -- Replace tab array `["Basic", "Stats", "Abilities", "Assets"]` with a collapsible-section layout (Bootstrap accordion or manual open/close) so all sections are visible on scroll on mobile. -- Each section has a sticky header showing completion status (green check if required fields filled). -- Keep existing CDN picker modal unchanged. - ---- - -## Phase 4 — Visual Ability Builder - -### 4.1 — Architecture - -The builder is a self-contained Blazor component `AbilityBuilder.razor` that: -- Accepts `AbilitiesJson` string (in) + `AbilitiesJsonChanged` callback (out) — **same interface as today** so `CardEditor.razor` needs zero changes for the swap. -- Internally maintains a `List` that compiles to JSON on every meaningful change. -- The canvas is rendered in a `
` with CSS `position:relative`/`overflow:auto` and nodes are `position:absolute` — no WebGL, no external JS canvas library, pure CSS+Blazor drag. - -### 4.2 — Node Types - -Each ability is its own independent mini-canvas. The top-level layout shows a card per ability with a mini node graph inside. - -``` -┌─────────────────────────────────────────┐ -│ [Active] "Strike" [×] │ -│ ┌──────┐ ┌──────────┐ ┌──────────┐ │ -│ │ Cost │→ │ Condition│→ │ Action │ │ -│ └──────┘ └──────────┘ └──────────┘ │ -│ │ │ -│ ┌──────────┐ │ -│ │ Effect │ │ -│ └──────────┘ │ -└─────────────────────────────────────────┘ -``` - -Node palette (left drawer, collapsible): -- **Trigger** (Triggered abilities): event picker -- **Cost** (Active only): CostGroup builder (AND/OR/XOR nesting) -- **Condition**: condition group builder (AND/OR/XOR already supported in model) -- **Action**: target selector + effect list -- **Effect**: specific effect type with its parameters - -### 4.3 — Node Design - -Each node is a `
` with: -- Header bar (color-coded by node type, drag handle) -- Body (type-specific form fields) -- Input port (left) / Output port (right) — `
` - -Connection lines are SVG `` elements rendered in an overlay `` sibling. - -Drag mechanics: -- `onmousedown` on header stores `(nodeId, offsetX, offsetY)` in component state -- `onmousemove` on canvas updates node position -- `onmouseup` clears drag state -- Touch equivalent: `ontouchstart/move/end` for mobile - -Zoom + pan: -- Canvas wraps in a `
` with CSS `transform: scale(zoom) translate(panX, panY)` -- Pinch-to-zoom via JS interop (`wheel` event, touch distance delta) -- Small JS file: `ability-builder.js` (zoom/pan math, port hit-test for connection dragging) - -### 4.4 — Panels - -**Left panel — Ability List + Node Palette:** -- List of all abilities on this card; click to focus that ability's canvas -- "Add Ability" button → opens "Choose Type" modal -- Node palette grouped: Trigger / Cost / Condition / Action / Effect - -**Center — Canvas:** -- One ability's node graph at a time -- Nodes draggable; connections drawn as bezier SVG paths -- Clicking a node selects it and opens the right panel - -**Right panel — Property Inspector:** -- Dynamic form for the selected node's properties -- Rendered via a big `@switch (selectedNode.Type)` block -- Inline add/remove for list-valued properties (e.g. CostEntry items within a CostGroup) - -**Bottom bar — JSON Preview (collapsible):** -- Read-only `