@ringozz/godot 4.7.2-659 → 4.7.2-661

package/README.md

@@ -91,13 +91,13 @@ 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. `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.
+- `loadAsset(path, cls, files, data, ready)` — 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.
+`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 — including a level's plan, which names refs no resource edge exposes — 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 level, plus a shared pack**, so a host fetches the shared data and only the level it is playing. A level is its scene — or, in a project that builds levels from their plans at run time, the `.gltfx` its plan lives in; a project with neither 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 sources the host must stage per file (the WebP-backed textures are transcoded; a plan's plain header JSONs are just written). 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`.
+The bake always splits: **one pack per level, plus a shared pack**, so a host fetches the shared data and only the level it is playing. A level is its scene — or, in a project that builds levels from their plans at run time, the `.gltfx` its plan lives in; a project with neither 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 sources the host must stage per file (the WebP-backed textures are transcoded). 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';
@@ -113,7 +113,7 @@ import foo from './models/foo.gltf';
 const scene = await foo;          // PackedScene
 ```
 
-Each asset module's default export is its load **promise** (`const { materialize, load } = loadAsset(resPath, Class, files, deps, import.meta.hot.data)` — the default is `load`, memoized on the module's HMR data), started eagerly at module import, and it also exports a `materialize` promise (its own files plus its deps' files). The files Godot reads are bundled into the module — `.import` sidecars and native text sources (`tscn`/`tres`/`po`/`gd`/`gdshader`/`gdshaderinc`) are inlined as text, imported products (`.scn`/`.ctex`) are emitted as files — and the module imports its **dependencies as generated modules too**, waiting only for their `materialize` before loading itself (dep loads start at module evaluation and run concurrently). Text-based source assets (`.gltf`/`.tscn`/`.tres`/`.obj`/`.gd`/`.gdshader`/`.gdshaderinc`) are scanned for references (`res://` paths and relative paths ending in known asset extensions); referenced loadable assets become dep modules, native-text leaves are staged as raw text so the engine loads them by `res://` on web, raw `.mtl` files (OBJ materials) are recursed into, and raw `.bin` buffers are import-time only. The modules are virtual (namespace `godot`), and every import of the same asset resolves to the same one (evaluated once) — so the promise is a stable singleton, read with `await` or React 19's `use()`:
+Each asset module's default export is its load **promise** (`const { materialize, load } = loadAsset(resPath, Class, files, import.meta.hot.data, ready)` — the default is `load`, memoized on the module's HMR data), started eagerly at module import, and it also exports a `materialize` promise (its own files plus its deps' files). The files Godot reads are bundled into the module — `.import` sidecars and native text sources (`tscn`/`tres`/`po`/`gd`/`gdshader`/`gdshaderinc`) are inlined as text, imported products (`.scn`/`.ctex`) are emitted as files — and the module imports its **dependencies as generated modules too**, waiting only for their `materialize` before loading itself (dep loads start at module evaluation and run concurrently). Text-based source assets (`.gltf`/`.tscn`/`.tres`/`.obj`/`.gd`/`.gdshader`/`.gdshaderinc`) are scanned for references (`res://` paths and relative paths ending in known asset extensions); referenced loadable assets become dep modules, native-text leaves are staged as raw text so the engine loads them by `res://` on web, raw `.mtl` files (OBJ materials) are recursed into, and raw `.bin` buffers are import-time only. The modules are virtual (namespace `godot`), and every import of the same asset resolves to the same one (evaluated once) — so the promise is a stable singleton, read with `await` or React 19's `use()`:
 
 ```tsx
 import foo from './models/foo.gltf';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.2-659",
+  "version": "4.7.2-661",
   "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-659",
-    "@ringozz/godot-windows-x86_64": "^4.7.2-659",
-    "@ringozz/godot-web-wasm32": "^4.7.2-659"
+    "@ringozz/godot-macos-arm64": "^4.7.2-661",
+    "@ringozz/godot-windows-x86_64": "^4.7.2-661",
+    "@ringozz/godot-web-wasm32": "^4.7.2-661"
   },
   "peerDependencies": {
     "@types/bun": "*"

package/src/dump-deps.gd

@@ -16,6 +16,12 @@ extends SceneTree
 ## is *loose* when it has an `.import` sidecar but is not a packed resource type — the set is
 ## derived, not listed.
 ##
+## A third source, because neither above can see it: a **level built from its plan**
+## (`extras.gltfx.plan`, which a host script reads at run time). It names its terrain by
+## *directory* and its ground/environment maps by relative route — no resource edge and no `res://`
+## literal — so `_plan_refs` reads the plan off the `.gltfx` and classifies its refs. A scene that
+## instances the `.gltfx` inherits them through `_collect`'s recursion.
+##
 ## 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.
@@ -38,7 +44,8 @@ func _initialize() -> void:
 		roots = ["res://"]
 	var sources := {}
 	for r in roots:
-		_scan(String(r).rstrip("/") + "/", sources)
+		var root := String(r).rstrip("/") + "/"
+		_scan(root, root, 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, "  "))
@@ -47,19 +54,20 @@ func _initialize() -> void:
 	quit()
 
 
