Expand Ruin-flow.md: failure modes, randomness note, disable timeline, cross-links

- §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 <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
dingo
2026-05-20 13:53:56 -04:00
co-authored by Claude Happy
parent 0d24a11bcf
commit 7dba78ea67
+72
View File
@@ -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.