Files
sor/Ruin-IssueResolution.md
T

5.6 KiB

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.

  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.