@ringozz/godot 4.7.1-1 → 4.7.1-10

package/src/debug.ts

@@ -2,7 +2,7 @@
  Copyright (c) Vladimir Davidovich. All rights reserved.
 ***********************************************************************/
 
-import { Rect2, Vector3 } from './index.ts';
+import { Rect2, str, varToStr, Vector3 } from './index.ts';
 import { CanvasItem } from '../gen/classes/CanvasItem.ts';
 import { ClassDB } from '../gen/classes/ClassDB.ts';
 import { Control } from '../gen/classes/Control.ts';
@@ -14,40 +14,25 @@ import { OS } from '../gen/classes/OS.ts';
 import { Time } from '../gen/classes/Time.ts';
 
 /**
- * Dump a Godot object's properties as an indented string.
- * Uses `getPropertyList()` + `get()` to safely introspect — never invokes JS getters.
+ * Dump a Godot value or object as a string.
+ * Value types (vectors, arrays, dictionaries, …) render via Godot's `str()`.
+ * Objects dump via Godot's `var_to_str` — its own property walk + recursion —
+ * with the node's `name` prepended when present.
  *
- * @param obj - Any Godot wrapper (Node, Resource, etc.) or plain value
- * @param depth - Max recursion depth into sub-objects (default 2)
- * @param maxProps - Max properties to show per object (default 30)
+ * @param obj - Any Godot wrapper (Node, Resource, …), value type, or plain value
  */
