Fix 1: SpectatorRegistryService → Redis sets (SADD/SREM/SMEMBERS/DEL) Fix 2: get_unit_by_id null crash → is Dictionary guard pattern Fix 3: Audit DiffTiles no-change guard completeness (server verify) Fix 4: Strip modelUrl/art2dUrl from UnitDelta record and DiffUnit Fix 5: iOS Safari scoped asset loading, ModelCache eviction, lazy load Fix 6: _fetch_state race → _syncing flag + session-id guard in _apply_state_from_payload Includes per-fix root cause table, exact file/class/line, code before/after, execution order rationale, and full files-changed summary. 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>
16 KiB
Delta-Sync Fix Plan
All six bugs from Delta-Sync-flow.md §14. Lists every file, class, method,
and exact change for each fix. No code is changed here — this is the plan only.
Fix 1 — Spectator registry must survive cross-pod routing
Problem
SpectatorRegistryService holds an in-memory ConcurrentDictionary per process.
In a load-balanced deployment, game.spectate lands on pod A (registers there) but the
next game action lands on pod B (empty map → spectator push silently skipped).
The "leave and rejoin several times" symptom is load-balancer roulette until both
requests happen to hit the same pod.
Root cause
| File | Class | Line | Detail |
|---|---|---|---|
Server/src/SOR.Game/SpectatorRegistryService.cs |
SpectatorRegistryService |
19 | _map: ConcurrentDictionary<Guid, ImmutableHashSet<Guid>> — in-memory, not shared |
SpectatorRegistryService.cs |
SpectatorRegistryService |
26-40 | All four methods operate on _map only |
Server/src/SOR.Game/ServiceRegistration.cs |
DI setup | 36 | services.AddSingleton<SpectatorRegistryService>() |
Changes
Server/src/SOR.Game/SpectatorRegistryService.cs — replace storage layer
- Remove
_map: ConcurrentDictionary<Guid, ImmutableHashSet<Guid>> - Inject
IConnectionMultiplexer _redis(same interface already used byRedisClientPush) - Rewrite all four methods using Redis set commands against key
spectators:{sessionId}:Register(sessionId, accountId)→SADD spectators:{sessionId} {accountId.ToString()}— add a TTL matching the maximum session lifetime so keys self-expireUnregister(sessionId, accountId)→SREM spectators:{sessionId} {accountId.ToString()}GetSpectators(sessionId)→SMEMBERS spectators:{sessionId}, parse each entry asGuidRemoveSession(sessionId)→DEL spectators:{sessionId}
- Keep
static Instancereference and theIReadOnlySet<Guid>return type — all callers unchanged
Server/src/SOR.Networking.Redis/RedisKeys.cs (or wherever push-channel constants live)
- Add
public static string SpectatorSetKey(Guid sessionId) => $"spectators:{sessionId}";
Server/src/SOR.Game/ServiceRegistration.cs — no change
IConnectionMultiplexer is already registered for RedisClientPush; AddSingleton<SpectatorRegistryService>() stays.
GameSpectateHandler.cs — no change (calls _registry.Register — same signature)
GameStopSpectatingHandler.cs — no change (calls _registry.Unregister — same signature)
GameHandlerBase.cs — no change (calls registry.GetSpectators / RemoveSession via static Instance — same signatures)
Fix 2 — get_unit_by_id crash when arch spirit is null-valued
Problem
GDScript dict.get(key, fallback) only returns fallback when the key is absent.
When p["archSpirit"] exists but holds null (explicitly set by server when a player
disconnects), p.get("archSpirit", {}) returns null, not {}. Any method call on
that null immediately crashes: Invalid call. Nonexistent function 'get' in base 'Nil'.
Root cause
| File | Function | Line | Bad pattern |
|---|---|---|---|
Client/origin-client/autoloads/Game.gd |
get_unit_by_id |
~276 | var arch: Dictionary = p.get("archSpirit", {}) → arch.get(...) crashes if null |
Client/origin-client/autoloads/Game.gd |
_apply_delta §7 |
~633 | var arch: Dictionary = player.get("archSpirit", {}) → arch.is_empty() crashes if null |
The safe pattern already used correctly in get_all_enemy_units (~line 254):
var arch = p.get("archSpirit")
if arch is Dictionary and not (arch as Dictionary).is_empty():
Changes
Client/origin-client/autoloads/Game.gd — get_unit_by_id (~line 276)
Replace:
var arch: Dictionary = p.get("archSpirit", {})
if arch.get("instanceId", "") == instance_id:
return arch
With:
var arch_val: Variant = p.get("archSpirit")
if arch_val is Dictionary and not (arch_val as Dictionary).is_empty():
if (arch_val as Dictionary).get("instanceId", "") == instance_id:
return arch_val
Client/origin-client/autoloads/Game.gd — _apply_delta §7 arch update (~line 633)
Replace:
var arch: Dictionary = player.get("archSpirit", {})
if arch.is_empty():
request_sync()
continue
_merge_unit_delta(arch, arch_delta)
With:
var arch_val: Variant = player.get("archSpirit")
if arch_val == null or not (arch_val is Dictionary):
request_sync()
continue
var arch := arch_val as Dictionary
if arch.is_empty():
request_sync()
continue
_merge_unit_delta(arch, arch_delta)
Audit pass on Game.gd — search for every other p.get( / player.get( / state.get(
call where the return value is immediately typed as Dictionary and a method is called on it
without a null/type guard. Apply the is Dictionary pattern to each. There may be other
crash sites beyond lines 276 and 633.
Fix 3 — Confirm ChangedTiles only sends changed tiles (server verification)
Problem
User reported receiving more tile data than expected. Bandwidth analysis showed the delta may be including unchanged tiles in some paths.
Root cause
| File | Method | Lines | What to verify |
|---|---|---|---|
Server/src/SOR.Game/GameStateDiffer.cs |
DiffTiles |
152-161 | No-change guard: if (!base1Changed && !base2Changed && !occupantChanged && !occOwnerChanged && !ruinChanged && !ruinOwnerChanged) continue; |
The guard at line 161 is correct for the fields that existed when it was written, but may be
incomplete if new fields have been added to TileDelta since then (e.g. RuinDisabledUntilTurn).
Changes
Server/src/SOR.Game/GameStateDiffer.cs — DiffTiles — audit the no-change guard
- List every field present in
TileDelta(GameMessages.cs:525-536) - Verify each field has a corresponding
bool fooChangedvariable inDiffTiles - Verify every
fooChangedis included in thecontinueguard condition - If any field is missing from the guard, add it — this is the source of spurious tile entries
No client changes needed. The client only iterates tiles it receives. If the server sends only genuinely-changed tiles, the client loop is bounded to that set. No client-side lookup optimization is needed.
Fix 4 — Remove modelUrl / art2dUrl from UnitDelta
Problem
modelUrl and art2dUrl are CDN URLs fixed for the lifetime of a card definition.
They are already sent in the initial UnitSnapshot (full add). Including them in every
subsequent UnitDelta wastes bandwidth. A multi-key casing fallback on the client
(modelUrl, ModelUrl, modelurl, etc.) is evidence of past inconsistency.
Root cause
| File | Location | Line | Detail |
|---|---|---|---|
Server/src/SOR.Game/GameStateDiffer.cs |
DiffUnit — change detection |
254-255 | prevC.Art2dUrl != nextC.Art2dUrl and prevC.ModelUrl != nextC.ModelUrl in anyChange block |
Server/src/SOR.Game/GameStateDiffer.cs |
DiffUnit — delta emission |
286-287 | Art2dUrl: ... ? nextC.Art2dUrl : null and ModelUrl: ... ? nextC.ModelUrl : null |
Server/src/SOR.Game/GameMessages.cs |
UnitDelta record |
560-561 | string? Art2dUrl and string? ModelUrl fields |
Client/origin-client/autoloads/Game.gd |
_merge_unit_delta |
~695, ~697 | Applies art2dUrl and modelUrl from delta to unit dict |
Changes
Server/src/SOR.Game/GameStateDiffer.cs — DiffUnit
- Remove
prevC.Art2dUrl != nextC.Art2dUrlandprevC.ModelUrl != nextC.ModelUrlfrom theanyChangeboolean expression (lines 254-255) - Remove
Art2dUrlandModelUrlfrom the returnedUnitDeltaconstructor (lines 286-287) — passnullfor both, or remove the parameters if the record is updated simultaneously
Server/src/SOR.Game/GameMessages.cs — UnitDelta record
- Remove
string? Art2dUrl(line 560) andstring? ModelUrl(line 561) from the record CardInstanceDto(used inUnitSnapshot) retains both fields — initial placement still delivers URLs to clients
Client/origin-client/autoloads/Game.gd — _merge_unit_delta
- Remove the two lines:
if ud.has("art2dUrl") and ud["art2dUrl"] != null: unit["art2dUrl"] = ud["art2dUrl"] if ud.has("modelUrl") and ud["modelUrl"] != null: unit["modelUrl"] = ud["modelUrl"] - URLs on the unit dict are set once in
unitsAdded(§2 of_apply_delta) and stay put
Client/origin-client/scenes/game/components/units/unit_mesh_builder.gd
- No immediate change. The multi-key lookup (
modelUrl,ModelUrl,model_url,modelurl) can be narrowed to a single canonical keymodelUrlin a follow-up cleanup once the server has consistently used only camelCase for a release cycle.
iOS Safari caveat
UnitSnapshot (CardInstanceDto) still includes modelUrl and art2dUrl, so initial
model loading on unit placement is unaffected. The per-definition caching strategy for iOS
Safari memory management is part of Fix 5.
Fix 5 — iOS Safari: scoped asset loading and memory management
Problem
iOS Safari kills browser tabs exceeding ~300 MB. The client loads and retains all card art and 3D models indefinitely as units are placed. No assets are evicted when units leave the board. As distinct cards accumulate, memory climbs until the tab crashes.
Root cause
| File | Area | Line | Detail |
|---|---|---|---|
Client/origin-client/scenes/game/components/units/unit_mesh_builder.gd |
ModelCache.load_model(...) |
~365 | Model loaded on unit add; never evicted |
Client/origin-client/autoloads/Game.gd |
_apply_delta §2 (unitsAdded) |
~538-556 | Unit appended with URL in dict; model load triggered; no cleanup path |
Client/origin-client/autoloads/ContentCache.gd |
Definition cache | — | No eviction policy |
Changes
New: Client/origin-client/autoloads/Platform.gd (new autoload, or add to existing utility autoload)
static func is_ios_safari() -> bool:OS.get_name() == "Web"AND user-agent contains"Safari"AND ("iPhone"OR"iPad") AND does NOT contain"Chrome"or"CriOS"- Gate for all iOS-specific memory paths
ModelCache (wherever ModelCache.load_model is defined — locate the file)
- Add
release_model(instance_id: String):- On iOS Safari (
Platform.is_ios_safari()): immediately free / queue_free theNode3Dresource and remove from cache - On non-iOS: move entry to a bounded LRU eviction pool (cap at ~20 concurrent models)
- On iOS Safari (
- Add definition-keyed deduplication: key the internal cache by
definition_id(from unit dict fieldcardDefinitionId), notinstance_id. Multiple units of the same card type (e.g. Spirit tokens) share one loaded resource. When all instances of a definition are removed from the board, the shared resource can be evicted. - Rename
load_model(url, callback, etag)to also acceptdefinition_idso the cache key can be set correctly without waiting for the model to load.
Client/origin-client/scenes/game/components/units/unit_mesh_builder.gd
- On iOS Safari: defer model load until the unit enters the viewport (lazy load). Set a
"modelPending": trueflag on the unit dict in_apply_delta §2. The mesh builder checks this flag when the unit body becomes visible and triggers the actualModelCache.load_model. - On non-iOS: existing eager-load behaviour unchanged.
- Add a call to
ModelCache.release_model(instance_id)when a unit's mesh node is freed / removed from the scene.
Client/origin-client/autoloads/Game.gd — _apply_delta §3 (unitsRemoved)
- After removing a unit from
player.field, callModelCache.release_model(iid)so the 3D asset is eligible for eviction
Client/origin-client/autoloads/ContentCache.gd
- Add stub
get_model_url_for_definition(definition_id: String) -> String— returns URL from the locally cached card definition if available. This is the foundation for eventually eliminatingmodelUrlfromUnitSnapshotentirely (future work, not this fix).
Scope
Client-only. No server changes. Prerequisite: Fix 4 (strip URLs from UnitDelta) should
land first to reduce per-action payload before the iOS memory work begins.
Fix 6 — _fetch_state race: multiple concurrent full-sync requests
Problem
When a version gap is detected in _on_server_push, _fetch_state() is called with no
in-flight guard. On poor connections or reconnect bursts, multiple gaps trigger multiple
concurrent game.get_state requests. Additionally, _apply_state_from_payload has no
session-id validation, allowing a stale response (in-flight when the session ends) to
overwrite state for a new session.
Root cause
| File | Function | Line | Issue |
|---|---|---|---|
Client/origin-client/autoloads/Game.gd |
_on_server_push — gap branch |
~751 | _fetch_state() called with no in-flight guard |
Client/origin-client/autoloads/Game.gd |
_fetch_state |
~313 | No _syncing flag; no session-id capture |
Client/origin-client/autoloads/Game.gd |
_apply_state_from_payload |
~479 | No session-id validation before applying received state |
Changes
Client/origin-client/autoloads/Game.gd — add _syncing member variable
var _syncing: bool = false # true while a game.get_state request is in-flight
Reset to false in _clear_state() alongside _state_version = -1.
_fetch_state() — add guard and track in-flight state
func _fetch_state() -> void:
if _syncing:
return
_syncing = true
Network.request("game.get_state",
{ "sessionId": session_id },
func(_t: String, p: Variant) -> void:
_syncing = false
_apply_state_from_payload(p),
func(_c: String, _m: String) -> void:
_syncing = false)
_apply_state_from_payload() — add session-id guard at top
func _apply_state_from_payload(p: Variant) -> void:
var d := p as Dictionary
var s := d.get("state", {}) as Dictionary
if s.is_empty():
return
# Ignore responses for sessions we have already left
var response_sid: String = str(s.get("sessionId", ""))
if not session_id.is_empty() and not response_sid.is_empty() \
and response_sid != session_id:
return
_state_version = int(s.get("stateVersion", -1))
state = s
state_updated.emit(state)
_on_server_push — gap detection — no change needed; the guard is now inside _fetch_state.
Execution Order
| Step | Fix | Reason |
|---|---|---|
| 1 | Fix 2 — null crash | Active crash; two targeted guard changes; zero risk |
| 2 | Fix 6 — _syncing flag |
Active client instability; contained to Game.gd |
| 3 | Fix 3 — verify DiffTiles |
Read-only audit; gate before other server changes |
| 4 | Fix 4 — strip modelUrl/art2dUrl from UnitDelta |
Server + client; reduces payload |
| 5 | Fix 1 — Redis spectator registry | Server infra change; needs staging deploy + test |
| 6 | Fix 5 — iOS Safari memory | Largest scope; depends on Fix 4 landing first |
Files Changed Summary
Server (C#)
| File | What changes |
|---|---|
SOR.Game/SpectatorRegistryService.cs |
Replace ConcurrentDictionary with Redis set operations (SADD, SREM, SMEMBERS, DEL) |
SOR.Networking.Redis/RedisKeys.cs |
Add SpectatorSetKey(Guid sessionId) constant |
SOR.Game/GameStateDiffer.cs |
Remove Art2dUrl/ModelUrl from DiffUnit change detection (lines 254-255) and emission (lines 286-287); audit DiffTiles guard completeness |
SOR.Game/GameMessages.cs |
Remove string? Art2dUrl and string? ModelUrl from UnitDelta record (lines 560-561) |
Client (GDScript)
| File | What changes |
|---|---|
autoloads/Game.gd |
Fix get_unit_by_id null guard (~276); fix _apply_delta §7 null guard (~633); add _syncing flag; add session-id guard in _apply_state_from_payload; remove art2dUrl/modelUrl from _merge_unit_delta; call ModelCache.release_model in _apply_delta §3 |
autoloads/Platform.gd |
New (or extend): is_ios_safari() -> bool detection helper |
autoloads/ContentCache.gd |
Add get_model_url_for_definition(definition_id) stub |
scenes/game/components/units/unit_mesh_builder.gd |
Hook model eviction on unit removal; lazy-load on iOS Safari; call ModelCache.release_model on mesh free |
ModelCache (locate file) |
Add release_model(instance_id); definition-keyed deduplication; LRU pool on non-iOS; immediate eviction on iOS Safari |