@ringozz/godot 4.7.2-654 → 4.7.2-657

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` | `buildAssetPacks()` + the `godot pack` subcommand: bake a project's `.pck`(s) + loose-texture manifest, one pack per scene |
+| `@ringozz/godot/pack` | `buildAssetPacks()` + the `godot pack` subcommand: bake a project's `.pck`(s) + loose-texture manifest, one pack per level (its scene, or the `.gltfx` its plan lives in) |
 | `@ringozz/godot/debug` | `initDebug()`, `dumpStr`, `snapshot`, `inspect`, `click`, `find`, `gc` |
 
 Class-scoped enums use bare names (import `ProcessMode` from `@ringozz/godot/Node`, not `NodeProcessMode`).
@@ -97,7 +97,7 @@ const tex   = await loadResourceAsync('res://textures/icon.jpg', Texture2D); //
 
 `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`.
+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`.
 
 ```ts
 import { loadAssetPack } from '@ringozz/godot/load';

package/package.json

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

package/src/pack.ts

@@ -7,6 +7,7 @@ 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
@@ -84,27 +85,43 @@ interface Dump {
  * 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 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.
  */
 export function splitPacks(graph: Graph): AssetPackSplit[] {
-	const stem = (asset: string) => asset.slice(asset.lastIndexOf('/') + 1).replace(/\.[^.]+$/, '');
+	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 closure = new Map(scenes.map((s) => [s, new Set([s, ...(graph[s] ?? [])])]));
+	const reachedByScene = new Set(scenes.flatMap((s) => graph[s] ?? []));
+	const levels = [
+		...scenes,
+		...Object.keys(graph).filter((s) => s.toLowerCase().endsWith('.gltfx') && !reachedByScene.has(s)),
+	].sort();
+	const closure = new Map(levels.map((s) => [s, new Set([s, ...(graph[s] ?? [])])]));
 
-	// One pack per scene, named after its file stem (`shared` is reserved; a repeated stem —
+	// 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>();
-	for (const scene of scenes) {
-		let name = stem(scene);
-		for (let n = 2; used.has(name); n++) name = `${stem(scene)}-${n}`;
+	for (const level of levels) {
+		let name = stem(level);
+		for (let n = 2; used.has(name); n++) name = `${stem(level)}-${n}`;
 		used.add(name);
-		packOf.set(scene, { name, owns: [] });
+		packOf.set(level, { 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));
+		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);
 	}
@@ -138,6 +155,10 @@ export async function buildAssetPacks(opts: BuildAssetPackOptions = {}): Promise
 	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);

package/src/planRefs.ts

@@ -0,0 +1,169 @@
+/**********************************************************************
+ 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;
+}
+
+/** 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 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;
+				for (const name of walk(join(root.disk, ...dir.split('/')))) 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 envs = [lighting.env, lighting.probe, ...(Array.isArray(lighting.stages) ? lighting.stages.map((s) => (isObject(s) ? s.env : null)) : [])];
+			for (const e of envs) {
+				if (!isObject(e) || typeof e.map !== 'string') continue;
+				const route = routeOf(root, e.map as string);
+				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();
+	}
+}