-func _scan(path: String, sources: Dictionary) -> void:
+## `root` is the scan root `path` lives under (a plan's refs are relative to it), carried down the walk.
+func _scan(root: String, 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)
+		_scan(root, 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)
+			var loose := _loose(root, 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.
@@ -70,24 +78,24 @@ func _scan(path: String, sources: Dictionary) -> void:
 
 ## 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:
+func _loose(root: String, path: String, seen: Dictionary) -> Array:
 	var loose := {}
-	_collect(path, loose, seen)
+	_collect(root, path, loose, seen)
 	var arr := loose.keys()
 	arr.sort()
 	return arr
 
 
-func _classify(dep: String, loose: Dictionary, seen: Dictionary) -> void:
+func _classify(root: String, dep: String, loose: Dictionary, seen: Dictionary) -> void:
 	if dep.is_empty():
 		return
 	if dep.get_extension().to_lower() in PACKED:
-		_collect(dep, loose, seen)
+		_collect(root, dep, loose, seen)
 	elif FileAccess.file_exists(dep + ".import"):
 		loose[dep] = true
 
 
-func _collect(path: String, loose: Dictionary, seen: Dictionary) -> void:
+func _collect(root: String, path: String, loose: Dictionary, seen: Dictionary) -> void:
 	if seen.has(path):
 		return
 	seen[path] = true
@@ -98,14 +106,17 @@ func _collect(path: String, loose: Dictionary, seen: Dictionary) -> void:
 		var cfg := ConfigFile.new()
 		if cfg.load(imp) == OK:
 			for dst in cfg.get_value("deps", "dest_files", []):
-				_collect(String(dst), loose, seen)
+				_collect(root, String(dst), loose, seen)
 	for dep in ResourceLoader.get_dependencies(path):
-		_classify(_res_path(String(dep)), loose, seen)
+		_classify(root, _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)
+			_classify(root, p, loose, seen)
+	# A level built from its plan names nothing above: its refs come from the plan itself.
+	if path.get_extension().to_lower() == "gltfx":
+		_plan_refs(root, path, loose, seen)
 
 
 ## `res://` path from a dependency entry (`uid://…::::res://…` or plain).
@@ -124,3 +135,65 @@ func _text_refs(path: String) -> Array:
 	for m in re.search_all(FileAccess.get_file_as_string(path)):
 		refs.append(m.get_string())
 	return refs
+
+
+## A level's refs, read from the plan its `.gltfx` carries (`extras.gltfx.plan`). They are
+## invisible to every source above (a *directory* rather than a route, relative routes, and a host
+## script that reads the JSON instead of a resource edge), so the plan is their only statement. Each
+## ref goes through `_classify`: what has an `.import` sidecar is staged, the header JSONs (which the
+## packs carry) are not.
+func _plan_refs(root: String, path: String, loose: Dictionary, seen: Dictionary) -> void:
+	var doc = JSON.parse_string(FileAccess.get_file_as_string(path))
+	var extras: Variant = doc.get("extras") if doc is Dictionary else null
+	var stamp: Variant = extras.get("gltfx") if extras is Dictionary else null
+	var plan: Variant = stamp.get("plan") if stamp is Dictionary else null
+	if not plan is Dictionary:
+		return
+
+	# The terrain: the plan names its directory, and the directory is the atlas list.
+	var terrain: Variant = plan.get("terrain")
+	if terrain is Dictionary and terrain.get("dir") is String:
+		_terrain_refs(root, root.path_join(String(terrain["dir"])), loose, seen)
+
+	# The rest are texture routes — the ground's patches / the water's maps, and the sky.
+	var ground: Variant = plan.get("ground")
+	if ground is Array:
+		for g in ground:
+			if not g is Dictionary:
+				continue
+			var fields: Variant = g.get("material") if g.get("source") == "overlay" else g.get("water")
+			if fields is Dictionary:
+				for key in ["diffuse", "normal", "orm"]:
+					_classify_route(root, fields.get(key), loose, seen)
+	var lighting: Variant = plan.get("lighting")
+	if lighting is Dictionary:
+		# A host renders one time of day: the authored stage's env, which the plan mirrors as `env`.
+		var stages: Variant = lighting.get("stages")
+		var env: Variant = stages[0].get("env") if stages is Array and stages.size() > 0 and stages[0] is Dictionary else null
+		if not env is Dictionary:
+			env = lighting.get("env")
+		_classify_route(root, env.get("map") if env is Dictionary else null, loose, seen)
+
+
+## A terrain directory **is** its atlas list (every atlas name is top-level in it), so each file is a
+## ref — except a layered container's *layers*: the manifest names them and their bytes live in its
+## imported product, so staging them would ship megabytes nothing reads.
+func _terrain_refs(root: String, dir: String, loose: Dictionary, seen: Dictionary) -> void:
+	var files := DirAccess.get_files_at(dir)
+	var layers := {}
+	for name in files:
+		if name.to_lower().ends_with(".webparray"):
+			for line in FileAccess.get_file_as_string(dir.path_join(name)).split("\n"):
+				var ref := line.strip_edges()
+				if not ref.is_empty() and not ref.begins_with("#"):
+					layers[ref.get_file()] = true
+	for name in files:
+		if not layers.has(name.get_file()):
+			_classify(root, dir.path_join(name), loose, seen)
+
+
+## Classifies a plan's route: relative and unsuffixed, so the served `.webp` spelling is tried too.
+func _classify_route(root: String, route: Variant, loose: Dictionary, seen: Dictionary) -> void:
+	if route is String:
+		for suffix in ["", ".webp"]:
+			_classify(root, root.path_join(route + suffix), loose, seen)

package/src/pack.ts

@@ -7,25 +7,23 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveEditor } from './editor.ts';
-import { mergePlanRefs, planRefs } from './planRefs.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)
+// Bakes a Godot project's assets for the runtime: imports them, then exports one native `.pck` **per
+// level** 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), in the dump's own two words: 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 one file the runtime reads is `<out>/packs.json`, beside the packs: every pack's `pck` and
+// `owns`, plus the `loose` lists. `preload.ts` mounts the reserved `shared` pack and the asset's
+// owner.
 //
