@ringozz/godot 4.7.2-661 → 4.7.2-676

package/src/load.ts

@@ -10,6 +10,20 @@ 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 {
+	FILES_DIR,
+	PACK_DOC,
+	mountClosure,
+	parseDoc,
+	parseRelease,
+	pckOf,
+	resolveEntry,
+	type PackDoc,
+	type Release,
+	type ResolvedEntry,
+	type StagedFile,
+	type StagedFiles,
+} from './pack.ts';
 import { decodeCtex } from './web-image.ts';
 
 /**
@@ -57,18 +71,6 @@ function track<T extends Resource>(res: T): T {
  */
 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:
@@ -79,7 +81,7 @@ 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
+// (`<name>.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
@@ -112,7 +114,27 @@ function registerAssetUid(uid: string, resPath: string): void {
 	}
 }
 
-async function materialize([resPath, entry]: [string, AssetFile]): Promise<void> {
+// res:// paths already staged, or being staged: MEMFS cannot be read back reliably — the engine's
+// `res://` lookup and the Emscripten path disagree by a leading slash — so `FileAccess.fileExists`
+// cannot answer "is this staged?", and two asset modules needing the same file would fetch and
+// allocate it twice. A path is forgotten when its bytes are removed after a load.
+const staged = new Map<string, Promise<void>>();
+
+async function materialize(entry: [string, StagedFile]): Promise<void> {
+	const [resPath] = entry;
+	const existing = staged.get(resPath);
+	if (existing) {
+		return existing;
+	}
+	const p = stage(entry).catch((err) => {
+		staged.delete(resPath);
+		throw err;
+	});
+	staged.set(resPath, p);
+	return p;
+}
+
+async function stage([resPath, entry]: [string, StagedFile]): Promise<void> {
 	if (FileAccess.fileExists(resPath)) {
 		return;
 	}
@@ -163,7 +185,7 @@ const nextTick = () => new Promise(requestAnimationFrame);
  * 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.
  */
-function materializeFiles(files: AssetFiles): Promise<unknown> {
+function materializeFiles(files: StagedFiles): Promise<unknown> {
 	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.
@@ -199,7 +221,7 @@ function cachedResource<C extends ResourceConstructor>(path: string): Promise<In
 export function loadAsset<C extends ResourceConstructor>(
 	path: string,
 	cls: C,
-	files: AssetFiles,
+	files: StagedFiles,
 	data: Record<string, unknown> = {},
 	ready?: Promise<unknown>,
 ): { materialize: Promise<unknown>; load: Promise<InstanceType<C>> } {
@@ -230,7 +252,7 @@ export function loadAsset<C extends ResourceConstructor>(
 export async function loadResourceAsync<C extends ResourceConstructor>(
 	path: string,
 	cls: C,
-	files?: AssetFiles,
+	files?: StagedFiles,
 ): Promise<InstanceType<C>> {
 	const err = ResourceLoader.loadThreadedRequest(path, cls.name);
 	if (err) {
@@ -263,6 +285,8 @@ export async function loadResourceAsync<C extends ResourceConstructor>(
 		for (const resPath of Object.keys(files)) {
 			if (!resPath.endsWith('.import')) {
 				DirAccess.removeAbsolute(resPath);
+				// The bytes are gone, so the memo must forget the path — a later module stages it again.
+				staged.delete(resPath);
 			}
 		}
 	}
@@ -321,3 +345,131 @@ function packName(url: string): string {
 	const base = url.split('?')[0].split('/').pop() ?? 'pack.pck';
 	return base.replace(/[^A-Za-z0-9._-]/g, '_') || 'pack.pck';
 }
+
+// ── Content packs ───────────────────────────────────────────────────────────
+// A content pack is deployed apart from the app, so a client is told where a release-relative path can
+// be read (`at`) and everything else follows: the release graph, each mounted pack's manifest and
+// `.pck`, and the loose files the entry needs. The bake also hands over the boot pack's own config —
+// its `.pck` and a bundled URL per loose product, the one thing only the app can provide, since those
+// bytes ship beside it. The runtime only ever sees URLs, all of them version-addressed and immutable.
+
+/**
+ * A pack the runtime has at hand: its `.pck`, its document, and where its staged products are read. The
+ * app's own pack is one of these — its bytes ship beside it, so its URLs are the host's, not a
+ * version-addressed path — and it is what `configurePacks({ boot })` hands over.
+ */
+export interface MountedPack {
+	/** The `.pck` to mount (`loadAssetPack`). */
+	pck: string;
+	doc: PackDoc;
+	/** The URL of one of this pack's products, by the file name `doc.stage` gives it. */
+	url: (file: string) => string;
+}
+
+/**
+ * How the runtime reads content packs: a URL per file, and the release that names the packs (or where
+ * to read one). The host owns its base and the way a version is encoded in it, so the protocol never
+ * builds a release-relative path — it knows a pack's name and its files (`pack.json`, `<name>.pck`,
+ * `files/<product>`), and asks.
+ */
+export interface PackSource {
+	/** A pack's file, as a fetchable URL or a local path — how the host addresses a version is its own. */
+	at?: (pack: string, version: string, file: string) => string;
+	/** The app's own pack, configured by the bake's own code: always mounted, its bytes bundled. */
+	boot?: MountedPack;
+	/**
+	 * The packs to mount. The app's own dependencies (pinned by its lockfile) are one way: there is no
+	 * release document to fetch, and the versions the app was built and tested with are the ones it
+	 * mounts. A URL is the other: mount what a release document names — a bake's `release.json`, a CDN's.
+	 */
+	release?: Release | string;
+}
+
+let packSource: PackSource = {};
+
+/**
+ * Points the runtime at a pack source. Merges, so the bake's boot config and the app's `at` may land in
+ * either order — the boot config rides on the app's own asset imports.
+ */
+export function configurePacks(source: PackSource): void {
+	packSource = { ...packSource, ...source };
+}
+
+/** Reads a document: a URL over the network, anything else off the filesystem. */
+async function readText(url: string): Promise<string> {
+	if (/^https?:/i.test(url)) {
+		const res = await fetch(url);
+		if (!res.ok) throw new Error(`godot-assets: ${url} (${res.status})`);
+		return res.text();
+	}
+	// Desktop and a dev bundle hand over a local path, and `res://` is the working tree there.
+	const text = FileAccess.getFileAsString(url.startsWith('res://') ? url : ProjectSettings.globalizePath(url));
+	if (!text) throw new Error(`godot-assets: cannot read ${url}`);
+	return text;
+}
+
+/** The release to mount: the packs the app pinned, or the document `configurePacks` was pointed at. */
+async function mountedRelease(): Promise<Release> {
+	const pinned = packSource.release;
+	if (!pinned) throw new Error('godot-assets: no release — configurePacks({ release }) with the packs to mount or its URL.');
+	return typeof pinned === 'string' ? parseRelease(await readText(pinned)) : pinned;
+}
+
+/**
+ * A resolved entry's files, as the loader stages them: the app's own pack addresses a product from its
+ * bundled URLs, a mounted pack from the host's addressing. This is the addressing the protocol
+ * deliberately does not know — which is why a resolution returns packs and file names, not URLs.
+ */
+function stagedFiles(
+	plan: ResolvedEntry,
+	boot: MountedPack | undefined,
+	fileUrl: (pack: string, file: string) => string,
+): StagedFiles {
+	const files: StagedFiles = {};
+	for (const { sidecar, content, product, pack, file } of plan.files) {
+		files[sidecar] = { content };
+		files[product] = { path: pack === null ? boot!.url(file) : fileUrl(pack, `${FILES_DIR}/${file}`) };
+	}
+	return files;
+}
+
+/**
+ * Loads one declared entry of a content pack: the release, then the packs the entry reaches and the
+ * loose files they stage, then the `res://` path the entry names. Nothing about a pack is baked into
+ * the app, so it can be republished without one.
+ */
+export async function loadPackEntry<C extends ResourceConstructor>(
+	pack: string,
+	entry: string,
+	cls: C,
+): Promise<InstanceType<C>> {
+	const at = packSource.at;
+	if (!at) throw new Error('godot-assets: no pack source — call configurePacks({ at }) first.');
+	const release = await mountedRelease();
+	// Mounting needs only the release — a pack's `.pck` is `<name>.pck` by convention — so the closure's
+	// packs are mounted while their documents are read, and only staging waits on those.
+	const names = mountClosure(release, pack);
+	const url = (name: string, file: string) => at(name, release[name].version, file);
+	const boot = packSource.boot;
+	const mounts = [...(boot ? [boot.pck] : []), ...names.map((name) => url(name, pckOf(name)))].map((pck) =>
+		loadAssetPack(pck),
+	);
+	const docs = Object.fromEntries(
+		await Promise.all(
+			names.map(async (name): Promise<[string, PackDoc]> => {
+				const doc = parseDoc(await readText(url(name, PACK_DOC)));
+				// A base that serves a version it wasn't asked for is the one thing a client cannot see:
+				// production's URLs are immutable, and a dev server pointed at a local bake serves content
+				// at another version on purpose. Say so; the load still works.
+				if (doc.version !== release[name].version) {
+					console.warn(`godot-assets: ${name} ${release[name].version} asked, ${doc.version ?? 'no version'} served`);
+				}
+				return [name, doc];
+			}),
+		),
+	);
+	const plan = resolveEntry(release, docs, pack, entry, boot?.doc);
+	// The boot is a mounted pack like any other, so an entry borrows its loose files too.
+	await Promise.all(mounts);
+	return loadAsset(plan.res, cls, stagedFiles(plan, boot, url)).load;
+}