@ringozz/godot 4.7.2-661 → 4.7.2-676

package/src/preload.ts

@@ -5,178 +5,124 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { plugin } from 'bun';
-import type { PackManifest } from './pack.ts';
+import { classOf, moduleExtensions } from './formats.ts';
+import { BOOT_MANIFEST, BOOT_MODULE, PACK_DIR, PACK_DIR_ENV, PACK_DOC, RELEASE, descriptorOf, packEntries, stagedKeys, type PackDoc, type PackEntry } from './pack.ts';
+import { assetModule, packModule, type ServedAsset } from './serve.ts';
 import type { BunPlugin } from 'bun';
 
-// Registers the godot-assets plugin: imports of Godot source assets become
-// virtual modules (namespace `godot`) that mount the project's asset pack and
-// load the resource.
+// Registers the godot-assets plugin: importing a Godot source asset becomes a module that stages what
+// the source needs and loads it (default export = the load promise, `materialize` = its files staged).
 //
-// A packed source asset (`tscn`/`tres`/`gltf`/`gd`/font/…) is loaded from the
-// `.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`, via
-// `ResourceLoader.get_dependencies`) and shipped in the manifest beside the packs.
+// What a source needs comes from the bake (`@ringozz/godot/pack`), never from scanning source text:
+// `dump-deps.gd` walked the project at bake time and wrote, per source, the loose (WebP-backed)
+// texture sources the wasm engine cannot decode — and the descriptor of every loose file the app's
+// pack owns. A packed source resolves inside the mounted `.pck`; only its loose textures are staged
+// per file, each with the `.import` text and product `descriptorOf` reads from the same sidecar the
+// bake read.
 //
-// The load promise persists on `import.meta.hot.data` (carried across HMR
-// re-evaluations) so `use()` never re-suspends; a rejected load is evicted so
-// the next evaluation retries. The default export is the single plugin —
-// registered globally via bunfig preload and loaded by `[serve.static] plugins`.
+// The bake's own pack is the module it generated beside the packs (`boot-pack.js`): its `.pck`, the
+// config the runtime stages content packs from, and the mount every asset module waits for. So
+// importing any asset is what mounts the app's pack, and the config an app still supplies
+// (`configurePacks({ at })`, where a content release is read) merges with it in either order.
+//
+// The load promise persists on `import.meta.hot.data` (carried across HMR re-evaluations) so `use()`
+// never re-suspends; a rejected load is evicted so the next evaluation retries. The default export is
+// the single plugin — registered globally via bunfig preload and loaded by `[serve.static] plugins`.
 
 const ROOT = process.cwd();
 const NS = 'godot';
 
-/** Extension -> class. `loose` = WebP-backed texture excluded from the pack, staged/transcoded per-file. */
-const FORMATS: Record<string, { cls?: string; loose?: boolean }> = {
-	gltf: { cls: 'PackedScene' },
-	// A scene-composition document (a glTF External Reference): an imported source whose product is a
-	// `PackedScene`, like a `.gltf`'s — and whose product is where its meshes/textures are referenced.
-	gltfx: { cls: 'PackedScene' },
-	tscn: { cls: 'PackedScene' },
-	obj: { cls: 'PackedScene' },
-	gd: { cls: 'GDScript' },
-	gdshader: { cls: 'Shader' },
-	gdshaderinc: { cls: 'ShaderInclude' },
-	jpg: { cls: 'CompressedTexture2D', loose: true },
-	jpeg: { cls: 'CompressedTexture2D', loose: true },
-	png: { cls: 'CompressedTexture2D', loose: true },
-	webp: { cls: 'CompressedTexture2D', loose: true },
-	// The layer manifest `godot/addons/sourcewebp` imports into a `.ctexarray` (a texture array whose
-	// layers are source WebP bytes). It has no runtime deps of its own; the host stages its product.
-	webparray: { cls: 'CompressedTexture2DArray', loose: true },
-	svg: { cls: 'CompressedTexture2D', loose: true },
-	exr: { cls: 'TextureLayered', loose: true },
-	hdr: { cls: 'TextureLayered', loose: true },
-	wav: { cls: 'AudioStreamWAV' },
-	ogg: { cls: 'AudioStreamOggVorbis' },
-	mp3: { cls: 'AudioStreamMP3' },
-	tres: { cls: 'Resource' },
-	po: { cls: 'Translation' },
-	ttf: { cls: 'FontFile' },
-	otf: { cls: 'FontFile' },
-	mtl: {},
-};
-
-const ASSET_RE = new RegExp(
-	`\\.(${Object.entries(FORMATS).filter(([, f]) => f.cls).map(([k]) => k).join('|')})$`,
-	'i',
-);
-const CLASS_BY_EXT: Record<string, string> = Object.fromEntries(
-	Object.entries(FORMATS).filter(([, f]) => f.cls).map(([k, f]) => [k, f.cls!]),
-);
-const LOOSE = new Set(Object.entries(FORMATS).filter(([, f]) => f.loose).map(([k]) => k));
+const ASSET_RE = new RegExp(`\\.(${moduleExtensions.join('|')})$`, 'i');
 