-// 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.
+// 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 and the file is restored once the bake ends: they are derived, and the file is tracked.
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -43,74 +41,63 @@ export interface BuildAssetPackOptions {
 	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. */
+/** A pack: `shared`, or a level's file stem, and the sources it owns. */
+export interface Pack {
+	/** `shared`, or a level'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 {
+/** A pack as the manifest carries it: a {@link Pack} plus its `.pck`. */
+interface PackFile extends Pack {
 	/** `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[];
+export interface PackManifest {
+	packs: PackFile[];
 	/** Packed source → the loose texture sources it needs at runtime (from `dump-deps.gd`). */
-	deps: Record<string, string[]>;
+	loose: Record<string, string[]>;
 }
 
-/** Each packed source's packed closure, as `dump-deps.gd` reports it. */
-interface Graph {
-	[source: string]: string[];
-}
+/** One bucket of the dump: a source → its closure (`dump-deps.gd`'s `packed` or `loose` half). */
+type Closures = Record<string, string[]>;
 
-/** The two build-time outputs of `dump-deps.gd`. */
-interface Dump {
-	graph: Graph;
-	deps: Record<string, string[]>;
-}
+/** A `spawnSync` runner for the editor. */
+type Run = (args: string[], env?: Record<string, string>) => void;
 
 /**
- * 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*.
+ * The ownership partition, from the packed closure of every source. 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 level reaches is that level's** (so a model only one level uses
+ * rides its pack, though it lives in a shared asset tree), while **a source several levels reach, or
+ * none does, is shared**. A level whose own pack would be empty is dropped: every source it reaches
+ * is reached by another level too, so it is already in `shared`, and a pack is mounted by *owner*.
  *
- * The graph it reads is the dump's *plus* every level's plan refs (`mergePlanRefs`), so a level's
- * terrain, its layered containers and their layers, and its ground/environment textures are part of
- * its closure whether or not a baked scene names them. When a project stops baking one scene per
- * level — a level built from its plan at run time is a single shared scene plus the plan — the level
- * unit becomes the `.gltfx` its plan lives in instead; until then both units exist and this keying
- * keeps the scenes.
+ * When a project stops baking one scene per level — a level built from its plan at run time is a
+ * single shared scene plus the plan — the level unit becomes the `.gltfx` its plan lives in instead;
+ * until then both units exist and this keying keeps the scenes.
  */
-export function splitPacks(graph: Graph): AssetPackSplit[] {
+export function splitPacks(packed: Closures): Pack[] {
 	const stem = (asset: string) =>
 		asset.slice(asset.lastIndexOf('/') + 1).replace(/\.(prefab|level)\.[^.]+$/i, '').replace(/\.[^.]+$/, '');
 	// A level is its scene — and, in a project that builds levels from their plans at run time, the
 	// `.gltfx` its plan lives in. A `.gltfx` a scene **reaches** is that scene's composition, not a
 	// second level: keying both would make every source of a baked level look shared.
-	const scenes = Object.keys(graph).filter((s) => s.toLowerCase().endsWith('.tscn')).sort();
-	const reachedByScene = new Set(scenes.flatMap((s) => graph[s] ?? []));
+	const scenes = Object.keys(packed).filter((s) => s.toLowerCase().endsWith('.tscn')).sort();
+	const reachedByScene = new Set(scenes.flatMap((s) => packed[s] ?? []));
 	const levels = [
 		...scenes,
-		...Object.keys(graph).filter((s) => s.toLowerCase().endsWith('.gltfx') && !reachedByScene.has(s)),
+		...Object.keys(packed).filter((s) => s.toLowerCase().endsWith('.gltfx') && !reachedByScene.has(s)),
 	].sort();
-	const closure = new Map(levels.map((s) => [s, new Set([s, ...(graph[s] ?? [])])]));
+	const closure = new Map(levels.map((s) => [s, new Set([s, ...(packed[s] ?? [])])]));
 
 	// One pack per level, 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>();
+	const packOf = new Map<string, Pack>();
 	for (const level of levels) {
 		let name = stem(level);
 		for (let n = 2; used.has(name); n++) name = `${stem(level)}-${n}`;
@@ -119,15 +106,14 @@ export function splitPacks(graph: Graph): AssetPackSplit[] {
 	}
 
 	const shared: string[] = [];
-	const sources = new Set([...Object.keys(graph), ...Object.values(graph).flat()]);
+	const sources = new Set([...Object.keys(packed), ...Object.values(packed).flat()]);
 	for (const source of sources) {
 		const owners = levels.filter((level) => closure.get(level)!.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 },
+		{ name: 'shared', owns: shared.sort() },
 		...[...packOf.values()]
 			.filter((pack) => pack.owns.length > 0)
 			.map((pack) => ({ ...pack, owns: pack.owns.sort() })),
@@ -135,8 +121,9 @@ export function splitPacks(graph: Graph): AssetPackSplit[] {
 }
 
 /**
- * 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.
+ * Bakes the packs (see {@link splitPacks}) and writes the runtime manifest: import, dump, split,
+ * then one preset and one `.pck` per pack. 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());
@@ -146,50 +133,49 @@ export async function buildAssetPacks(opts: BuildAssetPackOptions = {}): Promise
 	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);
-	// A level's plan names what no scene does any more — its terrain directory, its layered containers
-	// and their layers, its ground/environment textures (`planRefs`). Merged here so the graph and the
-	// loose lists carry the level's whole closure with or without a baked scene.
-	mergePlanRefs(graph, deps, planRefs(cwd, roots));
-
-	const packs = splitPacks(graph);
-	const owned = packs.flatMap((pack) => pack.owns);
-	const manifest: AssetPackManifestEntry[] = [];
+	// `dump-deps.gd` reads a level's plan for the refs no resource edge exposes, so its `loose` lists
+	// carry the level's whole closure with or without a baked scene.
+	const { packed, loose } = dump(run, cwd, roots);
+	const packs = splitPacks(packed);
 
-	// The project's own presets, with any this tool generated in an earlier run dropped.
+	// One preset per pack, all written from the project's own base preset before any export: each
+	// excludes exactly the sources the other packs own (see the module comment).
 	const original = pruneGenerated(cfg, prefix);
-	const index = (original.match(/^\[preset\.\d+\]/gm) ?? []).length;
+	const first = (original.match(/^\[preset\.\d+\]/gm) ?? []).length;
+	const baseExcludes = excludeFilter(basePreset);
+	const generated = packs.map((pack, i) =>
+		presetFor(basePreset, first + i, `${prefix}${pack.name}`, excludesFor(baseExcludes, packs, pack)),
+	);
 	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`);
+		writeFileSync(presets, `${original.trimEnd()}\n\n${generated.join('\n\n')}\n`);
+		const manifest: PackFile[] = [];
+		for (const { name, owns } of packs) {
 			const pck = `${out}/${name}.pck`;
 			run(['--headless', '--path', '.', '--export-pack', `${prefix}${name}`, pck]);
-			manifest.push({ name, pck: resPath(pck), ...(always ? { always } : {}), owns });
+			manifest.push({ name, pck: resPath(pck), owns });
 		}
+		writeFileSync(
+			resolve(cwd, out, 'packs.json'),
+			`${JSON.stringify({ packs: manifest, loose } satisfies PackManifest, null, '\t')}\n`,
+		);
+		const sources = manifest.reduce((n, pack) => n + pack.owns.length, 0);
+		console.log(`[pack] ${manifest.length} packs (${manifest.map((p) => `${p.name}:${p.owns.length}`).join(', ')}) over ${sources} sources`);
 	} 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>) => {
+function runner(editor: string, cwd: string): Run {
+	return (args, env) => {
 		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})`);
@@ -197,8 +183,8 @@ function runner(editor: string, cwd: string) {
 	};
 }
 
-/** 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 {
+/** Runs `dump-deps.gd`: every source's packed closure, and the loose textures it needs. */
+function dump(run: Run, cwd: string, roots: string[]): { packed: Closures; loose: Closures } {
 	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),
@@ -209,13 +195,25 @@ function dump(run: (args: string[], env?: Record<string, string>) => void, cwd:
 	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])),
+		packed: Object.fromEntries(entries.map(([source, s]) => [source, s.packed])),
+		loose: Object.fromEntries(entries.map(([source, s]) => [source, s.loose])),
 	};
 }
 
 const resPath = (rel: string) => `res://${rel.replace(/^res:\/\//, '')}`;
 
+/** A pack's `exclude_filter`: the base preset's own excludes plus every source the others own. */
+function excludesFor(base: string[], packs: Pack[], mine: Pack): string[] {
+	const own = new Set(mine.owns);
+	return [
+		...base,
+		...packs
+			.flatMap((pack) => pack.owns)
+			.filter((source) => !own.has(source))
+			.map((source) => source.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);

package/src/preload.ts

@@ -5,7 +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 { PackManifest } from './pack.ts';
 import type { BunPlugin } from 'bun';
 
 // Registers the godot-assets plugin: imports of Godot source assets become
@@ -75,25 +75,28 @@ const isLoose = (abs: string) => LOOSE.has(extOf(abs));
 
 // 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
+// level, 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.
+// must stage per file. A module mounts the reserved `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;
 
+/** The pack every asset mounts, as `splitPacks` names it (its `name` is reserved for this). */
+const SHARED_PACK = 'shared';
+
 /** 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'));
+const MANIFEST = readJson<PackManifest>(resolve(PACK_DIR, 'packs.json'));
 
-/** The packs an asset needs mounted: the always-mounted ones plus its owner. */
+/** The packs an asset needs mounted: the shared one plus its owner. */
 function packsFor(resPath: string): string[] {
 	return (MANIFEST?.packs ?? [])
-		.filter((pack) => pack.always || pack.owns.includes(resPath))
+		.filter((pack) => pack.name === SHARED_PACK || pack.owns.includes(resPath))
 		.map((pack) => resolve(ROOT, pack.pck.replace(/^res:\/\//, '')));
 }
 
@@ -130,7 +133,7 @@ function analyze(abs: string): Map<string, 'text' | 'file'> {
 	if (isLoose(abs)) {
 		addLoose(abs, files);
 	}
-	for (const loose of MANIFEST?.deps[resOf(abs)] ?? []) {
+	for (const loose of MANIFEST?.loose[resOf(abs)] ?? []) {
 		addLoose(resolve(ROOT, loose.slice('res://'.length)), files);
 	}
 	return files;

package/src/planRefs.ts

@@ -1,209 +0,0 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-// A level's refs, read from its **plan**. A `.gltfx` level scene carries the converter's derived
-// render state under `extras.wartales.plan`: it names the level's terrain by *directory* and its
-// ground/environment textures by resource route. A host's closure walk cannot see any of it — the
-// routes are relative to the manifest that names them, a layered container's layers are plain text
-// lines, and a runtime script reads the plan dynamically (so no scene names them literally any more).
-// Reading it here keeps a `.gltfx` source's closure complete without a baked scene.
-//
-// Pure filesystem: a project directory plus the `res://` roots a host scans in, the refs out. No
-// engine, no editor — so it is unit-testable and runs before the pack bake.
-
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-
-/** The refs a `.gltfx`'s plan implies, ready to merge into a dump. */
-export interface PlanRefs {
-	/** The level source's own extra loose refs: its terrain data, layered-container manifests, and the
-	 *  ground/environment textures its plan names. */
-	loose: string[];
-}
-
-// Two of the refs a plan names are plain files rather than imported sources — the terrain's header
-// JSONs, which a plan-built level reads at run time. They are in the level's `loose` list, so a
-// *staging* host writes them; a *pack* needs no help either, because Godot loads a `.json` as a
-// `JSON` resource (verified: `ResourceLoader.exists` is true and the class is `JSON`), so an
-// `all_resources` preset packs it — and since no pack *owns* a source it is not excluded from any,
-// every pack carries those few KB.
-
-const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
-
-/** The `extras.wartales.plan` of a parsed gltfx document, or null for a foreign/older document. */
-export function planOf(doc: unknown): Record<string, unknown> | null {
-	if (!isObject(doc) || !isObject(doc.extras)) return null;
-	const w = (doc.extras as Record<string, unknown>)['wartales'];
-	if (!isObject(w) || !isObject(w.plan)) return null;
-	return w.plan as Record<string, unknown>;
-}
-
-/** Every `src/<dir>`-style root as an absolute disk directory, paired with its `res://` prefix. */
-function rootDirs(projectDir: string, roots: string[]): { disk: string; res: string }[] {
-	const out: { disk: string; res: string }[] = [];
-	for (const root of roots) {
-		const rel = root.replace(/^res:\/\//, '');
-		out.push({ disk: join(projectDir, ...rel.split('/')), res: `res://${rel}` });
-	}
-	return out;
-}
-
-/** A path's last segment. */
-const base = (p: string) => p.slice(p.lastIndexOf('/') + 1);
-
-/** Every file under `dir`, as paths relative to `dir` (posix, one level of nesting per entry). */
-function walk(dir: string, prefix = ''): string[] {
-	const out: string[] = [];
-	let entries: string[];
-	try {
-		entries = readdirSync(dir);
-	} catch {
-		return out;
-	}
-	for (const name of entries) {
-		if (name.startsWith('.')) continue;
-		const full = join(dir, name);
-		const rel = prefix ? `${prefix}/${name}` : name;
-		try {
-			if (readdirSync(full).length >= 0) {
-				out.push(...walk(full, rel));
-				continue;
-			}
-		} catch {
-			// not a directory
-		}
-		out.push(rel);
-	}
-	return out;
-}
-
-/**
- * The environment a **host renders**: the level's authored stage — `stages[0].env`, which the plan
- * also carries as `lighting.env`. A host shows one time of day, so the other stages (a viewer's
- * blend material) and the reflection probe (which a host does not sample) are not runtime refs.
- */
-function authoredEnvMap(lighting: Record<string, unknown>): string | null {
-	const stages = Array.isArray(lighting.stages) ? lighting.stages : [];
-	const stage0 = stages.length && isObject(stages[0]) ? (stages[0] as Record<string, unknown>) : null;
-	const env = (stage0 && isObject(stage0.env) ? stage0.env : null) ?? (isObject(lighting.env) ? lighting.env : null);
-	return env && typeof env.map === 'string' ? env.map : null;
-}
-
-/**
- * The layer file names the `.webparray` manifests in `dir` name, one per line. Those layers are read
- * by their *importer* and live inside the imported product afterwards, so nothing loads them at run
- * time: they are import-time inputs, and the directory walk must not stage them.
- */
-function layerSources(dir: string): Set<string> {
-	const names = new Set<string>();
-	for (const manifest of walk(dir)) {
-		if (!manifest.toLowerCase().endsWith(".webparray")) continue;
-		let text: string;
-		try {
-			text = readFileSync(join(dir, ...manifest.split("/")), "utf8");
-		} catch {
-			continue;
-		}
-		for (const line of text.split("\n")) {
-			const ref = line.trim();
-			if (ref && !ref.startsWith("#")) names.add(base(ref));
-		}
-	}
-	return names;
-}
-
-/** The resource route of a ref the plan names, probing the served `.webp` suffix a texture carries. */
-function routeOf(root: { disk: string; res: string }, route: string): string | null {
-	for (const candidate of [route, `${route}.webp`]) {
-		if (existsSync(join(root.disk, ...candidate.split('/')))) return `${root.res}/${candidate}`;
-	}
-	return null;
-}
-
-/**
- * Every `.gltfx` under `roots` with its plan-derived refs. A level's terrain is discovered by
- * *listing* its directory (the tree holds exactly the level's atlas there, so no name list to keep in
- * step), its manifests' layers are read from the manifests, and its ground/environment textures are
- * probed per route (a plan route may or may not carry the served `.webp` suffix).
- */
-export function planRefs(projectDir: string, roots: string[]): Map<string, PlanRefs> {
-	const out = new Map<string, PlanRefs>();
-	for (const root of rootDirs(projectDir, roots)) {
-		for (const file of walk(root.disk)) {
-			if (!file.toLowerCase().endsWith('.gltfx')) continue;
-			let doc: unknown;
-			try {
-				doc = JSON.parse(readFileSync(join(root.disk, ...file.split('/')), 'utf8'));
-			} catch {
-				continue;
-			}
-			const plan = planOf(doc);
-			if (!plan) continue;
-			const levelRoute = `${root.res}/${file}`;
-			const loose = new Set<string>();
-
-			// The terrain: the plan names its directory, and the tree holds exactly the level's own atlas
-			// there (the height and tile-normal maps, the composed weight planes, the passmap and its
-			// meta, the header JSON and the layered containers) — so the directory *is* the list. A
-			// container's *layers* are deliberately not listed: they live inside its imported product,
-			// and are import-time inputs, so nothing stages them at run time.
-			const terrain = isObject(plan.terrain) ? plan.terrain : null;
-			if (terrain && typeof terrain.dir === 'string') {
-				const dir = terrain.dir;
-				const abs = join(root.disk, ...dir.split('/'));
-				const layers = layerSources(abs);
-				for (const name of walk(abs)) {
-					if (name.endsWith(".import") || layers.has(base(name))) continue;
-					loose.add(`${root.res}/${dir}/${name}`);
-				}
-			}
-
-			// The ground's patches and the rig's skies: plain resource routes with the served suffix.
-			const ground = Array.isArray(plan.ground) ? plan.ground : [];
-			for (const g of ground) {
-				if (!isObject(g)) continue;
-				const fields = g.source === 'overlay' ? [isObject(g.material) ? g.material : {}] : [isObject(g.water) ? g.water : {}];
-				for (const f of fields) {
-					for (const key of ['diffuse', 'normal', 'orm']) {
-						if (typeof f[key] !== 'string') continue;
-						const route = routeOf(root, f[key] as string);
-						if (route) loose.add(route);
-					}
-				}
-			}
-			const lighting = isObject(plan.lighting) ? plan.lighting : {};
-			const map = authoredEnvMap(lighting);
-			const route = map ? routeOf(root, map) : null;
-			if (route) loose.add(route);
-
-			out.set(levelRoute, { loose: [...loose].sort() });
-		}
-	}
-	return out;
-}
-
-/**
- * Merge `planRefs` into a dump's `graph`/`loose` halves: a `.gltfx` source gains its plan's refs, and
- * so does every source that reaches it (a scene that instances it, so mounting the scene stages the
- * level's terrain and ground too — a union, and a no-op for a project with no plan).
- */
-export function mergePlanRefs(
-	graph: Record<string, string[]>,
-	deps: Record<string, string[]>,
-	refs: Map<string, PlanRefs>,
-): void {
-	for (const [level, r] of refs) {
-		if (!(level in graph)) continue;
-		deps[level] = [...new Set([...(deps[level] ?? []), ...r.loose])].sort();
-	}
-	// A scene that instances a `.gltfx` carries that plan's refs too: mounting the scene must stage the
-	// level's terrain and ground, not only its model composition. (The scene may already name some of
-	// them — a baked one does — so this is a union, and a no-op for a project with no plan.)
-	for (const source of Object.keys(graph)) {
-		const plans = graph[source].filter((dep) => refs.has(dep));
-		if (!plans.length || refs.has(source)) continue;
-		const extra = plans.flatMap((p) => refs.get(p)!.loose);
-		deps[source] = [...new Set([...(deps[source] ?? []), ...extra])].sort();
-	}
-}