From 7dba78ea679ac1991019c8450bdd8529620e4b76 Mon Sep 17 00:00:00 2001 From: dingo Date: Wed, 20 May 2026 13:53:56 -0400 Subject: [PATCH] Expand Ruin-flow.md: failure modes, randomness note, disable timeline, cross-links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - §18: failure-mode table covering all error paths (NO_VALID_RUIN_TILE, CANNOT_CHANNEL_RUIN, null/malformed AbilitiesJson, invalid relocate dest, etc.) - §19: randomness & determinism note — Random.Shared is non-deterministic; replay tests need tolerance or a seeded/mock RNG - §20: disable-duration turn-boundary example with concrete timeline (set T5 → disabled T6/T7 → re-enables T8) - §21: See Also cross-links to Ability-flow.md and Delta-Sync-flow.md - §9: added row flagging non-deterministic tile/ability selection (→ §19) - TOC updated with sections 18-21 Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude Co-Authored-By: Happy --- Ruin-flow.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/Ruin-flow.md b/Ruin-flow.md index d7143ec..336bd7c 100644 --- a/Ruin-flow.md +++ b/Ruin-flow.md @@ -22,6 +22,10 @@ 15. [Client: Ruins Are Not Selectable Units](#15-client-ruins-are-not-selectable-units) 16. [End-to-End Sequence Diagram](#16-end-to-end-sequence-diagram) 17. [File & Class Summary](#17-file--class-summary) +18. [Failure Modes & Error Paths](#18-failure-modes--error-paths) +19. [Randomness & Determinism](#19-randomness--determinism) +20. [Disable Duration: Turn-Boundary Example](#20-disable-duration-turn-boundary-example) +21. [See Also](#21-see-also) --- @@ -393,6 +397,7 @@ private static string? FindUnitType(GameState state, string instanceId) | **Condition gating** | All `ActivationConditions` must pass (empty = always eligible). | | **Exactly one ability fires** | `Random.Shared.Next(eligible.Count)` — if multiple abilities are eligible, one is chosen at random. | | **No per-turn limit checked here** | `FireRuinAbilities` doesn't check `TriggerLimitPerTurn`; the limit applies when other cards trigger `OnRuinActivation` via `FireTrigger`. | +| **Non-deterministic** | Both tile selection (`ChannelCard:423`) and ability selection (`FireRuinAbilities:493`) use `Random.Shared.Next()` — see §19. | | **Observer notification last** | `FireTrigger(RuinActivation)` is called *after* the chosen ability executes. | | **Ruin order** | `player.Field` insertion order (i.e., channeling order). No explicit priority number. | @@ -769,3 +774,70 @@ PLAYER CLIENT SERVER BOARD/STATE | `scenes/game/components/hud/tile_drawer.gd:18-31` | Ruin section variable declarations | | `scenes/game/components/hud/tile_drawer.gd:91-98` | Ruin section/label creation | | `scenes/game/components/hud/tile_drawer.gd:419-426` | Populate ruin details + active effects on tile inspection | + +--- + +## 18. Failure Modes & Error Paths + +| Failure | Where detected | Error / behaviour | +|---------|---------------|-------------------| +| **No valid tile for affinity** | `GameEngine.cs:421` | `throw new GameException("NO_VALID_RUIN_TILE")` — propagated to client as an error response; card stays in hand, no cost deducted | +| **Player flag blocks channeling** | `GameEngine.cs:293` | `throw new GameException("CANNOT_CHANNEL_RUIN")` — same recovery path as above | +| **`AbilitiesJson` is null or empty string** | `AbilitySystem.cs — ParseAbilities()` | Returns an empty `AbilityDefinition[]`; `eligible.Count == 0` causes the Ruin to silently skip activation that turn | +| **`AbilitiesJson` is malformed JSON** | `ParseAbilities()` | `JsonSerializer.Deserialize` throws; uncaught exception surfaces as a 500 / session fault — treat as a data-authoring bug | +| **No `OnRuinActivationTrigger` ability defined** | `FireRuinAbilities:490` | `eligible.Count == 0 → continue` — Ruin sits on board forever without ever firing | +| **All abilities fail `ActivationConditions`** | `FireRuinAbilities:488` | Same as above — Ruin present, no activation | +| **`RelocateRuinEffect` — destination out of bounds** | `AbilitySystem.cs:3047` | `board.GetTile(destCoord)` returns null → `break`; relocation silently no-ops | +| **`RelocateRuinEffect` — destination already has a Ruin** | `AbilitySystem.cs:3048` | `destTile.RuinId is not null → break`; relocation silently no-ops | +| **`ActivateRuinAbilityEffect` — no owner found** | `AbilitySystem.cs:3058` | `ruinOwner is null → break`; effect silently no-ops | +| **`DisableRuinForDurationEffect` — ruin not on board** | `AbilitySystem.cs:3079` | `ruinDis.Position.HasValue` is false → `break`; no-op | +| **Client: no valid tile (pre-flight)** | `selection_controller.gd:529` | Shows "No valid tile available" `AcceptDialog`; never sends `send_play_card` | + +--- + +## 19. Randomness & Determinism + +Both random choices in the Ruin system use `Random.Shared.Next()` (the process-wide shared `System.Random` instance): + +| Choice | Location | Notes | +|--------|----------|-------| +| Tile placement | `GameEngine.cs:423` — `validTiles[Random.Shared.Next(...)]` | Chosen from all affinity-matching, ruin-free tiles | +| Ability selection | `AbilitySystem.cs:493` — `eligible[Random.Shared.Next(...)]` | Chosen from eligible `OnRuinActivation` abilities; also used inside `ActivateRuinAbilityEffect` at line 3071 | + +**`Random.Shared` is not seeded and not reproducible between runs.** Consequences for testing: + +- **Deterministic replay tests are not possible** without replacing `Random.Shared` or injecting a seeded `Random` instance. +- **QA scripted tests** that verify Ruin placement or ability selection must either mock the random source, accept any valid outcome, or repeat the scenario enough times to cover all branches statistically. +- **Balance analysis** that counts per-ability activation rates should aggregate across many games, not assume round-robin behaviour. + +--- + +## 20. Disable Duration: Turn-Boundary Example + +`DisableRuinForDurationEffect` sets: +```csharp +tile.RuinDisabledUntilTurn = ctx.State.TurnNumber + disableTurns; // AbilitySystem.cs:3089 +``` + +`FireRuinAbilities` skips a Ruin when: +```csharp +tile.RuinDisabledUntilTurn > 0 && state.TurnNumber <= tile.RuinDisabledUntilTurn // line 473 +``` + +**Example — `ForNTurns: 2`, effect fires on Turn 5:** + +| Turn | `RuinDisabledUntilTurn` | `TurnNumber <= 7`? | Ruin fires? | +|------|-------------------------|--------------------|-------------| +| 5 (effect fires) | set to **7** (5 + 2) | — | No (effect fires this turn, activation already skipped or not yet reached) | +| 6 | 7 | 6 ≤ 7 → true | **Skipped** | +| 7 | 7 | 7 ≤ 7 → true | **Skipped** | +| 8 | 7 | 8 ≤ 7 → false | **Fires normally** | + +The Ruin is **disabled on turns 6 and 7**, and **re-enables on turn 8**. The disable window is inclusive on both ends. + +--- + +## 21. See Also + +- **[Ability-flow.md](Ability-flow.md)** — Deep dive into triggered ability execution, `FireTrigger` pipeline, condition evaluation, cost payment, and target resolution. Ruin abilities go through the same `ExecuteActions` path documented there. +- **[Delta-Sync-flow.md](Delta-Sync-flow.md)** — How `GameStateDelta` / `TileDelta` are assembled and pushed to clients after every state mutation, including the `RuinId` / `RuinCleared` fields documented in §13 above.