- §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>
38 KiB
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
- What Is a Ruin?
- Data Model
- Ability Definition Schema
- Ruin-Specific Trigger Events
- Client: Channeling a Ruin
- Server: Channeling a Ruin (
ChannelCard) - Board Operations: PlaceRuin / RemoveRuin
- Turn-Start Activation:
FireRuinAbilities - Activation Order & Priority Rules
- Ruin-Specific Effects
- Observer Triggers:
RuinActivation&UnitOccupyRuin - Double-Fire Guard (6-D)
- Network: Tile Deltas & DTOs
- Client: Rendering & Inspection
- Client: Ruins Are Not Selectable Units
- End-to-End Sequence Diagram
- File & Class Summary
- Failure Modes & Error Paths
- Randomness & Determinism
- Disable Duration: Turn-Boundary Example
- 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
// 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 unlessRelocateRuinEffectfiresAbilitiesJson— inherited fromCardDefinition; may be mutated by effects
3. Ability Definition Schema
Server/src/SOR.Game/Abilities/Models/AbilityDefinition.cs
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.TriggeredTriggerEventof typeOnRuinActivationTrigger(JSON$type: "OnRuinActivation")
4. Ruin-Specific Trigger Events
Server/src/SOR.Game/Abilities/Models/Triggers.cs — Lines 42-161
OnRuinActivationTrigger (line 147)
// §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)
// §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)
# 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)
# 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)
# 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
# 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)
// 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)
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:
- Parse affinity from card;
hasAffinity = falseif card has no affinity. - Collect all tiles where
AffinitySystem.IsAffinityValid(tile, ruinAffinity)is true (skipped entirely if no affinity) ANDtile.RuinId == null. - Throw
NO_VALID_RUIN_TILEif empty. - Pick one at random — fully server-authoritative.
- Remove card from hand, deduct SP/ST.
- Create
FieldCard, add toplayer.Field, callboard.PlaceRuin. - 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
/// 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
// GameEngine.cs — line 1070
AbilitySystem.FireRuinAbilities(state);
Called near the end of StartTurn(), after:
- MP/Defense reset
- Aura re-evaluation
OnTurnStarttriggers
8.2 Full implementation
// 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)
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)
// Effects.cs
public sealed class RelocateRuinEffect : Effect { }
// 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)
// 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
}
// 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)
// Effects.cs — lines 354-357
public sealed class DisableRuinForDurationEffect : Effect
{
public DurationModel Duration = DurationModel.EndOfTurn;
}
// 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:
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)
// 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
// 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)
// 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)
// 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)
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)
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)
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)
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)
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.Sharedor injecting a seededRandominstance. - 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:
tile.RuinDisabledUntilTurn = ctx.State.TurnNumber + disableTurns; // AbilitySystem.cs:3089
FireRuinAbilities skips a Ruin when:
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 — Deep dive into triggered ability execution,
FireTriggerpipeline, condition evaluation, cost payment, and target resolution. Ruin abilities go through the sameExecuteActionspath documented there. - Delta-Sync-flow.md — How
GameStateDelta/TileDeltaare assembled and pushed to clients after every state mutation, including theRuinId/RuinClearedfields documented in §13 above.