@ringozz/godot 4.7.2-626 → 4.7.2-628

package/src/load.ts

@@ -1,231 +1,271 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-import { DirAccess } from '../gen/classes/DirAccess.ts';
-import { FileAccess } from '../gen/classes/FileAccess.ts';
-import { ProjectSettings } from '../gen/classes/ProjectSettings.ts';
-import { ResourceLoader, ThreadLoadStatus } from '../gen/classes/ResourceLoader.ts';
-import { ResourceUID } from '../gen/classes/ResourceUID.ts';
-import type { Resource } from '../gen/classes/Resource.ts';
-import { cleanupHooks, stageFile } from './runtime.ts';
-import { decodeCtex } from './web-image.ts';
-
-// Each loaded wrapper is released at shutdown via a `cleanupHooks` entry
-// holding a WeakRef: module-scope asset imports (the preload modules' memoized
-// load promises) keep their wrappers reachable, so GC alone can't collect them
-// before the engine stops. WeakRef keeps the entries from pinning resources
-// during the app's lifetime.
-function track<T extends Resource>(res: T): T {
-    const ref = new WeakRef<Resource>(res);
-    cleanupHooks.add(() => {
-        const r = ref.deref();
-        if (r) {
-            try { r.free(); } catch {}
-        }
-    });
-    return res;
-}
-
-/**
- * A Godot `Resource` subclass constructor: its `.name` is the registered class
- * name (used as the `ResourceLoader` type hint), and `InstanceType<C>` is the
- * loaded resource type.
- */
-type ResourceConstructor = { new(...args: any[]): Resource } & Function;
-
-/**
- * A file to stage before loading, keyed by `res://` path: sidecars (`.import`)
- * arrive as `content` (text); imported products (`.scn`/`.ctex`) arrive as
- * `path` (fetched).
- */
-interface AssetFile {
-	content?: string;
-	path?: string;
-}
-
-export type AssetFiles = Record<string, AssetFile>;
-
-const UID_RE = /uid="(uid:\/\/[\w.]+)"/;
-
-// Godot encodes `uid://` numbers in base 34 over `a-y` then `0-8`
-// (core/io/resource_uid.cpp). Decode in JS with BigInt: `ResourceUID.textToId`
-// returns a JS number, and these ids exceed `Number.MAX_SAFE_INTEGER`, so the
-// low digits would be lost. BigInt flows through `_C` losslessly (int64).
-const UID_CHARS = 'abcdefghijklmnopqrstuvwxy012345678';
-
-function uidToId(uid: string): bigint {
-	let id = 0n;
-	for (let i = 6; i < uid.length; i++) {
-		id = id * 34n + BigInt(UID_CHARS.indexOf(uid[i]));
-	}
-	return id;
-}
-
-/**
- * Registers an asset's `uid://` → `res://` path so scene ext_resource references
- * resolve it (Godot's `ResourceUID` map) instead of warning and falling back to
- * the stored text path. Idempotent; skips unknown/malformed uids.
- */
-function registerAssetUid(uid: string, resPath: string): void {
-	const id = uidToId(uid);
-	if (id !== 0n && !ResourceUID.hasId(id as unknown as number)) {
-		ResourceUID.addId(id as unknown as number, resPath);
-	}
-}
-
-async function materialize([resPath, entry]: [string, AssetFile]): Promise<void> {
-	if (FileAccess.fileExists(resPath)) {
-		return;
-	}
-	let bytes: Uint8Array;
-	if (entry.content !== undefined) {
-		// Sidecars (`.import`) and native text sources carry the asset's `uid=`;
-		// register it so scenes resolve by uid. `.import` maps to the source path
-		// (resPath minus the suffix); native files map to themselves.
-		const uid = entry.content.match(UID_RE)?.[1];
-		if (uid) {
-			registerAssetUid(uid, resPath.endsWith('.import') ? resPath.slice(0, -'.import'.length) : resPath);
-		}
-		bytes = new TextEncoder().encode(entry.content);
-	} else if (entry.path) {
-		const res = await fetch(entry.path);
-		if (!res.ok) {
-			return;
-		}
-		bytes = new Uint8Array(await res.arrayBuffer());
-		if (resPath.endsWith('.ctex')) {
-			// On web, decode embedded PNG/WebP blobs with the browser before
-			// staging, so the engine never runs an image codec (see web-image.ts).
-			bytes = await decodeCtex(bytes);
-		}
-	} else {
-		return;
-	}
-	stageFile?.(ProjectSettings.globalizePath(resPath), bytes);
-}
-
-const nextTick = () => new Promise(requestAnimationFrame);
-
-/**
- * An asset module as generated by `@ringozz/godot/preload`: `default` is the
- * load promise, `materialize` resolves once its bundled files (plus its deps'
- * files) are staged on the engine's filesystem.
- */
-interface AssetModule {
-	default: Promise<unknown>;
-	materialize: Promise<unknown>;
-}
-
-/**
- * Stages the asset's bundled files before loading: `.import` sidecars as text
- * and imported products (`.scn`/`.ctex`) as fetched paths. On web the bytes are
- * written straight into Emscripten's MEMFS via Godot's `copyToFS` (JS-heap only,
- * no wasm copy); a no-op on desktop where the files already exist. `deps`
- * supplies referenced asset modules whose file-staging is awaited (so Godot can
- * resolve them) and whose load failures are logged.
- */
-function materializeFiles(files: AssetFiles, deps: AssetModule[] = []): Promise<unknown> {
-	for (const dep of deps) {
-		dep.default.catch((err) => console.error('[godot] dependency load failed:', err));
-	}
-	if (stageFile === undefined) {
-		// Desktop: the files already exist on disk (res:// = cwd) and uids come
-		// from `.godot/uid_cache.bin`, so there is nothing to stage.
-		return Promise.resolve();
-	}
-	return Promise.all([...Object.entries(files).map(materialize), ...deps.map((dep) => dep.materialize)]);
-}
-
-/**
- * Returns a promise resolving to the resource already cached in the engine at
- * `path` (`ResourceCache`), or `null` when it isn't loaded yet. Used by
- * {@link loadAsset} to skip file staging and the threaded load when a
- * re-evaluated module (e.g. web HMR) references an asset that is still cached.
- * `getCachedRef` returns the same JS wrapper as `loadThreadedGet` (instance
- * binding), so identity is preserved.
- */
-function cachedResource<C extends ResourceConstructor>(path: string): Promise<InstanceType<C>> | null {
-	const result = ResourceLoader.getCachedRef(path) as InstanceType<C>;
-	return result ? Promise.resolve(result) : null;
-}
-
-/**
- * Entry point for the generated asset modules (`@ringozz/godot/preload`): checks
- * the engine's `ResourceCache` once (`cachedResource`), stages the bundled files
- * via `materializeFiles` when needed, then loads via {@link loadResourceAsync},
- * memoizing the resulting load promise on `data` (the module's
- * `import.meta.hot.data`, carried across HMR re-evaluations; `{}` on desktop
- * where modules evaluate once). Memoization keeps `use()` seeing the **same**
- * fulfilled promise object across re-evaluations — no Suspense fallback flash on
- * hot reload; a rejected load is evicted so the next evaluation retries. Returns
- * the `materialize` promise (own + deps' files staged) and the load promise.
- */
-export function loadAsset<C extends ResourceConstructor>(
-	path: string,
-	cls: C,
-	files: AssetFiles,
-	deps: AssetModule[] = [],
-	data: Record<string, unknown> = {},
-): { materialize: Promise<unknown>; load: Promise<InstanceType<C>> } {
-	const cached = cachedResource<C>(path);
-	if (cached) cached.then(track);
-	const materialize = cached ? Promise.resolve() : materializeFiles(files, deps);
-	const existing = data[path] as Promise<InstanceType<C>> | undefined;
-	const load = existing ?? cached ?? materialize.then(() => loadResourceAsync(path, cls, files));
-	data[path] = load;
-	load.catch(() => {
-		if (data[path] === load) delete data[path];
-	});
-	return { materialize, load };
-}
-
-/**
- * Loads a resource in the background. `cls` supplies both the `ResourceLoader`
- * type hint (its registered `.name`) and the return type. On web, call
- * {@link materializeFiles} with the asset's bundled files first; on desktop the
- * files already exist. Pass the same `files` map to have the staged files
- * deleted from MEMFS once the resource is loaded (the resource stays cached in
- * the engine, so the bytes are no longer needed).
- */
-export async function loadResourceAsync<C extends ResourceConstructor>(
-	path: string,
-	cls: C,
-	files?: AssetFiles,
-): Promise<InstanceType<C>> {
-	const err = ResourceLoader.loadThreadedRequest(path, cls.name);
-	if (err) {
-		throw new Error(`loadResourceAsync(${path}): loadThreadedRequest failed (${err})`);
-	}
-
-	let result: InstanceType<C>;
-	while (true) {
-		const status = ResourceLoader.loadThreadedGetStatus(path);
-		if (status === ThreadLoadStatus.THREAD_LOAD_LOADED) {
-			result = ResourceLoader.loadThreadedGet(path) as InstanceType<C>;
-			break;
-		}
-		if (status === ThreadLoadStatus.THREAD_LOAD_FAILED || status === ThreadLoadStatus.THREAD_LOAD_INVALID_RESOURCE) {
-			// Collect the engine's LoadToken so a failed load doesn't leave it
-			// registered (a bare `RefCounted` leaked at exit). Safe no-op when
-			// no token exists.
-			ResourceLoader.loadThreadedGet(path);
-			throw new Error(`loadResourceAsync(${path}): load failed (status ${status})`);
-		}
-		await nextTick();
-	}
-	if (files && stageFile !== undefined) {
-		// Keep `.import` sidecars — they route imported source paths to their
-		// products (ResourceFormatImporter recognizes a path by its sidecar).
-		// Delete everything else: the products are read only on a cache miss, and
-		// the resource stays cached after loading, so the bytes are dead weight.
-		// Best-effort: a file may already be gone (another module's cleanup or a
-		// cache-miss re-stage).
-		for (const resPath of Object.keys(files)) {
-			if (!resPath.endsWith('.import')) {
-				DirAccess.removeAbsolute(resPath);
-			}
-		}
-	}
-	return track(result);
-}
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { DirAccess } from '../gen/classes/DirAccess.ts';
+import { FileAccess } from '../gen/classes/FileAccess.ts';
+import { ProjectSettings } from '../gen/classes/ProjectSettings.ts';
+import { ResourceLoader, ThreadLoadStatus } from '../gen/classes/ResourceLoader.ts';
+import { ResourceUID } from '../gen/classes/ResourceUID.ts';
+import type { Resource } from '../gen/classes/Resource.ts';
+import { cleanupHooks, stageFile } from './runtime.ts';
+import { transcoder } from '@ringozz/godot/transcoder';
+import { decodeCtex } from './web-image.ts';
+
+/**
+ * Produces the bytes staged for a `.ctex`: the platform transcoder (resolved
+ * once by `@ringozz/godot/transcoder`) when it yields a result, otherwise the raw
+ * RGBA8 browser decode. Never throws — a failed transcode degrades to the
+ * uncompressed path.
+ */
+async function transcodeCtex(bytes: Uint8Array): Promise<Uint8Array> {
+    const encode = await transcoder;
+    if (encode) {
+        try {
+            const out = await encode(bytes);
+            if (out) {
+                return out;
+            }
+        } catch (err) {
+            console.warn('[godot] texture transcode failed; using raw RGBA8:', err);
+        }
+    }
+    return decodeCtex(bytes);
+}
+
+// Each loaded wrapper is released at shutdown via a `cleanupHooks` entry
+// holding a WeakRef: module-scope asset imports (the preload modules' memoized
+// load promises) keep their wrappers reachable, so GC alone can't collect them
+// before the engine stops. WeakRef keeps the entries from pinning resources
+// during the app's lifetime.
+function track<T extends Resource>(res: T): T {
+    const ref = new WeakRef<Resource>(res);
+    cleanupHooks.add(() => {
+        const r = ref.deref();
+        if (r) {
+            try { r.free(); } catch {}
+        }
+    });
+    return res;
+}
+
+/**
+ * A Godot `Resource` subclass constructor: its `.name` is the registered class
+ * name (used as the `ResourceLoader` type hint), and `InstanceType<C>` is the
+ * loaded resource type.
+ */
+type ResourceConstructor = { new(...args: any[]): Resource } & Function;
+
+/**
+ * A file to stage before loading, keyed by `res://` path: sidecars (`.import`)
+ * arrive as `content` (text); imported products (`.scn`/`.ctex`) arrive as
+ * `path` (fetched).
+ */
+interface AssetFile {
+	content?: string;
+	path?: string;
+}
+
+export type AssetFiles = Record<string, AssetFile>;
+
+const UID_RE = /uid="(uid:\/\/[\w.]+)"/;
+
+// Compressed-texture products whose payloads may need decoding/transcoding:
+// `.ctex` (CompressedTexture2D) and the layered `.ctexarray` / `.ccube` /
+// `.ccubearray` (2D array / cubemap / cubemap array). `.ctex3d` has its own
+// layout and is left to the engine.
+const COMPRESSED_TEXTURE_RE = /\.(ctex|ctexarray|ccube|ccubearray)$/;
+
+// Textures the runtime must receive *exactly* as the server served them, so they are decoded to raw RGBA8
+// instead of going through the platform transcoder (spark -> BC7/ASTC): the terrain height atlas
+// (`<level>.dat/terrain/height.webp`), whose 12-bit packed R/G the vertex shader decodes per texel, so
+// block quantisation shows as blocky relief on every slope. Everything else may be compressed — the
+// surface arrays, the weight planes and the `_n` tile normal all ship as layered containers the runtime
+// only samples (see `docs/godot.md`'s M4 section). The `.ctex` product is named after its source plus an
+// md5, which is what the pattern keys on.
+const EXACT_TEXTURE_RE = /(^|\/)height\.webp-[0-9a-f]+\.ctex$/;
+
+// Godot encodes `uid://` numbers in base 34 over `a-y` then `0-8`
+// (core/io/resource_uid.cpp). Decode in JS with BigInt: `ResourceUID.textToId`
+// returns a JS number, and these ids exceed `Number.MAX_SAFE_INTEGER`, so the
+// low digits would be lost. BigInt flows through `_C` losslessly (int64).
+const UID_CHARS = 'abcdefghijklmnopqrstuvwxy012345678';
+
+function uidToId(uid: string): bigint {
+	let id = 0n;
+	for (let i = 6; i < uid.length; i++) {
+		id = id * 34n + BigInt(UID_CHARS.indexOf(uid[i]));
+	}
+	return id;
+}
+
+/**
+ * Registers an asset's `uid://` → `res://` path so scene ext_resource references
+ * resolve it (Godot's `ResourceUID` map) instead of warning and falling back to
+ * the stored text path. Idempotent; skips unknown/malformed uids.
+ */
+function registerAssetUid(uid: string, resPath: string): void {
+	const id = uidToId(uid);
+	if (id !== 0n && !ResourceUID.hasId(id as unknown as number)) {
+		ResourceUID.addId(id as unknown as number, resPath);
+	}
+}
+
+async function materialize([resPath, entry]: [string, AssetFile]): Promise<void> {
+	if (FileAccess.fileExists(resPath)) {
+		return;
+	}
+	let bytes: Uint8Array;
+	if (entry.content !== undefined) {
+		// Sidecars (`.import`) and native text sources carry the asset's `uid=`;
+		// register it so scenes resolve by uid. `.import` maps to the source path
+		// (resPath minus the suffix); native files map to themselves.
+		const uid = entry.content.match(UID_RE)?.[1];
+		if (uid) {
+			registerAssetUid(uid, resPath.endsWith('.import') ? resPath.slice(0, -'.import'.length) : resPath);
+		}
+		bytes = new TextEncoder().encode(entry.content);
+	} else if (entry.path) {
+		const res = await fetch(entry.path);
+		if (!res.ok) {
+			return;
+		}
+		bytes = new Uint8Array(await res.arrayBuffer());
+		if (COMPRESSED_TEXTURE_RE.test(resPath)) {
+			// On web, decode embedded PNG/WebP blobs with the browser before
+			// staging, so the engine never runs an image codec. A registered
+			// transcoder (e.g. spark.js) may instead rebuild the container as a
+			// device-native block-compressed texture by the built-in transcoder —
+			// except for `EXACT_TEXTURE_RE`'s routes, which must stay raw (see there).
+			bytes = EXACT_TEXTURE_RE.test(resPath) ? await decodeCtex(bytes) : await transcodeCtex(bytes);
+		}
+	} else {
+		return;
+	}
+	stageFile?.(ProjectSettings.globalizePath(resPath), bytes);
+}
+
+const nextTick = () => new Promise(requestAnimationFrame);
+
+/**
+ * An asset module as generated by `@ringozz/godot/preload`: `default` is the
+ * load promise, `materialize` resolves once its bundled files (plus its deps'
+ * files) are staged on the engine's filesystem.
+ */
+interface AssetModule {
+	default: Promise<unknown>;
+	materialize: Promise<unknown>;
+}
+
+/**
+ * Stages the asset's bundled files before loading: `.import` sidecars as text
+ * and imported products (`.scn`/`.ctex`) as fetched paths. On web the bytes are
+ * written straight into Emscripten's MEMFS via Godot's `copyToFS` (JS-heap only,
+ * no wasm copy); a no-op on desktop where the files already exist. `deps`
+ * supplies referenced asset modules whose file-staging is awaited (so Godot can
+ * resolve them) and whose load failures are logged.
+ */
+function materializeFiles(files: AssetFiles, deps: AssetModule[] = []): Promise<unknown> {
+	for (const dep of deps) {
+		dep.default.catch((err) => console.error('[godot] dependency load failed:', err));
+	}
+	if (stageFile === undefined) {
+		// Desktop: the files already exist on disk (res:// = cwd) and uids come
+		// from `.godot/uid_cache.bin`, so there is nothing to stage.
+		return Promise.resolve();
+	}
+	return Promise.all([...Object.entries(files).map(materialize), ...deps.map((dep) => dep.materialize)]);
+}
+
+/**
+ * Returns a promise resolving to the resource already cached in the engine at
+ * `path` (`ResourceCache`), or `null` when it isn't loaded yet. Used by
+ * {@link loadAsset} to skip file staging and the threaded load when a
+ * re-evaluated module (e.g. web HMR) references an asset that is still cached.
+ * `getCachedRef` returns the same JS wrapper as `loadThreadedGet` (instance
+ * binding), so identity is preserved.
+ */
+function cachedResource<C extends ResourceConstructor>(path: string): Promise<InstanceType<C>> | null {
+	const result = ResourceLoader.getCachedRef(path) as InstanceType<C>;
+	return result ? Promise.resolve(result) : null;
+}
+
+/**
+ * Entry point for the generated asset modules (`@ringozz/godot/preload`): checks
+ * the engine's `ResourceCache` once (`cachedResource`), stages the bundled files
+ * via `materializeFiles` when needed, then loads via {@link loadResourceAsync},
+ * memoizing the resulting load promise on `data` (the module's
+ * `import.meta.hot.data`, carried across HMR re-evaluations; `{}` on desktop
+ * where modules evaluate once). Memoization keeps `use()` seeing the **same**
+ * fulfilled promise object across re-evaluations — no Suspense fallback flash on
+ * hot reload; a rejected load is evicted so the next evaluation retries. Returns
+ * the `materialize` promise (own + deps' files staged) and the load promise.
+ */
+export function loadAsset<C extends ResourceConstructor>(
+	path: string,
+	cls: C,
+	files: AssetFiles,
+	deps: AssetModule[] = [],
+	data: Record<string, unknown> = {},
+): { materialize: Promise<unknown>; load: Promise<InstanceType<C>> } {
+	const cached = cachedResource<C>(path);
+	if (cached) cached.then(track);
+	const materialize = cached ? Promise.resolve() : materializeFiles(files, deps);
+	const existing = data[path] as Promise<InstanceType<C>> | undefined;
+	const load = existing ?? cached ?? materialize.then(() => loadResourceAsync(path, cls, files));
+	data[path] = load;
+	load.catch(() => {
+		if (data[path] === load) delete data[path];
+	});
+	return { materialize, load };
+}
+
+/**
+ * Loads a resource in the background. `cls` supplies both the `ResourceLoader`
+ * type hint (its registered `.name`) and the return type. On web, call
+ * {@link materializeFiles} with the asset's bundled files first; on desktop the
+ * files already exist. Pass the same `files` map to have the staged files
+ * deleted from MEMFS once the resource is loaded (the resource stays cached in
+ * the engine, so the bytes are no longer needed).
+ */
+export async function loadResourceAsync<C extends ResourceConstructor>(
+	path: string,
+	cls: C,
+	files?: AssetFiles,
+): Promise<InstanceType<C>> {
+	const err = ResourceLoader.loadThreadedRequest(path, cls.name);
+	if (err) {
+		throw new Error(`loadResourceAsync(${path}): loadThreadedRequest failed (${err})`);
+	}
+
+	let result: InstanceType<C>;
+	while (true) {
+		const status = ResourceLoader.loadThreadedGetStatus(path);
+		if (status === ThreadLoadStatus.THREAD_LOAD_LOADED) {
+			result = ResourceLoader.loadThreadedGet(path) as InstanceType<C>;
+			break;
+		}
+		if (status === ThreadLoadStatus.THREAD_LOAD_FAILED || status === ThreadLoadStatus.THREAD_LOAD_INVALID_RESOURCE) {
+			// Collect the engine's LoadToken so a failed load doesn't leave it
+			// registered (a bare `RefCounted` leaked at exit). Safe no-op when
+			// no token exists.
+			ResourceLoader.loadThreadedGet(path);
+			throw new Error(`loadResourceAsync(${path}): load failed (status ${status})`);
+		}
+		await nextTick();
+	}
+	if (files && stageFile !== undefined) {
+		// Keep `.import` sidecars — they route imported source paths to their
+		// products (ResourceFormatImporter recognizes a path by its sidecar).
+		// Delete everything else: the products are read only on a cache miss, and
+		// the resource stays cached after loading, so the bytes are dead weight.
+		// Best-effort: a file may already be gone (another module's cleanup or a
+		// cache-miss re-stage).
+		for (const resPath of Object.keys(files)) {
+			if (!resPath.endsWith('.import')) {
+				DirAccess.removeAbsolute(resPath);
+			}
+		}
+	}
+	return track(result);
+}