@ringozz/godot 4.7.2-649 → 4.7.2-654

package/README.md

@@ -53,7 +53,7 @@ await import('./app.ts'); // may now import @ringozz/godot / react-godot freely
 | `@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`, `loadAssetPack` (native `.pck` packs) |
-| `@ringozz/godot/pack` | `buildAssetPack()` + the `godot pack` subcommand: bake a project's `.pck` + loose-texture manifest |
+| `@ringozz/godot/pack` | `buildAssetPacks()` + the `godot pack` subcommand: bake a project's `.pck`(s) + loose-texture manifest, one pack per scene |
 | `@ringozz/godot/debug` | `initDebug()`, `dumpStr`, `snapshot`, `inspect`, `click`, `find`, `gc` |
 
 Class-scoped enums use bare names (import `ProcessMode` from `@ringozz/godot/Node`, not `NodeProcessMode`).
@@ -90,9 +90,22 @@ const node  = scene.instantiate();
 const tex   = await loadResourceAsync('res://textures/icon.jpg', Texture2D); // 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.
+- `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. `files` lists overlap (a scene and the model it instantiates can share one loose texture), so a product may need re-staging after another module's cleanup: `materialize` creates the parent directory itself and treats an already-staged file as done, because the engine's `copyToFS` throws on a path that is already there while `FileAccess.fileExists('res://…')` cannot see the Emscripten spelling of it.
 - `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 packs
+
+`godot pack` (the `godot` bin, `@ringozz/godot/pack`) bakes a project's assets for the runtime: it imports them, asks `dump-deps.gd` for each source's packed closure and its loose (WebP-backed) textures, and exports native `.pck`s — the engine-converted binary resources plus a remap table — through the project's committed `export_presets.cfg`. `loadAssetPack(url)` fetches a pack into MEMFS and hands it to `ProjectSettings.loadResourcePack`; packs are add-only, so several can be mounted and `res://` resolves across all of them.
+
+The bake always splits: **one pack per scene, plus a shared pack**, so a host fetches the shared data and only the level it is playing. A project with no scene under its roots gets a single `shared.pck`. What the runtime reads is `.godot/packs/packs.json` beside the packs: which packs exist, which sources each owns, and which loose (WebP-backed) textures the host must stage and transcode per file. The preload plugin mounts the right packs per asset, so importing a level pulls in the shared pack and that level's, nothing else. How the split is decided — and why it needs no configuration — is in `AGENTS.md`.
+
+```ts
+import { loadAssetPack } from '@ringozz/godot/load';
+await loadAssetPack('/packs/shared.pck');   // usually the preload plugin does this per asset
+```
+
+### Asset imports
+
 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.2-649",
