# Delta Sync Flow -- End-to-End Reference This document traces the full lifecycle of a game state delta: from the moment a player action is received on the server, through delta computation, serialisation, transport, and final application on the client. --- ## Table of Contents 1. [Overview](#1-overview-) 2. [Wire Types](#2-wire-types-) 3. [Server -- Action Handler](#3-server----action-handler-) 4. [Server -- State Persistence (SaveStateAsync)](#4-server----state-persistence-savestateasync-) 5. [Server -- Delta Computation (GameStateDiffer)](#5-server----delta-computation-gamestatediffer-) 6. [Server -- Push Decision (PushStateToPlayersAsync)](#6-server----push-decision-pushstatetoplayersasync-) 7. [Transport -- Redis Pub/Sub via IClientPush](#7-transport----redis-pubsub-via-iclientpush-) 8. [Client -- WebSocket Reception (Network.gd)](#8-client----websocket-reception-networkgd-) 9. [Client -- Push Dispatch (Game.gd)](#9-client----push-dispatch-gamegd-) 10. [Client -- Delta Application (_apply_delta)](#10-client----delta-application-applydelta-) 11. [Client -- Unit Merge (_merge_unit_delta)](#11-client----unit-merge-mergeunitdelta-) 12. [Fallback and Resync Paths](#12-fallback-and-resync-paths-) 13. [Design Invariants](#13-design-invariants-) 14. [Fixes Applied](#14-fixes-applied) --- ## 1. Overview ``` Player action (WebSocket request) | v [Handler] load session (FOR UPDATE lock) | capture prevStateJson BEFORE mutation | v [GameEngine] apply action -> newState | v [SaveStateAsync] serialize newState -> DB, commit tx | v [PushStateToPlayersAsync] compute per-viewer deltas | (or fallback to full state) +---> player A delta ---> Redis channel push:{accountA} +---> player B delta ---> Redis channel push:{accountB} +---> spectators ---> full state_update (never delta) | v (gateway subscribes to Redis and forwards) WebSocket push -> client | v [Network.gd] parse JSON, emit message_received signal | v [Game.gd _on_server_push] match game.state_delta | version guard: too old -> drop; gap -> fetch full | v [_apply_delta] 10-section merge loop -> state_updated.emit(state) ``` --- ## 2. Wire Types **File:** `Server/src/SOR.Game/GameMessages.cs` ### Envelope (line 506) ```csharp public sealed record GameStateDeltaPush(GameStateDelta Delta); ``` Sent as the payload of a `game.state_delta` push message. ### GameStateDelta (lines 512-523) ```csharp public sealed record GameStateDelta( int StateVersion, IReadOnlyList? ChangedTiles, IReadOnlyList? UnitsAdded, IReadOnlyList? UnitsRemoved, IReadOnlyList? UnitsChanged, IReadOnlyDictionary? ArchSpiritByAccount, IReadOnlyDictionary? PlayerStatsByAccount, IReadOnlyDictionary? PublicCountsByAccount, PrivateViewerDelta? PrivateByViewer, GameMetaDelta? MetaDelta, IReadOnlyList? ActiveEffects = null); ``` **Sparse pattern:** a `null` collection means no change in that category. `ActiveEffects` is always populated when effects exist -- full replacement, not delta. ### Sub-types | Type | Lines | Description | |---|---|---| | `TileDelta` | 525-536 | Board coord + changed base1/base2/affinity/occupant/ruin. `OccupantCleared` and `RuinCleared` are explicit booleans to distinguish set-to-null from no-change. | | `UnitSnapshot` | 538-540 | Full `CardInstanceDto` with `OwnerAccountId` -- used for newly placed units. | | `UnitDelta` | 542-561 | Partial unit update; nullable fields; `null` = unchanged. `Art2dUrl` and `ModelUrl` were removed — those fields belong only in `UnitSnapshot` (`CardInstanceDto`) and are stable for the lifetime of a card definition. | | `PublicCountsDelta` | 563-566 | Hand/deck/discard counts visible to opponents (not actual cards). | | `ArchSpiritUpdate` | 568-570 | Either a `Full` snapshot or a `Delta` -- server sends full on first sight, delta thereafter. | | `PrivateViewerDelta` | 572-575 | Own hand additions, removals by ID, discard additions. Never sent to opponents. | | `PlayerStatsDelta` | 577-582 | SP, ST, and zone counts per account. | | `GameMetaDelta` | 584-587 | Phase, active player account ID, turn number. | --- ## 3. Server -- Action Handler **Example file:** `Server/src/SOR.Game/Handlers/GameDrawHandler.cs` Every game-action handler follows the same four-step skeleton: ```csharp // GameDrawHandler.cs lines 36-48 var session = await LoadActiveSessionAsync(_gameDb, req.SessionId, actorId, ct); var prevStateJson = session.StateJson!; // <- capture BEFORE mutation var state = GameEngine.Deserialize(prevStateJson); var (newState, _) = GameEngine.Draw(state, actorId); // <- engine returns new object await SaveStateAsync(_gameDb, session, newState, actorId, "game.draw", JsonSerializer.Serialize(req), ct); // <- persist + commit tx await PushStateToPlayersAsync(_clientPush, session, newState, ct, prevStateJson); ``` **Critical ordering:** - `prevStateJson` captured from `session.StateJson` **before** calling `SaveStateAsync`. - `SaveStateAsync` overwrites `session.StateJson` with the new state. - `PushStateToPlayersAsync` receives both snapshots to compute the diff. ### LoadActiveSessionAsync (GameHandlerBase.cs lines 29-61) Begins a PostgreSQL transaction and issues `SELECT ... FOR UPDATE` to serialize concurrent mutations on the same session row. Lock held until `SaveStateAsync` commits. ```csharp var session = await gameDb.GameSessions .FromSqlInterpolated($""" SELECT * FROM game.game_sessions WHERE "Id" = {sessionId} FOR UPDATE """) .SingleOrDefaultAsync(ct); ``` --- ## 4. Server -- State Persistence (SaveStateAsync) **File:** `Server/src/SOR.Game/Handlers/GameHandlerBase.cs`, lines 68-90 ```csharp internal static async Task SaveStateAsync( GameDbContext gameDb, GameSession session, GameState state, string actorId, string actionType, string? payloadJson, CancellationToken ct, string? resultJson = null) { var seqNum = state.NextActionSequence++; // increment; saved JSON reflects consumed number session.StateJson = GameEngine.Serialize(state); session.LastActionAt = DateTimeOffset.UtcNow; gameDb.ActionLogs.Add(new GameActionLog { SequenceNumber = seqNum, ... }); await gameDb.SaveChangesAsync(ct); await gameDb.Database.CommitTransactionAsync(ct); } ``` `state.NextActionSequence` becomes the `StateVersion` carried in deltas -- the client uses this integer to detect gaps. --- ## 5. Server -- Delta Computation (GameStateDiffer) **File:** `Server/src/SOR.Game/GameStateDiffer.cs` ### ComputeDelta -- viewer-specific (line 21) ```csharp public static GameStateDelta ComputeDelta(GameState prev, GameState next, string viewerAccountId) { var changedTiles = DiffTiles(prev, next); var (unitsAdded, unitsRemoved, unitsChanged) = DiffAllFieldUnits(prev, next); // Private data: only this viewer's hand / discard changes PrivateViewerDelta? privateByViewer = null; if (prevViewer != null && nextViewer != null) { var added = nextHandIds.Except(prevHandIds); // hand diff: set operations var removed = prevHandIds.Except(nextHandIds); // discard: append-only via Skip(prevCount) if (handAdded != null || handRemovedIds != null || discardAdded != null) privateByViewer = new PrivateViewerDelta(handAdded, handRemovedIds, discardAdded); } return new GameStateDelta( StateVersion: next.NextActionSequence, ChangedTiles: changedTiles, UnitsAdded: unitsAdded, UnitsRemoved: unitsRemoved, UnitsChanged: unitsChanged, ArchSpiritByAccount: DiffArchByAccount(prev, next), PlayerStatsByAccount: DiffStatsByAccount(prev, next), PublicCountsByAccount: DiffPublicCountsByAccount(prev, next, viewerAccountId), PrivateByViewer: privateByViewer, MetaDelta: DiffMeta(prev, next), ActiveEffects: DiffActiveEffects(next)); } ``` ### ComputeSpectatorDelta (line 82) Same structure but `PrivateByViewer = null` and `viewerAccountId = null` -- spectators see all public counts, no private zone data. ### Diff Helpers | Method | Lines | What it diffs | |---|---|---| | `DiffTiles` | 123-181 | Board tiles; emits `TileDelta` for each coord where base1/base2/affinity/occupant/ruin changed. | | `DiffAllFieldUnits` | 184-229 | Builds prev/next unit maps by `InstanceId` across all players; splits into added/removed/changed. | | `DiffUnit` | 231-288 | Compares individual `CardInstance` fields; returns `null` when nothing changed. | | `DiffPlayerStats` | 290-307 | Compares SP, ST, deck/hand/discard counts; returns `null` when unchanged. | | `DiffArchByAccount` | 309-343 | Per-account ArchSpirit: `Full` snapshot if prev had none, otherwise `Delta` from `DiffUnit`. | | `DiffStatsByAccount` | 345-363 | Calls `DiffPlayerStats` per account; omits null results. | | `DiffPublicCountsByAccount` | 365-392 | Hand/deck/discard counts for players other than the viewer. | | `DiffMeta` | 407-419 | Phase, active player, turn number. | | `DiffActiveEffects` | 112-120 | Always returns the full active-effects list (full replacement, never sparse). | --- ## 6. Server -- Push Decision (PushStateToPlayersAsync) **File:** `Server/src/SOR.Game/Handlers/GameHandlerBase.cs`, lines 291-393 ```csharp internal static async Task PushStateToPlayersAsync( IClientPush clientPush, GameSession session, GameState state, CancellationToken ct, string? prevStateJson = null) { if (prevStateJson != null) { var prevState = GameEngine.Deserialize(prevStateJson); var allIds = GetAllPlayerIds(session); // P1, P2, + any AdditionalPlayers // ActiveEffects excluded from IsEmpty: it is always populated even when empty, // so including it would always trigger the full-state fallback. (line 313) static bool IsEmpty(GameStateDelta d) => d.MetaDelta == null && d.ChangedTiles == null && d.UnitsAdded == null && d.UnitsRemoved == null && d.UnitsChanged == null && d.ArchSpiritByAccount == null && d.PlayerStatsByAccount == null && d.PublicCountsByAccount == null && d.PrivateByViewer == null; // lines 315-317: one viewer-specific delta per player var deltas = allIds.ToDictionary( pid => pid, pid => GameStateDiffer.ComputeDelta(prevState, state, pid)); if (deltas.Values.Any(IsEmpty)) // line 321 -- any player sees no change? { // Fallback: push full game.state_update to everyone foreach (var pid in allIds) tasks.Add(clientPush.PushAsync(pid, ServerMessage.Push("game.state_update", new GameStateUpdatePush(GameEngine.ToDto(state, pid))), ct)); } else { // Happy path: viewer-specific delta to each player (lines 344-346) foreach (var (pid, delta) in deltas) tasks.Add(clientPush.PushAsync(pid, ServerMessage.Push("game.state_delta", new GameStateDeltaPush(delta)), ct)); } // Spectators always receive full public state, never a delta (lines 348-360). // Spectator IDs are fetched from a Redis Set (key: spectators:{sessionId}), // so registration survives pod restarts and cross-pod load balancing. foreach (var specId in spectators) tasks.Add(clientPush.PushAsync(specId.ToString(), ServerMessage.Push("game.state_update", new GameStateUpdatePush(GameEngine.ToDtoSpectator(state))), ct)); await Task.WhenAll(tasks); } else { // No prevStateJson: initial connect / reconnect / timer expiry -> full state } await PushPendingPromptsAsync(clientPush, state, ct); // ability pause prompts } ``` **Decision tree:** ``` prevStateJson present? +-- NO -> full game.state_update to all players +-- YES -> compute per-player deltas any delta IsEmpty? +-- YES -> full game.state_update to all players +-- NO -> game.state_delta (viewer-specific) to each player spectators always -> game.state_update (public DTO, no delta) ``` --- ## 7. Transport -- Redis Pub/Sub via IClientPush **Interface:** `Server/src/SOR.Networking.Abstractions/Push/IClientPush.cs` ```csharp Task PushAsync(string userId, IServerMessage message, CancellationToken ct); ``` **Implementation:** `Server/src/SOR.Networking.Redis/RedisClientPush.cs` - Serialises the `IServerMessage` to bytes via `IMessageSerializer`. - Publishes to Redis channel `push:{userId}`. - The gateway (SOR.Host) subscribes to these channels and forwards bytes over the player's active WebSocket connection. - Best-effort delivery: if the player is disconnected the publish is dropped silently. **Wire JSON format:** ```json { "type": "game.state_delta", "ref": 0, "payload": { "delta": { "stateVersion": 42, "changedTiles": [...], "unitsChanged": [...], "privateByViewer": { "handAdded": [...] }, "metaDelta": { "phase": "combat" }, "activeEffects": [...] } } } ``` `ref: 0` indicates an unsolicited push (not a reply to a client request). --- ## 8. Client -- WebSocket Reception (Network.gd) **File:** `Client/origin-client/autoloads/Network.gd` ```gdscript ## Emitted for server-pushed messages that do not match a pending request. signal message_received(type: String, payload: Variant) # line 35 ``` All incoming WebSocket packets are polled in `_process`. Each packet is parsed as JSON and its `ref` sequence number checked against `_pending` (outstanding requests): ```gdscript # Network.gd lines 283-284 # Not a reply to a known request -- broadcast/push to listeners. message_received.emit(type, payload) ``` Push messages (`ref == 0`) bypass the request-reply correlation table and are broadcast via `message_received` to any connected listener. --- ## 9. Client -- Push Dispatch (Game.gd) **File:** `Client/origin-client/autoloads/Game.gd` ### Subscription (line 109) ```gdscript func _ready() -> void: Network.message_received.connect(_on_server_push) ``` ### Version-guarded dispatch (lines 702-755) ```gdscript func _on_server_push(type: String, payload: Variant) -> void: match type: "game.state_delta": # line 739 var d := payload as Dictionary var delta := d.get("delta", {}) as Dictionary if delta.is_empty(): return var v := int(delta.get("stateVersion", -1)) # Already up to date (acting player got full state in their ACK reply) if _state_version >= 0 and v <= _state_version: # line 744 return # Gap detected: missed one or more deltas if _state_version >= 0 and v > _state_version + 1: # line 747 print("[Game] WARN: missed delta (have %d, got %d) -- requesting full sync" % [_state_version, v]) _fetch_state() # guarded by _syncing flag; at most one in-flight request return _apply_delta(delta) # line 755 -- happy path ``` `_state_version` (line 104) initialised to `-1`; updated on full state receipt (line 727) and after each applied delta (line 669). --- ## 10. Client -- Delta Application (_apply_delta) **File:** `Client/origin-client/autoloads/Game.gd`, lines 512-674 Ten sections processed in order. Each guarded with `is Array` / `is Dictionary` so a missing or null section is safely skipped. ### Section 1 -- Changed Tiles (lines 517-536) ```gdscript var changed_tiles = delta.get("changedTiles") if changed_tiles is Array: var tiles: Array = state.get("board", {}).get("tiles", []) for td: Dictionary in changed_tiles: var tx := int(td.get("x", -1)) var ty := int(td.get("y", -1)) for tile: Dictionary in tiles: if c.get("x") == tx and c.get("y") == ty: if td.has("base1") and td["base1"] != null: tile["base1"] = td["base1"] if td.has("occupantCleared") and bool(td["occupantCleared"]): tile["occupantId"] = null; tile["occupantOwner"] = null elif td.has("occupantId") and td["occupantId"] != null: tile["occupantId"] = td["occupantId"] # ... base2, resolvedAffinity, ruinId, ruinOwner, occupantOwner break ``` `OccupantCleared` and `RuinCleared` booleans handle the set-to-null case that a plain nullable field cannot express. ### Section 2 -- Added Units (lines 538-556) ```gdscript var added_units = delta.get("unitsAdded") if added_units is Array: for add_entry: Dictionary in added_units: var owner_id := str(add_entry.get("ownerAccountId", "")) var unit := add_entry.get("unit", {}) as Dictionary var field: Array = _player_by_id(owner_id).get("field", []) if not exists: # idempotency guard: skip if instanceId already present field.append(unit) ``` ### Section 3 -- Removed Units (lines 558-567) ```gdscript var removed_ids = delta.get("unitsRemoved") if removed_ids is Array: for iid: String in removed_ids: for p: Dictionary in state.get("players", []): var field: Array = p.get("field", []) for i in range(field.size() - 1, -1, -1): if field[i].get("instanceId", "") == iid: field.remove_at(i); break ``` ### Section 4 -- Changed Units (lines 569-576) ```gdscript var changed_units = delta.get("unitsChanged") if changed_units is Array: for ud: Dictionary in changed_units: var iid := str(ud.get("instanceId", "")) var unit := get_unit_by_id(iid) if not unit.is_empty(): _merge_unit_delta(unit, ud) # see Section 11 ``` ### Section 5 -- Private Viewer Data (lines 578-600) ```gdscript var private_delta = delta.get("privateByViewer") if private_delta is Dictionary and not private_delta.is_empty(): # handAdded -> append new cards to own hand # handRemovedIds -> remove by instanceId from own hand # discardAdded -> append to own discard ``` Never present in another player's delta -- the server sets `PrivateByViewer` only for the owning account. ### Section 6 -- Public Counts (lines 602-613) ```gdscript var public_counts = delta.get("publicCountsByAccount") if public_counts is Dictionary: for aid_v in public_counts.keys(): var player := _player_by_id(str(aid_v)) if counts.has("handCount") ...: player["handCount"] = int(counts["handCount"]) if counts.has("deckCount") ...: player["deckCount"] = int(counts["deckCount"]) if counts.has("discardCount") ...: player["discardCount"] = int(counts["discardCount"]) ``` Opponents see card **counts** here; their actual cards are never transmitted. ### Section 7 -- ArchSpirit Updates (lines 615-638) ```gdscript var arch_by_account = delta.get("archSpiritByAccount") if arch_by_account is Dictionary: var full_arch: Variant = arch_update.get("full") if full_arch is Dictionary and not full_arch.is_empty(): player["archSpirit"] = full_arch # full replacement on first sight continue var arch_delta := arch_update.get("delta") as Dictionary if arch.is_empty(): request_sync() # missing baseline -> fetch full state continue _merge_unit_delta(arch, arch_delta) ``` Server sends `Full` on first sight of an arch spirit (e.g. just placed), `Delta` thereafter. ### Section 8 -- Player Stats (lines 640-655) ```gdscript var stats_by_account = delta.get("playerStatsByAccount") if stats_by_account is Dictionary: if stats.has("currentSp") and stats["currentSp"] != null: player["currentSp"] = int(stats["currentSp"]) if stats.has("currentSt") and stats["currentSt"] != null: player["currentSt"] = int(stats["currentSt"]) # also: deckCount, handCount, discardCount ``` ### Section 9 -- Meta (lines 657-662) ```gdscript var meta = delta.get("metaDelta") if meta is Dictionary and not meta.is_empty(): if meta.has("phase") ...: state["phase"] = meta["phase"] if meta.has("activePlayerAccountId") ...: state["activePlayerAccountId"] = ... if meta.has("turnNumber") ...: state["turnNumber"] = int(meta["turnNumber"]) ``` ### Section 10 -- Active Effects (lines 664-667) ```gdscript var active_effects = delta.get("activeEffects") if active_effects is Array: state["activeEffects"] = active_effects # full replacement ``` ### Version Update and Signal (lines 669-674) ```gdscript _state_version = int(delta.get("stateVersion", _state_version)) state_updated.emit(state) # triggers UI rebuild ``` --- ## 11. Client -- Unit Merge (_merge_unit_delta) **File:** `Client/origin-client/autoloads/Game.gd` -- function `_merge_unit_delta` > **Note on line numbers throughout this document:** line references were accurate at > time of writing but drift as code evolves. Prefer the method/symbol name for > navigation; treat line numbers as a starting hint only. Used by sections 4 (field units) and 7 (arch spirits). Merges only non-null fields: ```gdscript func _merge_unit_delta(unit: Dictionary, ud: Dictionary) -> void: if ud.has("currentHealth") and ud["currentHealth"] != null: unit["currentHealth"] = int(ud["currentHealth"]) if ud.has("maxHealth") and ud["maxHealth"] != null: unit["maxHealth"] = int(ud["maxHealth"]) if ud.has("currentDefense") and ud["currentDefense"] != null: unit["currentDefense"] = int(ud["currentDefense"]) if ud.has("maxDefense") and ud["maxDefense"] != null: unit["maxDefense"] = int(ud["maxDefense"]) if ud.has("damage") and ud["damage"] != null: unit["damage"] = int(ud["damage"]) if ud.has("isExhausted") and ud["isExhausted"] != null: unit["isExhausted"] = bool(ud["isExhausted"]) if ud.has("canMove") and ud["canMove"] != null: unit["canMove"] = bool(ud["canMove"]) if ud.has("canAttack") and ud["canAttack"] != null: unit["canAttack"] = bool(ud["canAttack"]) if ud.has("canBeAttacked") and ud["canBeAttacked"] != null: unit["canBeAttacked"] = bool(ud["canBeAttacked"]) if ud.has("canUseAbility") and ud["canUseAbility"] != null: unit["canUseAbility"] = bool(ud["canUseAbility"]) if ud.has("currentMp") and ud["currentMp"] != null: unit["currentMp"] = int(ud["currentMp"]) if ud.has("maxMp") and ud["maxMp"] != null: unit["maxMp"] = int(ud["maxMp"]) if ud.has("extraAttacksRemaining") and ud["extraAttacksRemaining"] != null: unit["extraAttacksRemaining"] = int(ud["extraAttacksRemaining"]) if ud.has("position") and ud["position"] != null: unit["position"] = ud["position"] if ud.has("effectsJson") and ud["effectsJson"] != null: unit["effectsJson"] = ud["effectsJson"] if ud.has("abilitiesJson") and ud["abilitiesJson"] != null: unit["abilitiesJson"] = ud["abilitiesJson"] if ud.has("abilityUsesJson") and ud["abilityUsesJson"] != null: unit["abilityUsesJson"] = ud["abilityUsesJson"] ``` The `ud.has(k) and ud[k] != null` pattern distinguishes JSON `null` (no change) from a missing key. `art2dUrl` and `modelUrl` are **not** merged here — they are stripped from `UnitDelta` on the server and only ever present in the initial `UnitSnapshot` (§2). They are applied once when the unit is added (§10 Section 2) and remain on the unit dict for the session. --- ## 12. Fallback and Resync Paths | Trigger | Behaviour | |---|---| | `prevStateJson == null` passed to handler | Full `game.state_update` pushed to all players (initial connect, reconnect, timer expiry). | | Any player's delta `IsEmpty()` | All players receive full `game.state_update` instead of deltas. In practice this should never fire: every turn-start regenerates MP for all units, meaning every player always has at least one stat change. If it does fire it indicates a diff bug, not a valid "no change" case. | | Spectator | Always receives full `game.state_update` (public DTO, no private data, no delta). | | Client: `v <= _state_version` | Delta dropped — acting player already received the new state in their ACK reply. | | Client: `v > _state_version + 1` | Gap in sequence — client calls `_fetch_state()`. A `_syncing` flag prevents multiple concurrent requests; subsequent gaps while a sync is in-flight are no-ops. `_apply_state_from_payload` validates the response `sessionId` before applying, discarding stale responses from a previous session. | | Client: arch spirit `null` or missing baseline | `archSpirit` key may exist with a `null` value (player disconnect). An `is Dictionary` guard detects this; missing baseline triggers `request_sync()` for full-state recovery. | --- ## 13. Design Invariants 1. **`prevStateJson` must be captured before `SaveStateAsync`.** Breaking this produces an empty diff (state compared to itself). 2. **`StateVersion` == `state.NextActionSequence` at time of push.** Incremented inside `SaveStateAsync` before serialisation, so the value baked into the delta exactly matches what is stored in the DB. 3. **`ActiveEffects` is always a full replacement, never sparse.** Comment at `GameStateDiffer.cs:109`: the collection is small, ordering matters, and partial diffs of effect lists would be error-prone. 4. **`PrivateByViewer` is viewer-exclusive.** `ComputeDelta` is called once per player with that player's account ID. Each player's delta contains only their own private zone data. 5. **Spectators never receive deltas.** `ComputeSpectatorDelta` exists but `PushStateToPlayersAsync` always pushes a full `game.state_update` to spectators (lines 348-360). 6. **FOR UPDATE lock serialises concurrent mutations.** All action handlers call `LoadActiveSessionAsync` which opens a transaction and locks the session row. Concurrent requests for the same session queue up in PostgreSQL. 7. **IsEmpty check excludes `ActiveEffects`.** Comment at `GameHandlerBase.cs:313`: `ActiveEffects` is always populated (even when it is an empty list), so including it in the emptiness check would always trigger the full-state fallback. --- ## 14. Fixes Applied All six issues identified in the original audit have been implemented and committed. --- ### Fix 1 — Spectator registry moved to Redis (commit `14a467d`) **Was:** `SpectatorRegistryService` held an in-memory `ConcurrentDictionary` per server pod. In a load-balanced deployment, `game.spectate` could land on pod A while the next action landed on pod B — pod B's registry was empty, so spectator pushes were silently skipped. **Now:** `SpectatorRegistryService` uses Redis Sets (`spectators:{sessionId}`). `RegisterAsync` → `SADD` with a 24-hour TTL; `UnregisterAsync` → `SREM`; `GetSpectatorsAsync` → `SMEMBERS`; `RemoveSessionAsync` → `DEL`. Spectator registration is now shared across all pods. **Files changed:** `SOR.Game/SpectatorRegistryService.cs`, `SOR.Shared/Redis/RedisKeys.cs`, `SOR.Game/Handlers/GameHandlerBase.cs`, `GameSpectateHandler.cs`, `GameStopSpectatingHandler.cs` --- ### Fix 2 — Null arch spirit guard in `get_unit_by_id` and `_apply_delta §7` (commit `e7bf257`) **Was:** `p.get("archSpirit", {})` returns `null` (not `{}`) when the key exists with a `null` value (server clears it on player disconnect). Calling `.get(...)` on `null` crashed: `Invalid call. Nonexistent function 'get' in base 'Nil'`. **Now:** Both sites use the safe pattern: ```gdscript var arch_val: Variant = p.get("archSpirit") if arch_val is Dictionary and not (arch_val as Dictionary).is_empty(): ... ``` **File changed:** `Client/origin-client/autoloads/Game.gd` --- ### Fix 3 — `DiffTiles` guard confirmed complete (commit `e7bf257`) **Was:** Concern that `ChangedTiles` might include unchanged tiles in some paths. **Audit result:** The no-change guard at `GameStateDiffer.cs:159-161` is complete for all fields present in `TileDelta`. `RuinDisabledUntilTurn` is intentionally absent from `TileDelta` (it is a server-side scheduler value, not a client-visible state field). No code change needed. --- ### Fix 4 — `modelUrl` / `art2dUrl` stripped from `UnitDelta` (commit `93e3c8b`) **Was:** `UnitDelta` included `Art2dUrl` and `ModelUrl` on every unit update. These CDN URLs are fixed for the lifetime of a card definition and were wasteful to repeat. The client had a multi-casing fallback (`modelUrl`, `ModelUrl`, `modelurl`, etc.) as evidence of the inconsistency. **Now:** - `UnitDelta` record has no URL fields. URLs are only in `UnitSnapshot` (`CardInstanceDto`), delivered once when the unit is first added. - `DiffUnit` no longer compares or emits `Art2dUrl` / `ModelUrl`. - `_merge_unit_delta` no longer applies URL fields from deltas. - `modelUrl` and `art2dUrl` are set once on the unit dict in the `unitsAdded` path and remain there for the session. **Files changed:** `SOR.Game/GameMessages.cs`, `SOR.Game/GameStateDiffer.cs`, `Client/origin-client/autoloads/Game.gd` --- ### Fix 5 — iOS Safari scoped asset loading (commit `c8c3666`) **Was:** All 3D models were loaded and retained indefinitely. On iOS Safari (~300 MB per-tab limit) this caused tab crashes as more distinct cards appeared over a game. **Now:** - **`Platform.gd`** (new autoload): `Platform.is_ios_safari()` detects iPhone/iPad Safari via `JavaScriptBridge.eval("navigator.userAgent")`, excluding Chrome/CriOS. - **`ModelCache.release_model(url, etag)`**: on iOS Safari, removes the `PackedScene` from the in-memory `_mem` dict when a unit leaves the board. Disk cache is preserved for fast reload if the same card type reappears. No-op on all other platforms. - **`unit_mesh_builder.gd`**: stores the resolved `model_url`/`model_etag` per unit in `_unit_model_urls` / `_unit_model_etags`. In the `to_remove` loop, calls `ModelCache.release_model` before pooling or freeing each unit. - **`ContentCache.get_model_url_for_definition(definition_id)`**: stub for looking up a card's `Model3D` CDN URL from the definition cache without a live unit dict — foundation for future eviction paths that do not require a fully loaded unit. **Files changed:** `Client/origin-client/autoloads/Platform.gd` (new), `Client/origin-client/autoloads/ModelCache.gd`, `Client/origin-client/autoloads/ContentCache.gd`, `Client/origin-client/scenes/game/components/units/unit_mesh_builder.gd`, `Client/origin-client/project.godot` --- ### Fix 6 — `_fetch_state` race: `_syncing` guard and session-id validation (commit `7e22d87`) **Was:** `_fetch_state()` had no in-flight guard. On poor connections, multiple consecutive deltas with gaps triggered concurrent `game.get_state` requests. `_apply_state_from_payload` had no session-id check, so a stale response in-flight from a previous session could overwrite state for a new game. **Now:** - `var _syncing: bool = false` added to state vars; reset in `_clear_state()`. - `_fetch_state()` returns immediately if `_syncing` is `true`; sets it to `true` before the request; clears it in both the success and error callbacks. - `_apply_state_from_payload()` validates `s.get("sessionId")` against the current `session_id` before applying state. Mismatched responses are silently discarded. **File changed:** `Client/origin-client/autoloads/Game.gd`