diff --git a/NewCard-AbilityChange.md b/NewCard-AbilityChange.md index 7eb7a6e..deb1535 100644 --- a/NewCard-AbilityChange.md +++ b/NewCard-AbilityChange.md @@ -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. |