+  "version": "4.7.2-654",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
   "publishConfig": {
     "access": "public"
@@ -66,9 +66,9 @@
     "precision": "single"
   },
   "optionalDependencies": {
-    "@ringozz/godot-macos-arm64": "^4.7.2-649",
-    "@ringozz/godot-windows-x86_64": "^4.7.2-649",
-    "@ringozz/godot-web-wasm32": "^4.7.2-649"
+    "@ringozz/godot-macos-arm64": "^4.7.2-654",
+    "@ringozz/godot-windows-x86_64": "^4.7.2-654",
+    "@ringozz/godot-web-wasm32": "^4.7.2-654"
   },
   "peerDependencies": {
     "@types/bun": "*"

package/src/dump-deps.gd

@@ -1,112 +1,126 @@
-@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://)
-
-## Imported source extensions: `_classify` recurses into these (an imported source's own deps are
-## empty — its *product* carries the refs) where any other extension with a sidecar is a loose texture.
-## `gltfx` is a scene-composition source: its product references the meshes and textures it composes.
-const PACKED := ["tscn", "tres", "gltf", "gltfx", "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
+@tool
+extends SceneTree
+## Dumps, for every packable (`.import`-less) source under the given roots, two things:
+##  - `loose`: the **loose** (WebP-backed) texture sources it needs — those must stay out of
+##    the asset packs and be staged/transcoded by the host, and the preload plugin
+##    (`@ringozz/godot/preload`) reads them from the manifest beside the packs so it never
+##    scans source text for references.
+##  - `packed`: the packed sources reachable from it — the graph `@ringozz/godot/pack`'s
+##    `splitPacks` uses to decide which pack owns a source (the ones only one scene reaches
+##    are that scene's).
+##
+## Sources of both (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 `buildAssetPacks`, which sets:
+##   GODOT_DUMP_OUT   – output res:// path (default res://.godot/pack-dump.json) — a build
+##                      input: the bake merges it into the manifest beside the packs.
+##   GODOT_DUMP_ROOTS – comma-separated res:// roots to scan (default res://)
+
+## Imported source extensions: `_classify` recurses into these (an imported source's own deps are
+## empty — its *product* carries the refs) where any other extension with a sidecar is a loose texture.
+## `gltfx` is a scene-composition source and `gltfxmesh` a shared-mesh one: their products reference the
+## meshes and textures they compose.
+const PACKED := ["tscn", "tres", "gltf", "gltfx", "gltfxmesh", "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/pack-dump.json"
+	var roots := OS.get_environment("GODOT_DUMP_ROOTS").split(",", false)
+	if roots.is_empty():
+		roots = ["res://"]
+	var sources := {}
+	for r in roots:
+		_scan(String(r).rstrip("/") + "/", sources)
+	DirAccess.make_dir_recursive_absolute(ProjectSettings.globalize_path(out.get_base_dir()))
+	var f := FileAccess.open(out, FileAccess.WRITE)
+	f.store_string(JSON.stringify(sources, "  "))
+	f.close()
+	print("[dump-deps] ", sources.size(), " sources -> ", out)
+	quit()
+
+
+func _scan(path: String, sources: 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) + "/", sources)
+	for file in d.get_files():
+		var p := path.path_join(file)
+		if p.get_extension().to_lower() in PACKED:
+			var seen := {}
+			var loose := _loose(p, seen)
+			# The graph holds authored packed sources only: the walk also visits the engine's
+			# own products (`res://.godot/imported/…`, reached through the `.import` sidecar),
+			# and a product is carried by its *source*, not owned in its own right.
+			var packed := seen.keys().filter(func(s: String) -> bool: return not s.begins_with("res://.godot/"))
+			packed.sort()
+			sources[p] = {"packed": packed, "loose": loose}
+
+
+## The loose texture sources reachable from `path` (transitive), sorted. `seen` collects every
+## packed source the walk touches — the graph — including `path` itself.
+func _loose(path: String, seen: Dictionary) -> Array:
+	var loose := {}
+	_collect(path, loose, seen)
+	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

@@ -107,8 +107,8 @@ export async function resolveEditor(): Promise<string> {
 if (import.meta.main) {
 	const command = process.argv[2];
 	if (command === 'pack') {
-		const { buildAssetPack, parsePackArgs } = await import('./pack.ts');
-		await buildAssetPack(parsePackArgs(process.argv.slice(3)));
+		const { buildAssetPacks, parsePackArgs } = await import('./pack.ts');
+		await buildAssetPacks(parsePackArgs(process.argv.slice(3)));
 		process.exit(0);
 	}
 	const exe = await resolveEditor();

package/src/export_presets.example.cfg

@@ -1,4 +1,4 @@
-; Example Godot export preset for `@ringozz/godot/pack`'s `buildAssetPack()`.
+; Example Godot export preset for `@ringozz/godot/pack`'s `buildAssetPacks()`.
 ; Copy to the project root as `export_presets.cfg` (the project owns it) and add
 ; your own non-asset trees to `exclude_filter`.
 ;
@@ -6,6 +6,10 @@
 ; 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.
+;
+; The bake always splits — one pack per scene (`Pack: <scene>`) plus a shared one — and
+; derives those presets from this one, pruning them again after exporting. Don't write
+; them by hand.
 
 [preset.0]
 

package/src/load.ts

@@ -143,7 +143,16 @@ async function materialize([resPath, entry]: [string, AssetFile]): Promise<void>
 	} else {
 		return;
 	}
-	stageFile?.(ProjectSettings.globalizePath(resPath), bytes);
+	// A staged product may already be there even though `FileAccess.fileExists(resPath)` says
+	// otherwise — the engine's `res://` lookup and the Emscripten path disagree by the leading
+	// slash — and the engine's `copyToFS` throws on a file it already has (`FS.createDataFile`
+	// does not replace). `files` lists overlap, and staged products are removed once their
+	// resource loads, so this is the normal re-stage, not an error: the bytes are the same file.
+	try {
+		stageFile?.(ProjectSettings.globalizePath(resPath), bytes);
+	} catch (err) {
+		if (!FileAccess.fileExists(ProjectSettings.globalizePath(resPath).replace(/\/{2,}/g, '/'))) throw err;
+	}
 }
 
 const nextTick = () => new Promise(requestAnimationFrame);

package/src/pack.ts

@@ -1,87 +1,241 @@
-/**********************************************************************
- 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'),
-	};
-}
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } 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 them, then exports one native
+// `.pck` **per scene** plus a shared one, so a host fetches the shared data and only the
+// level it is playing. `dump-deps.gd` supplies both inputs (no host-side scanning): each
+// source's packed closure — which decides what a pack owns — and the loose (WebP-backed)
+// texture sources, which the host stages and transcodes per file.
+//
+// The result the runtime reads is one file beside the packs: `<out>/packs.json`, holding
+// each pack (its path, whether it mounts always, and the sources it owns) plus those loose
+// texture lists. `preload.ts` reads it to mount the right packs per asset.
+//
+// The project owns `export_presets.cfg` (a committed, editor-managed file), and the scoping
+// has to live there: `--export-pack` runs against a preset. Per-pack scoping is therefore an
+// `exclude_filter` — the repo's `all_resources` convention, which ignores `include_filter`
+// and, unlike the selected modes, never pulls dependencies back in — so each pack excludes
+// exactly the sources the others own (see `splitPacks`). Those presets are cloned from the
+// project's own base preset, one written at a time, and the file is restored when the bake
+// ends: they are derived and the file is tracked.
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The dump's one build-time output, merged into the manifest beside the packs. */
+const DUMP = '.godot/pack-dump.json';
+
+export interface BuildAssetPackOptions {
+	/** res:// roots whose assets are baked (default `['res://src']`). */
+	roots?: string[];
+	/** Output directory for the packs + manifest, project-relative (default `.godot/packs`). */
+	out?: string;
+	/** The `export_presets.cfg` preset the generated pack presets derive from (default `Pack`). */
+	preset?: string;
+	/** Editor executable override (default: `resolveEditor()`). */
+	godot?: string;
+}
+
+/** A pack's assignment: its name, whether it mounts always, and the sources it owns. */
+interface AssetPackSplit {
+	/** `shared`, or a scene's file stem. */
+	name: string;
+	/** Mount for every asset (the shared pack). */
+	always?: boolean;
+	/** The packable sources this pack owns — the lookup the plugin mounts by. */
+	owns: string[];
+}
+
+/** One baked pack as the runtime sees it. */
+interface AssetPackManifestEntry extends AssetPackSplit {
+	/** `res://` path of the `.pck`, for `loadAssetPack`. */
+	pck: string;
+}
+
+/** The runtime manifest beside the packs: what to mount, and what to stage per file. */
+export interface AssetPackManifest {
+	packs: AssetPackManifestEntry[];
+	/** Packed source → the loose texture sources it needs at runtime (from `dump-deps.gd`). */
+	deps: Record<string, string[]>;
+}
+
+/** Each packed source's packed closure, as `dump-deps.gd` reports it. */
+interface Graph {
+	[source: string]: string[];
+}
+
+/** The two build-time outputs of `dump-deps.gd`. */
+interface Dump {
+	graph: Graph;
+	deps: Record<string, string[]>;
+}
+
+/**
+ * The ownership partition, from the dependency graph. A **level is a scene** (`.tscn`) among
+ * the scanned sources — a project's levels are its scenes, so nothing declares them — and:
+ * **a source exactly one scene reaches is that scene's** (so a model only one level uses
+ * rides its pack, though it lives in a shared asset tree), while **a source several scenes
+ * reach, or none does, is shared**. A scene whose own pack would be empty is dropped: every
+ * source it reaches is reached by another scene too, so it is already in `shared`, and a pack
+ * is mounted by *owner*.
+ */
+export function splitPacks(graph: Graph): AssetPackSplit[] {
+	const stem = (asset: string) => asset.slice(asset.lastIndexOf('/') + 1).replace(/\.[^.]+$/, '');
+	const scenes = Object.keys(graph).filter((s) => s.toLowerCase().endsWith('.tscn')).sort();
+	const closure = new Map(scenes.map((s) => [s, new Set([s, ...(graph[s] ?? [])])]));
+
+	// One pack per scene, named after its file stem (`shared` is reserved; a repeated stem —
+	// two `level.tscn` in different directories — gets a suffix).
+	const used = new Set(['shared']);
+	const packOf = new Map<string, AssetPackSplit>();
+	for (const scene of scenes) {
+		let name = stem(scene);
+		for (let n = 2; used.has(name); n++) name = `${stem(scene)}-${n}`;
+		used.add(name);
+		packOf.set(scene, { name, owns: [] });
+	}
+
+	const shared: string[] = [];
+	const sources = new Set([...Object.keys(graph), ...Object.values(graph).flat()]);
+	for (const source of sources) {
+		const owners = scenes.filter((scene) => closure.get(scene)!.has(source));
+		if (owners.length === 1) packOf.get(owners[0])!.owns.push(source);
+		else shared.push(source);
+	}
+	shared.sort();
+	return [
+		{ name: 'shared', always: true, owns: shared },
+		...[...packOf.values()]
+			.filter((pack) => pack.owns.length > 0)
+			.map((pack) => ({ ...pack, owns: pack.owns.sort() })),
+	];
+}
+
+/**
+ * Bakes the packs (see {@link splitPacks}) and writes the runtime manifest. A project with no
+ * scene under its roots gets a single `shared.pck` and the same manifest.
+ */
+export async function buildAssetPacks(opts: BuildAssetPackOptions = {}): Promise<void> {
+	const editor = opts.godot ?? (await resolveEditor());
+	const cwd = process.cwd();
+	const roots = opts.roots ?? ['res://src'];
+	const out = opts.out ?? '.godot/packs';
+	const base = opts.preset ?? 'Pack';
+	const prefix = `${base}: `;
+	const presets = resolve(cwd, 'export_presets.cfg');
+
+	const cfg = readFileSync(presets, 'utf8');
+	const basePreset = presetBlock(cfg, base);
+	const baseExcludes = excludeFilter(basePreset);
+	mkdirSync(resolve(cwd, out), { recursive: true });
+
+	const run = runner(editor, cwd);
+	run(['--headless', '--path', '.', '--import']);
+	const { graph, deps } = dump(run, cwd, roots);
+
+	const packs = splitPacks(graph);
+	const owned = packs.flatMap((pack) => pack.owns);
+	const manifest: AssetPackManifestEntry[] = [];
+
+	// The project's own presets, with any this tool generated in an earlier run dropped.
+	const original = pruneGenerated(cfg, prefix);
+	const index = (original.match(/^\[preset\.\d+\]/gm) ?? []).length;
+	try {
+		for (const { name, always, owns } of packs) {
+			const exclude = [
+				...baseExcludes,
+				...owned.filter((source) => !owns.includes(source)).map((source) => source.replace(/^res:\/\//, '')),
+			];
+			writeFileSync(presets, `${original.trimEnd()}\n\n${presetFor(basePreset, index, `${prefix}${name}`, exclude)}\n`);
+			const pck = `${out}/${name}.pck`;
+			run(['--headless', '--path', '.', '--export-pack', `${prefix}${name}`, pck]);
+			manifest.push({ name, pck: resPath(pck), ...(always ? { always } : {}), owns });
+		}
+	} finally {
+		// Derived — leave the project's own file as it was, so a bake does not churn a tracked,
+		// editor-managed file.
+		writeFileSync(presets, original);
+	}
+	writeFileSync(resolve(cwd, out, 'packs.json'), `${JSON.stringify({ packs: manifest, deps } satisfies AssetPackManifest, null, '\t')}\n`);
+	console.log(`[pack] ${manifest.length} packs (${manifest.map((p) => `${p.name}:${p.owns.length}`).join(', ')}) over ${owned.length} sources`);
+}
+
+/** A `spawnSync` runner that throws on a non-zero editor exit. */
+function runner(editor: string, cwd: string) {
+	return (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})`);
+		}
+	};
+}
+
+/** Runs `dump-deps.gd` and splits its output into the graph and the loose-texture lists. */
+function dump(run: (args: string[], env?: Record<string, string>) => void, cwd: string, roots: string[]): Dump {
+	copyFileSync(resolve(HERE, 'dump-deps.gd'), resolve(cwd, '.godot', 'pack-dump-deps.gd'));
+	run(['--headless', '--path', '.', '--script', 'res://.godot/pack-dump-deps.gd'], {
+		GODOT_DUMP_OUT: resPath(DUMP),
+		GODOT_DUMP_ROOTS: roots.join(','),
+	});
+	const abs = resolve(cwd, DUMP);
+	if (!existsSync(abs)) throw new Error(`godot-assets: the dump wrote no ${DUMP} (see dump-deps.gd).`);
+	const sources = JSON.parse(readFileSync(abs, 'utf8')) as Record<string, { packed: string[]; loose: string[] }>;
+	const entries = Object.entries(sources);
+	return {
+		graph: Object.fromEntries(entries.map(([source, s]) => [source, s.packed])),
+		deps: Object.fromEntries(entries.map(([source, s]) => [source, s.loose])),
+	};
+}
+
+const resPath = (rel: string) => `res://${rel.replace(/^res:\/\//, '')}`;
+
+/** The preset whose `name=` matches, as its raw `[preset.N]` … block (options included). */
+function presetBlock(cfg: string, name: string): string {
+	const m = new RegExp(`^name=${JSON.stringify(name)}$`, 'm').exec(cfg);
+	if (!m) throw new Error(`godot-assets: no "${name}" preset in export_presets.cfg (see export_presets.example.cfg).`);
+	const rest = cfg.slice(cfg.lastIndexOf('[preset.', m.index));
+	// The next *preset* header — not this one's `[preset.N.options]`.
+	const end = rest.search(/\n\[preset\.\d+\]/);
+	return (end < 0 ? rest : rest.slice(0, end)).trimEnd();
+}
+
+/** A preset block's `exclude_filter` entries. */
+function excludeFilter(block: string): string[] {
+	const line = /^exclude_filter="([^"]*)"/m.exec(block);
+	return (line?.[1] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+/** A pack's preset: the base preset's own (platform + options), renamed and re-excluded. */
+function presetFor(base: string, index: number, name: string, exclude: string[]): string {
+	return base
+		.replace(/^\[preset\.\d+\]/, `[preset.${index}]`)
+		.replace(/\[preset\.\d+\.options\]/, `[preset.${index}.options]`)
+		.replace(/^name="[^"]*"/m, `name=${JSON.stringify(name)}`)
+		.replace(/^exclude_filter="[^"]*"/m, `exclude_filter=${JSON.stringify(exclude.join(','))}`);
+}
+
+/** Drops the presets this tool generated in an earlier run (so re-bakes are idempotent). */
+function pruneGenerated(cfg: string, prefix: string): string {
+	const generated = new RegExp(`^name="${prefix}[^"]*"$`, 'm');
+	return cfg.split(/(?=\[preset\.\d+\])/).filter((block) => !generated.test(block)).join('');
+}
+
+/** 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;
+	};
+	return {
+		roots: opt('--roots')?.split(',').filter(Boolean),
+		out: opt('--out'),
+		preset: opt('--preset'),
+		godot: opt('--godot'),
+	};
+}

package/src/preload.ts

@@ -5,6 +5,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { plugin } from 'bun';
+import type { AssetPackManifest } from './pack.ts';
 import type { BunPlugin } from 'bun';
 
 // Registers the godot-assets plugin: imports of Godot source assets become
@@ -12,13 +13,13 @@ import type { BunPlugin } from 'bun';
 // 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`),
+// `.pck` baked by `godot pack`: the module mounts the pack(s) (`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`).
+// is computed by the engine (`@ringozz/godot/pack`'s `dump-deps.gd`, via
+// `ResourceLoader.get_dependencies`) and shipped in the manifest beside the packs.
 //
 // 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
@@ -72,17 +73,29 @@ const extOf = (abs: string) => abs.slice(abs.lastIndexOf('.') + 1).toLowerCase()
 const resOf = (abs: string) => 'res://' + abs.slice(ROOT.length + 1).replaceAll('\\', '/');
 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[]>)
-	: {};
+// A project bakes native `.pck`s (`godot --export-pack`) — the engine-converted binary
+// resources + remap tables — through `@ringozz/godot/pack`'s `buildAssetPacks`: one per
+// scene, plus a shared one, so a host fetches the shared data and only the level it is
+// playing. The manifest beside them (`<pack dir>/packs.json`) is the whole runtime contract:
+// which packs exist, which sources each owns, and which loose (WebP-backed) textures the host
+// must stage per file. A module mounts the packs marked `always` (the shared pack) plus its
+// asset's owner, so importing a level brings in exactly what it needs.
+//
+// Everything is optional: with no manifest (desktop, or a project that has not baked) modules
+// load source paths directly.
+const readJson = <T>(file: string): T | null =>
+	existsSync(file) ? (JSON.parse(readFileSync(file, 'utf8')) as T) : null;
+
+/** Where the packs were baked — `godot pack`'s `--out` (`GODOT_PACKS` overrides for a host). */
+const PACK_DIR = resolve(ROOT, process.env.GODOT_PACKS ?? '.godot/packs');
+const MANIFEST = readJson<AssetPackManifest>(resolve(PACK_DIR, 'packs.json'));
+
+/** The packs an asset needs mounted: the always-mounted ones plus its owner. */
+function packsFor(resPath: string): string[] {
+	return (MANIFEST?.packs ?? [])
+		.filter((pack) => pack.always || pack.owns.includes(resPath))
+		.map((pack) => resolve(ROOT, pack.pck.replace(/^res:\/\//, '')));
+}
 
 /** Reads the imported destination (`dest_files`) out of an `.import` sidecar. */
 function parseSidecarDest(text: string): string | null {
@@ -117,7 +130,7 @@ function analyze(abs: string): Map<string, 'text' | 'file'> {
 	if (isLoose(abs)) {
 		addLoose(abs, files);
 	}
-	for (const loose of DEPS[resOf(abs)] ?? []) {
+	for (const loose of MANIFEST?.deps[resOf(abs)] ?? []) {
 		addLoose(resolve(ROOT, loose.slice('res://'.length)), files);
 	}
 	return files;
@@ -133,9 +146,11 @@ function ensureModule(abs: string): string {
 		`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 mounts = packsFor(res);
+	if (mounts.length) {
+		mounts.forEach((url, i) => imports.push(`import pack${i} from ${JSON.stringify(url)} with { type: 'file' };`));
+		const loads = mounts.map((_, i) => `loadAssetPack(pack${i})`);
+		ready = loads.length === 1 ? loads[0] : `Promise.all([${loads.join(', ')}])`;
 	}
 	const map: string[] = [];
 	let fi = 0;