@ringozz/godot 4.7.1-1 → 4.7.1-11

package/src/preload.ts

@@ -0,0 +1,198 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { plugin } from 'bun';
+import type { BunPlugin } from 'bun';
+
+// Registers the godot-assets plugin: imports of Godot source assets become
+// virtual modules (namespace `godot`) that call `loadAsset` (`@ringozz/godot/load`)
+// and export the resulting `materialize` (own + deps' files) and load promise.
+// `loadAsset` checks the engine's `ResourceCache` once; when the asset is
+// already loaded (e.g. a re-evaluated module under web HMR) the load resolves to
+// the cached instance and `materialize` short-circuits, skipping file staging
+// and the threaded load. The load promise persists on the module's
+// `import.meta.hot.data` (per-module state carried across hot replacements), so
+// HMR re-evaluations return the *same* fulfilled promise object — React's `use()`
+// keeps its tracked status and never re-suspends (no Suspense fallback flash); a
+// rejected load is evicted from `data` so the next evaluation retries; on
+// desktop `data` is `{}` and modules evaluate once. Dependencies are generated
+// modules too, so a dep's load starts at module evaluation while the parent only
+// waits for dep *files*. The default export is the single plugin — registered
+// globally via bunfig preload and loaded by `[serve.static] plugins` for
+// `Bun.serve` HTML routes.
+
+const ROOT = process.cwd();
+const NS = 'godot';
+
+/** Format metadata: `cls` = Godot class (importable), `scan` = scan text refs, `native` = no `.import` sidecar. */
+const FORMATS: Record<string, { cls?: string; scan?: boolean; native?: boolean }> = {
+	gltf: { cls: 'PackedScene', scan: true },
+	tscn: { cls: 'PackedScene', scan: true, native: true },
+	obj: { cls: 'PackedScene', scan: true },
+	jpg: { cls: 'CompressedTexture2D' },
+	jpeg: { cls: 'CompressedTexture2D' },
+	png: { cls: 'CompressedTexture2D' },
+	webp: { cls: 'CompressedTexture2D' },
+	svg: { cls: 'Texture2D' },
+	exr: { cls: 'TextureLayered' },
+	hdr: { cls: 'TextureLayered' },
+	wav: { cls: 'AudioStreamWAV' },
+	ogg: { cls: 'AudioStreamOggVorbis' },
+	mp3: { cls: 'AudioStreamMP3' },
+	tres: { cls: 'Resource', scan: true, native: true },
+	po: { cls: 'Translation', native: true },
+	mtl: { scan: true },
+};
+
+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 SCANNED = new Set(Object.entries(FORMATS).filter(([, f]) => f.scan).map(([k]) => k));
+const NATIVE = new Set(Object.entries(FORMATS).filter(([, f]) => f.native).map(([k]) => k));
+
+const extOf = (abs: string) => abs.slice(abs.lastIndexOf('.') + 1).toLowerCase();
+const resOf = (abs: string) => 'res://' + abs.slice(ROOT.length + 1).replaceAll('\\', '/');
+const isScannableText = (abs: string) => SCANNED.has(extOf(abs));
+const isNativeText = (abs: string) => NATIVE.has(extOf(abs));
+const isSourceAsset = (abs: string) => existsSync(abs + '.import') || isNativeText(abs);
+
+/** 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];
+		}
+	}
+	const remap = text.match(/^path="([^"]+)"/m);
+	return remap ? remap[1] : null;
+}
+
+// Generalized reference extraction for text-based source assets: absolute
+// `res://` paths (Godot scenes/resources) and relative path tokens ending in a
+// known asset extension (glTF uris, OBJ/MTL textures). The literal dot before
+// the extension avoids matching MIME types inside `data:` URIs.
+const RES_RE = /res:\/\/[\w./\\-]+/g;
+const REL_RE = new RegExp(`([\\w./\\\\-]+\\.(?:${Object.keys(FORMATS).join('|')}))`, 'g');
+
+function extractRefs(text: string): string[] {
+	const refs: string[] = [];
+	for (const m of text.matchAll(RES_RE)) refs.push(m[0]);
+	for (const m of text.matchAll(REL_RE)) refs.push(m[1]);
+	return refs;
+}
+
+/**
+ * Adds a source asset's own files to `files`: imported assets contribute their
+ * `.import` sidecar (text) + imported product (file); native text formats
+ * (tscn/tres/po) contribute the file itself (text).
+ */
+function addSource(srcAbs: string, files: Map<string, 'text' | 'file'>): void {
+	const impAbs = srcAbs + '.import';
+	if (existsSync(impAbs)) {
+		files.set(resOf(srcAbs) + '.import', 'text');
+		const dest = parseSidecarDest(readFileSync(impAbs, 'utf8'));
+		if (dest) {
+			files.set(dest, 'file');
+		}
+	} else if (isNativeText(srcAbs)) {
+		files.set(resOf(srcAbs), 'text');
+	}
+}
+
+/**
+ * Collects the referenced source assets (deps) of a text source: source assets
+ * become dep modules (each handles its own transitive deps); raw text formats
+ * without a sidecar (`.mtl`) are recursed into. Buffers (`.bin`) are skipped.
+ */
+function collectDeps(abs: string, visited: Set<string>, deps: string[]): void {
+	if (visited.has(abs)) {
+		return;
+	}
+	visited.add(abs);
+	if (!isScannableText(abs)) {
+		return;
+	}
+	for (const ref of extractRefs(readFileSync(abs, 'utf8'))) {
+		const refAbs = ref.startsWith('res://')
+			? resolve(ROOT, ref.slice('res://'.length))
+			: resolve(dirname(abs), ref);
+		if (visited.has(refAbs)) {
+			continue;
+		}
+		if (isSourceAsset(refAbs)) {
+			deps.push(refAbs);
+		} else if (isScannableText(refAbs)) {
+			collectDeps(refAbs, visited, deps);
+		}
+	}
+}
+
+function analyze(abs: string): { files: Map<string, 'text' | 'file'>; deps: string[] } {
+	const files = new Map<string, 'text' | 'file'>();
+	const deps: string[] = [];
+	addSource(abs, files);
+	collectDeps(abs, new Set(), deps);
+	return { files, deps };
+}
+
+function ensureModule(abs: string): string {
+	const res = resOf(abs);
+	const cls = CLASS_BY_EXT[extOf(abs)] ?? 'Resource';
+	const { files, deps } = analyze(abs);
+
+	const imports = [
+		`import { loadAsset } from '@ringozz/godot/load';`,
+		`import { ${cls} } from '@ringozz/godot/${cls}';`,
+	];
+	const map: string[] = [];
+	let ti = 0;
+	let fi = 0;
+	for (const [resPath, kind] of files) {
+		const absP = resolve(ROOT, resPath.slice('res://'.length));
+		const v = kind === 'text' ? `c${ti++}` : `f${fi++}`;
+		const type = kind === 'text' ? 'text' : 'file';
+		const field = kind === 'text' ? 'content' : 'path';
+		imports.push(`import ${v} from ${JSON.stringify(absP)} with { type: '${type}' };`);
+		map.push(`  ${JSON.stringify(resPath)}: { ${field}: ${v} },`);
+	}
+	deps.forEach((dep, i) => imports.push(`import * as dep${i} from ${JSON.stringify(dep)};`));
+
+	const filesVar = files.size ? `const files = {\n${map.join('\n')}\n};` : `const files = {};`;
+	const loadAsset = `const { materialize, load } = loadAsset(${JSON.stringify(res)}, ${cls}, files, [${deps.map((_, i) => `dep${i}`).join(', ')}], import.meta.hot.data);`;
+	return imports.join('\n') + '\n' + filesVar + '\n' + loadAsset + '\n' + `export { materialize, load as default };` + '\n';
+}
+
+const assetPlugin: BunPlugin = {
+	name: 'godot-assets',
+	setup(build) {
+		build.onResolve({ filter: ASSET_RE }, (args) => {
+			const importerAbs = args.importer?.startsWith(`${NS}:`)
+				? args.importer.slice(NS.length + 1)
+				: args.importer;
+			const base = importerAbs ? dirname(importerAbs) : (args.resolveDir ?? ROOT);
+			const abs = resolve(base, args.path);
+			// A module's own native-text source (e.g. `.tscn`) self-imports the
+			// same path — let it load as a real file.
+			if (abs === importerAbs) {
+				return;
+			}
+			return { path: abs, namespace: NS };
+		});
+		build.onLoad({ filter: /.*/, namespace: NS }, (args) => ({
+			contents: ensureModule(args.path),
+			loader: 'js',
+		}));
+	},
+};
+
+export default assetPlugin;
+plugin(assetPlugin);

