@ringozz/godot 4.7.2-641 → 4.7.2-646

package/README.md

@@ -52,7 +52,8 @@ await import('./app.ts'); // may now import @ringozz/godot / react-godot freely
 | `@ringozz/godot/ClassName` | Classes, one per module — e.g. `@ringozz/godot/Label`, `@ringozz/godot/Node` |
 | `@ringozz/godot/runtime` | Low-level dispatch: `_C`, `_S`, `_R`, `_G`, `_P`, `_V`, `toValueType`, `getGodot`, `GodotVar` |
 | `@ringozz/godot/boot` | Platform boot: `getNativeModule()`; web `preloadGodot()` (awaited before importing the app; no-op on desktop) |
-| `@ringozz/godot/load` | Async resource loading: `loadResourceAsync`, `loadAsset` |
+| `@ringozz/godot/load` | Async resource loading: `loadResourceAsync`, `loadAsset`, `loadAssetPack` (native `.pck` packs) |
+| `@ringozz/godot/pack` | `buildAssetPack()` + the `godot pack` subcommand: bake a project's `.pck` + loose-texture manifest |
 | `@ringozz/godot/debug` | `initDebug()`, `dumpStr`, `snapshot`, `inspect`, `click`, `find`, `gc` |
 
 Class-scoped enums use bare names (import `ProcessMode` from `@ringozz/godot/Node`, not `NodeProcessMode`).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.2-641",
+  "version": "4.7.2-646",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
   "publishConfig": {
     "access": "public"
@@ -26,6 +26,7 @@
       "default": "./src/boot.ts"
     },
     "./load": "./src/load.ts",
+    "./pack": "./src/pack.ts",
     "./transcoder": {
       "browser": "./src/transcoder.browser.ts",
       "default": "./src/transcoder.ts"
@@ -65,9 +66,9 @@
     "precision": "single"
   },
   "optionalDependencies": {
-    "@ringozz/godot-macos-arm64": "^4.7.2-641",
-    "@ringozz/godot-windows-x86_64": "^4.7.2-641",
-    "@ringozz/godot-web-wasm32": "^4.7.2-641"
+    "@ringozz/godot-macos-arm64": "^4.7.2-646",
+    "@ringozz/godot-windows-x86_64": "^4.7.2-646",
+    "@ringozz/godot-web-wasm32": "^4.7.2-646"
   },
   "peerDependencies": {
     "@types/bun": "*"

package/src/dump-deps.gd

@@ -0,0 +1,109 @@
+@tool
+extends SceneTree
+## Dumps, for every packed source resource, the set of **loose** (WebP-backed)
+## texture sources that must stay out of the asset pack and be staged/transcoded
+## by the host. The preload plugin (`@ringozz/godot/preload`) reads deps.json so
+## it never scans source text for references.
+##
+## Sources of loose refs (union): the engine's `ResourceLoader.get_dependencies`
+## (for imported sources the real refs live on the imported product, reached via
+## the `.import` `dest_files`), plus a text scan for string-valued paths
+## (`albedo_array = "res://.../*.webparray"`, `load("res://...")`) that no static
+## resource edge exposes. A dep is *loose* when it has an `.import` sidecar but is
+## not a packed resource type — the set is derived, not listed.
+##
+## Driven by `@ringozz/godot/pack`'s `buildAssetPack`, which sets:
+##   GODOT_DUMP_OUT   – output res:// path (default res://.godot/packs/deps.json)
+##   GODOT_DUMP_ROOTS – comma-separated res:// roots to scan (default res://)
+
+const PACKED := ["tscn", "tres", "gltf", "obj", "gd", "gdshader", "gdshaderinc", "ttf", "otf", "po"]
+const SCANNED := ["tscn", "tres", "gd", "gdshader", "gdshaderinc", "gltf", "obj"]
+
+
+func _initialize() -> void:
+	var out := OS.get_environment("GODOT_DUMP_OUT")
+	if out.is_empty():
+		out = "res://.godot/packs/deps.json"
+	var roots := OS.get_environment("GODOT_DUMP_ROOTS").split(",", false)
+	if roots.is_empty():
+		roots = ["res://"]
+	var deps := {}
+	for r in roots:
+		_scan(String(r).rstrip("/") + "/", deps)
+	DirAccess.make_dir_recursive_absolute(ProjectSettings.globalize_path(out.get_base_dir()))
+	var f := FileAccess.open(out, FileAccess.WRITE)
+	f.store_string(JSON.stringify(deps, "  "))
+	f.close()
+	print("[dump-deps] ", deps.size(), " resources -> ", out)
+	quit()
+
+
+func _scan(path: String, out: Dictionary) -> void:
+	var d := DirAccess.open(path)
+	if d == null:
+		return
+	for dir in d.get_directories():
+		if dir.begins_with(".") or dir == "node_modules":
+			continue
+		_scan(path.path_join(dir) + "/", out)
+	for file in d.get_files():
+		var p := path.path_join(file)
+		if p.get_extension().to_lower() in PACKED:
+			out[p] = _loose(p)
+
+
+## The loose texture sources reachable from `path` (transitive), sorted.
+func _loose(path: String) -> Array:
+	var loose := {}
+	_collect(path, loose, {})
+	var arr := loose.keys()
+	arr.sort()
+	return arr
+
+
+func _classify(dep: String, loose: Dictionary, seen: Dictionary) -> void:
+	if dep.is_empty():
+		return
+	if dep.get_extension().to_lower() in PACKED:
+		_collect(dep, loose, seen)
+	elif FileAccess.file_exists(dep + ".import"):
+		loose[dep] = true
+
+
+func _collect(path: String, loose: Dictionary, seen: Dictionary) -> void:
+	if seen.has(path):
+		return
+	seen[path] = true
+	# An imported source's own `get_dependencies` is empty (the importer hides the
+	# refs); the imported *product* carries them — recurse through the sidecar.
+	var imp := path + ".import"
+	if FileAccess.file_exists(imp):
+		var cfg := ConfigFile.new()
+		if cfg.load(imp) == OK:
+			for dst in cfg.get_value("deps", "dest_files", []):
+				_collect(String(dst), loose, seen)
+	for dep in ResourceLoader.get_dependencies(path):
+		_classify(_res_path(String(dep)), loose, seen)
+	# String-valued resource paths are invisible to dependency analysis; scan the
+	# text for loose refs the engine cannot report.
+	if path.get_extension().to_lower() in SCANNED:
+		for p in _text_refs(path):
+			_classify(p, loose, seen)
+
+
+## `res://` path from a dependency entry (`uid://…::::res://…` or plain).
+func _res_path(dep: String) -> String:
+	var i := dep.find("res://")
+	if i < 0:
+		return ""
+	return dep.substr(i)
+
+
+## Literal `res://` paths appearing in a text source.
+func _text_refs(path: String) -> Array:
+	var re := RegEx.new()
+	re.compile('res://[^"\']+')
+	var refs := []
+	for m in re.search_all(FileAccess.get_file_as_string(path)):
+		refs.append(m.get_string())
+	return refs

package/src/editor.ts

@@ -94,7 +94,7 @@ async function provision(): Promise<void> {
     }
 }
 
