Add iOS Safari memory crash fix draft v2
Patches all 8 gaps from code review: CONNECT_ONE_SHOT replaces no-op signal clear, evict_all flushes pending callbacks, disk-cache hits queue correctly without re-downloading, pool reset covers transform/meta/groups, pool size is capped, instrumentation added, _exit_tree cleanup added to unit_mesh_builder for both tweens and pool nodes. 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,517 @@
|
||||
# iOS Safari Memory Crash - Fix Draft v2
|
||||
|
||||
**Status:** Draft v2 — addresses 8 review gaps from v1. Code not yet applied to any existing files.
|
||||
**Affected platform:** iOS Safari (WKWebView), Godot 4.5 WebAssembly/WebGL export.
|
||||
**Symptom:** Game crashes ~60s into play on iOS. On rejoin the server sends a full state dump and the crash fires again immediately, producing "A problem repeatedly occurred" and trapping the player in a rejoin loop.
|
||||
|
||||
---
|
||||
|
||||
## Changes from v1
|
||||
|
||||
| # | Review gap | v1 status | v2 fix |
|
||||
|---|-----------|-----------|--------|
|
||||
| 1 | `get_signal_connection_list().clear()` is a no-op | Bug carried from original source | Replaced with CONNECT_ONE_SHOT |
|
||||
| 2 | `evict_all()` leaves `_pending` alive — callbacks fire into freed scene | Missing | Flush `_pending` with null on evict |
|
||||
| 3 | Disk-cache hits silently re-download when slots full | Bug in v1 draft | Separate parse-slot path from network path |
|
||||
| 4 | Pool reuse missing transform/meta reset | Missing | Full reset in `_acquire_from_pool()` |
|
||||
| 5 | Pool has no size cap | Missing | Per-type cap + overflow `free()` |
|
||||
| 6 | No instrumentation plan | Missing | Debug-gated counters on all hot paths |
|
||||
| 7 | Null fallback for parse storm | Caller responsibility, unverified | Confirmed + noted in patch |
|
||||
| 8 | `unit_mesh_builder._exit_tree()` hard cleanup | Missing | Added with tween kill + pool clear |
|
||||
|
||||
---
|
||||
|
||||
## Part 1 - Issue Analysis
|
||||
|
||||
*(unchanged from v1 — root cause and failure modes are correctly identified)*
|
||||
|
||||
### Root cause: iOS WKWebView process kill due to memory pressure
|
||||
|
||||
Godot web export compiles to WebAssembly. The WASM linear heap is a fixed block allocated at startup. iOS Safari enforces a hard per-tab memory ceiling (roughly 1-1.5 GB total). When the ceiling is crossed the OS kills the renderer process. "A problem repeatedly occurred" is that kill dialog - the OS forcibly reclaiming memory from the tab.
|
||||
|
||||
### Why it crashes after ~60 seconds
|
||||
|
||||
**1. ModelCache (autoloads/ModelCache.gd:28) — unbounded in-memory PackedScene store**
|
||||
|
||||
Every unique GLB model stays in `_mem` as a parsed PackedScene holding full mesh data, textures, and materials in the WASM heap. Never released until the tab closes.
|
||||
|
||||
**2. No unit pooling — queue_free() + fresh allocation on every state change (unit_mesh_builder.gd:178)**
|
||||
|
||||
Every rebuild removes stale units via `body.queue_free()` (deferred) then allocates brand-new StaticBody3D + CollisionShape3D + MeshInstance3D + StandardMaterial3D. Old and new coexist in the heap for one full frame.
|
||||
|
||||
**3. Untracked materialize/dissolve tweens accumulate live closures (unit_mesh_builder.gd:614, 657)**
|
||||
|
||||
`_play_materialize_shader_timed()` and `_play_dissolve_shader_timed()` each create a Tween that is not stored. If a rebuild fires while a tween runs, its closure holds live ShaderMaterial refs for up to ~1.35 s.
|
||||
|
||||
### Why it crashes immediately on rejoin
|
||||
|
||||
`build_board()` triggers `add_tile()` for every tile simultaneously. Each tile calls `ModelCache.load_model()`. With the disk cache warm, `_parse_gltf()` is called ONCE PER TILE with no concurrency limit — up to 128 simultaneous parses — spiking the WASM heap above the iOS ceiling before the first frame renders.
|
||||
|
||||
---
|
||||
|
||||
## Part 2 - Fix Specifications (v2)
|
||||
|
||||
---
|
||||
|
||||
### Fix 1 — Throttle concurrent parse/download jobs
|
||||
|
||||
**File:** `Client/origin-client/autoloads/ModelCache.gd`
|
||||
|
||||
**What it does:**
|
||||
|
||||
- Caps simultaneous jobs (network downloads AND disk-cache parses) at `_MAX_JOBS` (4). Both are parse-budget consumers.
|
||||
- Names the counters `_active_jobs` / `_job_queue` to make the shared budget explicit and avoid future confusion.
|
||||
- Replaces `get_signal_connection_list("request_completed").clear()` — which is a no-op in Godot 4 (returns a copy) — with `CONNECT_ONE_SHOT`, which auto-disconnects after the first fire.
|
||||
- Disk-cache hits when all slots are busy now queue a parse-only descriptor (`"parse_from_disk": true`) so they drain correctly when a slot opens, instead of silently re-downloading.
|
||||
- Adds `_finish_job()` to drain the queue after each job completes.
|
||||
- Adds debug-gated logging via `OS.is_debug_build()`.
|
||||
|
||||
**Where to apply:** Replace the top statics, `load_model()`, `_download()`, and add `_finish_job()` in ModelCache.gd.
|
||||
|
||||
```gdscript
|
||||
# ── ADD near top of ModelCache.gd alongside existing static vars ──────────────
|
||||
|
||||
## Shared parse-budget cap. Both HTTP downloads and disk-cache parses count
|
||||
## against this limit because both call _parse_gltf() and spike the WASM heap.
|
||||
## Renamed from _active_downloads to make the scope clear.
|
||||
const _MAX_JOBS := 4
|
||||
|
||||
# Jobs queued while all slots are busy.
|
||||
# Each entry is a Dictionary with keys: url, key, disk, parse_from_disk (bool)
|
||||
static var _job_queue: Array = []
|
||||
static var _active_jobs: int = 0
|
||||
|
||||
# Set to true during evict_all(); pending callbacks are nulled instead of fired.
|
||||
static var _shutting_down: bool = false
|
||||
|
||||
|
||||
# ── REPLACE load_model() entirely ────────────────────────────────────────────
|
||||
|
||||
func load_model(url: String, callback: Callable, etag: String = "") -> void:
|
||||
if _shutting_down:
|
||||
callback.call(null)
|
||||
return
|
||||
var key := _cache_key(url, etag)
|
||||
var disk := _disk_path(url, etag)
|
||||
|
||||
# 1 — memory hit
|
||||
if _mem.has(key):
|
||||
var packed: PackedScene = _mem[key]
|
||||
callback.call(packed.instantiate() if packed != null else null)
|
||||
return
|
||||
|
||||
# 2 — already in-flight
|
||||
if _pending.has(key):
|
||||
_pending[key].append(callback)
|
||||
return
|
||||
|
||||
# 3 — disk hit; queue a parse-only job if all slots are busy
|
||||
if FileAccess.file_exists(disk):
|
||||
_pending[key] = [callback]
|
||||
if _active_jobs < _MAX_JOBS:
|
||||
_active_jobs += 1
|
||||
_parse_disk_job(key, disk, url)
|
||||
else:
|
||||
_job_queue.append({ "url": url, "key": key, "disk": disk, "parse_from_disk": true })
|
||||
return
|
||||
|
||||
# 4 — start a network download
|
||||
_pending[key] = [callback]
|
||||
if _active_jobs < _MAX_JOBS:
|
||||
_active_jobs += 1
|
||||
_download(url, key, disk)
|
||||
else:
|
||||
_job_queue.append({ "url": url, "key": key, "disk": disk, "parse_from_disk": false })
|
||||
|
||||
if OS.is_debug_build():
|
||||
print("ModelCache: queued %s (jobs=%d queued=%d)" % [url, _active_jobs, _job_queue.size()])
|
||||
|
||||
|
||||
# ── ADD: parse from disk in a job slot ───────────────────────────────────────
|
||||
|
||||
func _parse_disk_job(key: String, disk: String, url: String) -> void:
|
||||
var bytes := FileAccess.get_file_as_bytes(disk)
|
||||
if not bytes.is_empty():
|
||||
var packed := _parse_gltf(bytes)
|
||||
if packed != null:
|
||||
_mem[key] = packed
|
||||
var callbacks: Array = _pending.get(key, [])
|
||||
_pending.erase(key)
|
||||
for cb: Callable in callbacks:
|
||||
if not _shutting_down:
|
||||
cb.call(packed.instantiate())
|
||||
_finish_job()
|
||||
return
|
||||
push_warning("ModelCache: corrupt disk cache for %s — re-downloading" % url)
|
||||
DirAccess.remove_absolute(disk)
|
||||
# Fall through to network download within the same job slot (no _finish_job yet)
|
||||
_download(url, key, disk)
|
||||
|
||||
|
||||
# ── REPLACE _download() entirely ─────────────────────────────────────────────
|
||||
|
||||
func _download(url: String, key: String, disk: String) -> void:
|
||||
var fetch := _fetch_url(url)
|
||||
if OS.is_debug_build():
|
||||
print("ModelCache: downloading %s (active_jobs=%d)" % [fetch, _active_jobs])
|
||||
|
||||
var http := HTTPRequest.new()
|
||||
http.body_size_limit = -1
|
||||
add_child(http)
|
||||
|
||||
# CONNECT_ONE_SHOT auto-disconnects after first fire; no manual clear needed.
|
||||
http.request_completed.connect(
|
||||
func(res: int, code: int, headers: PackedStringArray, body: PackedByteArray):
|
||||
http.queue_free()
|
||||
|
||||
var callbacks: Array = _pending.get(key, [])
|
||||
_pending.erase(key)
|
||||
|
||||
if res != HTTPRequest.RESULT_SUCCESS:
|
||||
push_warning("ModelCache: network error result=%d http=%d - %s" % [res, code, url])
|
||||
for cb: Callable in callbacks:
|
||||
if not _shutting_down: cb.call(null)
|
||||
_finish_job(); return
|
||||
|
||||
if code < 200 or code >= 300:
|
||||
push_warning("ModelCache: HTTP %d - %s" % [code, url])
|
||||
for cb: Callable in callbacks:
|
||||
if not _shutting_down: cb.call(null)
|
||||
_finish_job(); return
|
||||
|
||||
if body.is_empty():
|
||||
push_warning("ModelCache: empty response - %s" % url)
|
||||
for cb: Callable in callbacks:
|
||||
if not _shutting_down: cb.call(null)
|
||||
_finish_job(); return
|
||||
|
||||
var packed := _parse_gltf(body)
|
||||
_mem[key] = packed
|
||||
if packed != null:
|
||||
var f := FileAccess.open(disk, FileAccess.WRITE)
|
||||
if f: f.store_buffer(body); f.close()
|
||||
|
||||
if OS.is_debug_build():
|
||||
print("ModelCache: parsed ok=%s mem_entries=%d jobs=%d" % [packed != null, _mem.size(), _active_jobs])
|
||||
|
||||
for cb: Callable in callbacks:
|
||||
if not _shutting_down:
|
||||
cb.call(packed.instantiate() if packed != null else null)
|
||||
_finish_job()
|
||||
, CONNECT_ONE_SHOT)
|
||||
|
||||
var err := http.request(fetch)
|
||||
if err != OK:
|
||||
push_warning("ModelCache: request() error %d - %s" % [err, fetch])
|
||||
var callbacks: Array = _pending.get(key, [])
|
||||
_pending.erase(key)
|
||||
for cb: Callable in callbacks:
|
||||
if not _shutting_down: cb.call(null)
|
||||
http.queue_free()
|
||||
_finish_job()
|
||||
|
||||
|
||||
# ── ADD _finish_job() below _download() ──────────────────────────────────────
|
||||
|
||||
func _finish_job() -> void:
|
||||
_active_jobs = maxi(0, _active_jobs - 1)
|
||||
if not _job_queue.is_empty() and _active_jobs < _MAX_JOBS:
|
||||
var next: Dictionary = _job_queue.pop_front()
|
||||
_active_jobs += 1
|
||||
if next.get("parse_from_disk", false):
|
||||
_parse_disk_job(next["key"], next["disk"], next["url"])
|
||||
else:
|
||||
_download(next["url"], next["key"], next["disk"])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fix 2 — Evict ModelCache on game exit, flush pending callbacks
|
||||
|
||||
**Files:** `Client/origin-client/autoloads/ModelCache.gd`, `Client/origin-client/scenes/game/game_screen.gd`
|
||||
|
||||
**What it does:**
|
||||
|
||||
- `evict_all()` sets `_shutting_down = true` first, then flushes all entries in `_pending` with `null` callbacks so in-flight HTTP requests that complete after the scene is freed do not fire into destroyed nodes.
|
||||
- Clears `_mem` and `_job_queue`.
|
||||
- Resets `_shutting_down` to false after flushing so the cache is usable again immediately (autoload persists between games).
|
||||
- Disk cache (.bin files) is intentionally left intact.
|
||||
|
||||
**Where to apply in ModelCache.gd:** Add `evict_all()` directly below the existing `evict()` method (~line 79).
|
||||
|
||||
```gdscript
|
||||
# ADD directly below evict() in ModelCache.gd
|
||||
|
||||
func evict_all() -> void:
|
||||
# Signal in-flight callbacks to return null instead of instantiating into
|
||||
# a freed scene. Must be set before flushing _pending.
|
||||
_shutting_down = true
|
||||
|
||||
# Flush all queued callbacks with null so callers don't hang.
|
||||
for key: String in _pending:
|
||||
for cb: Callable in _pending[key]:
|
||||
cb.call(null)
|
||||
_pending.clear()
|
||||
|
||||
_mem.clear()
|
||||
_job_queue.clear()
|
||||
# _active_jobs is left alone; in-flight HTTPRequest nodes own those slots
|
||||
# and will call _finish_job() when complete (which will drain an empty queue).
|
||||
|
||||
# Re-arm immediately so load_model() works for the next game.
|
||||
_shutting_down = false
|
||||
|
||||
if OS.is_debug_build():
|
||||
print("ModelCache: evict_all complete")
|
||||
```
|
||||
|
||||
**Where to apply in game_screen.gd:** At the end of `_exit_tree()`, after the existing cleanup calls (line 379).
|
||||
|
||||
```gdscript
|
||||
# ADD at end of _exit_tree() in game_screen.gd (after Chat.release_bubble_visibility)
|
||||
|
||||
ModelCache.evict_all()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fix 3 - Track and kill shader tweens on rebuild + hard cleanup on exit
|
||||
|
||||
**File:** `Client/origin-client/scenes/game/components/units/unit_mesh_builder.gd`
|
||||
|
||||
**What it does (v2 additions over v1):**
|
||||
|
||||
- Adds `_active_tweens` member var and kills all tracked tweens at the start of each `rebuild_units()` call.
|
||||
- Tracks both materialize (line 614) and dissolve (line 657) tweens identically.
|
||||
- Adds `_exit_tree()` which kills remaining tweens — prevents retained ShaderMaterial refs if the scene tears down mid-animation.
|
||||
- Debug-gated counter log on each rebuild.
|
||||
|
||||
**Where to apply:** Four locations.
|
||||
|
||||
```gdscript
|
||||
# 1. ADD near line 34 alongside existing member var declarations
|
||||
|
||||
var _active_tweens: Array[Tween] = []
|
||||
|
||||
|
||||
# 2. ADD at the very start of rebuild_units(), before the move_anims kill loop
|
||||
# (before line 43: "for iid: String in move_anims:")
|
||||
|
||||
# Kill all in-flight shader tweens so ShaderMaterial refs are released now.
|
||||
for t: Tween in _active_tweens:
|
||||
if is_instance_valid(t):
|
||||
t.kill()
|
||||
_active_tweens.clear()
|
||||
if OS.is_debug_build():
|
||||
print("UnitMeshBuilder: rebuild shader tween kill done")
|
||||
|
||||
|
||||
# 3. REPLACE the Tween creation line in _play_materialize_shader_timed()
|
||||
# Current line 614: var tween: Tween = create_tween()
|
||||
# Replace with:
|
||||
|
||||
var tween: Tween = create_tween()
|
||||
_active_tweens.append(tween)
|
||||
tween.finished.connect(func() -> void: _active_tweens.erase(tween), CONNECT_ONE_SHOT)
|
||||
# Lines 615-629 (set_trans, set_ease, tween_property, tween_method, tween_callback) unchanged
|
||||
|
||||
|
||||
# 4. REPLACE the Tween creation line in _play_dissolve_shader_timed()
|
||||
# Current line 657: var tween: Tween = create_tween()
|
||||
# Replace with:
|
||||
|
||||
var tween: Tween = create_tween()
|
||||
_active_tweens.append(tween)
|
||||
tween.finished.connect(func() -> void: _active_tweens.erase(tween), CONNECT_ONE_SHOT)
|
||||
# Lines 658-664 (set_trans, set_ease, tween_method) unchanged
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fix 4 - Pool unit scene nodes with full reset, size cap, and hard cleanup
|
||||
|
||||
**File:** `Client/origin-client/scenes/game/components/units/unit_mesh_builder.gd`
|
||||
|
||||
**What it does (v2 additions over v1):**
|
||||
|
||||
- **Full reset in `_acquire_from_pool()`**: resets `position`, `rotation`, `scale`, `collision_layer`, `collision_mask`, removes all groups and stale metadata. Prevents stale transform or collision state from the previous occupant.
|
||||
- **Per-type pool cap** (`_MAX_POOL_PER_TYPE = 6`): overflow bodies are `free()`d immediately (not `queue_free()`) to reclaim memory synchronously.
|
||||
- **Debug counters**: logs pool hit/miss and pool sizes on each unit add.
|
||||
- **`_exit_tree()` pool teardown**: combined with Fix 3 into a single exit handler.
|
||||
|
||||
**Where to apply:** Six locations.
|
||||
|
||||
```gdscript
|
||||
# 1. ADD member vars near line 34
|
||||
|
||||
const _MAX_POOL_PER_TYPE := 6 # overflow beyond this is freed immediately
|
||||
|
||||
var _unit_pool: Dictionary = {} # card_type (String) -> Array[StaticBody3D]
|
||||
var _pool_root: Node3D = null
|
||||
|
||||
|
||||
# 2. ADD _ready() -- unit_mesh_builder currently has no _ready()
|
||||
|
||||
func _ready() -> void:
|
||||
_pool_root = Node3D.new()
|
||||
_pool_root.name = "UnitPool"
|
||||
_pool_root.visible = false
|
||||
add_child(_pool_root)
|
||||
|
||||
|
||||
# 3. ADD _pool_unit() helper
|
||||
# Call instead of body.queue_free() in the stale-unit removal path.
|
||||
|
||||
func _pool_unit(body: StaticBody3D, card_type: String) -> void:
|
||||
if not is_instance_valid(body):
|
||||
return
|
||||
# Free MeshInstance3D children synchronously - releases material/mesh refs now.
|
||||
for child: Node in body.get_children():
|
||||
if child is MeshInstance3D:
|
||||
child.free()
|
||||
body.visible = false
|
||||
body.reparent(_pool_root, false)
|
||||
if not _unit_pool.has(card_type):
|
||||
_unit_pool[card_type] = []
|
||||
var pool: Array = _unit_pool[card_type]
|
||||
if pool.size() >= _MAX_POOL_PER_TYPE:
|
||||
body.free() # pool full -- free immediately
|
||||
else:
|
||||
pool.append(body)
|
||||
|
||||
|
||||
# 4. ADD _acquire_from_pool() helper
|
||||
|
||||
func _acquire_from_pool(card_type: String) -> StaticBody3D:
|
||||
if not _unit_pool.has(card_type):
|
||||
return null
|
||||
var pool: Array = _unit_pool[card_type]
|
||||
if pool.is_empty():
|
||||
return null
|
||||
var body: StaticBody3D = pool.pop_back()
|
||||
if not is_instance_valid(body):
|
||||
return null
|
||||
# Full reset -- clears all state from the previous occupant.
|
||||
body.position = Vector3.ZERO
|
||||
body.rotation = Vector3.ZERO
|
||||
body.scale = Vector3.ONE
|
||||
body.collision_layer = 1
|
||||
body.collision_mask = 1
|
||||
for group: String in body.get_groups():
|
||||
body.remove_from_group(group)
|
||||
# Remove stale metadata; add_unit_mesh() re-sets these five keys immediately.
|
||||
for key: String in body.get_meta_list():
|
||||
if key not in ["unit_id", "owner_id", "card_type", "team_color", "above_tile"]:
|
||||
body.remove_meta(key)
|
||||
body.reparent(units_root, false)
|
||||
body.visible = true
|
||||
return body
|
||||
|
||||
|
||||
# 5. In rebuild_units(): REPLACE the else branch at line 122
|
||||
#
|
||||
# Current else branch:
|
||||
# else:
|
||||
# body.queue_free()
|
||||
#
|
||||
# New else branch:
|
||||
|
||||
else:
|
||||
_pool_unit(body, card_type)
|
||||
|
||||
# The ascend-departure timer path keeps queue_free() because the body
|
||||
# must stay alive for the 1.55 s departure animation.
|
||||
|
||||
|
||||
# 6. In add_unit_mesh(): REPLACE the StaticBody3D.new() block at lines 178-184
|
||||
#
|
||||
# Current code:
|
||||
# var body: StaticBody3D = StaticBody3D.new()
|
||||
# body.set_meta("unit_id", iid)
|
||||
# body.set_meta("owner_id", owner_id)
|
||||
# body.set_meta("card_type", card_type)
|
||||
# body.set_meta("team_color", team_color)
|
||||
# if not owner_id.is_empty():
|
||||
# unit_owner_ids[iid] = owner_id
|
||||
#
|
||||
# Replace with:
|
||||
|
||||
var _pool_hit := false
|
||||
var body: StaticBody3D = _acquire_from_pool(card_type)
|
||||
if body == null:
|
||||
body = StaticBody3D.new()
|
||||
# CollisionShape3D added once on fresh alloc; pooled bodies already have one.
|
||||
var cshape: CollisionShape3D = CollisionShape3D.new()
|
||||
body.add_child(cshape)
|
||||
units_root.add_child(body)
|
||||
else:
|
||||
_pool_hit = true
|
||||
# Metadata re-set unconditionally (pool reset leaves stale values).
|
||||
body.set_meta("unit_id", iid)
|
||||
body.set_meta("owner_id", owner_id)
|
||||
body.set_meta("card_type", card_type)
|
||||
body.set_meta("team_color", team_color)
|
||||
if not owner_id.is_empty():
|
||||
unit_owner_ids[iid] = owner_id
|
||||
if OS.is_debug_build():
|
||||
var pool_sizes := {}
|
||||
for ct: String in _unit_pool:
|
||||
pool_sizes[ct] = _unit_pool[ct].size()
|
||||
print("UnitMeshBuilder: add_unit iid=%s pool_hit=%s pools=%s" % [iid, _pool_hit, pool_sizes])
|
||||
# NOTE: Remove the original "var shape: CollisionShape3D = CollisionShape3D.new()" line
|
||||
# at line 186 -- it is now inside the if-block above as "cshape". The var mi / var mat
|
||||
# lines (187-189) and all code below are unchanged.
|
||||
|
||||
|
||||
# 7. ADD _exit_tree() -- combines Fix 3 and Fix 4 cleanup (single function)
|
||||
|
||||
func _exit_tree() -> void:
|
||||
# Kill all in-flight shader tweens (Fix 3)
|
||||
for t: Tween in _active_tweens:
|
||||
if is_instance_valid(t):
|
||||
t.kill()
|
||||
_active_tweens.clear()
|
||||
# Free all pooled unit nodes (Fix 4)
|
||||
# Freeing _pool_root frees all children (pooled StaticBody3D nodes) with it.
|
||||
if is_instance_valid(_pool_root):
|
||||
_pool_root.free()
|
||||
_unit_pool.clear()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part 3 - How the Fixes Resolve the Crashes
|
||||
|
||||
### The 60-second crash
|
||||
|
||||
**Fix 3** eliminates the silent ShaderMaterial leak. Before this fix every materialize/dissolve animation created an anonymous Tween holding live `ShaderMaterial` refs on nodes that were already removed from the scene. Under normal play several animations fire per turn; over 60 seconds dozens of these leaked materials accumulate. Fix 3 kills all in-flight tweens at the start of each rebuild so materials are released immediately.
|
||||
|
||||
**Fix 4** eliminates the per-rebuild heap spike. Before this fix every unit removal triggered `queue_free()` (deferred) followed by a fresh `StaticBody3D` allocation — old and new coexisted in the WASM heap for one full frame. Over many turns the heap baseline rises because deferred frees do not compact the WASM allocator. Fix 4 replaces the pattern with a pool: the StaticBody3D shell is retained and reused; only the MeshInstance3D children (which carry mesh + material data) are replaced per-turn.
|
||||
|
||||
**Fix 2** provides a clean-slate guarantee between games. Even with Fixes 3 and 4 in place, `_mem` in ModelCache accumulates parsed `PackedScene` objects across the session. When the user finishes a game and starts another, those PackedScenes remain loaded even if the new board uses a completely different unit set. Fix 2 evicts everything when the game screen exits, and flushes pending callbacks with null so in-flight HTTP requests that complete after scene teardown do not fire into freed nodes.
|
||||
|
||||
### The immediate rejoin crash
|
||||
|
||||
**Fix 1** is the direct fix. The rejoin crash is caused by up to 128 simultaneous `_parse_gltf()` calls when the server delivers a full board state and `build_board()` fires `add_tile()` for every tile at once. Each parse allocates a large `GLTFDocument` + `GLTFState` + scene graph before compressing to a `PackedScene`. With 128 running in parallel the WASM heap spikes far above the iOS ceiling before the first frame renders.
|
||||
|
||||
Fix 1 caps simultaneous jobs (both network downloads and disk-cache parses) at `_MAX_JOBS = 4` via a shared budget. Disk-cache hits that arrive when all slots are busy now queue as parse-only descriptors and drain correctly when a slot opens — v1 had a bug where these would silently trigger a full re-download instead. The board finishes loading in the same total time (network is the real bottleneck) but without the instantaneous spike.
|
||||
|
||||
### Null handling for failed model parses (item 7)
|
||||
|
||||
`ModelCache.load_model()` already calls the callback with `null` on parse failure. Callers in `board_controller.gd` (`try_load_tile_model`, `try_load_tile_bottom`) should be verified to handle a `null` node gracefully (i.e. skip model attachment, leave placeholder mesh). This is not a change to ModelCache itself but a verification step before applying Fix 1.
|
||||
|
||||
### Summary table
|
||||
|
||||
| Fix | Crash addressed | Mechanism |
|
||||
|-----|----------------|----------|
|
||||
| Fix 1 - Throttle jobs | Rejoin crash (immediate) | Caps simultaneous GLB parses/downloads at 4; queues disk-cache hits correctly |
|
||||
| Fix 2 - evict_all on exit | 60s leak + cross-game accumulation | Clears PackedScene mem-cache and flushes pending callbacks on game exit |
|
||||
| Fix 3 - Track tweens | 60s ShaderMaterial leak | Kills in-flight shader tweens on rebuild; releases refs immediately |
|
||||
| Fix 4 - Unit pooling | 60s heap spike per turn | Reuses StaticBody3D shells; full reset on acquire; capped pool size |
|
||||
|
||||
### Recommended apply order
|
||||
|
||||
1. **Fix 1** — highest priority; directly prevents the rejoin loop that traps the player.
|
||||
2. **Fix 3** — low risk, high impact; pure additive change to unit_mesh_builder.
|
||||
3. **Fix 2** — low risk; one new method + one call site.
|
||||
4. **Fix 4** — most structural; verify `rebuild_units()` and `add_unit_mesh()` thoroughly after applying.
|
||||
Reference in New Issue
Block a user