Files
sor/Ruin-IssueResolution.md

150 lines
5.6 KiB
Markdown

# 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`.