-export function dumpStr(obj: unknown, depth = 2, maxProps = 30): string {
-  if (obj == null || typeof obj !== 'object') return String(obj);
-  let cls: string;
-  try { cls = (obj as any).getClass?.(); } catch { cls = (obj as any).constructor?.name ?? typeof obj; }
-  if (!cls) return String(obj);
-  const lines = [`[${cls}]`];
-  let count = 0;
-  try {
-    const plist = (obj as any).getPropertyList?.();
-    if (plist?.size) {
-      for (let i = 0; i < plist.size() && count < maxProps; i++) {
-        const name = plist.get(i).get('name');
-        if (!name || (name + '').startsWith('_')) continue;
-        let val: unknown;
-        try { val = (obj as any).get(name); } catch { val = '<err>'; }
-        if (typeof val === 'object' && val !== null && depth > 1)
-          lines.push(`  ${name}:\n${indent(dumpStr(val, depth - 1, maxProps), '    ')}`);
-        else
-          lines.push(`  ${name}: ${String(val)}`);
-        count++;
-      }
-    }
-  } catch { /* not a GodotVar */ }
-  return lines.join('\n');
-}
+export function dumpStr(obj: unknown): string {
+    if (obj == null || typeof obj !== 'object') return String(obj);
+
+    // Value types & heap containers (Vector3, Array, Dictionary, …) have no getClass() —
+    // let Godot's str() render them.
+    if (!(obj as any).getClass) return str(obj as any);
 
-function indent(s: string, prefix: string): string { return s.split('\n').join('\n' + prefix); }
+    const dump = varToStr(obj as any);
+    let name: unknown;
+    try { name = (obj as any).name; } catch { name = undefined; }
+    return name === undefined || name === null || name === '' ? dump : `${name}: ${dump}`;
+}
 
 /**
  * Serialize a scene subtree as a tree-formatted string.
@@ -56,34 +41,36 @@ function indent(s: string, prefix: string): string { return s.split('\n').join('
  * @param depth - Max depth (default 99)
  */
 export function dumpTreeStr(node: Node, depth = 99): string {
-  const lines: string[] = [];
-  (function walk(n: Node, d: number, ind: string) {
-    if (d <= 0) return;
-    lines.push(`${ind}${n.getClass()} "${n.name}" (${n.getChildCount()} children)`);
-    for (let i = 0; i < n.getChildCount(); i++) {
-      const c = n.getChild(i);
-      if (c) walk(c as Node, d - 1, ind + '  ');
-    }
-  })(node, depth, '');
-  return lines.join('\n');
+    const lines: string[] = [];
+    (function walk(n: Node, d: number, ind: string) {
+        if (d <= 0) return;
+        lines.push(`${ind}${n.getClass()} "${n.name}" (${n.getChildCount()} children)`);
+        for (let i = 0; i < n.getChildCount(); i++) {
+            const c = n.getChild(i);
+            if (c) walk(c as Node, d - 1, ind + '  ');
+        }
+    })(node, depth, '');
+    return lines.join('\n');
 }
 
 /**
  * Return a snapshot of engine runtime stats as a formatted string.
  *
  * Includes process frames, FPS, physics frames, node count, time scale,
- * and main-loop class.
+ * and main-loop class. Never throws: `Engine.getMainLoop()` can be null or
+ * throw while the engine is starting/stopping, in which case those rows show `N/A`.
  */
 export function statsStr(): string {
-  const tree = Engine.getMainLoop() as any;
-  return [
-    `Frames:     ${Engine.getProcessFrames()}`,
-    `FPS:        ${Engine.getFramesPerSecond()}`,
-    `Physics:    ${Engine.getPhysicsFrames()}`,
-    `Nodes:      ${tree.getNodeCount()}`,
-    `Time scale: ${Engine.timeScale}`,
-    `Main loop:  ${Engine.getMainLoop().getClass()}`,
-  ].join('\n');
+    let tree: any = null;
+    try { tree = Engine.getMainLoop(); } catch { tree = null; }
+    return [
+        `Frames:     ${Engine.getProcessFrames()}`,
+        `FPS:        ${Engine.getFramesPerSecond()}`,
+        `Physics:    ${Engine.getPhysicsFrames()}`,
+        `Nodes:      ${tree?.getNodeCount?.() ?? 'N/A'}`,
+        `Time scale: ${Engine.timeScale}`,
+        `Main loop:  ${tree ? tree.getClass() : 'N/A'}`,
+    ].join('\n');
 }
 
 /**
@@ -91,16 +78,43 @@ export function statsStr(): string {
  * Requires the `--expose-gc` Node.js flag.
  */
 export function gc(): string {
-  const before = process.memoryUsage().heapUsed;
-  if (typeof Bun !== 'undefined')
-    Bun.gc(true);
-  else if (globalThis.gc)
-    globalThis.gc({ type: 'major', execution: 'sync' });
-  else
-    return 'gc() unavailable — need --expose-gc';
-
-  const after = process.memoryUsage().heapUsed;
-  return `GC: freed ${((before - after) / 1024).toFixed(0)} KB`;
+    const before = globalThis.process?.memoryUsage?.().heapUsed;
+    if (globalThis.Bun)
+        globalThis.Bun.gc(true);
+    else if (globalThis.gc)
+        globalThis.gc({ type: 'major', execution: 'sync' });
+    else
+        return 'gc() unavailable — need --expose-gc';
+
+    const after = globalThis.process?.memoryUsage?.().heapUsed;
+    const freed = typeof before === 'number' && typeof after === 'number' ? (before - after) / 1024 : 0;
+    return `GC: freed ${freed.toFixed(0)} KB`;
+}
+
+/**
+ * `DOMRect` is not a global in Bun (desktop), but `getBoundingClientRect()`
+ * constructs one. Install a minimal spec-compatible polyfill on desktop so the
+ * helper works identically on desktop and web (browsers already define it).
+ */
+function ensureDOMRect(): void {
+    if (typeof (globalThis as any).DOMRect !== 'undefined') return;
+    (globalThis as any).DOMRect = class DOMRect {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        constructor(x = 0, y = 0, width = 0, height = 0) {
+            this.x = x;
+            this.y = y;
+            this.width = width;
+            this.height = height;
+        }
+        get left() { return this.x; }
+        get top() { return this.y; }
+        get right() { return this.x + this.width; }
+        get bottom() { return this.y + this.height; }
+        toJSON() { return { x: this.x, y: this.y, width: this.width, height: this.height }; }
+    };
 }
 
 /**
@@ -111,109 +125,112 @@ export function gc(): string {
  *   breakpoints in any module.
  * - Registers an `uncaughtException` handler that logs but keeps the process
  *   alive for interactive debugging.
+ * - Polyfills `DOMRect` (needed by `getBoundingClientRect()` on desktop).
  */
 export function initDebug(): void {
-  globalThis.process?.on('uncaughtException', (err, origin) => {
-    console.error(`\n✗ ${origin}:`, err.stack);
-  });
-
-  Object.defineProperty(CanvasItem.prototype, 'getBoundingClientRect', {
-    configurable: true,
-    value(this: CanvasItem): DOMRect | null {
-      const scale = DisplayServer.screenGetScale();
-      if (this instanceof Control) {
-        const rc = (this as Control).getGlobalRect();
-        return new DOMRect(
-          rc.position.x / scale, rc.position.y / scale,
-          rc.size.x / scale, rc.size.y / scale,
-        );
-      }
-
-      if (typeof (this as any).getRect !== 'function') return null;
-
-      const rect = (this as any).getRect() as Rect2;
-      const t = this.getScreenTransform();
-
-      const pos = rect.position;
-      const sz = rect.size;
-      const tx = t.x;
-      const ty = t.y;
-      const to = t.origin;
-
-      const x0 = pos.x, y0 = pos.y;
-      const x1 = x0 + sz.x, y1 = y0 + sz.y;
-      const txx = tx.x, txy = tx.y;
-      const tyx = ty.x, tyy = ty.y;
-      const tox = to.x, toy = to.y;
-
-      let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-      const accum = (px: number, py: number) => {
-        if (px < minX) minX = px; if (py < minY) minY = py;
-        if (px > maxX) maxX = px; if (py > maxY) maxY = py;
-      };
-
-      accum(txx * x0 + tyx * y0 + tox, txy * x0 + tyy * y0 + toy);
-      accum(txx * x1 + tyx * y0 + tox, txy * x1 + tyy * y0 + toy);
-      accum(txx * x0 + tyx * y1 + tox, txy * x0 + tyy * y1 + toy);
-      accum(txx * x1 + tyx * y1 + tox, txy * x1 + tyy * y1 + toy);
-
-      return new DOMRect(
-        minX / scale, minY / scale,
-        (maxX - minX) / scale, (maxY - minY) / scale,
-      );
-    },
-  });
-
-  Object.defineProperty(Node3D.prototype, 'getBoundingClientRect', {
-    configurable: true,
-    value(this: Node3D): DOMRect | null {
-      if (typeof (this as any).getAabb !== 'function') return null;
-
-      const aabb = (this as any).getAabb();
-      const gt = this.globalTransform;
-      const viewport = this.getViewport();
-      if (!viewport) return null;
-      const camera = viewport.getCamera3d();
-      if (!camera) return null;
-      const scale = DisplayServer.screenGetScale();
-
-      const b = gt.basis;
-      const bx = b.x, by = b.y, bz = b.z;
-      const o = gt.origin;
-      const p = aabb.position, e = aabb.end;
-
-      const [px, py, pz] = [p.x, p.y, p.z];
-      const [ex, ey, ez] = [e.x, e.y, e.z];
-      const [bxx, bxy, bxz] = [bx.x, bx.y, bx.z];
-      const [byx, byy, byz] = [by.x, by.y, by.z];
-      const [bzx, bzy, bzz] = [bz.x, bz.y, bz.z];
-      const [ox, oy, oz] = [o.x, o.y, o.z];
-
-      const corners = [
-        [px, py, pz], [ex, py, pz], [px, ey, pz], [ex, ey, pz],
-        [px, py, ez], [ex, py, ez], [px, ey, ez], [ex, ey, ez],
-      ];
-
-      let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-
-      for (const [cx, cy, cz] of corners) {
-        const wx = bxx * cx + byx * cy + bzx * cz + ox;
-        const wy = bxy * cx + byy * cy + bzy * cz + oy;
-        const wz = bxz * cx + byz * cy + bzz * cz + oz;
-        const s = camera.unprojectPosition(new Vector3(wx, wy, wz));
-        if (s.x < minX) minX = s.x; if (s.y < minY) minY = s.y;
-        if (s.x > maxX) maxX = s.x; if (s.y > maxY) maxY = s.y;
-      }
-
-      return new DOMRect(
-        minX / scale, minY / scale,
-        (maxX - minX) / scale, (maxY - minY) / scale,
-      );
-    },
-  });
-
-  (globalThis as any).$ = {
-    Engine, OS, ClassDB, Time,
-    dumpStr, dumpTreeStr, statsStr, gc,
-  };
+    globalThis.process?.on?.('uncaughtException', (err, origin) => {
+        console.error(`\n✗ ${origin}:`, err.stack);
+    });
+
+    ensureDOMRect();
+
+    Object.defineProperty(CanvasItem.prototype, 'getBoundingClientRect', {
+        configurable: true,
+        value(this: CanvasItem): DOMRect | null {
+            const scale = DisplayServer.screenGetScale();
+            if (this instanceof Control) {
+                const rc = (this as Control).getGlobalRect();
+                return new DOMRect(
+                    rc.position.x / scale, rc.position.y / scale,
+                    rc.size.x / scale, rc.size.y / scale,
+                );
+            }
+
+            if (typeof (this as any).getRect !== 'function') return null;
+
+            const rect = (this as any).getRect() as Rect2;
+            const t = this.getScreenTransform();
+
+            const pos = rect.position;
+            const sz = rect.size;
+            const tx = t.x;
+            const ty = t.y;
+            const to = t.origin;
+
+            const x0 = pos.x, y0 = pos.y;
+            const x1 = x0 + sz.x, y1 = y0 + sz.y;
+            const txx = tx.x, txy = tx.y;
+            const tyx = ty.x, tyy = ty.y;
+            const tox = to.x, toy = to.y;
+
+            let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+            const accum = (px: number, py: number) => {
+                if (px < minX) minX = px; if (py < minY) minY = py;
+                if (px > maxX) maxX = px; if (py > maxY) maxY = py;
+            };
+
+            accum(txx * x0 + tyx * y0 + tox, txy * x0 + tyy * y0 + toy);
+            accum(txx * x1 + tyx * y0 + tox, txy * x1 + tyy * y0 + toy);
+            accum(txx * x0 + tyx * y1 + tox, txy * x0 + tyy * y1 + toy);
+            accum(txx * x1 + tyx * y1 + tox, txy * x1 + tyy * y1 + toy);
+
+            return new DOMRect(
+                minX / scale, minY / scale,
+                (maxX - minX) / scale, (maxY - minY) / scale,
+            );
+        },
+    });
+
+    Object.defineProperty(Node3D.prototype, 'getBoundingClientRect', {
+        configurable: true,
+        value(this: Node3D): DOMRect | null {
+            if (typeof (this as any).getAabb !== 'function') return null;
+
+            const aabb = (this as any).getAabb();
+            const gt = this.globalTransform;
+            const viewport = this.getViewport();
+            if (!viewport) return null;
+            const camera = viewport.getCamera3d();
+            if (!camera) return null;
+            const scale = DisplayServer.screenGetScale();
+
+            const b = gt.basis;
+            const bx = b.x, by = b.y, bz = b.z;
+            const o = gt.origin;
+            const p = aabb.position, e = aabb.end;
+
+            const [px, py, pz] = [p.x, p.y, p.z];
+            const [ex, ey, ez] = [e.x, e.y, e.z];
+            const [bxx, bxy, bxz] = [bx.x, bx.y, bx.z];
+            const [byx, byy, byz] = [by.x, by.y, by.z];
+            const [bzx, bzy, bzz] = [bz.x, bz.y, bz.z];
+            const [ox, oy, oz] = [o.x, o.y, o.z];
+
+            const corners = [
+                [px, py, pz], [ex, py, pz], [px, ey, pz], [ex, ey, pz],
+                [px, py, ez], [ex, py, ez], [px, ey, ez], [ex, ey, ez],
+            ];
+
+            let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+
+            for (const [cx, cy, cz] of corners) {
+                const wx = bxx * cx + byx * cy + bzx * cz + ox;
+                const wy = bxy * cx + byy * cy + bzy * cz + oy;
+                const wz = bxz * cx + byz * cy + bzz * cz + oz;
+                const s = camera.unprojectPosition(new Vector3(wx, wy, wz));
+                if (s.x < minX) minX = s.x; if (s.y < minY) minY = s.y;
+                if (s.x > maxX) maxX = s.x; if (s.y > maxY) maxY = s.y;
+            }
+
+            return new DOMRect(
+                minX / scale, minY / scale,
+                (maxX - minX) / scale, (maxY - minY) / scale,
+            );
+        },
+    });
+
+    (globalThis as any).$ = {
+        Engine, OS, ClassDB, Time,
+        dumpStr, dumpTreeStr, statsStr, gc,
+    };
 }

