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>
This commit is contained in:
dingo
2026-05-20 19:20:04 -04:00
co-authored by Claude Happy
parent 47effec8d6
commit e5cfbae7bd
+343
View File
@@ -0,0 +1,343 @@
# 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):
```gdscript
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:
```gdscript
var arch: Dictionary = p.get("archSpirit", {})
if arch.get("instanceId", "") == instance_id:
return arch
```
With:
```gdscript
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:
```gdscript
var arch: Dictionary = player.get("archSpirit", {})
if arch.is_empty():
request_sync()
continue
_merge_unit_delta(arch, arch_delta)
```
With:
```gdscript
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:
```gdscript
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**
```gdscript
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**
```gdscript
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**
```gdscript
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 |