-async function resolveEditor(): Promise<string> {
+export async function resolveEditor(): Promise<string> {
     if (process.env.GODOT_PATH) return process.env.GODOT_PATH;
     if (!process.env.GODOT_NODE_WRAPPER) {
         const system = systemGodot();
@@ -105,7 +105,13 @@ async function resolveEditor(): Promise<string> {
 }
 
 if (import.meta.main) {
-    const exe = await resolveEditor();
-    const result = spawnSync(exe, process.argv.slice(2), { stdio: 'inherit', env: { ...process.env, GODOT_NODE_WRAPPER: '1' } });
-    process.exit(result.status ?? 1);
+	const command = process.argv[2];
+	if (command === 'pack') {
+		const { buildAssetPack, parsePackArgs } = await import('./pack.ts');
+		await buildAssetPack(parsePackArgs(process.argv.slice(3)));
+		process.exit(0);
+	}
+	const exe = await resolveEditor();
+	const result = spawnSync(exe, process.argv.slice(2), { stdio: 'inherit', env: { ...process.env, GODOT_NODE_WRAPPER: '1' } });
+	process.exit(result.status ?? 1);
 }

package/src/export_presets.example.cfg

@@ -0,0 +1,37 @@
+; Example Godot export preset for `@ringozz/godot/pack`'s `buildAssetPack()`.
+; Copy to the project root as `export_presets.cfg` (the project owns it) and add
+; your own non-asset trees to `exclude_filter`.
+;
+; The texture sources (`*.webp`/`*.png`/… below) MUST stay excluded: the wasm
+; engine has no WebP decoder, so those products are staged/transcoded by the host
+; (see `dump-deps.gd`), not read from the pack. `export_filter="all_resources"`
+; ignores `include_filter` — scope with `exclude_filter` only.
+
+[preset.0]
+
+name="Pack"
+platform="Web"
+runnable=true
+dedicated_server=false
+custom_features=""
+export_filter="all_resources"
+include_filter=""
+exclude_filter="node_modules/*,.git/*,.godot/packs/*,*.webp,*.png,*.svg,*.jpg,*.jpeg,*.hdr,*.exr,*.webparray"
+export_path=""
+script_export_mode=2
+
+[preset.0.options]
+
+custom_template/debug=""
+custom_template/release=""
+variant/extensions_support=false
+variant/thread_support=false
+vram_texture_compression/for_desktop=false
+vram_texture_compression/for_mobile=false
+html/export_icon=true
+html/custom_html_shell=""
+html/head_include=""
+html/canvas_resize_policy=2
+html/focus_canvas_on_start=true
+html/experimental_virtual_keyboard=false
+progressive_web_app/enabled=false

package/src/load.ts

@@ -148,34 +148,19 @@ async function materialize([resPath, entry]: [string, AssetFile]): Promise<void>
 
 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.
+ * and imported products (`.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.
  */
-function materializeFiles(files: AssetFiles, deps: AssetModule[] = []): Promise<unknown> {
-	for (const dep of deps) {
-		dep.default.catch((err) => console.error('[godot] dependency load failed:', err));
-	}
+function materializeFiles(files: AssetFiles): Promise<unknown> {
 	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)]);
+	return Promise.all(Object.entries(files).map(materialize));
 }
 
 /**
@@ -200,18 +185,22 @@ function cachedResource<C extends ResourceConstructor>(path: string): Promise<In
  * 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.
+ * the `materialize` promise (bundled files staged) and the load promise.
  */
 export function loadAsset<C extends ResourceConstructor>(
 	path: string,
 	cls: C,
 	files: AssetFiles,
-	deps: AssetModule[] = [],
 	data: Record<string, unknown> = {},
+	ready?: Promise<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);
+	// `ready` mounts the pack(s) holding this asset (see `loadAssetPack`);
+	// staging waits for that so the pack's remaps are in place when the resource
+	// resolves. A no-op when omitted (desktop / no pack).
+	const mounted = ready ?? Promise.resolve();
+	const materialize = cached ? Promise.resolve() : mounted.then(() => materializeFiles(files));
 	const existing = data[path] as Promise<InstanceType<C>> | undefined;
 	const load = existing ?? cached ?? materialize.then(() => loadResourceAsync(path, cls, files));
 	data[path] = load;
@@ -270,3 +259,56 @@ export async function loadResourceAsync<C extends ResourceConstructor>(
 	}
 	return track(result);
 }
+
+// ── Asset packs ──────────────────────────────────────────────────────────────
+// Mounting for Godot `.pck` packs. A pack is fetched, its bytes staged into the
+// engine's filesystem (web: MEMFS via `copyToFS`; desktop: nothing — the working
+// tree is `res://`), then handed to `ProjectSettings.loadResourcePack`, whose
+// remap table resolves a source path (`res://scene.tscn`) to the packed binary.
+// Memoized per URL (shared by every module that references it); a failed mount is
+// evicted so a later call retries. PackedData is add-only — packs are never unloaded.
+
+const mounted = new Map<string, Promise<void>>();
+
+/** Mounts the `.pck` at `url` (fetch + stage + `loadResourcePack`). */
+export function loadAssetPack(url: string): Promise<void> {
+	const existing = mounted.get(url);
+	if (existing) {
+		return existing;
+	}
+	const p = mount(url);
+	mounted.set(url, p);
+	p.catch(() => {
+		if (mounted.get(url) === p) {
+			mounted.delete(url);
+		}
+	});
+	return p;
+}
+
+async function mount(url: string): Promise<void> {
+	if (stageFile === undefined) {
+		// Desktop: the app's assets exist on disk. External packs (a path) mount directly.
+		const external = /^([A-Za-z]:[\\/]|\/)/.test(url) || url.startsWith('res://');
+		if (external && !ProjectSettings.loadResourcePack(url)) {
+			throw new Error(`loadAssetPack(${url}): loadResourcePack failed`);
+		}
+		return;
+	}
+	const res = await fetch(url);
+	if (!res.ok) {
+		throw new Error(`loadAssetPack(${url}): fetch failed (${res.status})`);
+	}
+	const bytes = new Uint8Array(await res.arrayBuffer());
+	const resPath = `res://.packs/${packName(url)}`;
+	stageFile(ProjectSettings.globalizePath(resPath), bytes);
+	if (!ProjectSettings.loadResourcePack(resPath)) {
+		throw new Error(`loadAssetPack(${url}): loadResourcePack failed for ${resPath}`);
+	}
+}
+
+/** A filesystem-safe pack name derived from the URL (basename, query stripped). */
+function packName(url: string): string {
+	const base = url.split('?')[0].split('/').pop() ?? 'pack.pck';
+	return base.replace(/[^A-Za-z0-9._-]/g, '_') || 'pack.pck';
+}

package/src/pack.ts

@@ -0,0 +1,87 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveEditor } from './editor.ts';
+
+// Bakes a Godot project's assets for the runtime: imports, dumps the loose
+// (WebP-backed) texture dependency manifest (`dump-deps.gd`, via
+// `ResourceLoader.get_dependencies` + a text scan for string-valued paths — no
+// host-side scanning), and exports a native `.pck` carrying the engine-converted
+// binary resources + remap table. The preload plugin (`preload.ts`) consumes both.
+//
+// The project owns `export_presets.cfg` (a committed, editor-managed file): this
+// runs `--export-pack <preset>` against it. That preset must exclude the texture
+// sources (`*.webp`/`*.png`/…): the wasm build has no WebP decoder, so those
+// products stay loose and are staged/transcoded by the host. See
+// `export_presets.example.cfg` for a canonical preset.
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export interface BuildAssetPackOptions {
+	/** res:// roots whose assets are scanned for loose textures (default `['res://src']`). */
+	roots?: string[];
+	/** Output `.pck` path, project-relative (default `.godot/packs/app.pck`). */
+	pack?: string;
+	/** Output `deps.json` path, project-relative (default `.godot/packs/deps.json`). */
+	deps?: string;
+	/** `export_presets.cfg` preset name to export (default `Pack`). */
+	preset?: string;
+	/** Editor executable override (default: `resolveEditor()`). */
+	godot?: string;
+}
+
+export async function buildAssetPack(opts: BuildAssetPackOptions = {}): Promise<void> {
+	const roots = opts.roots ?? ['res://src'];
+	const pack = opts.pack ?? '.godot/packs/app.pck';
+	const deps = opts.deps ?? '.godot/packs/deps.json';
+	const preset = opts.preset ?? 'Pack';
+	const editor = opts.godot ?? (await resolveEditor());
+	const cwd = process.cwd();
+
+	const presets = resolve(cwd, 'export_presets.cfg');
+	if (!existsSync(presets) || !new RegExp(`^name=${JSON.stringify(preset)}$`, 'm').test(readFileSync(presets, 'utf8'))) {
+		throw new Error(`godot-assets: no "${preset}" preset in export_presets.cfg (see export_presets.example.cfg).`);
+	}
+
+	const run = (args: string[], env?: Record<string, string>) => {
+		const r = spawnSync(editor, args, { cwd, stdio: 'inherit', env: { ...process.env, ...env } });
+		if ((r.status ?? 1) !== 0) {
+			throw new Error(`godot-assets: \`${editor} ${args.join(' ')}\` failed (${r.status})`);
+		}
+	};
+
+	mkdirSync(resolve(cwd, dirname(pack)), { recursive: true });
+	mkdirSync(resolve(cwd, dirname(deps)), { recursive: true });
+
+	run(['--headless', '--path', '.', '--import']);
+
+	const dump = resolve(cwd, '.godot', 'pack-dump-deps.gd');
+	copyFileSync(resolve(HERE, 'dump-deps.gd'), dump);
+	run(['--headless', '--path', '.', '--script', 'res://.godot/pack-dump-deps.gd'], {
+		GODOT_DUMP_OUT: `res://${deps.replace(/^res:\/\//, '')}`,
+		GODOT_DUMP_ROOTS: roots.join(','),
+	});
+
+	run(['--headless', '--path', '.', '--export-pack', preset, pack]);
+}
+
+/** Parses `godot pack` CLI args into {@link BuildAssetPackOptions}. */
+export function parsePackArgs(args: string[]): BuildAssetPackOptions {
+	const opt = (flag: string): string | undefined => {
+		const i = args.indexOf(flag);
+		return i >= 0 ? args[i + 1] : undefined;
+	};
+	const list = (flag: string): string[] | undefined => opt(flag)?.split(',').filter(Boolean);
+	return {
+		roots: list('--roots'),
+		pack: opt('--pack'),
+		deps: opt('--deps'),
+		preset: opt('--preset'),
+		godot: opt('--godot'),
+	};
+}

package/src/preload.ts

@@ -8,52 +8,52 @@ import { plugin } from 'bun';
 import type { BunPlugin } from 'bun';
 
 // Registers the godot-assets plugin: imports of Godot source assets become
-// virtual modules (namespace `godot`) that call `loadAsset` (`@ringozz/godot/load`)
-// and export the resulting `materialize` (own + deps' files) and load promise.
-// `loadAsset` checks the engine's `ResourceCache` once; when the asset is
-// already loaded (e.g. a re-evaluated module under web HMR) the load resolves to
-// the cached instance and `materialize` short-circuits, skipping file staging
-// and the threaded load. The load promise persists on the module's
-// `import.meta.hot.data` (per-module state carried across hot replacements), so
-// HMR re-evaluations return the *same* fulfilled promise object — React's `use()`
-// keeps its tracked status and never re-suspends (no Suspense fallback flash); a
-// rejected load is evicted from `data` so the next evaluation retries; on
-// desktop `data` is `{}` and modules evaluate once. Dependencies are generated
-// modules too, so a dep's load starts at module evaluation while the parent only
-// waits for dep *files*. The default export is the single plugin — registered
-// globally via bunfig preload and loaded by `[serve.static] plugins` for
-// `Bun.serve` HTML routes.
+// virtual modules (namespace `godot`) that mount the project's asset pack and
+// load the resource.
+//
+// A packed source asset (`tscn`/`tres`/`gltf`/`gd`/font/…) is loaded from the
+// `.pck` baked by `godot pack`: the module mounts the pack (`loadAssetPack`),
+// whose remap table resolves the source path to the packed binary (`.scn`/`.res`)
+// with refs the engine resolves itself. The
+// plugin never scans source text for references — the only per-file staging is
+// for *loose* (WebP-backed) textures the wasm engine cannot decode, whose list
+// is computed by the engine (`@ringozz/godot/pack`'s `dump-deps.gd` ->
+// `.godot/packs/deps.json`, via `ResourceLoader.get_dependencies`).
+//
+// The load promise persists on `import.meta.hot.data` (carried across HMR
+// re-evaluations) so `use()` never re-suspends; a rejected load is evicted so
+// the next evaluation retries. The default export is the single plugin —
+// registered globally via bunfig preload and loaded by `[serve.static] plugins`.
 
 const ROOT = process.cwd();
 const NS = 'godot';
 
-/** Format metadata: `cls` = Godot class (importable), `scan` = scan text refs, `native` = no `.import` sidecar. */
-const FORMATS: Record<string, { cls?: string; scan?: boolean; native?: boolean }> = {
-	gltf: { cls: 'PackedScene', scan: true },
-	tscn: { cls: 'PackedScene', scan: true, native: true },
-	obj: { cls: 'PackedScene', scan: true },
-	gd: { cls: 'GDScript', scan: true, native: true },
-	gdshader: { cls: 'Shader', scan: true, native: true },
-	gdshaderinc: { cls: 'ShaderInclude', scan: true, native: true },
-	jpg: { cls: 'CompressedTexture2D' },
-	jpeg: { cls: 'CompressedTexture2D' },
-	png: { cls: 'CompressedTexture2D' },
-	webp: { cls: 'CompressedTexture2D' },
+/** Extension -> class. `loose` = WebP-backed texture excluded from the pack, staged/transcoded per-file. */
+const FORMATS: Record<string, { cls?: string; loose?: boolean }> = {
+	gltf: { cls: 'PackedScene' },
+	tscn: { cls: 'PackedScene' },
+	obj: { cls: 'PackedScene' },
+	gd: { cls: 'GDScript' },
+	gdshader: { cls: 'Shader' },
+	gdshaderinc: { cls: 'ShaderInclude' },
+	jpg: { cls: 'CompressedTexture2D', loose: true },
+	jpeg: { cls: 'CompressedTexture2D', loose: true },
+	png: { cls: 'CompressedTexture2D', loose: true },
+	webp: { cls: 'CompressedTexture2D', loose: true },
 	// The layer manifest `godot/addons/sourcewebp` imports into a `.ctexarray` (a texture array whose
-	// layers are source WebP bytes). No `scan`: the layer paths it lists are import-time inputs, not
-	// runtime deps, so the host must not stage them.
-	webparray: { cls: 'CompressedTexture2DArray' },
-	svg: { cls: 'CompressedTexture2D' },
-	exr: { cls: 'TextureLayered' },
-	hdr: { cls: 'TextureLayered' },
+	// layers are source WebP bytes). It has no runtime deps of its own; the host stages its product.
+	webparray: { cls: 'CompressedTexture2DArray', loose: true },
+	svg: { cls: 'CompressedTexture2D', loose: true },
+	exr: { cls: 'TextureLayered', loose: true },
+	hdr: { cls: 'TextureLayered', loose: true },
 	wav: { cls: 'AudioStreamWAV' },
 	ogg: { cls: 'AudioStreamOggVorbis' },
 	mp3: { cls: 'AudioStreamMP3' },
-	tres: { cls: 'Resource', scan: true, native: true },
-	po: { cls: 'Translation', native: true },
+	tres: { cls: 'Resource' },
+	po: { cls: 'Translation' },
 	ttf: { cls: 'FontFile' },
 	otf: { cls: 'FontFile' },
-	mtl: { scan: true },
+	mtl: {},
 };
 
 const ASSET_RE = new RegExp(
@@ -63,14 +63,23 @@ const ASSET_RE = new RegExp(
 const CLASS_BY_EXT: Record<string, string> = Object.fromEntries(
 	Object.entries(FORMATS).filter(([, f]) => f.cls).map(([k, f]) => [k, f.cls!]),
 );
-const SCANNED = new Set(Object.entries(FORMATS).filter(([, f]) => f.scan).map(([k]) => k));
-const NATIVE = new Set(Object.entries(FORMATS).filter(([, f]) => f.native).map(([k]) => k));
+const LOOSE = new Set(Object.entries(FORMATS).filter(([, f]) => f.loose).map(([k]) => k));
 
 const extOf = (abs: string) => abs.slice(abs.lastIndexOf('.') + 1).toLowerCase();
 const resOf = (abs: string) => 'res://' + abs.slice(ROOT.length + 1).replaceAll('\\', '/');
-const isScannableText = (abs: string) => SCANNED.has(extOf(abs));
-const isNativeText = (abs: string) => NATIVE.has(extOf(abs));
-const isSourceAsset = (abs: string) => existsSync(abs + '.import') || isNativeText(abs);
+const isLoose = (abs: string) => LOOSE.has(extOf(abs));
+
+// A project may bake a native `.pck` (`godot --export-pack`, path overridable via
+// `GODOT_PACK`) carrying the engine-converted binary resources + remap table. Its
+// sibling `deps.json` (from `scripts/dump-deps.gd`) maps each packed source to the
+// loose textures it references. Both are optional: without them (desktop, or a
+// project that hasn't baked a pack) modules load source paths directly.
+const PACK_ABS = resolve(ROOT, process.env.GODOT_PACK ?? '.godot/packs/app.pck');
+const HAS_PACK = existsSync(PACK_ABS);
+const DEPS_ABS = resolve(dirname(PACK_ABS), 'deps.json');
+const DEPS: Record<string, string[]> = existsSync(DEPS_ABS)
+	? (JSON.parse(readFileSync(DEPS_ABS, 'utf8')) as Record<string, string[]>)
+	: {};
 
 /** Reads the imported destination (`dest_files`) out of an `.import` sidecar. */
 function parseSidecarDest(text: string): string | null {
@@ -85,120 +94,52 @@ function parseSidecarDest(text: string): string | null {
 	return remap ? remap[1] : null;
 }
 
-// Reference extraction for text-based source assets: absolute `res://` paths
-// (Godot scenes/resources) and relative path tokens ending in a known asset
-// extension (glTF uris, OBJ/MTL textures). The literal dot before the extension
-// avoids matching MIME types inside `data:` URIs. Regexes are built fresh per
-// call: a `/g` instance is stateful, and reusing one module-level regex across
-// many files misbehaves under the dev server's bundler (a stale lastIndex
-// shifted a scan's results). The `//` fragment right after `res:` is a mere
-// path remainder of the `res://` match, not a real relative ref, so it's
-// skipped (otherwise it mis-resolves as a Windows UNC `\\…` path).
-//
-// The extension must TERMINATE a token: `(?![\w.])` rejects matches where the
-// extension is only the head of a longer identifier or a dotted sub-field, e.g.
-// `X.po` in `X.position`, `foo.gd` in `foo.gd.position`, or `scene.tscn2`. A
-// real relative ref (`foo.po`, `x.gd`, `ui/scene.tscn`) always ends its token.
-// `String.raw` keeps the `\w` escapes intact — a plain template literal would
-// drop the backslashes, turning `\w` into `w` (a wrong guard `(?![w.])`).
-const REL_TERM = String.raw`(?![\w.])`;
-const REL_PATTERN = String.raw`([\w./\\-]+\.(?:` + Object.keys(FORMATS).join('|') + `))` + REL_TERM;
-function extractRefs(text: string): string[] {
-	const refs: string[] = [];
-	for (const m of text.matchAll(/res:\/\/[\w./\\-]+/g)) refs.push(m[0]);
-	const rel = new RegExp(REL_PATTERN, 'g');
-	for (const m of text.matchAll(rel)) if (!m[1].startsWith('/')) refs.push(m[1]);
-	return refs;
-}
-
-/**
- * Adds a source asset's own files to `files`: imported assets contribute their
- * `.import` sidecar (text) + imported product (file); native text formats
- * (tscn/tres/po/gd) contribute the file itself (text).
- */
-function addSource(srcAbs: string, files: Map<string, 'text' | 'file'>): void {
+/** Adds a loose texture source to `files`: its `.import` sidecar (text) + product (file). */
+function addLoose(srcAbs: string, files: Map<string, 'text' | 'file'>): void {
 	const impAbs = srcAbs + '.import';
-	if (existsSync(impAbs)) {
-		files.set(resOf(srcAbs) + '.import', 'text');
-		const dest = parseSidecarDest(readFileSync(impAbs, 'utf8'));
-		if (dest) {
-			files.set(dest, 'file');
-		}
-	} else if (isNativeText(srcAbs)) {
-		stageNativeText(srcAbs, files);
-	}
-}
-
-/** Stages a native text source (`res://` path → `text`) so web staging + inlining picks it up. */
-function stageNativeText(srcAbs: string, files: Map<string, 'text' | 'file'>): void {
-	files.set(resOf(srcAbs), 'text');
-}
-
-/**
- * Collects the referenced source assets (deps) of a text source: every referenced
- * source asset is staged (native text → `files`, products → dep modules), and
- * loadable source assets also become dep modules so their own files + transitive
- * deps are handled. Raw text formats without a sidecar (`.mtl`) are recursed into.
- * Buffers (`.bin`) are skipped.
- */
-function collectDeps(abs: string, visited: Set<string>, deps: string[], files: Map<string, 'text' | 'file'>): void {
-	if (visited.has(abs)) {
-		return;
-	}
-	visited.add(abs);
-	if (!isScannableText(abs)) {
+	if (!existsSync(impAbs)) {
 		return;
 	}
-	for (const ref of extractRefs(readFileSync(abs, 'utf8'))) {
-		const refAbs = ref.startsWith('res://')
-			? resolve(ROOT, ref.slice('res://'.length))
-			: resolve(dirname(abs), ref);
-		if (visited.has(refAbs)) {
-			continue;
-		}
-		// Stage native text (e.g. `.gd`, nested `.tscn`) so the engine loads it
-		// by `res://` on web (idempotent); loadable assets also become dep
-		// modules for their own files + transitive deps.
-		if (isSourceAsset(refAbs)) {
-			if (isNativeText(refAbs)) {
-				visited.add(refAbs);
-				stageNativeText(refAbs, files);
-			}
-			if (CLASS_BY_EXT[extOf(refAbs)]) {
-				deps.push(refAbs);
-			}
-		}
-		// Any scannable ref (a source's own text, or a raw leaf like `.mtl`) is
-		// recursed into so its internal `res://` refs are traced/staged too.
-		if (isScannableText(refAbs)) {
-			collectDeps(refAbs, visited, deps, files);
-		}
+	files.set(resOf(srcAbs) + '.import', 'text');
+	const dest = parseSidecarDest(readFileSync(impAbs, 'utf8'));
+	if (dest) {
+		files.set(dest, 'file');
 	}
 }
 
-function analyze(abs: string): { files: Map<string, 'text' | 'file'>; deps: string[] } {
+function analyze(abs: string): Map<string, 'text' | 'file'> {
 	const files = new Map<string, 'text' | 'file'>();
-	const deps: string[] = [];
-	addSource(abs, files);
-	collectDeps(abs, new Set(), deps, files);
-	return { files, deps };
+	// A directly imported loose texture stages itself; a packed resource stages the
+	// loose textures the engine's dependency dump found for it.
+	if (isLoose(abs)) {
+		addLoose(abs, files);
+	}
+	for (const loose of DEPS[resOf(abs)] ?? []) {
+		addLoose(resolve(ROOT, loose.slice('res://'.length)), files);
+	}
+	return files;
 }
 
 function ensureModule(abs: string): string {
 	const res = resOf(abs);
 	const cls = CLASS_BY_EXT[extOf(abs)] ?? 'Resource';
-	const { files, deps } = analyze(abs);
+	const files = analyze(abs);
 
 	const imports = [
-		`import { loadAsset } from '@ringozz/godot/load';`,
+		`import { loadAsset, loadAssetPack } from '@ringozz/godot/load';`,
 		`import { ${cls} } from '@ringozz/godot/${cls}';`,
 	];
+	let ready = 'undefined';
+	if (HAS_PACK) {
+		imports.push(`import pack0 from ${JSON.stringify(PACK_ABS)} with { type: 'file' };`);
+		ready = 'loadAssetPack(pack0)';
+	}
 	const map: string[] = [];
 	let fi = 0;
-	// Text files (own `.tscn`/`.tres`/`.po`, `.import` sidecars, staged `.gd`
-	// leaves) are inlined as string literals — Bun's `with { type: 'text' }`
-	// import resolves to a null/default under the dev server's HMR wrapper for
-	// a module's own path; products (`.scn`/`.ctex`) are fetched by path.
+	// Loose texture files: sidecars as inlined string literals (Bun's
+	// `with { type: 'text' }` import resolves to a null/default under the dev
+	// server's HMR wrapper for a module's own path), products fetched by path so
+	// the host can transcode them.
 	for (const [resPath, kind] of files) {
 		const absP = resolve(ROOT, resPath.slice('res://'.length));
 		if (kind === 'text') {
@@ -209,10 +150,9 @@ function ensureModule(abs: string): string {
 		imports.push(`import ${v} from ${JSON.stringify(absP)} with { type: 'file' };`);
 		map.push(`  ${JSON.stringify(resPath)}: { path: ${v} },`);
 	}
-	deps.forEach((dep, i) => imports.push(`import * as dep${i} from ${JSON.stringify(dep)};`));
 
 	const filesVar = files.size ? `const files = {\n${map.join('\n')}\n};` : `const files = {};`;
-	const loadAsset = `const { materialize, load } = loadAsset(${JSON.stringify(res)}, ${cls}, files, [${deps.map((_, i) => `dep${i}`).join(', ')}], import.meta.hot.data);`;
+	const loadAsset = `const { materialize, load } = loadAsset(${JSON.stringify(res)}, ${cls}, files, import.meta.hot.data, ${ready});`;
 	return imports.join('\n') + '\n' + filesVar + '\n' + loadAsset + '\n' + `export { materialize, load as default };` + '\n';
 }
 
@@ -220,13 +160,13 @@ 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.
+			// 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' &&
@@ -236,17 +176,8 @@ const assetPlugin: BunPlugin = {
 			) {
 				return;
 			}
-			const importerAbs = args.importer?.startsWith(`${NS}:`)
-				? args.importer.slice(NS.length + 1)
-				: args.importer;
-			const base = importerAbs ? dirname(importerAbs) : (args.resolveDir ?? ROOT);
-			const abs = resolve(base, args.path);
-			// A module's own native-text source (e.g. `.tscn`) self-imports the
-			// same path — let it load as a real file.
-			if (abs === importerAbs) {
-				return;
-			}
-			return { path: abs, namespace: NS };
+			const base = args.importer ? dirname(args.importer) : (args.resolveDir ?? ROOT);
+			return { path: resolve(base, args.path), namespace: NS };
 		});
 		build.onLoad({ filter: /.*/, namespace: NS }, (args) => ({
 			contents: ensureModule(args.path),

package/src/web-image.ts

@@ -12,8 +12,8 @@
 // a single parse/allocate pair covers everything — a container is just a list of
 // layers.
 //
-// Exposes the container/format helpers, `pickGodotFormats` (probing the WebGL2
-// extensions GLES3 checks) and `decodeCtex` — the default staging path, which
+// Exposes the container/format helpers, `pickGodotFormats` (the driver's
+// compressed-format list) and `decodeCtex` — the default staging path, which
 // decodes the PNG/WebP payloads with the browser and rebuilds a raw RGBA8
 // container so no image codec runs in wasm. The optional compressed-transcode
 // hook lives in load.ts.
@@ -209,16 +209,50 @@ export function allocateCtex(
 }
 
 // ---------------------------------------------------------------------------
-// Capability probing. Godot's Compatibility (GLES3) renderer is what the web
-// wasm build uses, and it only uploads a compressed format natively when the
-// matching GL extension is present; this build compiles in NO decompressors, so
-// a format the device can't upload breaks the texture rather than degrading.
-// It selects formats for layered/3D textures exactly as for 2D — the
-// `astc_layered_supported`/`astc_3d_supported` flags it computes are only used
-// to derive `astc_supported`/`astc_hdr_supported` — so this probe covers texture
-// arrays and cubemaps too.
+// Capability probing. GLES3 uploads a compressed format only when its config
+// reports it supported, and this build compiles in NO decompressors, so a format
+// the device can't upload breaks the texture rather than degrading. Ask the
+// driver (`COMPRESSED_TEXTURE_FORMATS`) rather than reading extension names:
+// Chrome on Windows lists no ETC2/EAC and rejects those uploads, while
+// `config.cpp` would still route one to it. RGTC arrays are the one place 2D and
+// layered differ — `_texture_set_data` force-decompresses them for
+// `TEXTURE_2D_ARRAY`, gated here on `Image::can_decompress("s3tc")`.
 // ---------------------------------------------------------------------------
 
+// `CompressedTexture` GL enums -> Godot `Image::Format`, for the targets the
+// encoder can emit; only the unsigned-normal variants (their siblings share it).
+const GL_TO_GODOT_FORMAT: Record<number, number> = {
+	0x83f0: FORMAT_DXT1, // COMPRESSED_RGB_S3TC_DXT1_EXT
+	0x8dbb: FORMAT_RGTC_R, // COMPRESSED_RED_RGTC1_EXT
+	0x8dbd: FORMAT_RGTC_RG, // COMPRESSED_RED_GREEN_RGTC2_EXT
+	0x8e8c: FORMAT_BPTC_RGBA, // COMPRESSED_RGBA_BPTC_UNORM_EXT
+	0x9270: FORMAT_ETC2_R11, // COMPRESSED_R11_EAC
+	0x9272: FORMAT_ETC2_RG11, // COMPRESSED_RG11_EAC
+	0x9274: FORMAT_ETC2_RGB8, // COMPRESSED_RGB8_ETC2
+	0x93b0: FORMAT_ASTC_4x4, // COMPRESSED_RGBA_ASTC_4x4_KHR
+};
+
+/** Enabled before reading the list — a browser may only list a format once its extension is enabled. */
+const PROBED_EXTENSIONS = [
+	'EXT_texture_compression_bptc',
+	'EXT_texture_compression_rgtc',
+	'WEBGL_compressed_texture_s3tc',
+	'WEBGL_compressed_texture_astc',
+	'WEBGL_compressed_texture_etc',
+];
+
+/** The Godot targets among a driver's `COMPRESSED_TEXTURE_FORMATS` list, in list order and deduplicated (pure). */
+export function godotFormatsFor(glFormats: ArrayLike<number>): number[] {
+	const formats = new Set<number>();
+	for (let i = 0; i < glFormats.length; i++) {
+		const godot = GL_TO_GODOT_FORMAT[glFormats[i]!];
+		if (godot !== undefined) {
+			formats.add(godot);
+		}
+	}
+	return [...formats];
+}
+
 /**
  * Compressed `Image::Format` targets the running device can upload. A list
  * because the encoder may also reject a format the browser exposes (e.g. spark
@@ -248,31 +282,15 @@ export function pickGodotFormats(): number[] {
 	if (!gl) {
 		return [];
 	}
-	const formats: number[] = [];
 	try {
-		const exts = new Set(gl.getSupportedExtensions() ?? []);
-		if (exts.has('EXT_texture_compression_bptc')) {
-			formats.push(FORMAT_BPTC_RGBA);
-		}
-		if (exts.has('EXT_texture_compression_rgtc')) {
-			formats.push(FORMAT_RGTC_RG);
-			formats.push(FORMAT_RGTC_R);
-		}
-		if (exts.has('WEBGL_compressed_texture_astc')) {
-			formats.push(FORMAT_ASTC_4x4);
-		}
-		if (exts.has('WEBGL_compressed_texture_s3tc')) {
-			formats.push(FORMAT_DXT1);
+		for (const name of PROBED_EXTENSIONS) {
+			gl.getExtension(name);
 		}
-		// ETC2/EAC is core WebGL2 (ES 3.0), which is how Godot's web config
-		// reports it (`etc2_supported = true` for non-GLES-over-GL) — so these
-		// are always uploadable, independent of any extension.
-		formats.push(FORMAT_ETC2_RGB8, FORMAT_ETC2_RG11, FORMAT_ETC2_R11);
+		return godotFormatsFor(gl.getParameter(gl.COMPRESSED_TEXTURE_FORMATS) as ArrayLike<number>);
 	} finally {
 		// Don't retain the probe context for the page's lifetime.
 		gl.getExtension('WEBGL_lose_context')?.loseContext();
 	}
-	return formats;
 }
 
 /**