package/src/index.ts

@@ -3,6 +3,8 @@
 ***********************************************************************/
 
 export * from '../gen/index.ts';
+import * as ValueTypes from '../gen/value-types/index.ts';
+import * as HeapTypes from '../gen/heap-types/index.ts';
 import { Engine } from '../gen/classes/Engine.ts';
 import { GodotInstance } from '../gen/classes/GodotInstance.ts';
 import { SceneTree } from '../gen/classes/SceneTree.ts';
@@ -11,6 +13,8 @@ import { gc } from './debug.ts';
 import { cancelAnimationFrame, getGodot, requestAnimationFrame } from './runtime.ts';
 
 // ---- make sure these classes are not tree-shaked ----
+void ValueTypes;
+void HeapTypes;
 void GodotInstance;
 void SceneTree;
 void Window;
@@ -22,7 +26,7 @@ Object.assign(globalThis as any, { requestAnimationFrame, cancelAnimationFrame }
 export async function runGodot(signal?: AbortSignal, unmount?: () => PromiseLike<void>) {
     signal?.throwIfAborted();
     signal?.addEventListener('abort', () => {
-        (Engine.getMainLoop() as SceneTree).quit();
+        (Engine.getMainLoop() as SceneTree)?.quit();
     }, { once: true });
 
     const godot = getGodot();

package/src/load.ts

@@ -0,0 +1,210 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { DirAccess } from '../gen/classes/DirAccess.ts';
+import { FileAccess } from '../gen/classes/FileAccess.ts';
+import { ProjectSettings } from '../gen/classes/ProjectSettings.ts';
+import { ResourceLoader, ThreadLoadStatus } from '../gen/classes/ResourceLoader.ts';
+import { ResourceUID } from '../gen/classes/ResourceUID.ts';
+import type { Resource } from '../gen/classes/Resource.ts';
+import { stageFile } from './runtime.ts';
+import { decodeCtex } from './web-image.ts';
+
+/**
+ * A Godot `Resource` subclass constructor: its `.name` is the registered class
+ * name (used as the `ResourceLoader` type hint), and `InstanceType<C>` is the
+ * loaded resource type.
+ */
+type ResourceConstructor = { new(...args: any[]): Resource } & Function;
+
+/**
+ * A file to stage before loading, keyed by `res://` path: sidecars (`.import`)
+ * arrive as `content` (text); imported products (`.scn`/`.ctex`) arrive as
+ * `path` (fetched).
+ */
+interface AssetFile {
+	content?: string;
+	path?: string;
+}
+
+export type AssetFiles = Record<string, AssetFile>;
+
+const UID_RE = /uid="(uid:\/\/[\w.]+)"/;
+
+// Godot encodes `uid://` numbers in base 34 over `a-y` then `0-8`
+// (core/io/resource_uid.cpp). Decode in JS with BigInt: `ResourceUID.textToId`
+// returns a JS number, and these ids exceed `Number.MAX_SAFE_INTEGER`, so the
+// low digits would be lost. BigInt flows through `_C` losslessly (int64).
+const UID_CHARS = 'abcdefghijklmnopqrstuvwxy012345678';
+
+function uidToId(uid: string): bigint {
+	let id = 0n;
+	for (let i = 6; i < uid.length; i++) {
+		id = id * 34n + BigInt(UID_CHARS.indexOf(uid[i]));
+	}
+	return id;
+}
+
+/**
+ * Registers an asset's `uid://` → `res://` path so scene ext_resource references
+ * resolve it (Godot's `ResourceUID` map) instead of warning and falling back to
+ * the stored text path. Idempotent; skips unknown/malformed uids.
+ */
+function registerAssetUid(uid: string, resPath: string): void {
+	const id = uidToId(uid);
+	if (id !== 0n && !ResourceUID.hasId(id as unknown as number)) {
+		ResourceUID.addId(id as unknown as number, resPath);
+	}
+}
+
+async function materialize([resPath, entry]: [string, AssetFile]): Promise<void> {
+	if (FileAccess.fileExists(resPath)) {
+		return;
+	}
+	let bytes: Uint8Array;
+	if (entry.content !== undefined) {
+		// Sidecars (`.import`) and native text sources carry the asset's `uid=`;
+		// register it so scenes resolve by uid. `.import` maps to the source path
+		// (resPath minus the suffix); native files map to themselves.
+		const uid = entry.content.match(UID_RE)?.[1];
+		if (uid) {
+			registerAssetUid(uid, resPath.endsWith('.import') ? resPath.slice(0, -'.import'.length) : resPath);
+		}
+		bytes = new TextEncoder().encode(entry.content);
+	} else if (entry.path) {
+		const res = await fetch(entry.path);
+		if (!res.ok) {
+			return;
+		}
+		bytes = new Uint8Array(await res.arrayBuffer());
+		if (resPath.endsWith('.ctex')) {
+			// On web, decode embedded PNG/WebP blobs with the browser before
+			// staging, so the engine never runs an image codec (see web-image.ts).
+			bytes = await decodeCtex(bytes);
+		}
+	} else {
+		return;
+	}
+	stageFile?.(ProjectSettings.globalizePath(resPath), bytes);
+}
+
+const nextTick = () => new Promise(requestAnimationFrame);
+
+/**
+ * An asset module as generated by `@ringozz/godot/preload`: `default` is the
+ * load promise, `materialize` resolves once its bundled files (plus its deps'
+ * files) are staged on the engine's filesystem.
+ */
+interface AssetModule {
+	default: Promise<unknown>;
+	materialize: Promise<unknown>;
+}
+
+/**
+ * Stages the asset's bundled files before loading: `.import` sidecars as text
+ * and imported products (`.scn`/`.ctex`) as fetched paths. On web the bytes are
+ * written straight into Emscripten's MEMFS via Godot's `copyToFS` (JS-heap only,
+ * no wasm copy); a no-op on desktop where the files already exist. `deps`
+ * supplies referenced asset modules whose file-staging is awaited (so Godot can
+ * resolve them) and whose load failures are logged.
+ */
+function materializeFiles(files: AssetFiles, deps: AssetModule[] = []): Promise<unknown> {
+	for (const dep of deps) {
+		dep.default.catch((err) => console.error('[godot] dependency load failed:', err));
+	}
+	if (stageFile === undefined) {
+		// Desktop: the files already exist on disk (res:// = cwd) and uids come
+		// from `.godot/uid_cache.bin`, so there is nothing to stage.
+		return Promise.resolve();
+	}
+	return Promise.all([...Object.entries(files).map(materialize), ...deps.map((dep) => dep.materialize)]);
+}
+
+/**
+ * Returns a promise resolving to the resource already cached in the engine at
+ * `path` (`ResourceCache`), or `null` when it isn't loaded yet. Used by
+ * {@link loadAsset} to skip file staging and the threaded load when a
+ * re-evaluated module (e.g. web HMR) references an asset that is still cached.
+ * `getCachedRef` returns the same JS wrapper as `loadThreadedGet` (instance
+ * binding), so identity is preserved.
+ */
+function cachedResource<C extends ResourceConstructor>(path: string): Promise<InstanceType<C>> | null {
+	const result = ResourceLoader.getCachedRef(path) as InstanceType<C>;
+	return result ? Promise.resolve(result) : null;
+}
+
+/**
+ * Entry point for the generated asset modules (`@ringozz/godot/preload`): checks
+ * the engine's `ResourceCache` once (`cachedResource`), stages the bundled files
+ * via `materializeFiles` when needed, then loads via {@link loadResourceAsync},
+ * memoizing the resulting load promise on `data` (the module's
+ * `import.meta.hot.data`, carried across HMR re-evaluations; `{}` on desktop
+ * where modules evaluate once). Memoization keeps `use()` seeing the **same**
+ * fulfilled promise object across re-evaluations — no Suspense fallback flash on
+ * hot reload; a rejected load is evicted so the next evaluation retries. Returns
+ * the `materialize` promise (own + deps' files staged) and the load promise.
+ */
+export function loadAsset<C extends ResourceConstructor>(
+	path: string,
+	cls: C,
+	files: AssetFiles,
+	deps: AssetModule[] = [],
+	data: Record<string, unknown> = {},
+): { materialize: Promise<unknown>; load: Promise<InstanceType<C>> } {
+	const cached = cachedResource<C>(path);
+	const materialize = cached ? Promise.resolve() : materializeFiles(files, deps);
+	const existing = data[path] as Promise<InstanceType<C>> | undefined;
+	const load = existing ?? cached ?? materialize.then(() => loadResourceAsync(path, cls, files));
+	data[path] = load;
+	load.catch(() => {
+		if (data[path] === load) delete data[path];
+	});
+	return { materialize, load };
+}
+
+/**
+ * Loads a resource in the background. `cls` supplies both the `ResourceLoader`
+ * type hint (its registered `.name`) and the return type. On web, call
+ * {@link materializeFiles} with the asset's bundled files first; on desktop the
+ * files already exist. Pass the same `files` map to have the staged files
+ * deleted from MEMFS once the resource is loaded (the resource stays cached in
+ * the engine, so the bytes are no longer needed).
+ */
+export async function loadResourceAsync<C extends ResourceConstructor>(
+	path: string,
+	cls: C,
+	files?: AssetFiles,
+): Promise<InstanceType<C>> {
+	const err = ResourceLoader.loadThreadedRequest(path, cls.name);
+	if (err) {
+		throw new Error(`loadResourceAsync(${path}): loadThreadedRequest failed (${err})`);
+	}
+
+	let result: InstanceType<C>;
+	while (true) {
+		const status = ResourceLoader.loadThreadedGetStatus(path);
+		if (status === ThreadLoadStatus.THREAD_LOAD_LOADED) {
+			result = ResourceLoader.loadThreadedGet(path) as InstanceType<C>;
+			break;
+		}
+		if (status === ThreadLoadStatus.THREAD_LOAD_FAILED || status === ThreadLoadStatus.THREAD_LOAD_INVALID_RESOURCE) {
+			throw new Error(`loadResourceAsync(${path}): load failed (status ${status})`);
+		}
+		await nextTick();
+	}
+	if (files && stageFile !== undefined) {
+		// Keep `.import` sidecars — they route imported source paths to their
+		// products (ResourceFormatImporter recognizes a path by its sidecar).
+		// Delete everything else: the products are read only on a cache miss, and
+		// the resource stays cached after loading, so the bytes are dead weight.
+		// Best-effort: a file may already be gone (another module's cleanup or a
+		// cache-miss re-stage).
+		for (const resPath of Object.keys(files)) {
+			if (!resPath.endsWith('.import')) {
+				DirAccess.removeAbsolute(resPath);
+			}
+		}
+	}
+	return result;
+}