Files
sor/Delta-Sync-fix-plan.md
e5cfbae7bd Add Delta-Sync-fix-plan.md: implementation plan for 6 delta-sync bugs
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>
2026-05-20 19:20:04 -04:00

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 by RedisClientPush)
  • 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-expire
    • Unregister(sessionId, accountId) → SREM spectators:{sessionId} {accountId.ToString()}
    • GetSpectators(sessionId) → SMEMBERS spectators:{sessionId}, parse each entry as Guid
    • RemoveSession(sessionId) → DEL spectators:{sessionId}
  • Keep static Instance reference and the IReadOnlySet<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 fooChanged variable in DiffTiles
  • Verify every fooChanged is included in the continue guard 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.Art2dUrl and prevC.ModelUrl != nextC.ModelUrl from the anyChange boolean expression (lines 254-255)
  • Remove Art2dUrl and ModelUrl from the returned UnitDelta constructor (lines 286-287) — pass null for both, or remove the parameters if the record is updated simultaneously

Server/src/SOR.Game/GameMessages.cs — UnitDelta record

  • Remove string? Art2dUrl (line 560) and string? ModelUrl (line 561) from the record
  • CardInstanceDto (used in UnitSnapshot) 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 key modelUrl in 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 the Node3D resource and remove from cache
    • On non-iOS: move entry to a bounded LRU eviction pool (cap at ~20 concurrent models)
  • Add definition-keyed deduplication: key the internal cache by definition_id (from unit dict field cardDefinitionId), not instance_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 accept definition_id so 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": true flag on the unit dict in _apply_delta §2. The mesh builder checks this flag when the unit body becomes visible and triggers the actual ModelCache.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, call ModelCache.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 eliminating modelUrl from UnitSnapshot entirely (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