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 := "v2" # bump this when the disk-key scheme changes # 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 = {} 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) ## 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: 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 — disk hit (bytes from previous session) if FileAccess.file_exists(disk): var bytes := FileAccess.get_file_as_bytes(disk) if not bytes.is_empty(): var packed := _parse_gltf(bytes) if packed != null: _mem[key] = packed callback.call(packed.instantiate()) return # Corrupted cache file — delete and re-download. push_warning("ModelCache: deleting corrupt disk cache for %s" % url) DirAccess.remove_absolute(disk) # 3 — already downloading → queue if _pending.has(key): _pending[key].append(callback) return # 4 — start download _pending[key] = [callback] _download(url, key, disk) ## 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 func _download(url: String, key: String, disk: String) -> void: var fetch := _fetch_url(url) print("ModelCache: downloading — %s" % fetch) var http := HTTPRequest.new() http.body_size_limit = -1 # unlimited add_child(http) http.request_completed.connect( func(res: int, code: int, headers: PackedStringArray, body: PackedByteArray): # Disconnect and free the requester before anything else. http.get_signal_connection_list("request_completed").clear() http.queue_free() var callbacks: Array = _pending.get(key, []) _pending.erase(key) # Log details to help diagnose content-type / truncation issues. 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] print("ModelCache: result=%d http=%d size=%d [%s] first=[%s]" \ % [res, code, body.size(), ct, first_hex.strip_edges()]) # res is the HTTPRequest.Result enum; anything != 0 means a network error. if res != HTTPRequest.RESULT_SUCCESS: push_warning("ModelCache: network error result=%d http=%d — %s" % [res, code, url]) for cb: Callable in callbacks: cb.call(null) return if code < 200 or code >= 300: push_warning("ModelCache: HTTP %d — %s" % [code, url]) for cb: Callable in callbacks: cb.call(null) return if body.is_empty(): push_warning("ModelCache: empty response — %s" % url) for cb: Callable in callbacks: cb.call(null) return # Parse directly from the downloaded bytes — avoids any file-path quirks. var packed := _parse_gltf(body) _mem[key] = packed if packed != null: # Only write a good file to the disk cache. var f := FileAccess.open(disk, FileAccess.WRITE) if f: f.store_buffer(body) f.close() for cb: Callable in callbacks: cb.call(packed.instantiate() if packed != null else null) ) 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: cb.call(null) http.get_signal_connection_list("request_completed").clear() http.queue_free() # 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"