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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user