Add Ruin-flow.md: end-to-end ruin system reference
Covers data model, channeling flow, FireRuinAbilities activation logic, priority/ordering rules, ruin-specific effects, observer triggers, double-fire guard (6-D), network deltas, and full client handling. 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:
+771
@@ -0,0 +1,771 @@
|
||||
# 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)
|
||||
|
||||
---
|
||||
|
||||
## 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`. |
|
||||
| **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 |
|
||||
Reference in New Issue
Block a user