Files
sor/Client/origin-client/autoloads/ModelCache.gd
T
c8c3666d26 Fix 5: iOS Safari scoped asset loading and memory management
- New Platform.gd autoload: is_ios_safari() detects iPhone/iPad Safari
  via JavaScriptBridge UA check (no Chrome/CriOS), gating all iOS memory paths
- ModelCache.release_model(url, etag): evicts a model from in-memory cache
  on iOS Safari when a unit leaves the board; no-op on other platforms so
  disk cache is always preserved for fast reload
- unit_mesh_builder: stores resolved model URL+ETag per unit (_unit_model_urls,
  _unit_model_etags); calls ModelCache.release_model in the to_remove loop so
  PackedScene refs are freed as soon as the unit is pooled or freed
- ContentCache.get_model_url_for_definition: stub for looking up a card's
  Model3D CDN URL without a loaded unit dict (foundation for future eviction paths)

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 22:35:05 -04:00

348 lines
12 KiB
GDScript

extends Node
## ModelCache — downloads and caches .glb / .gltf 3D models from CDN.
##
## Usage:
## ModelCache.load_model(url, func(node: Node3D): ..., etag)
##
## The callback receives a freshly-instantiated Node3D on success, or null on
## failure. Multiple callers requesting the same URL+ETag share a single
## download. Parsed PackedScenes are kept in memory so re-instantiation is
## instant. Raw GLB bytes are written to:
## user://remote_model_cache/<sha256(url#etag)>.bin
## so subsequent app launches skip the download.
##
## Cache versioning:
## A sentinel file "user://remote_model_cache/_cache_ver" stores the current
## cache scheme version. When the scheme changes (bump _CACHE_VER), all
## stale .bin files from the old scheme are purged on first launch.
const _CACHE_DIR := "user://remote_model_cache"
const _CACHE_VER := "v3" # bump this when cached GLBs need to be re-fetched
# On web exports, direct CDN fetches are blocked by CORS (Ceph RadosGW doesn't send
# Access-Control-Allow-Origin). Route through the game server proxy instead.
const _CDN_BASE := "https://cdn.aeternalisgames.com"
const _PROXY_BASE := "https://hub.aeternalisgames.com/cdn"
# cache-key (String) → PackedScene or null (null means "tried and failed")
static var _mem: Dictionary = {}
# cache-key (String) → Array[Callable] (callbacks waiting on an in-flight download)
static var _pending: Dictionary = {}
## 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.
const _MAX_JOBS := 4
# Jobs queued while all slots are busy.
# Each entry: { 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 receive null instead of
# firing into a freed scene context.
static var _shutting_down: bool = false
func _ready() -> void:
DirAccess.make_dir_recursive_absolute(_CACHE_DIR)
_migrate_cache()
## Purge all .bin files if the cache version sentinel doesn't match _CACHE_VER.
## This evicts entries written under an old disk-key scheme so stale models
## are re-downloaded with the new scheme.
func _migrate_cache() -> void:
var ver_path := _CACHE_DIR + "/_cache_ver"
var stored := ""
if FileAccess.file_exists(ver_path):
var f := FileAccess.open(ver_path, FileAccess.READ)
if f:
stored = f.get_as_text().strip_edges()
f.close()
if stored == _CACHE_VER:
return
# Version mismatch — delete every .bin file in the cache directory.
var dir := DirAccess.open(_CACHE_DIR)
if dir:
dir.list_dir_begin()
var name := dir.get_next()
while name != "":
if name.ends_with(".bin"):
DirAccess.remove_absolute(_CACHE_DIR + "/" + name)
name = dir.get_next()
dir.list_dir_end()
# Write new sentinel.
var f := FileAccess.open(ver_path, FileAccess.WRITE)
if f:
f.store_string(_CACHE_VER)
f.close()
## Release a model from the in-memory cache without touching disk.
## On iOS Safari this immediately frees resident memory when a unit leaves the board.
## On other platforms this is a no-op — the OS manages heap pressure.
## Disk cache (.bin) is intentionally kept so the model reloads instantly if the same
## unit type is played again in the same session.
func release_model(url: String, etag: String = "") -> void:
if url.is_empty():
return
if not Platform.is_ios_safari():
return
var key := _cache_key(url, etag)
_mem.erase(key)
if OS.is_debug_build():
print("ModelCache: released %s (mem_entries=%d)" % [url, _mem.size()])
## Remove a cached entry (memory + disk) so the next load_model call re-downloads it.
## Use before retrying a previously-failed URL.
func evict(url: String, etag: String = "") -> void:
var key := _cache_key(url, etag)
_mem.erase(key)
var disk := _disk_path(url, etag)
if FileAccess.file_exists(disk):
DirAccess.remove_absolute(disk)
## Drop all in-memory PackedScene references and flush the pending queue.
## Sets _shutting_down first so any in-flight HTTP callbacks that complete
## after scene teardown return null instead of firing into freed nodes.
## Disk cache (.bin files) is intentionally left intact so subsequent
## sessions still benefit from skipping re-downloads.
func evict_all() -> void:
_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 intentionally left alone; in-flight HTTPRequest nodes own
# those slots and will call _finish_job() when complete (draining 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")
## Request a model by CDN URL.
## callback(node: Node3D) is called on the main thread; node may be null.
## If the same URL+ETag is already downloading, callbacks are queued and all
## fire together when the download completes.
## etag: the ContentETag from the server DTO (empty string = no etag, use URL only).
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 })
if OS.is_debug_build():
print("ModelCache: disk-hit queued %s (jobs=%d queued=%d)" % [url, _active_jobs, _job_queue.size()])
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: net-queued %s (jobs=%d queued=%d)" % [url, _active_jobs, _job_queue.size()])
## Returns the URL to actually fetch — on web, rewrites CDN URLs to go through
## the game server proxy so CORS headers are added.
func _fetch_url(url: String) -> String:
if OS.has_feature("web") and url.begins_with(_CDN_BASE + "/"):
return _PROXY_BASE + "/" + url.substr(_CDN_BASE.length() + 1)
return url
## Parse a disk-cached model within a job slot.
## Falls through to _download() if the disk file is corrupt or missing.
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)
# Re-use the already-acquired job slot for the network download.
_download(url, key, disk)
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.
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)
# Log content-type and first bytes for CDN diagnosis.
var ct := ""
for h: String in headers:
if h.to_lower().begins_with("content-type"):
ct = h
break
var first_hex := ""
for i in mini(16, body.size()):
first_hex += "%02X " % body[i]
if OS.is_debug_build():
print("ModelCache: result=%d http=%d size=%d [%s] first=[%s]" % [res, code, body.size(), ct, first_hex.strip_edges()])
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 active_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()
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"])
# Parse GLB/GLTF bytes using GLTFDocument.append_from_buffer.
# Returns a PackedScene ready for instantiation, or null on failure.
func _parse_gltf(data: PackedByteArray) -> PackedScene:
# Validate GLB magic bytes ("glTF" = 0x46546C67 little-endian).
if data.size() >= 4:
var magic := data.decode_u32(0)
if magic != 0x46546C67:
# Try to give a human-readable diagnosis.
var preview := ""
for i in mini(20, data.size()):
var b := data[i]
preview += char(b) if b >= 0x20 and b < 0x7F else "."
push_warning(
"ModelCache: not a GLB file — expected 'glTF' magic, got 0x%X ('%s'). " \
+ "Only binary .glb format is supported at runtime. " \
+ "Re-export from Blender as glTF 2.0 Binary (.glb)." % [magic, preview])
return null
var doc := GLTFDocument.new()
var state := GLTFState.new()
# Empty base_path is correct for self-contained GLBs.
var err := doc.append_from_buffer(data, "", state)
if err != OK:
push_warning("ModelCache: GLTFDocument.append_from_buffer error %d" % err)
return null
var root := doc.generate_scene(state)
if root == null:
push_warning("ModelCache: generate_scene returned null")
return null
var packed := PackedScene.new()
var pack_err := packed.pack(root)
root.queue_free()
if pack_err != OK:
push_warning("ModelCache: PackedScene.pack error %d" % pack_err)
return null
return packed
## Disk key is sha256(url + "#" + etag) when etag is non-empty, or sha256(url) otherwise.
func _cache_key(url: String, etag: String) -> String:
if etag.is_empty():
return url
return url + "#" + etag
func _disk_path(url: String, etag: String = "") -> String:
return _CACHE_DIR + "/" + _cache_key(url, etag).sha256_text() + ".bin"