package/src/runtime.ts

@@ -2,13 +2,23 @@
  Copyright (c) Vladimir Davidovich. All rights reserved.
 ***********************************************************************/
 
-const { platform, arch } = globalThis.process ?? {};
-const mapping: any = {
-    'darwin-arm64': 'macos-arm64',
-    'win32-x64': 'windows-x86_64',
-};
-const suffix = mapping[`${platform}-${arch}`];
-const { default: _mod } = await (suffix ? import(`@ringozz/godot-${suffix}`) : import('@ringozz/godot-web-wasm32'));
+/** Shared runtime: platform-specific native-module selection lives in
+ *  `boot.ts` (desktop) / `boot.browser.ts` (web, via the `exports` `./boot`
+ *  entry's `browser` condition). `_mod` is the native module — the desktop
+ *  addon's `module.exports` or the wasm module's `.default`.
+ *
+ *  The boot leaf is imported by **package self-reference** (`@ringozz/godot/boot`),
+ *  not by relative path: a bare specifier resolves through this package's own
+ *  `exports` map (whose `./boot` entry's `browser` condition selects
+ *  `boot.browser.ts` on web) exactly like the entrypoint's
+ *  `import { preloadGodot } from '@ringozz/godot/boot'`, so both sides land on the
+ *  same absolute path and share ONE `boot.browser.ts` module instance. (A relative
+ *  `./boot.ts` import would let a consumer's bundler realpath it into
+ *  `node_modules/.bun/...` while the entrypoint keeps the `node_modules/@ringozz/godot`
+ *  path — two instances, and the preload handoff below would read `null`.)
+ */
+import { getNativeModule } from '@ringozz/godot/boot';
+const { default: _mod } = getNativeModule() as any;
 
 /** Godot instance */
 import type { GodotInstance } from '../gen/classes/GodotInstance.ts';
