docs(plan): incorporate design decisions and interactive protocol spec

- Lock RecursiveAbility + FullClientPrompt as axioms (Axiom A/B/C)
- Resolve all 6 open questions: SpiritToken constraints, hard EffectsJson
  cutover (migration tool for ~100 cards, column drop), RequiresLOS via
  ArchSpirit as LOS origin, ChooseOne.ChooserRole confirmed, custom drag
- Expand Phase 5 with PendingBranchPick/TilePick/PlayerPick/RevealChoice,
  LOS engine rule, ChooserRole resolution paths

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
dingo
2026-04-19 11:30:17 -04:00
co-authored by Claude Happy
parent f31aa1f477
commit 8795794865
+70 -13
View File
@@ -153,12 +153,13 @@ public CostGroup? CostGroup { get; set; } // NEW — replaces Cost
| # | Migration | Notes |
|---|---|---|
| 2.1 | Add `CardType.SpiritToken` enum value | Engine already conceptually has tokens; needs to be a proper DB-storable `CardType` so custom token definitions can be persisted |
| 2.2 | Deprecate `EffectsJson` column | `AbilitySystem` already reads both; complete the read fallback in code so all writes go to `AbilitiesJson`. Schedule a `UPDATE cards SET abilities_json = effects_json WHERE abilities_json IS NULL` data migration. |
| 2.3 | Add `CardDefinition.RequiresLos` note | Field already exists (`RequiresLos: bool?`) — only a UI gap (see Phase 3) |
| 2.4 | Rename / alias `OtherCostsJson` → managed by `CostGroup` on `AbilityDefinition` | No DB column change needed; `OtherCostsJson` on CardDefinition was for card-level channel costs — confirm not duplicated with ability cost and document |
| 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. |
**Schema version**: bump `DefinitionVersion` trigger covers all card changes automatically.
**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`
---
@@ -378,7 +379,7 @@ These changes make the engine process the new schema. Each item is independent o
| # | Change | Notes |
|---|---|---|
| 5.1 | Read `CostGroup` from `AbilityDefinition`; resolve OR/XOR cost paths, send client pick request | Interactive OR/XOR costs require client round-trip; add `PendingCostGroupPick` alongside existing `PendingCostPick` |
| 5.1 | Full interactive resolution protocol (Axiom B) | Add `PendingCostGroupPick`, `PendingBranchPick`, `PendingTilePick`, `PendingPlayerPick`, `PendingRevealChoicePick`. All pending states serializable as part of `GameState`. Enforce `TimeoutMs` with server-side Random fallback. |
| 5.2 | Implement `CloneSpiritAsTokenEffect` | Use existing SummonToken infrastructure; source stats copied from Spirit target |
| 5.3 | Implement `AscendFromZoneEffect` / `TransitionFromZoneEffect` | Reuse ArchSpirit tier logic; zone lookup before ascend |
| 5.4 | Implement `ModifyChannelRangeEffect` | Apply delta to unit's current channel range runtime state |
@@ -390,6 +391,8 @@ These changes make the engine process the new schema. Each item is independent o
| 5.10 | `SkipTurnEffect` / `ChangeAttackTypeEffect` / `ObstructMovementTypeEffect` | Runtime flag application |
| 5.11 | `UnitFilters` on all enriched TriggerEvent types (§1.3) | Trigger evaluation: after ownership check, apply unit filters |
| 5.12 | Handle `SpiritToken` as a full CardType in channeling + combat paths | Currently tokens are runtime-only; custom token definitions via `CardDefinition` now possible |
| 5.13 | LOS for Repentance/Instinct abilities | `RequiresLos` check uses controlling player's active ArchSpirit as origin instead of the card source (which is not on the battlefield) |
| 5.14 | `ChooseOne.ChooserRole` resolution | `"Opponent"` → send `PendingBranchPick` to opponent's client; `"Random"` → server picks immediately; `"Self"` → existing flow |
---
@@ -423,7 +426,8 @@ Phase 5 sub-items are independently mergeable after Phase 1 lands.
| `SOR.Game/Abilities/Models/Effects.cs` | Add 15 new effect types (§1.4) |
| `SOR.Game/Abilities/Models/Filters.cs` | Add 9 new filter types (§1.5) |
| `SOR.Game/Abilities/Models/AbilityDefinition.cs` | Add `CostGroup`, `OnEnterAuraActions`, `OnLeaveAuraActions` |
| `SOR.Database/Entities/Catalog/CardDefinition.cs` | Document `EffectsJson` deprecation; no column add needed |
| `SOR.Database/Entities/Catalog/CardDefinition.cs` | Remove `EffectsJson` property + `OtherCostsJson` (if confirmed unused) |
| `SOR.Tools/Migrations/EffectsJsonCutover.cs` | New: one-time migration console app to convert ~100+ existing cards |
| `SOR.Database/Enums/CardType.cs` | Add `SpiritToken` value |
| `SOR.Database/Migrations/` | New EF migration for SpiritToken enum |
| `SOR.Admin/Components/Pages/Cards/CardEditor.razor` | Revamp to accordion/wizard layout (Phase 3) |
@@ -435,14 +439,67 @@ Phase 5 sub-items are independently mergeable after Phase 1 lands.
---
## Open Questions / Decisions Needed
## Design Axioms (Confirmed)
1. **SpiritToken CardType:** Custom token definitions stored as full `CardDefinition` rows (can be queried, versioned) vs inline JSONB blob in the ability's `SummonTokenEffect.TokenDefJson`. The spec says "Custom Token (configured same as new Card from this prompt)" which implies full CardDefinition. Recommend: add `CardType.SpiritToken` + allow token CardDefinitions; `SummonTokenEffect` gains `CardDefinitionId?` alongside existing `TokenDefJson` for inline.
These are not open questions — they are locked design decisions that every implementation phase must honour.
2. **OR/XOR cost client protocol:** When an OR/XOR cost group is presented, the client must indicate which branch was chosen before the server can validate and deduct. Needs a new `PendingCostGroupPick` message type in the game protocol — this is a larger client-change surface than the existing cost flow. Confirm scope boundary (Phase 5.1).
### A. The Ability System Is Fully Recursive
3. **Drag-and-drop library vs custom:** Pure CSS/Blazor drag is feasible for a bounded canvas but adds ~200 lines of drag-state management. If there is an appetite to pull in a lightweight JS library (e.g. `interact.js` ~50KB), the interop layer becomes simpler. Recommend custom approach first; library swap is isolated.
Every layer of an ability can nest arbitrarily:
- `CostGroup` contains `CostEntry` leaves **and/or** child `CostGroup` nodes (AND/OR/XOR).
- `ConditionGroup` (AND/OR/XOR/NOT) can contain leaf conditions **and/or** child condition groups.
- Each `Action` inside an `AbilityDefinition` can be a leaf action (Target + Effects) **or** a `ChooseOne` branch selector whose branches each contain their own `Action[]`.
- Branch `Action[]` may themselves contain further `ChooseOne` nodes — unlimited depth.
- `SearchDeckEffect.ThenAction` and `ApplyOnEventEffect.Effects` are recursive action/effect trees.
4. **Backwards compatibility of `EffectsJson`:** Cards currently using `EffectsJson` (Repentance, Instinct, Terramorpha) will be dual-read during the migration window. Define a cutover date or keep the fallback permanently (low cost to keep).
There is no hardcoded depth limit. The engine processes these via recursive descent.
5. **ChooseOne actor:** Currently `ChooseOne` is always resolved by the controlling player. The spec mentions Opponent-chooses and Random-chooses variants. `ChooseOne` needs a `ChooserRole` field (matches `CostGroup` pattern) — add in Phase 1.4 alongside the effect additions.
### B. Every Client Decision Must Be Prompted
At every point the server needs a human choice it cannot auto-resolve, execution **pauses** and the appropriate `Pending*` state is persisted. The client receives a typed prompt and **must** respond before the ability continues. There are no silent auto-picks when a human should be choosing.
Distinct prompt categories and their `Pending*` state types:
| Decision Point | `Pending*` Type | Chooser |
|---|---|---|
| Which OR/XOR cost branch to pay | `PendingCostGroupPick` | `CostGroup.ChooserRole` |
| Which specific cards satisfy a cost (DiscardFromHand, SendSpirit, etc.) | `PendingCostPick` (existing) | `CostEntry.PickMode` |
| Which ability branch to take (`ChooseOne`) | `PendingBranchPick` | `ChooseOne.ChooserRole` |
| Which target(s) to assign to an action | `PendingTargetPick` (existing) | `TargetSelector.Ownership` when it resolves to a human |
| Which tile to place a summoned token / repositioned unit | `PendingTilePick` | action-level |
| Which player to assign control to (e.g. `UnderControlOf: Choice`) | `PendingPlayerPick` | effect-level |
| Reveal-and-choose (`RevealCardsEffect` → `DoAdditionalEffect`) | `PendingRevealChoicePick` | effect-level |
All `Pending*` types share a common envelope:
```
PendingInteraction {
AbilityInstanceId: Guid // which ability instance is paused
StepId: string // opaque step identifier for the client to echo back
Type: string // discriminator matching the table above
Payload: object // type-specific data (options, filters, count, etc.)
Chooser: string // "Self" | "Opponent" | "Ally" | "Random"
TimeoutMs: int // server enforces; Random-pick on timeout
}
```
The game state machine must support being serialized mid-ability-resolution (all `Pending*` state is part of `GameState`) so the server can survive a restart while waiting for a client response.
### C. ChooseOne Has a ChooserRole
`ChooseOne.ChooserRole: string` — same values as `CostGroup.ChooserRole`:
- `"Self"` — the ability's controlling player chooses.
- `"Opponent"` — the opposing player chooses which branch fires.
- `"Random"` — server picks a branch at random (no client prompt).
---
## Resolved Decisions
| # | Decision | Resolution |
|---|---|---|
| 1 | SpiritToken storage | `CardType.SpiritToken` added as a full `CardDefinition` row. `SummonTokenEffect` gains `CardDefinitionId?`. Tokens are **not addable to decks, not grantable to collections** — enforced at deck-build validation and collection-grant endpoints. |
| 2 | OR/XOR client protocol | Confirmed required. Full `PendingCostGroupPick` + `PendingBranchPick` protocol (see Axiom B above). |
| 3 | Drag-and-drop implementation | Custom CSS/Blazor approach first. No external library. |
| 4 | EffectsJson migration | **Hard cutover. No backwards compat shim.** All existing cards migrated in a one-time SQL + C# script run as part of Phase 2. After migration `EffectsJson` column is dropped. See §2.2 below. |
| 5 | ChooseOne ChooserRole | Confirmed. Added in Phase 1.4. |
| 6 | RequiresLOS for Repentance/Instinct | LOS source is the **controlling player's ArchSpirit** (since the card itself is not on the battlefield). The engine looks up the active ArchSpirit for that player and uses it as the origin for LOS calculation. |