docs: add Ruin issue resolution plan
This commit is contained in:
@@ -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`.
|
||||
Reference in New Issue
Block a user