@@ -42,6 +52,9 @@ export const _set = _mod._set as (target: GodotVar, nameId: number, val: unknown
 /** Register Godot object wrapper. */
 export const _R = _mod._R as (typeId: number, ctor: Function) => string;
 
+/** Stage bytes into the web MEMFS (Godot's `copyToFS`); undefined on desktop. */
+export const stageFile = (_mod as any).stageFile as ((path: string, bytes: Uint8Array) => void) | undefined;
+
 /** Get a Signal value from an Object by signal name, or connect a callback when 3rd arg given. */
 export const _G = _mod._G as (target: GodotVar, signalNameId: number, callback?: unknown) => unknown;
 

package/src/web-image.ts

@@ -0,0 +1,118 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// Web-only: decode the embedded PNG/WebP blobs of a `.ctex` CompressedTexture2D
+// container with the browser's `createImageBitmap`, and rebuild the container as
+// a raw RGBA8 `DATA_FORMAT_IMAGE` ctex — so no image codec runs in wasm on web.
+// Anything that isn't a PNG/WebP-embedded ctex is returned unchanged.
+
+const CTEX_MAGIC = 'GST2';
+const DATA_FORMAT_IMAGE = 0;
+const DATA_FORMAT_PNG = 1;
+const DATA_FORMAT_WEBP = 2;
+const FORMAT_RGBA8 = 5;
+const FORMAT_BIT_STREAM = 1 << 22;
+
+// Outer header: magic(4) version(4) w(4) h(4) df(4) mipmap_limit(4) reserved(12).
+const OUTER_HEADER_SIZE = 36;
+// Sub-header: data_format(4) w(2) h(2) mipmaps(4) format(4).
+const SUB_HEADER_OFFSET = OUTER_HEADER_SIZE;
+const SUB_HEADER_SIZE = 16;
+const BLOB_TABLE_OFFSET = SUB_HEADER_OFFSET + SUB_HEADER_SIZE;
+
+interface DecodedBitmap {
+	width: number;
+	height: number;
+	data: Uint8Array;
+}
+
+async function decodeWebBitmap(blob: Uint8Array<ArrayBuffer>, type: string): Promise<DecodedBitmap> {
+	const bmp = await createImageBitmap(new Blob([blob], { type }), {
+		imageOrientation: 'none',
+		colorSpaceConversion: 'none',
+		premultiplyAlpha: 'none',
+	});
+	try {
+		const canvas = new OffscreenCanvas(bmp.width, bmp.height);
+		const ctx = canvas.getContext('2d', { colorSpace: 'srgb', willReadFrequently: true }) as
+			| OffscreenCanvasRenderingContext2D
+			| null;
+		if (!ctx) {
+			throw new Error('web-image: no 2d context for OffscreenCanvas');
+		}
+		ctx.drawImage(bmp, 0, 0);
+		const img = ctx.getImageData(0, 0, bmp.width, bmp.height);
+		return { width: bmp.width, height: bmp.height, data: new Uint8Array(img.data.buffer, img.data.byteOffset, img.data.byteLength) };
+	} finally {
+		bmp.close();
+	}
+}
+
+/**
+ * Decodes the embedded PNG/WebP blobs of a `.ctex` file with the browser's
+ * `createImageBitmap` and rebuilds it as a raw RGBA8 (`DATA_FORMAT_IMAGE`)
+ * container. Non-ctex bytes, streamable textures, and `DATA_FORMAT_IMAGE` /
+ * `DATA_FORMAT_BASIS_UNIVERSAL` containers are returned unchanged. Throws if an
+ * embedded blob can't be decoded or its dimensions don't match the expected
+ * mipmap layout, so a would-be undecodable texture fails loudly at materialize
+ * time. A no-op outside browsers (no `createImageBitmap`).
+ */
+export async function decodeCtex(bytes: Uint8Array): Promise<Uint8Array> {
+	if (
+		typeof createImageBitmap !== 'function' ||
+		bytes.length < SUB_HEADER_OFFSET + SUB_HEADER_SIZE ||
+		String.fromCharCode(...bytes.subarray(0, 4)) !== CTEX_MAGIC
+	) {
+		return bytes;
+	}
+	const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	if (dv.getUint32(16, true) & FORMAT_BIT_STREAM) {
+		return bytes; // streamable layout differs; leave it to the engine
+	}
+	const dataFormat = dv.getUint32(SUB_HEADER_OFFSET, true);
+	if (dataFormat !== DATA_FORMAT_PNG && dataFormat !== DATA_FORMAT_WEBP) {
+		return bytes; // raw and BASIS_UNIVERSAL containers pass through
+	}
+	const w = dv.getUint16(SUB_HEADER_OFFSET + 4, true);
+	const h = dv.getUint16(SUB_HEADER_OFFSET + 6, true);
+	const mipmaps = dv.getUint32(SUB_HEADER_OFFSET + 8, true);
+	const type = dataFormat === DATA_FORMAT_WEBP ? 'image/webp' : 'image/png';
+
+	let ofs = BLOB_TABLE_OFFSET;
+	const levels: Uint8Array[] = [];
+	for (let i = 0; i <= mipmaps; i++) {
+		if (ofs + 4 > bytes.length) {
+			throw new Error(`web-image: truncated ctex at mipmap ${i}`);
+		}
+		const size = dv.getUint32(ofs, true);
+		ofs += 4;
+		if (ofs + size > bytes.length) {
+			throw new Error(`web-image: truncated ctex blob at mipmap ${i}`);
+		}
+		const bmp = await decodeWebBitmap(bytes.slice(ofs, ofs + size), type);
+		ofs += size;
+		const ew = Math.max(w >> i, 1);
+		const eh = Math.max(h >> i, 1);
+		if (bmp.width !== ew || bmp.height !== eh) {
+			throw new Error(`web-image: mipmap ${i} decoded as ${bmp.width}x${bmp.height}, expected ${ew}x${eh}`);
+		}
+		levels.push(bmp.data);
+	}
+
+	const dataSize = levels.reduce((n, level) => n + level.length, 0);
+	const out = new Uint8Array(BLOB_TABLE_OFFSET + dataSize);
+	out.set(bytes.subarray(0, OUTER_HEADER_SIZE)); // outer header verbatim
+	const odv = new DataView(out.buffer);
+	odv.setUint32(SUB_HEADER_OFFSET, DATA_FORMAT_IMAGE, true);
+	odv.setUint16(SUB_HEADER_OFFSET + 4, w, true);
+	odv.setUint16(SUB_HEADER_OFFSET + 6, h, true);
+	odv.setUint32(SUB_HEADER_OFFSET + 8, mipmaps, true);
+	odv.setUint32(SUB_HEADER_OFFSET + 12, FORMAT_RGBA8, true);
+	let p = BLOB_TABLE_OFFSET;
+	for (const level of levels) {
+		out.set(level, p);
+		p += level.length;
+	}
+	return out;
+}