-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 bakes native `.pck`s (`godot --export-pack`) — the engine-converted binary
-// resources + remap tables — through `@ringozz/godot/pack`'s `buildAssetPacks`: one per
-// 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 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<PackManifest>(resolve(PACK_DIR, 'packs.json'));
-
-/** The packs an asset needs mounted: the shared one plus its owner. */
-function packsFor(resPath: string): string[] {
-	return (MANIFEST?.packs ?? [])
-		.filter((pack) => pack.name === SHARED_PACK || 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 {
-	const deps = text.match(/^dest_files=\[([^\]]*)\]/m);
-	if (deps) {
-		const first = deps[1].match(/"([^"]+)"/);
-		if (first) {
-			return first[1];
-		}
+/** Where the boot pack was baked — `godot pack`'s `--out` ({@link PACK_DIR_ENV} overrides for a host). */
+const DIR = resolve(ROOT, process.env[PACK_DIR_ENV] ?? PACK_DIR);
+const MANIFEST = readJson<PackDoc>(resolve(DIR, BOOT_MANIFEST));
+/** The bake's generated boot module (`{ mounting }` + its config); null when unbaked. */
+const BOOT = MANIFEST ? resolve(DIR, BOOT_MODULE) : null;
+
+/**
+ * A content pack's entries, from the bake's own documents — `release.json` and each pack's emitted
+ * manifest, the same shapes the runtime fetches. A pack carries no entry module: the plugin serves one
+ * built from these, so an entry, its `res://` path and its class come from one declaration — the rule
+ * the bake emits the pack's types from as well (`packEntries`).
+ */
+const PACK_ENTRIES = readPacks();
+
+function readPacks(): Map<string, PackEntry[]> {
+	const packs = new Map<string, PackEntry[]>();
+	const release = readJson<Record<string, unknown>>(resolve(DIR, RELEASE));
+	for (const pack of Object.keys(release ?? {})) {
+		const entries = packEntries(readJson<PackDoc>(resolve(DIR, pack, PACK_DOC))?.exports);
+		if (entries.length) packs.set(pack, entries);
 	}
-	const remap = text.match(/^path="([^"]+)"/m);
-	return remap ? remap[1] : null;
+	return packs;
 }
 
-/** Adds a loose texture source to `files`: its `.import` sidecar (text) + product (file). */
-function addLoose(srcAbs: string, files: Map<string, 'text' | 'file'>): void {
-	const impAbs = srcAbs + '.import';
-	if (!existsSync(impAbs)) {
-		return;
-	}
-	files.set(resOf(srcAbs) + '.import', 'text');
-	const dest = parseSidecarDest(readFileSync(impAbs, 'utf8'));
-	if (dest) {
-		files.set(dest, 'file');
-	}
+/**
+ * The loose texture sources one asset stages: what the bake's manifest recorded for it, or itself when
+ * it *is* a loose texture — a source with an `.import` sidecar is excluded from the pack, so a texture
+ * imported on its own has no packed source to name it (the same rule `dump-deps.gd` classifies by).
+ */
+function needsOf(abs: string): string[] {
+	const res = resOf(abs);
+	const baked = MANIFEST?.needs[res];
+	if (baked) return baked;
+	return existsSync(abs + '.import') ? [res] : [];
 }
 
-function analyze(abs: string): Map<string, 'text' | 'file'> {
-	const files = new Map<string, 'text' | 'file'>();
-	// A directly imported loose texture stages itself; a packed resource stages the
-	// loose textures the engine's dependency dump found for it.
-	if (isLoose(abs)) {
-		addLoose(abs, files);
-	}
-	for (const loose of MANIFEST?.loose[resOf(abs)] ?? []) {
-		addLoose(resolve(ROOT, loose.slice('res://'.length)), files);
-	}
-	return files;
+/**
+ * A loose file's staging descriptor: the bake's own (its manifest carries every loose file the app's
+ * pack owns), or its sidecar when the bake never saw it — which is what keeps the plugin and a content
+ * pack's runtime staging on the same rule, `descriptorOf`.
+ */
+function descriptorFor(loose: string): { path: string; import: string } | null {
+	const baked = MANIFEST?.stage[loose];
+	if (baked) return baked;
+	const sidecar = resolve(ROOT, loose.slice('res://'.length)) + '.import';
+	return existsSync(sidecar) ? descriptorOf(readFileSync(sidecar, 'utf8')) : null;
 }
 
-function ensureModule(abs: string): string {
-	const res = resOf(abs);
-	const cls = CLASS_BY_EXT[extOf(abs)] ?? 'Resource';
-	const files = analyze(abs);
-
-	const imports = [
-		`import { loadAsset, loadAssetPack } from '@ringozz/godot/load';`,
-		`import { ${cls} } from '@ringozz/godot/${cls}';`,
-	];
-	let ready = 'undefined';
-	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;
-	// Loose texture files: sidecars as inlined string literals (Bun's
-	// `with { type: 'text' }` import resolves to a null/default under the dev
-	// server's HMR wrapper for a module's own path), products fetched by path so
-	// the host can transcode them.
-	for (const [resPath, kind] of files) {
-		const absP = resolve(ROOT, resPath.slice('res://'.length));
-		if (kind === 'text') {
-			map.push(`  ${JSON.stringify(resPath)}: { content: ${JSON.stringify(readFileSync(absP, 'utf8'))} },`);
-			continue;
-		}
-		const v = `f${fi++}`;
-		imports.push(`import ${v} from ${JSON.stringify(absP)} with { type: 'file' };`);
-		map.push(`  ${JSON.stringify(resPath)}: { path: ${v} },`);
-	}
-
-	const filesVar = files.size ? `const files = {\n${map.join('\n')}\n};` : `const files = {};`;
-	const loadAsset = `const { materialize, load } = loadAsset(${JSON.stringify(res)}, ${cls}, files, import.meta.hot.data, ${ready});`;
-	return imports.join('\n') + '\n' + filesVar + '\n' + loadAsset + '\n' + `export { materialize, load as default };` + '\n';
+/**
+ * One source's module, from the bake's own records: the loose textures the bake recorded for it (`needs`
+ * / `stage`, or its sidecar when the bake never saw it), each as the absolute path the bundler imports
+ * plus the two keys it stages under. Every other decision is the module text's (`serve.ts`).
+ */
+function servedAsset(abs: string): ServedAsset {
+	return {
+		res: resOf(abs),
+		// The filter is `moduleExtensions`, so a path that reached here has a class.
+		cls: classOf(abs)!,
+		boot: BOOT,
+		files: needsOf(abs).flatMap((loose) => {
+			const descriptor = descriptorFor(loose);
+			if (!descriptor) return [];
+			const { sidecar, product } = stagedKeys(loose, descriptor);
+			return [
+				{
+					specifier: resolve(ROOT, descriptor.path.replace(/^res:\/\//, '')),
+					sidecar,
+					content: descriptor.import,
+					product,
+				},
+			];
+		}),
+	};
 }
 
+/**
+ * Exactly the pack names the bake declares — nothing else is touched. A wider filter would shadow
+ * resolutions Bun makes itself (it injects a `react-refresh` import in dev, and that import must fall
+ * through to it, not to a plugin that declines).
+ */
+const PACK_RE = PACK_ENTRIES.size
+	? new RegExp(`^(${[...PACK_ENTRIES.keys()].map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})$`)
+	: null;
+
 const assetPlugin: BunPlugin = {
 	name: 'godot-assets',
 	setup(build) {
@@ -200,8 +146,15 @@ const assetPlugin: BunPlugin = {
 			const base = args.importer ? dirname(args.importer) : (args.resolveDir ?? ROOT);
 			return { path: resolve(base, args.path), namespace: NS };
 		});
+		// A pack's own module (the pack carries no entry file, so the plugin serves it, built from the
+		// bake's manifests). The filter names the packs exactly: anything else resolves as usual.
+		if (PACK_RE) {
+			build.onResolve({ filter: PACK_RE }, (args) => ({ path: args.path, namespace: NS }));
+		}
 		build.onLoad({ filter: /.*/, namespace: NS }, (args) => ({
-			contents: ensureModule(args.path),
+			contents: PACK_ENTRIES.has(args.path)
+				? packModule(args.path, PACK_ENTRIES.get(args.path)!)
+				: assetModule(servedAsset(args.path)),
 			loader: 'js',
 		}));
 	},

package/src/serve.ts

@@ -0,0 +1,67 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// The source text the preload plugin serves, as a virtual module per import: one for a Godot source
+// asset (the loose textures it stages, then the load), one for a content pack (a named export per entry
+// it declares). Pure — a module's text is a function of the facts the plugin resolved — which is what
+// makes the one part of the plugin that decides what an import becomes reachable without a bake, a
+// bundler or an engine. The plugin resolves those facts (`preload.ts`); nothing here touches a disk.
+
+import { entryId, type PackEntry } from './pack.ts';
+
+/** The facts the plugin resolved for one source asset, as the module it serves reads them. */
+export interface ServedAsset {
+	/** The source's `res://` path — what the module loads. */
+	res: string;
+	/** The class it loads as. */
+	cls: string;
+	/**
+	 * One entry per loose texture the source needs: the file to bundle (an absolute path, so the host can
+	 * transcode it), and the two keys it stages under. The sidecar text is inlined rather than imported
+	 * as text — Bun's `with { type: 'text' }` resolves to a null/default under the dev server's HMR
+	 * wrapper for a module's own path.
+	 */
+	files: Array<{ specifier: string; sidecar: string; content: string; product: string }>;
+	/** The boot module every asset module waits for (`{ mounting }`); `null` when the project is unbaked. */
+	boot: string | null;
+}
+
+/**
+ * One source's module: its loose textures as bundled files, and the load. The boot module supplies the
+ * mount to wait for, so the pack's remaps are in place before anything resolves — and importing it is
+ * also what mounts the boot pack.
+ */
+export function assetModule({ res, cls, files, boot }: ServedAsset): string {
+	const imports = [
+		`import { loadAsset } from '@ringozz/godot/load';`,
+		`import { ${cls} } from '@ringozz/godot/${cls}';`,
+	];
+	const map: string[] = [];
+	files.forEach(({ specifier, sidecar, content, product }, n) => {
+		imports.push(`import f${n} from ${JSON.stringify(specifier)} with { type: 'file' };`);
+		map.push(`\t${JSON.stringify(sidecar)}: { content: ${JSON.stringify(content)} },`);
+		map.push(`\t${JSON.stringify(product)}: { path: f${n} },`);
+	});
+	if (boot) imports.push(`import { mounting } from ${JSON.stringify(boot)};`);
+	const staged = map.length ? `const files = {\n${map.join('\n')}\n};` : 'const files = {};';
+	const load = `const { materialize, load } = loadAsset(${JSON.stringify(res)}, ${cls}, files, import.meta.hot.data, ${boot ? 'mounting' : 'undefined'});`;
+	return `${imports.join('\n')}\n${staged}\n${load}\nexport { materialize, load as default };\n`;
+}
+
+/**
+ * A content pack's module: one named export per entry its document declares, each loading through
+ * `loadPackEntry`, so a client resolves the entry by name from the document it fetched. Nothing about
+ * the pack is baked in — no entry file, no path — and the class is the same format-table rule every
+ * asset import uses.
+ */
+export function packModule(pack: string, entries: PackEntry[]): string {
+	const imports = ["import { loadPackEntry } from '@ringozz/godot/load';"];
+	for (const cls of new Set(entries.map((e) => e.cls))) {
+		imports.push(`import { ${cls} } from '@ringozz/godot/${cls}';`);
+	}
+	const lines = entries.map(
+		(e) => `export const ${entryId(e.entry)} = loadPackEntry(${JSON.stringify(pack)}, ${JSON.stringify(e.entry)}, ${e.cls});`,
+	);
+	return `${imports.join('\n')}\n\n${lines.join('\n')}\n`;
+}