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/.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() ## 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"