- Issue 1: SpectatorRegistryService is in-memory per-process; spectators
miss updates in scaled deployments due to load-balancer routing mismatch.
Fix: move registry to Redis.
- Issue 2: get_unit_by_id null crash when arch is null (not absent) on
player disconnect. Fix: use 'is Dictionary' guard instead of .get({}).
- Issue 3: ChangedTiles must only include actually-changed tiles; fix is
server-side only.
- Issue 4: modelUrl/art2dUrl sent in every UnitDelta; strip from delta,
derive from card definition; iOS Safari: cache on first sight.
- Issue 5: iOS Safari memory crash from unbounded asset cache; layered
fix: scoped loading, lazy load, disk cache for non-iOS, evict on removal.
- Issue 6: _fetch_state() race on version gap; fix with _syncing flag.
- §12: clarified IsEmpty should never fire in practice (MP always regenerates).
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>
33 KiB
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
- Overview
- Wire Types
- Server -- Action Handler
- Server -- State Persistence (SaveStateAsync)
- Server -- Delta Computation (GameStateDiffer)
- Server -- Push Decision (PushStateToPlayersAsync)
- Transport -- Redis Pub/Sub via IClientPush
- Client -- WebSocket Reception (Network.gd)
- Client -- Push Dispatch (Game.gd)
- Client -- Delta Application (_apply_delta)
- Client -- Unit Merge (_merge_unit_delta)
- Fallback and Resync Paths
- Design Invariants
- Known Issues & Planned Fixes
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)
public sealed record GameStateDeltaPush(GameStateDelta Delta);
Sent as the payload of a game.state_delta push message.
GameStateDelta (lines 512-523)
public sealed record GameStateDelta(
int StateVersion,
IReadOnlyList<TileDelta>? ChangedTiles,
IReadOnlyList<UnitSnapshot>? UnitsAdded,
IReadOnlyList<string>? UnitsRemoved,
IReadOnlyList<UnitDelta>? UnitsChanged,
IReadOnlyDictionary<string, ArchSpiritUpdate>? ArchSpiritByAccount,
IReadOnlyDictionary<string, PlayerStatsDelta>? PlayerStatsByAccount,
IReadOnlyDictionary<string, PublicCountsDelta>? PublicCountsByAccount,
PrivateViewerDelta? PrivateByViewer,
GameMetaDelta? MetaDelta,
IReadOnlyList<ActiveEffectDto>? 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. |
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:
// 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:
prevStateJsoncaptured fromsession.StateJsonbefore callingSaveStateAsync.SaveStateAsyncoverwritessession.StateJsonwith the new state.PushStateToPlayersAsyncreceives 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.
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
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)
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
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)
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
Task PushAsync(string userId, IServerMessage message, CancellationToken ct);
Implementation: Server/src/SOR.Networking.Redis/RedisClientPush.cs
- Serialises the
IServerMessageto bytes viaIMessageSerializer. - 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:
{
"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
## 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):
# 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)
func _ready() -> void:
Network.message_received.connect(_on_server_push)
Version-guarded dispatch (lines 702-755)
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() # sends game.get_state request to server
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
var active_effects = delta.get("activeEffects")
if active_effects is Array:
state["activeEffects"] = active_effects # full replacement
Version Update and Signal (lines 669-674)
_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:
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"]
# art2dUrl / Art2dUrl and modelUrl / ModelUrl / modelurl all checked (capitalisation guard)
if ud.has("art2dUrl") and ud["art2dUrl"] != null: unit["art2dUrl"] = ud["art2dUrl"]
if ud.has("modelUrl") and ud["modelUrl"] != null: unit["modelUrl"] = ud["modelUrl"]
The ud.has(k) and ud[k] != null pattern distinguishes JSON null (no change) from a missing key.
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() which sends game.get_state; server replies with full state. |
Client: arch spirit is_empty() |
Missing baseline -- client calls request_sync() for the same full-state recovery. |
13. Design Invariants
-
prevStateJsonmust be captured beforeSaveStateAsync. Breaking this produces an empty diff (state compared to itself). -
StateVersion==state.NextActionSequenceat time of push. Incremented insideSaveStateAsyncbefore serialisation, so the value baked into the delta exactly matches what is stored in the DB. -
ActiveEffectsis always a full replacement, never sparse. Comment atGameStateDiffer.cs:109: the collection is small, ordering matters, and partial diffs of effect lists would be error-prone. -
PrivateByVieweris viewer-exclusive.ComputeDeltais called once per player with that player's account ID. Each player's delta contains only their own private zone data. -
Spectators never receive deltas.
ComputeSpectatorDeltaexists butPushStateToPlayersAsyncalways pushes a fullgame.state_updateto spectators (lines 348-360). -
FOR UPDATE lock serialises concurrent mutations. All action handlers call
LoadActiveSessionAsyncwhich opens a transaction and locks the session row. Concurrent requests for the same session queue up in PostgreSQL. -
IsEmpty check excludes
ActiveEffects. Comment atGameHandlerBase.cs:313:ActiveEffectsis always populated (even when it is an empty list), so including it in the emptiness check would always trigger the full-state fallback.
14. Known Issues & Planned Fixes
Issue 1 — Spectators miss updates: SpectatorRegistryService is in-memory per process (High)
Root cause: SpectatorRegistryService (SpectatorRegistryService.cs:11) is registered as an in-memory singleton with a static Instance reference set in its constructor. Action handlers access it via SpectatorRegistryService.Instance (a static field).
In a horizontally scaled deployment (multiple server pods / load balancer), a spectator's game.spectate request is handled by pod A, which registers them in pod A's in-memory map. The next game action may be routed to pod B — pod B's SpectatorRegistryService has an empty map. GetSpectators(sessionId) returns empty, the spectator push is silently skipped. Only when the load balancer happens to route both the game.spectate and the subsequent action to the same pod does the spectator receive updates — explaining why leaving and rejoining several times eventually "works".
Additionally, even within a single pod: Instance is only set when the DI container first resolves SpectatorRegistryService, which happens lazily on the first request to GameSpectateHandler. If no spectator has ever called game.spectate since the pod started, Instance is null and PushStateToPlayersAsync silently skips the if (registry != null) guard.
Planned fix: Move spectator registration into Redis (the same pub/sub layer already used for player pushes). Replace the in-memory _map with a Redis set keyed by spectators:{sessionId}. Register/Unregister become SADD/SREM; GetSpectators becomes SMEMBERS. This makes spectator state shared across all pods with no per-process affinity requirement.
Issue 2 — get_unit_by_id crashes when a player's arch spirit is null on disconnect (High)
Root cause: Game.gd — get_unit_by_id
var arch: Dictionary = p.get("archSpirit", {})
if arch.get("instanceId", "") == instance_id:
return arch
In GDScript, Dictionary.get(key, default) returns the default only when the key is absent. If the key exists with a null value — which happens when a player leaves and their arch spirit is cleared — p.get("archSpirit", {}) returns null. The following .get("instanceId", "") call on null crashes: Invalid call. Nonexistent function 'get' in base 'Nil'.
Planned fix:
var arch_val: Variant = p.get("archSpirit")
if arch_val is Dictionary and not arch_val.is_empty():
if arch_val.get("instanceId", "") == instance_id:
return arch_val
This pattern should be applied everywhere in the client that reads a dict value that could be null rather than absent (i.e. dict.get(key) followed by an is Dictionary guard, not dict.get(key, {})).
Issue 3 — ChangedTiles should only contain tiles that actually changed (Medium)
Location: GameStateDiffer.cs — DiffTiles
The delta's ChangedTiles array must only include tiles where at least one field (base1, base2, resolvedAffinity, occupantId, ruinId, etc.) actually differs between prev and next. Sending unchanged tiles wastes bandwidth and forces the client to process unnecessary entries.
Verify that DiffTiles performs a field-by-field equality check before emitting a TileDelta, and emits null (no entry) for unchanged tiles. If any path exists where all tiles are included unconditionally, that is the bug. The fix is entirely server-side — the client already applies only what it receives; no client changes are needed.
Issue 4 — modelUrl / art2dUrl sent in UnitDelta on every unit change (Low / Bandwidth)
Location: GameStateDiffer.cs — DiffUnit, _merge_unit_delta lines 571-572
modelUrl and art2dUrl are CDN URL strings that are fixed for the lifetime of a card definition. They are set once when the unit is first added (via UnitSnapshot in UnitsAdded). Sending them again in every subsequent UnitDelta is pure waste. The casing inconsistency (art2dUrl, Art2dUrl, modelUrl, ModelUrl, modelurl all checked on the client) also indicates the server is not emitting these consistently.
Planned fix:
- Strip
modelUrlandart2dUrlfromUnitDeltaentirely. They should only ever appear in the initialUnitSnapshot. - Longer term: derive asset URLs from the card definition stored on the client (each card's
definitionIdis already in the unit snapshot). The client card catalog holds the canonical URLs, so no URL transmission is needed at all. - iOS Safari exception: because iOS Safari applies strict per-origin memory limits, asset URLs should be sent once on first sight (via
UnitSnapshot) and held in a scoped cache keyed bydefinitionId. Subsequent units using the same definition reuse the cached URL rather than re-fetching. See Issue 5 for the broader iOS memory strategy.
Issue 5 — iOS Safari crashes from unbounded asset cache (High / Mobile)
iOS Safari enforces a hard per-tab memory ceiling (~300 MB). The client currently loads and retains all card art, 3D models, and assets as the game progresses, never evicting them. As more distinct cards are seen, memory climbs until the tab is killed.
Planned fix (layered):
-
Detect iOS Safari via
OS.get_name() == "Web"plus a user-agent check for Safari on iOS. Apply a separate asset management path for this client. -
Scope asset loading to visible scene only. Only load model/art assets for cards currently on the board or in the local player's hand. Unload assets when cards leave these zones (moved to discard, removed, etc.).
-
Lazy load on demand. Trigger asset loads when a unit enters the viewport, not on game-state receipt. Cards in hand that are not being hovered or inspected do not need their 3D model resident.
-
Disk cache for non-iOS clients. Desktop browsers and Android Chrome support the Cache API and IndexedDB with generous quotas — use these to persist card assets across sessions. Scope this to non-iOS Safari only; Safari's IndexedDB quota is small and unreliable.
-
Drop invisible assets. When a unit is removed from the board (captured, discarded) and is not in hand, release its model and art resources immediately rather than waiting for scene transition.
Issue 6 — _fetch_state() race: multiple concurrent full-sync requests on version gap (Low)
Location: Game.gd — version gap handler
if _state_version >= 0 and v > _state_version + 1:
_fetch_state()
return
There is no in-flight guard. On poor connections, multiple consecutive deltas can arrive with gaps, triggering multiple _fetch_state() calls simultaneously. Each causes a full state response; the last one wins, but the intermediate responses can briefly corrupt _state_version.
Planned fix: Add var _syncing: bool = false. Check if _syncing: return at the top of the gap branch. Set _syncing = true before _fetch_state(). Reset to false in the game.state_update handler after applying the full state.