diff --git a/Ruin-IssueResolution.md b/Ruin-IssueResolution.md new file mode 100644 index 0000000..0dafe13 --- /dev/null +++ b/Ruin-IssueResolution.md @@ -0,0 +1,149 @@ +# Ruin-IssueResolution + +## Summary of Requested Fixes +1. Add client confirmation before channeling a **Ruin**. +2. Validate a Ruin tile is available **before sending** `game.play_card`. +3. Ensure Ruin placement only picks tiles that **do not already contain a Ruin**. +4. Fix bug where Ruin activation appears to run **all triggered abilities** instead of one. + +--- + +## Root-Cause Analysis (why all abilities can fire) + +### Current intended behavior +`AbilitySystem.FireRuinAbilities(...)` explicitly selects **one** eligible `OnRuinActivation` ability at random for each Ruin, then executes that one. + +### Why "all" can still happen +After executing the chosen ability, code emits: +- `TriggerEventKind.RuinActivation` with `SourceId = ruin.InstanceId` + +Then `AbilitySystem.FireTrigger(...)` scans all field cards (including Ruins) for triggered abilities matching `OnRuinActivationTrigger`. + +Because of that: +- The same Ruin can match the emitted `RuinActivation` event again +- Its other `OnRuinActivation` triggered abilities can also execute via the general trigger pipeline + +So the selected-one behavior is effectively bypassed by a second trigger path. + +--- + +## Resolution Plan + +## A) Client: confirmation prompt before channeling Ruin +**File:** `Client/origin-client/scenes/game/game_screen.gd` + +### Plan +- In `_on_hand_card_clicked(...)` under `cardType == "Ruin"`, replace immediate send with a confirm flow. +- Use existing modal/confirm UI pattern (or add a small reusable confirm dialog): + - Title: `Channel Ruin?` + - Body: `Ruin placement is random. Continue?` + - Buttons: `Cancel` / `Channel` +- Only call `Game.send_play_card(iid, 0, 0)` on explicit confirm. + +### Acceptance criteria +- Clicking Ruin does not instantly channel. +- Cancel does nothing. +- Confirm channels once. + +--- + +## B) Client preflight: require at least one valid Ruin tile before sending +**File:** `Client/origin-client/scenes/game/game_screen.gd` + +### Plan +- Before showing confirmation (or before sending), compute candidate tiles from current board state: + - Affinity-valid for the Ruin + - `ruinId` is null/empty (no existing ruin) +- If no candidates: + - Do not send play request. + - Show user-facing message (toast/snackbar) like: `No valid tile available for this Ruin.` + +### Notes +- This is UX protection only; server must still enforce for correctness. + +### Acceptance criteria +- Client blocks Ruin channel request when zero valid no-ruin tiles exist. +- User receives clear reason. + +--- + +## C) Server: enforce no-ruin placement and robust selection +**File:** `Server/src/SOR.Game/GameEngine.cs` (Ruin branch in `ChannelCard`) + +### Plan +- Change candidate set from: + - affinity-valid tiles +- to: + - affinity-valid tiles **AND** `tile.RuinId == null` +- Keep random selection among filtered candidates. +- If filtered set is empty, throw `NO_VALID_TILE`. + +### Optional hardening +- Add a dedicated error code: `NO_VALID_RUIN_TILE` for clearer client handling. + +### Acceptance criteria +- A Ruin is never placed on a tile already containing another Ruin. +- Existing Ruins remain stable under repeated channels. + +--- + +## D) Server: stop double execution of OnRuinActivation abilities +**Primary file:** `Server/src/SOR.Game/Abilities/AbilitySystem.cs` + +### Plan (minimal-risk) +- In `FireTrigger(...)`, when `occurrence.Kind == TriggerEventKind.RuinActivation`, skip executing `OnRuinActivationTrigger` abilities on the **source Ruin** (`unit.InstanceId == occurrence.Data?.SourceId`). +- Keep event propagation for observer cards (non-source cards), preserving intended "notify observers" behavior. + +### Alternative (cleaner but wider change) +- Emit a separate observer-only event kind (e.g., `RuinActivatedNotice`) and map observer triggers to that. +- This is a larger schema/API change; prefer minimal-risk patch first. + +### Acceptance criteria +- For one Ruin activation tick, exactly one of that Ruin's eligible `OnRuinActivation` abilities executes. +- Observer triggers still work. +- No regression for other trigger kinds. + +--- + +## Test Plan + +## 1) Unit tests (server) +- **Ruin candidate filtering** + - Board with affinity-valid tiles all occupied by existing Ruins -> `NO_VALID_TILE` (or new code). + - Mixed board -> selected tile never has `RuinId` set. + +- **Single-ability execution** + - Ruin with 3 eligible `OnRuinActivation` abilities. + - Run turn-start activation. + - Assert exactly 1 executes for source Ruin. + +- **Observer behavior preserved** + - Another card with `OnRuinActivation` trigger should still react when source ruin activates. + +## 2) Integration tests +- Play Ruin from hand in a live session: + - Confirm dialog shown. + - Cancel path sends no request. + - Confirm path sends request once. +- Fill board with existing Ruins (or simulate no valid tile) and verify client preflight blocks send. +- Multi-turn simulation confirms one source Ruin effect per activation. + +## 3) Manual QA checklist +- Ruin click spam cannot bypass confirmation into multiple sends. +- Ruin placements remain random but only on no-ruin tiles. +- Combat/move interactions with Ruin tiles still trigger `UnitOccupyRuin` as before. + +--- + +## Implementation Order (recommended) +1. **D** fix double-trigger bug first (highest gameplay correctness impact). +2. **C** enforce no-ruin placement on server (authoritative rule). +3. **B** add client preflight check (UX + fewer failed requests). +4. **A** add client confirmation dialog (final UX guard). + +--- + +## Risks / Notes +- Existing Ruin card definitions using `OnRuinActivation` as observer triggers on non-source cards should remain functional with source-skip approach. +- If you later need richer semantics (source vs observer), consider explicit trigger event split. +- Keep client/server error code mapping aligned if introducing `NO_VALID_RUIN_TILE`.