diff --git a/Delta-Sync-fix-plan.md b/Delta-Sync-fix-plan.md new file mode 100644 index 0000000..d7f3d01 --- /dev/null +++ b/Delta-Sync-fix-plan.md @@ -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>` — 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()` | + +### Changes + +**`Server/src/SOR.Game/SpectatorRegistryService.cs`** — replace storage layer +- Remove `_map: ConcurrentDictionary>` +- 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` 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()` 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 |