Files
sor/Ruin-flow.md
7dba78ea67 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>
2026-05-20 13:53:56 -04:00

844 lines
38 KiB
Markdown

# Ruin-flow.md — End-to-End Ruin & Ability System Reference
> All line numbers and snippets reflect the state of the codebase as of May 2026.
---
## Table of Contents
1. [What Is a Ruin?](#1-what-is-a-ruin)
2. [Data Model](#2-data-model)
3. [Ability Definition Schema](#3-ability-definition-schema)
4. [Ruin-Specific Trigger Events](#4-ruin-specific-trigger-events)
5. [Client: Channeling a Ruin](#5-client-channeling-a-ruin)
6. [Server: Channeling a Ruin (`ChannelCard`)](#6-server-channeling-a-ruin-channelcard)
7. [Board Operations: PlaceRuin / RemoveRuin](#7-board-operations-placeruin--removeruin)
8. [Turn-Start Activation: `FireRuinAbilities`](#8-turn-start-activation-fireruinabilities)
9. [Activation Order & Priority Rules](#9-activation-order--priority-rules)
10. [Ruin-Specific Effects](#10-ruin-specific-effects)
11. [Observer Triggers: `RuinActivation` & `UnitOccupyRuin`](#11-observer-triggers-ruinactivation--unitoccupyruin)
12. [Double-Fire Guard (6-D)](#12-double-fire-guard-6-d)
13. [Network: Tile Deltas & DTOs](#13-network-tile-deltas--dtos)
14. [Client: Rendering & Inspection](#14-client-rendering--inspection)
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)
---
## 1. What Is a Ruin?
A **Ruin** is a `CardType.Ruin` card (defined in `CardEnums.cs:5`) that is placed on the board and activates passively at the **start of every turn** if a Spirit, ArchSpirit, or SpiritToken occupies the same tile.
Key distinctions from unit cards:
- Ruins **do not block tile occupancy** — units freely share their tile.
- Ruins are **not selectable** as attack targets or movement neighbors.
- Ruins have **no player interaction after placement** — they fire automatically each turn.
- Placement is **random** (server-chosen); the player has no tile choice.
---
## 2. Data Model
### 2.1 Card Definition (database)
```
Server/src/SOR.Database/Entities/Catalog/CardDefinition.cs
```
| Column | Type | Notes |
|--------|------|-------|
| `Id` | Guid | Unique per card definition |
| `CardType` | enum | `"Ruin"` |
| `Name`, `Description` | string | Display |
| `SpCost`, `StCost` | int | Channeling cost |
| `Affinity` | string? | If set, restricts valid placement tiles |
| **`AbilitiesJson`** | JSONB | Array of `AbilityDefinition` — the abilities the Ruin executes |
| `IsPublished` | bool | Controls deck-builder visibility |
### 2.2 Tile (board state)
```
Server/src/SOR.Game/Grid/Tile.cs
```
```csharp
// Lines 37-44
public string? RuinId { get; set; } // InstanceId of Ruin on this tile, or null
public string? RuinOwner { get; set; } // AccountId of owner
/// Turn number after which this tile's Ruin re-enables. 0 = not disabled.
/// Set by DisableRuinForDurationEffect; checked in FireRuinAbilities.
public int RuinDisabledUntilTurn { get; set; }
```
### 2.3 FieldCard (in-game instance)
```
Server/src/SOR.Game/GameState.cs — PlayerState.Field
```
Ruins live in `PlayerState.Field` as `FieldCard` instances (same collection as units) with:
- `CardType = "Ruin"`
- `Position` (Coord?) — set on placement, never changes unless `RelocateRuinEffect` fires
- `AbilitiesJson` — inherited from `CardDefinition`; may be mutated by effects
---
## 3. Ability Definition Schema
```
Server/src/SOR.Game/Abilities/Models/AbilityDefinition.cs
```
```csharp
public sealed class AbilityDefinition
{
public AbilityType Type; // Triggered (for Ruin activation)
public Condition[]? ActivationConditions; // Optional; all must pass to be eligible
public ActionGroup? ActionGroup; // Logical grouping (AND/OR/XOR)
public Action[] Actions; // Flat array (backwards-compat)
// Triggered-only:
public TriggerEvent? TriggerEvent; // OnRuinActivationTrigger for Ruin abilities
public int? TriggerLimitPerTurn;
public int? TriggerLimitPerGame;
public string[]? SourceZoneGate;
// Display/anim:
public string? Name;
public string? Description;
public DurationModel? Duration;
public AbilityAnimationDefinition? Animation;
}
```
Ruin abilities must have:
- `Type == AbilityType.Triggered`
- `TriggerEvent` of type `OnRuinActivationTrigger` (JSON `$type: "OnRuinActivation"`)
---
## 4. Ruin-Specific Trigger Events
```
Server/src/SOR.Game/Abilities/Models/Triggers.cs — Lines 42-161
```
### `OnRuinActivationTrigger` (line 147)
```csharp
// §8.8 Ruin — registered as PolyType "OnRuinActivation" (line 43)
public sealed class OnRuinActivationTrigger : TriggerEvent
{
public string RuinOwnership { get; set; } = "Any"; // "Mine", "Enemy", "Any"
public string? OccupantOwnership { get; set; } // filter by occupant owner
public Filter[]? OccupantFilters { get; set; } // additional occupant filters
}
```
- **Used by:** Ruin card abilities that should execute when the Ruin activates at turn start.
- **Also used by:** Observer cards on *other* cards that want to react when *any* Ruin fires.
### `OnUnitOccupyRuinTrigger` (line 155)
```csharp
// §8.8 Ruin — registered as PolyType "OnUnitOccupyRuin" (line 44)
public sealed class OnUnitOccupyRuinTrigger : TriggerEvent
{
public string UnitOwnership { get; set; } = "Any";
public Filter? Filter { get; set; }
public Filter[]? OccupantFilters { get; set; }
}
```
- **Fires when:** A unit moves onto a tile that already has a Ruin.
- **Does NOT** auto-activate the Ruin — only notifies observer cards.
---
## 5. Client: Channeling a Ruin
### 5.1 Card click in hand (`game_screen.gd:654`)
```gdscript
# game_screen.gd — line 654
if card.get("cardType", "") == "Ruin":
_sel_ctrl.channel_ruin(card)
return
```
Ruin cards bypass the normal tile-highlight flow and go straight to `channel_ruin`.
### 5.2 `channel_ruin` — pre-flight check (`selection_controller.gd:515`)
```gdscript
# selection_controller.gd — lines 515-538
func channel_ruin(card: Dictionary) -> void:
var card_affinity: String = card.get("affinity", "")
var board: Dictionary = Game.get_board()
var has_valid: bool = false
for tile: Dictionary in board.get("tiles", []):
var ruin_id_v: Variant = tile.get("ruinId", null)
var ruin_id: String = "" if ruin_id_v == null else str(ruin_id_v)
if not ruin_id.is_empty() and ruin_id != "null":
continue # tile already has a Ruin
if card_affinity != "" and not _tile_matches_channel_affinity(tile, card_affinity):
continue # affinity mismatch
has_valid = true
break
if not has_valid:
# Show "No valid tile available" error dialog
...
return
_confirm_channel_ruin(card)
```
### 5.3 Confirmation dialog (`selection_controller.gd:541`)
```gdscript
# lines 541-552
func _confirm_channel_ruin(card: Dictionary) -> void:
var dlg: ConfirmationDialog = ConfirmationDialog.new()
dlg.title = "Channel Ruin"
dlg.dialog_text = "Ruin placement is random.\nContinue?"
dlg.ok_button_text = "Channel"
...
dlg.confirmed.connect(func() -> void:
Game.send_play_card(card.get("instanceId", ""), 0, 0) # no tile targets
dlg.queue_free())
```
### 5.4 No tile targeting
```gdscript
# tile_target_resolver.gd — lines 66-67
"Repentance", "Instinct", "Ruin":
pass # No tile target — server handles placement for Ruins
```
The client sends **zero tile targets**. The server is authoritative for placement.
---
## 6. Server: Channeling a Ruin (`ChannelCard`)
```
Server/src/SOR.Game/GameEngine.cs — lines 262-440
```
### 6.1 Gate checks (lines 284-294)
```csharp
// GameEngine.cs
if (card.CardType == "Ruin" && !player.CanChannelRuin)
throw new GameException("CANNOT_CHANNEL_RUIN"); // line 293-294
```
`player.CanChannelRuin` can be toggled false by `SetCanChannelRuinEffect`.
### 6.2 Ruin branch (lines 413-440)
```csharp
else if (card.CardType == "Ruin")
{
// Place on a random tile matching the Ruin's affinity (may already be occupied).
var hasAffinity = Enum.TryParse<Affinity>(card.Affinity, out var ruinAffinity);
var validTiles = board.Tiles.Values
.Where(t => (!hasAffinity || AffinitySystem.IsAffinityValid(t, ruinAffinity))
&& t.RuinId == null) // 6-C: never overwrite an existing Ruin
.ToList();
if (validTiles.Count == 0) throw new GameException("NO_VALID_RUIN_TILE"); // line 421
var ruinCoord = validTiles[Random.Shared.Next(validTiles.Count)].Coord; // line 423
player.Hand.Remove(card);
player.CurrentSp -= card.SpCost;
player.CurrentSt -= card.StCost;
var ruinField = ToFieldCard(card, ruinCoord);
player.Field.Add(ruinField);
board.PlaceRuin(ruinCoord, ruinField.InstanceId, actorId); // line 431
AbilitySystem.FireTrigger(state, new TriggerOccurrence // line 433
{
Kind = TriggerEventKind.Channeled,
ActorId = actorId,
CardType = "Ruin",
Data = new TriggerEventData { SourceId = ruinField.InstanceId },
});
}
```
**Step-by-step:**
1. Parse affinity from card; `hasAffinity = false` if card has no affinity.
2. Collect all tiles where `AffinitySystem.IsAffinityValid(tile, ruinAffinity)` is true (skipped entirely if no affinity) **AND** `tile.RuinId == null`.
3. Throw `NO_VALID_RUIN_TILE` if empty.
4. Pick one at random — fully server-authoritative.
5. Remove card from hand, deduct SP/ST.
6. Create `FieldCard`, add to `player.Field`, call `board.PlaceRuin`.
7. Fire `TriggerEventKind.Channeled` — observer cards (e.g., "when I channel a Ruin…") can react here.
---
## 7. Board Operations: `PlaceRuin` / `RemoveRuin`
```
Server/src/SOR.Game/Grid/Board.cs — lines 164-178
```
```csharp
/// Place a Ruin on a tile. Does not check occupancy — Ruins share tiles with units.
public void PlaceRuin(Coord c, string instanceId, string ownerAccountId) // line 165
{
var tile = GetTile(c) ?? throw new GameException($"TILE_OUT_OF_BOUNDS:{c}");
tile.RuinId = instanceId;
tile.RuinOwner = ownerAccountId;
}
public void RemoveRuin(string instanceId) // line 172
{
var tile = Tiles.Values.FirstOrDefault(t => t.RuinId == instanceId);
if (tile is null) return;
tile.RuinId = null;
tile.RuinOwner = null;
}
```
**No occupancy check** — a Ruin is placed without regard to whether a unit is already on the tile.
---
## 8. Turn-Start Activation: `FireRuinAbilities`
```
Server/src/SOR.Game/Abilities/AbilitySystem.cs — lines 458-512
```
### 8.1 When it's called
```csharp
// GameEngine.cs — line 1070
AbilitySystem.FireRuinAbilities(state);
```
Called near the **end of `StartTurn()`**, after:
- MP/Defense reset
- Aura re-evaluation
- `OnTurnStart` triggers
### 8.2 Full implementation
```csharp
// AbilitySystem.cs — lines 458-512
public static GameState FireRuinAbilities(GameState state)
{
foreach (var (ownerId, player) in state.Players)
{
var ruins = player.Field
.OfType<FieldCard>()
.Where(c => c.CardType == "Ruin" && c.Position.HasValue)
.ToList();
foreach (var ruin in ruins)
{
var tile = state.Board?.GetTile(ruin.Position!.Value);
if (tile?.OccupantId is null) continue; // skip: no unit on tile
// Skip if this ruin is disabled by DisableRuinForDurationEffect.
if (tile.RuinDisabledUntilTurn > 0 && state.TurnNumber <= tile.RuinDisabledUntilTurn)
continue;
// Only fires if a Spirit or ArchSpirit is on the tile.
var occupantType = FindUnitType(state, tile.OccupantId);
if (occupantType is not ("Spirit" or "ArchSpirit" or "SpiritToken")) continue;
var abilities = ParseAbilities(ruin.AbilitiesJson);
var ctx = new AbilityContext { State = state, ActorId = ownerId, Source = ruin };
var eligible = abilities
.Where(a => a.Type == AbilityType.Triggered
&& a.TriggerEvent is OnRuinActivationTrigger)
.Where(a => a.ActivationConditions is not { Length: > 0 }
|| a.ActivationConditions.All(c => EvaluateCondition(c, ctx, ruin)))
.ToList();
if (eligible.Count == 0) continue;
// Select exactly one ability at random.
var chosen = eligible[Random.Shared.Next(eligible.Count)]; // line 493
var chosenActions = GetEffectiveActions(chosen, ctx, abilityIndex: 0, chosen.Range, chosen.Duration);
if (chosenActions is not null)
ExecuteActions(chosenActions, ctx, clientTargets: null);
// Notify observer cards that the ruin activated.
FireTrigger(state, new TriggerOccurrence
{
Kind = TriggerEventKind.RuinActivation,
ActorId = ownerId,
Data = new TriggerEventData
{
SourceId = ruin.InstanceId,
TargetId = tile.OccupantId,
},
});
}
}
return state;
}
```
### 8.3 Helper: `FindUnitType` (lines 514-523)
```csharp
private static string? FindUnitType(GameState state, string instanceId)
{
foreach (var player in state.Players.Values)
{
var c = player.Field.FirstOrDefault(x => x.InstanceId == instanceId)
?? player.ArchSpirit as CardInstance;
if (c?.InstanceId == instanceId) return c.CardType;
}
return null;
}
```
---
## 9. Activation Order & Priority Rules
| Rule | Detail |
|------|--------|
| **Per-player, per-ruin** | Outer loop: players; inner loop: ruins in `player.Field` list order. |
| **Prerequisite 1: occupant** | Tile must have `OccupantId != null`. |
| **Prerequisite 2: not disabled** | `tile.RuinDisabledUntilTurn == 0` or `turnNumber > disabledUntilTurn`. |
| **Prerequisite 3: occupant type** | Occupant must be `"Spirit"`, `"ArchSpirit"`, or `"SpiritToken"`. |
| **Ability filter** | Only abilities with `Type == Triggered` + `TriggerEvent is OnRuinActivationTrigger`. |
| **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. |
---
## 10. Ruin-Specific Effects
```
Server/src/SOR.Game/Abilities/Models/Effects.cs — Lines 334-357
Server/src/SOR.Game/Abilities/AbilitySystem.cs — Lines 3040-3093
```
### 10.1 `RelocateRuinEffect` (Effects.cs:337 / executed at AbilitySystem.cs:3041)
```csharp
// Effects.cs
public sealed class RelocateRuinEffect : Effect { }
```
```csharp
// AbilitySystem.cs — lines 3041-3053
case RelocateRuinEffect when target is Coord destCoord:
{
if (ctx.Source is not FieldCard ruinFc || ctx.State.Board is null) break;
var board = ctx.State.Board;
var ruinTile = board.Tiles.Values.FirstOrDefault(t => t.RuinId == ruinFc.InstanceId);
if (ruinTile is null) break;
var destTile = board.GetTile(destCoord);
if (destTile is null || destTile.RuinId is not null) break; // dest must be ruin-free
board.RemoveRuin(ruinFc.InstanceId);
board.PlaceRuin(destCoord, ruinFc.InstanceId, ctx.ActorId);
ruinFc.Position = destCoord;
break;
}
```
Moves a Ruin to a new tile. Destination must be in-bounds and ruin-free.
### 10.2 `ActivateRuinAbilityEffect` (Effects.cs:345 / executed at AbilitySystem.cs:3055)
```csharp
// Effects.cs — lines 345-351
public sealed class ActivateRuinAbilityEffect : Effect
{
public string? AbilityRef; // If set, activate ability by Name
public bool Random = true; // If true (default), pick random eligible ability
public bool ChooseAllTargets; // Auto-resolve all targets without player interaction
}
```
```csharp
// AbilitySystem.cs — lines 3055-3075
case ActivateRuinAbilityEffect arAe when target is FieldCard ruinCard && ruinCard.CardType == "Ruin":
{
var ruinOwner = FindCardOwner(ctx.State, ruinCard.InstanceId);
if (ruinOwner is null) break;
var ruinCtx = new AbilityContext { State = ctx.State, ActorId = ruinOwner.AccountId, Source = ruinCard };
var ruinAbilities = ParseAbilities(ruinCard.AbilitiesJson);
var eligible = ruinAbilities
.Where(a => a.Type == AbilityType.Triggered && a.TriggerEvent is OnRuinActivationTrigger)
.Where(a => a.ActivationConditions is not { Length: > 0 }
|| a.ActivationConditions.All(c => EvaluateCondition(c, ruinCtx, ruinCard)))
.ToList();
if (eligible.Count == 0) break;
AbilityDefinition chosen;
if (!arAe.Random && arAe.AbilityRef is not null)
chosen = eligible.FirstOrDefault(a => a.Name == arAe.AbilityRef)
?? eligible[Random.Shared.Next(eligible.Count)];
else
chosen = eligible[Random.Shared.Next(eligible.Count)];
var chosenActs = GetEffectiveActions(chosen, ruinCtx, 0, chosen.Range, chosen.Duration);
if (chosenActs is not null)
ExecuteActions(chosenActs, ruinCtx, clientTargets: null);
break;
}
```
Programmatically activates a Ruin's ability from another card's effect. Same eligibility logic as `FireRuinAbilities`. Can target a specific ability by `AbilityRef` name or pick randomly.
### 10.3 `DisableRuinForDurationEffect` (Effects.cs:354 / executed at AbilitySystem.cs:3077)
```csharp
// Effects.cs — lines 354-357
public sealed class DisableRuinForDurationEffect : Effect
{
public DurationModel Duration = DurationModel.EndOfTurn;
}
```
```csharp
// AbilitySystem.cs — lines 3077-3093
case DisableRuinForDurationEffect drfd when target is FieldCard ruinDis && ruinDis.CardType == "Ruin":
{
if (ruinDis.Position.HasValue && ctx.State.Board is not null)
{
var ruinDisTile = ctx.State.Board.GetTile(ruinDis.Position.Value);
if (ruinDisTile is not null)
{
int disableTurns = drfd.Duration.Type switch
{
DurationType.ForNTurns => drfd.Duration.N ?? 1,
_ => 1,
};
ruinDisTile.RuinDisabledUntilTurn = ctx.State.TurnNumber + disableTurns; // line 3089
}
}
break;
}
```
Sets `tile.RuinDisabledUntilTurn`. `FireRuinAbilities` checks this at line 473 and skips the ruin if still within the disable window.
### 10.4 `SetCanChannelRuinEffect`
```
Server/src/SOR.Game/Abilities/Models/Effects.cs — line 174
```
Gates whether a player can channel new Ruins at all. Checked in `ChannelCard` at `GameEngine.cs:293`.
---
## 11. Observer Triggers: `RuinActivation` & `UnitOccupyRuin`
### 11.1 `RuinActivation` — fired from `FireRuinAbilities` (line 499)
After the chosen ability executes, `FireTrigger` broadcasts `TriggerEventKind.RuinActivation` so **other** cards (not the source Ruin itself — see §12) can react:
```csharp
FireTrigger(state, new TriggerOccurrence
{
Kind = TriggerEventKind.RuinActivation,
ActorId = ownerId,
Data = new TriggerEventData { SourceId = ruin.InstanceId, TargetId = tile.OccupantId },
});
```
Observer cards use `OnRuinActivationTrigger` with `RuinOwnership = "Any"` (or `"Mine"` / `"Enemy"`) to react.
### 11.2 `UnitOccupyRuin` — fired from `GameEngine.MoveUnit` (line 671)
```csharp
// GameEngine.cs — lines 667-677
// Fire UnitOccupyRuin if the destination tile has a Ruin.
var destTileAfterMove = board.GetTile(targetPos);
if (destTileAfterMove?.RuinId is not null)
{
AbilitySystem.FireTrigger(state, new TriggerOccurrence
{
Kind = TriggerEventKind.UnitOccupyRuin,
ActorId = actorId,
Data = new TriggerEventData { SourceId = unitInstanceId, TargetId = destTileAfterMove.RuinId },
});
}
```
Fires mid-turn whenever a unit steps onto a Ruin tile. Does **not** activate the Ruin itself — it is purely a notification hook for observer cards using `OnUnitOccupyRuinTrigger`.
---
## 12. Double-Fire Guard (6-D)
```
Server/src/SOR.Game/Abilities/AbilitySystem.cs — lines 303-309
```
```csharp
// 6-D: Prevent double-firing the source Ruin's own OnRuinActivation abilities.
// FireRuinAbilities already executed one chosen ability directly; the subsequent
// FireTrigger call is only for observer cards. Skip the source Ruin itself.
if (occurrence.Kind == TriggerEventKind.RuinActivation
&& def.TriggerEvent is OnRuinActivationTrigger
&& card.InstanceId == occurrence.Data?.SourceId)
continue;
```
**Why this exists:** `FireRuinAbilities` deliberately calls `FireTrigger(RuinActivation)` after executing the ability so observer cards can react. Without this guard, `FireTrigger`'s own scan would find the source Ruin again and execute its `OnRuinActivation` abilities a second time. The guard skips the source Ruin when processing the broadcast, so only *other* cards react.
---
## 13. Network: Tile Deltas & DTOs
```
Server/src/SOR.Game/GameMessages.cs
```
### Full tile state (sent on game join / reconnect)
```csharp
// GameMessages.cs — lines 745-753
public sealed record TileDto(
CoordDto Coord,
string Base1,
string Base2,
string ResolvedAffinity,
string? OccupantId,
string? OccupantOwner,
string? RuinId, // ← Ruin instance ID or null
string? RuinOwner); // ← owner account ID or null
```
### Incremental delta (pushed after any state change)
```csharp
// GameMessages.cs — lines 525-536
public sealed record TileDelta(
int X,
int Y,
...
string? OccupantOwner,
string? RuinId, // ← new RuinId, or null if cleared
bool RuinCleared, // ← true when Ruin was removed from tile
string? RuinOwner);
```
The server pushes `TileDelta` to all viewers whenever a tile's ruin state changes (placement, relocation, removal).
---
## 14. Client: Rendering & Inspection
```
Client/origin-client/scenes/game/components/hud/tile_drawer.gd
```
### Variables declared (lines 18-31)
```gdscript
var tile_drawer_ruin_labels: Array = [] # 2 label nodes for Name + Owner
var tile_drawer_ruin_section: Dictionary = {} # collapsible "Ruin Details" section
var tile_drawer_ruin_effects_section: Dictionary = {} # collapsible "Active Effects" section
var tile_drawer_ruin_effects_labels: Array = []
```
### Section creation (lines 91-92)
```gdscript
tile_drawer_ruin_section = create_tile_drawer_section(vbox, "Ruin Details", false)
tile_drawer_ruin_effects_section = create_scrollable_section(vbox, "Active Effects")
```
### Label slots (line 98)
```gdscript
tile_drawer_ruin_labels = create_detail_labels(tile_drawer_ruin_section["content"], 2)
# Slot 0: "Ruin: <instanceId>"
# Slot 1: "Owner: <displayName>"
```
### Population on tile click (lines 419-426)
```gdscript
var ruin_id_value: Variant = tile_data.get("ruinId", "")
var ruin_id: String = "" if ruin_id_value == null else str(ruin_id_value)
var ruin_owner_id: String = str(tile_data.get("ruinOwner", ""))
if ruin_id_value != null and not ruin_id.is_empty() and ruin_id != "null":
var ruin_lines: Array = ["Ruin: %s" % ruin_id, "Owner: %s" % Game.get_display_name(ruin_owner_id)]
var ruin_tooltips: Array = ["", ""]
set_tile_drawer_lines(tile_drawer_ruin_section, tile_drawer_ruin_labels, ruin_lines, ruin_tooltips)
set_effects_section(ruin_id, tile_drawer_ruin_effects_section, tile_drawer_ruin_effects_labels)
else:
set_tile_drawer_lines(tile_drawer_ruin_section, tile_drawer_ruin_labels, [])
clear_effects_section(tile_drawer_ruin_effects_section, tile_drawer_ruin_effects_labels)
```
Active effects targeting the Ruin (by its `instanceId`) are fetched and displayed in the scrollable effects section via `append_active_effect_lines` (line 316).
---
## 15. Client: Ruins Are Not Selectable Units
```
Client/origin-client/scenes/game/components/units/unit_registry.gd — lines 61-105
Client/origin-client/scenes/game/components/selection/selection_controller.gd — lines 94-178
Client/origin-client/scenes/game/components/board/tile_target_resolver.gd — lines 173-300
```
### `is_ruin_unit` / `is_ruin_instance` (unit_registry.gd:64-73)
```gdscript
func is_ruin_unit(unit: Dictionary) -> bool:
return str(unit.get("cardType", "")).to_lower() == "ruin"
func is_ruin_instance(iid: String) -> bool:
if iid.is_empty(): return false
var unit: Dictionary = Game.get_unit_by_id(iid)
return not unit.is_empty() and is_ruin_unit(unit)
```
### Ruins excluded from:
| Location | Line | What's excluded |
|----------|------|----------------|
| `unit_registry.gd:40` | `rebuild_ownership` | Ruins not added to friendly/enemy unit ID maps |
| `unit_registry.gd:100` | `all_board_units()` | Ruins excluded from the "all board units" array |
| `selection_controller.gd:99` | `select_unit` | Clicking a Ruin unit does nothing (returns early) |
| `selection_controller.gd:176` | board click occupant resolution | Ruin occupant not treated as selectable unit |
| `tile_target_resolver.gd:176` | `valid_attack_targets` | Ruins are never valid attack targets |
| `tile_target_resolver.gd:300` | ArchSpirit movement targets | Ruins skipped when computing ArchSpirit range |
---
## 16. End-to-End Sequence Diagram
```
PLAYER CLIENT SERVER BOARD/STATE
│ │ │ │
│ clicks Ruin │ │ │
│──────────────>│ │ │
│ │ channel_ruin(card) │ │
│ │ [pre-flight: any valid tile?] │
│ │ [no → AcceptDialog "No valid tile"] │
│ │ [yes → _confirm_channel_ruin(card)] │
│ │ ConfirmationDialog shown │ │
│ clicks Channel │ │ │
│──────────────>│ │ │
│ │ send_play_card(iid,0,0) ─────────────────────────>│
│ │ │ ChannelCard() │
│ │ │ ├─ validate CanChannelRuin│
│ │ │ ├─ filter valid tiles │
│ │ │ │ (affinity + no RuinId) │
│ │ │ ├─ pick random tile │
│ │ │ ├─ deduct SP/ST │
│ │ │ ├─ create FieldCard ─────>│ player.Field.Add
│ │ │ ├─ board.PlaceRuin ──────>│ tile.RuinId = iid
│ │ │ └─ FireTrigger(Channeled)─>│ observer cards react
│ │<── TileDelta(RuinId) ───│ │
│ │ tile_drawer updates │ │
│ │ │ │
╔═══════════════╪═════════════════════════╪══════════════════════════╪══╗
║ NEXT TURN START ║
╚═══════════════╪═════════════════════════╪══════════════════════════╪══╝
│ │ │ StartTurn() │
│ │ │ ├─ MP/Def reset │
│ │ │ ├─ Auras re-eval │
│ │ │ ├─ OnTurnStart triggers │
│ │ │ └─ FireRuinAbilities() │
│ │ │ for each ruin: │
│ │ │ ├─ check tile.OccupantId != null
│ │ │ ├─ check not disabled │
│ │ │ ├─ check occupant type = Spirit/ArchSpirit/SpiritToken
│ │ │ ├─ filter eligible abilities (OnRuinActivation + conditions)
│ │ │ ├─ pick ONE at random │
│ │ │ ├─ ExecuteActions() ───>│ effects applied
│ │ │ └─ FireTrigger(RuinActivation)
│ │ │ (source Ruin skipped by 6-D guard)
│ │ │ observer cards react │
│ │<── GameStateDelta ──────│ │
│ │ animations / HUD update │ │
│ │ │ │
╔═══════════════╪═════════════════════════╪══════════════════════════╪══╗
║ UNIT MOVES ONTO RUIN TILE (mid-turn) ║
╚═══════════════╪═════════════════════════╪══════════════════════════╪══╝
│ │ │ MoveUnit() │
│ │ │ ├─ move unit │
│ │ │ ├─ FireTrigger(UnitMoved)│
│ │ │ └─ if destTile.RuinId != null:
│ │ │ FireTrigger(UnitOccupyRuin)
│ │ │ (observer cards only — ruin doesn't auto-fire)
│ │<── GameStateDelta ──────│ │
```
---
## 17. File & Class Summary
### Server
| File | Key Items |
|------|-----------|
| `SOR.Database/Entities/Catalog/CardDefinition.cs` | `CardDefinition` — `AbilitiesJson` JSONB column |
| `SOR.Database/Enums/CardEnums.cs:5` | `CardType.Ruin` enum value |
| `SOR.Game/Grid/Tile.cs:37-44` | `RuinId`, `RuinOwner`, `RuinDisabledUntilTurn` |
| `SOR.Game/Grid/Board.cs:165-178` | `PlaceRuin()`, `RemoveRuin()` |
| `SOR.Game/GameEngine.cs:262` | `ChannelCard()` — full channeling logic |
| `SOR.Game/GameEngine.cs:413-440` | Ruin branch of `ChannelCard` |
| `SOR.Game/GameEngine.cs:1070` | `FireRuinAbilities(state)` call site |
| `SOR.Game/GameEngine.cs:667-677` | `UnitOccupyRuin` trigger firing on move |
| `SOR.Game/GameMessages.cs:525-536` | `TileDelta` — `RuinId`, `RuinCleared`, `RuinOwner` |
| `SOR.Game/GameMessages.cs:745-753` | `TileDto` — `RuinId`, `RuinOwner` |
| `SOR.Game/Abilities/AbilitySystem.cs:458-512` | `FireRuinAbilities()` |
| `SOR.Game/Abilities/AbilitySystem.cs:303-309` | 6-D double-fire guard |
| `SOR.Game/Abilities/AbilitySystem.cs:3041-3093` | Effect execution: `RelocateRuin`, `ActivateRuinAbility`, `DisableRuinForDuration` |
| `SOR.Game/Abilities/Models/AbilityDefinition.cs` | `AbilityDefinition` — full ability schema |
| `SOR.Game/Abilities/Models/Triggers.cs:147-161` | `OnRuinActivationTrigger`, `OnUnitOccupyRuinTrigger` |
| `SOR.Game/Abilities/Models/Effects.cs:337-357` | `RelocateRuinEffect`, `ActivateRuinAbilityEffect`, `DisableRuinForDurationEffect` |
| `SOR.Game/Abilities/Models/Effects.cs:174` | `SetCanChannelRuinEffect` |
### Client (GDScript)
| File | Key Items |
|------|-----------|
| `scenes/game/game_screen.gd:654-656` | Route Ruin card click to `_sel_ctrl.channel_ruin()` |
| `scenes/game/components/selection/selection_controller.gd:515-556` | `channel_ruin()` pre-flight check; `_confirm_channel_ruin()` dialog; `send_play_card` |
| `scenes/game/components/board/tile_target_resolver.gd:66-67` | `"Ruin": pass` — no tile target computed |
| `scenes/game/components/board/tile_target_resolver.gd:176,300` | Ruins excluded from attack targets and ArchSpirit range |
| `scenes/game/components/units/unit_registry.gd:64-105` | `is_ruin_unit()`, `is_ruin_instance()`, `all_board_units()` (excludes ruins) |
| `scenes/game/components/selection/selection_controller.gd:99,176` | Ruins not selectable; not resolved as unit on board click |
| `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.