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:
@@ -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 |
|
||||
Reference in New Issue
Block a user