@ringozz/godot 4.7.1-11 → 4.7.1-13

package/README.md

@@ -74,7 +74,7 @@ const tex   = await loadResourceAsync('res://textures/icon.jpg', Texture2D); //
 - `loadResourceAsync(path, cls, files?)` — generic over the Godot class: `cls.name` is the `ResourceLoader` type hint, and the return type is `InstanceType<typeof cls>`. Loads in the background (`loadThreadedRequest` + status polling). Godot default arguments apply: the napi dispatch truncates trailing `undefined` args, so `loadThreadedRequest` uses its default `CACHE_MODE_REUSE` and the resource stays cached in the engine (scene re-references don't re-read the file). On web it only works for paths already staged into MEMFS (generated asset modules handle this). When the asset's `files` map is passed, the staged product files (`.ctex`/`.scn`/native sources) are deleted from MEMFS after the resource loads — only the `.import` sidecars are kept, since they route imported source paths to their products. The decoded texture bytes don't linger in the JS heap.
 - `loadAsset(path, cls, files, deps, data)` — the generated asset modules' entry point (also usable directly): returns `{ materialize, load }`. It checks the engine's `ResourceCache` first (when the asset is already loaded, `load` resolves to the cached instance and staging is skipped), stages the bundled files via Godot's `copyToFS` (zero-copy handover of the fetched bytes; a no-op on desktop where the files already exist), loads via `loadResourceAsync`, and memoizes `load` on `data` (pass `import.meta.hot.data`) so HMR re-evaluations reuse the same fulfilled promise.
 
-Asset imports are resolved by `@ringozz/godot/preload` (a Bun plugin, registered via `bunfig.toml` preload for `bun run`/`bun test` and via `[serve.static] plugins` for `Bun.serve`'s fullstack HTML routes; the module's default export is the single plugin object) into a module per asset:
+Asset imports are resolved by `@ringozz/godot/preload` (a Bun plugin, registered via `bunfig.toml` preload for `bun run`/`bun test` and via `[serve.static] plugins` for `Bun.serve`'s fullstack HTML routes; the module's default export is the single plugin object) into a module per asset. Only **JS imports** are virtualized — HTML asset references (`<link rel="icon">`, `<img src>`) and CSS `url()` refs fall through to Bun's normal (content-hashed) asset handling, so favicons and other web assets co-exist with Godot imports:
 
 ```ts
 import foo from './models/foo.gltf';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.1-11",
+  "version": "4.7.1-13",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
   "keywords": [
     "godot"
@@ -38,7 +38,7 @@
   "optionalDependencies": {
     "@ringozz/godot-macos-arm64": "^4.7.1-3",
     "@ringozz/godot-windows-x86_64": "^4.7.1-3",
-    "@ringozz/godot-web-wasm32": "^4.7.1-10"
+    "@ringozz/godot-web-wasm32": "^4.7.1-12"
   },
   "peerDependencies": {
     "@types/bun": "*"

package/src/index.ts

@@ -10,7 +10,7 @@ import { GodotInstance } from '../gen/classes/GodotInstance.ts';
 import { SceneTree } from '../gen/classes/SceneTree.ts';
 import { Window } from '../gen/classes/Window.ts';
 import { gc } from './debug.ts';
-import { cancelAnimationFrame, getGodot, requestAnimationFrame } from './runtime.ts';
+import { cancelAnimationFrame, cleanupHooks, getGodot, requestAnimationFrame } from './runtime.ts';
 
 // ---- make sure these classes are not tree-shaked ----
 void ValueTypes;
@@ -34,7 +34,19 @@ export async function runGodot(signal?: AbortSignal, unmount?: () => PromiseLike
         await new Promise(requestAnimationFrame);
 
     await unmount?.();
-    console.log(gc());
+    while (cleanupHooks.size) {
+        const hooks = Array.from(cleanupHooks); cleanupHooks.clear();
+        await Promise.all(hooks.map((hook) => hook()));
+    }
+
+    // Let pending Napi wrapper finalizers run before tearing down the engine:
+    // Bun.gc(true) marks unreachable wrappers but their ~GodotVar/~Variant
+    // (which unrefs RefCounted objects) only runs on later macrotasks — and one
+    // wrapper's finalizer can free others. Freeing the engine first would report
+    // every still-referenced RefCounted as leaked, so drain a few gc+tick rounds.
+    for (let i = 0; i < 4; i++) {
+        console.log(gc());
+        await new Promise((resolve) => setTimeout(resolve, 0));
+    }
     return godot.free();
 }
-

package/src/load.ts

@@ -8,9 +8,25 @@ 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 { cleanupHooks, stageFile } from './runtime.ts';
 import { decodeCtex } from './web-image.ts';
 
+// Each loaded wrapper is released at shutdown via a `cleanupHooks` entry
+// holding a WeakRef: module-scope asset imports (the preload modules' memoized
+// load promises) keep their wrappers reachable, so GC alone can't collect them
+// before the engine stops. WeakRef keeps the entries from pinning resources
+// during the app's lifetime.
+function track<T extends Resource>(res: T): T {
+    const ref = new WeakRef<Resource>(res);
+    cleanupHooks.add(() => {
+        const r = ref.deref();
+        if (r) {
+            try { r.free(); } catch {}
+        }
+    });
+    return res;
+}
+
 /**
  * A Godot `Resource` subclass constructor: its `.name` is the registered class
  * name (used as the `ResourceLoader` type hint), and `InstanceType<C>` is the
@@ -153,6 +169,7 @@ export function loadAsset<C extends ResourceConstructor>(
 	data: Record<string, unknown> = {},
 ): { materialize: Promise<unknown>; load: Promise<InstanceType<C>> } {
 	const cached = cachedResource<C>(path);
+	if (cached) cached.then(track);
 	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));
@@ -189,6 +206,10 @@ export async function loadResourceAsync<C extends ResourceConstructor>(
 			break;
 		}
 		if (status === ThreadLoadStatus.THREAD_LOAD_FAILED || status === ThreadLoadStatus.THREAD_LOAD_INVALID_RESOURCE) {
+			// Collect the engine's LoadToken so a failed load doesn't leave it
+			// registered (a bare `RefCounted` leaked at exit). Safe no-op when
+			// no token exists.
+			ResourceLoader.loadThreadedGet(path);
 			throw new Error(`loadResourceAsync(${path}): load failed (status ${status})`);
 		}
 		await nextTick();
@@ -206,5 +227,5 @@ export async function loadResourceAsync<C extends ResourceConstructor>(
 			}
 		}
 	}
-	return result;
+	return track(result);
 }

package/src/preload.ts

@@ -175,6 +175,22 @@ const assetPlugin: BunPlugin = {
 	name: 'godot-assets',
 	setup(build) {
 		build.onResolve({ filter: ASSET_RE }, (args) => {
+			// Only JS module imports of Godot source assets become `godot`
+			// modules. `Bun.build` reports JS imports as `import-statement`
+			// (and `dynamic-import`/`require-*`) but HTML asset references
+			// (<link>/<img>) and CSS url() refs as `internal`/`url-token` —
+			// those fall through so Bun copies/hashes the file normally. The
+			// runtime preload (bun run / bun test) reports JS imports with no
+			// kind (`undefined`), so treat that as a JS import too.
+			if (
+				args.kind !== undefined &&
+				args.kind !== 'import-statement' &&
+				args.kind !== 'dynamic-import' &&
+				args.kind !== 'require-call' &&
+				args.kind !== 'require-resolve'
+			) {
+				return;
+			}
 			const importerAbs = args.importer?.startsWith(`${NS}:`)
 				? args.importer.slice(NS.length + 1)
 				: args.importer;

package/src/runtime.ts

@@ -79,3 +79,6 @@ export function _P(signal: any, onfulfilled?: any, onrejected?: any) {
         if (res !== 0) reject(new Error('Failed to connect signal: error code ' + res));
     }).then(onfulfilled, onrejected);
 }
+
+/** Cleanup callbacks run once by `runGodot` just before the engine is freed; may be async. */
+export const cleanupHooks: Set<() => void | Promise<void>> = new Set();