@ringozz/godot 4.7.2-659 → 4.7.2-664

package/src/dump-deps.gd

@@ -1,32 +1,52 @@
 @tool
 extends SceneTree
-## Dumps, for every packable (`.import`-less) source under the given roots, two things:
-##  - `loose`: the **loose** (WebP-backed) texture sources it needs — those must stay out of
-##    the asset packs and be staged/transcoded by the host, and the preload plugin
-##    (`@ringozz/godot/preload`) reads them from the manifest beside the packs so it never
-##    scans source text for references.
-##  - `packed`: the packed sources reachable from it — the graph `@ringozz/godot/pack`'s
-##    `splitPacks` uses to decide which pack owns a source (the ones only one scene reaches
-##    are that scene's).
+## Dumps, for every packable (`.import`-less) source under the given roots, two halves. The **loose**
+## (WebP-backed) texture sources it needs: those must stay out of the pack and be staged/transcoded by
+## the host, and the preload plugin (`@ringozz/godot/preload`) reads them from the manifest beside the
+## pack, so it never scans source text for references. And the **external** refs the walk reached
+## outside the roots: a pack may reference the boot sources and its declared dependencies, never a
+## sibling, so the bake checks those instead of trusting the tree.
 ##
 ## Sources of both (union): the engine's `ResourceLoader.get_dependencies` (for imported
-## sources the real refs live on the imported product, reached via the `.import`
-## `dest_files`), plus a text scan for string-valued paths (`albedo_array =
-## "res://.../*.webparray"`, `load("res://...")`) that no static resource edge exposes. A dep
-## is *loose* when it has an `.import` sidecar but is not a packed resource type — the set is
-## derived, not listed.
+## sources the real refs live on the imported *product*, reached through the `.import` sidecar —
+## `deps/dest_files`, or the `[remap] path` an importer that writes only that serves the source as,
+## exactly as `@ringozz/godot/preload` reads it), plus a text scan for string-valued paths
+## (`albedo_array = "res://.../*.webparray"`, `load("res://...")`) that no static resource edge
+## exposes — the engine reports *no* dependency for a script at all (`GDScriptParser::get_dependencies`
+## is a stub), so a `.gd`'s literal loads are only ever found here. A dep is *loose* when it has an
+## `.import` sidecar but is not a packed resource type — the set is derived, not listed.
 ##
-## Driven by `@ringozz/godot/pack`'s `buildAssetPacks`, which sets:
-##   GODOT_DUMP_OUT   – output res:// path (default res://.godot/pack-dump.json) — a build
-##                      input: the bake merges it into the manifest beside the packs.
-##   GODOT_DUMP_ROOTS – comma-separated res:// roots to scan (default res://)
+## A third source, because neither above can see it: a **scene built from its plan**
+## (`extras.gltfx.plan`, which a host script reads at run time). It names its terrain by
+## *directory* and its ground/environment maps by relative route — no resource edge and no `res://`
+## literal — so `_plan_refs` reads the plan off the `.gltfx` and classifies its refs. A scene that
+## instances the `.gltfx` inherits them through `_collect`'s recursion. It reads the plan's own role
+## names (`terrain.dir`, a patch's `material.{diffuse,normal,orm}` / `water.normal`, the authored
+## stage's `env.map`), which no engine check can validate — so a plan that resolves *nothing*, or one
+## stamped under another `extras` namespace, is warned about rather than silently staging nothing.
+##
+## Driven by `@ringozz/godot/bake`'s `buildAssetPacks`, which sets:
+##   GODOT_DUMP_OUT     – output res:// path (default res://.godot/pack-dump.json) — a build
+##                        input: the bake merges it into the document beside the packs.
+##   GODOT_DUMP_ROOTS   – comma-separated res:// roots to scan (default res://)
+##   GODOT_DUMP_PACKED  – comma-separated extensions whose *product* the pack carries: such a source is
+##                        walked (an imported source's own deps are empty — its product carries the
+##                        refs) where any other extension with a sidecar is a loose texture to stage
+##   GODOT_DUMP_SCANNED – comma-separated extensions whose text names `res://` paths the engine cannot
+##                        report, so it is scanned for literals
+##
+## The two extension lists are required rather than defaulted: they are the format table's
+## (`formats.ts`), and an empty one would classify every texture as packed — staging the wrong set
+## instead of failing.
+
+var _packed := PackedStringArray()
+var _scanned := PackedStringArray()
+
 
-## Imported source extensions: `_classify` recurses into these (an imported source's own deps are
-## empty — its *product* carries the refs) where any other extension with a sidecar is a loose texture.
-## `gltfx` is a scene-composition source and `gltfxmesh` a shared-mesh one: their products reference the
-## meshes and textures they compose.
-const PACKED := ["tscn", "tres", "gltf", "gltfx", "gltfxmesh", "obj", "gd", "gdshader", "gdshaderinc", "ttf", "otf", "po"]
-const SCANNED := ["tscn", "tres", "gd", "gdshader", "gdshaderinc", "gltf", "obj"]
+## A plan's routes are relative to the converter's output root (`--out`), *not* to the scan root — a
+## pack is scanned on its own, so the two differ. `GODOT_DUMP_PLAN_BASE` names that root; the first
+## scan root stands in when unset (a project whose content prefix is where it bakes).
+var _plan_base := ""
 
 
 func _initialize() -> void:
@@ -36,9 +56,20 @@ func _initialize() -> void:
 	var roots := OS.get_environment("GODOT_DUMP_ROOTS").split(",", false)
 	if roots.is_empty():
 		roots = ["res://"]
+	_packed = _extensions("GODOT_DUMP_PACKED")
+	_scanned = _extensions("GODOT_DUMP_SCANNED")
+	if _packed.is_empty() or _scanned.is_empty():
+		push_error("[dump-deps] GODOT_DUMP_PACKED and GODOT_DUMP_SCANNED are required — the dump is driven by `godot pack`.")
+		quit(1)
+		return
+	_plan_base = OS.get_environment("GODOT_DUMP_PLAN_BASE")
+	if _plan_base.is_empty():
+		_plan_base = String(roots[0])
+	_plan_base = _plan_base.rstrip("/") + "/"
 	var sources := {}
 	for r in roots:
-		_scan(String(r).rstrip("/") + "/", sources)
+		var root := String(r).rstrip("/") + "/"
+		_scan(root, root, sources)
 	DirAccess.make_dir_recursive_absolute(ProjectSettings.globalize_path(out.get_base_dir()))
 	var f := FileAccess.open(out, FileAccess.WRITE)
 	f.store_string(JSON.stringify(sources, "  "))
@@ -47,47 +78,59 @@ func _initialize() -> void:
 	quit()
 
 
-func _scan(path: String, sources: Dictionary) -> void:
+## A comma-separated `GODOT_DUMP_*` extension list.
+func _extensions(name: String) -> PackedStringArray:
+	return PackedStringArray(OS.get_environment(name).split(",", false))
+
+
+## `root` is the scan root `path` lives under (a plan's refs are relative to it), carried down the walk.
+func _scan(root: String, path: String, sources: Dictionary) -> void:
 	var d := DirAccess.open(path)
 	if d == null:
 		return
 	for dir in d.get_directories():
 		if dir.begins_with(".") or dir == "node_modules":
 			continue
-		_scan(path.path_join(dir) + "/", sources)
+		_scan(root, path.path_join(dir) + "/", sources)
 	for file in d.get_files():
 		var p := path.path_join(file)
-		if p.get_extension().to_lower() in PACKED:
-			var seen := {}
-			var loose := _loose(p, seen)
-			# The graph holds authored packed sources only: the walk also visits the engine's
-			# own products (`res://.godot/imported/…`, reached through the `.import` sidecar),
-			# and a product is carried by its *source*, not owned in its own right.
-			var packed := seen.keys().filter(func(s: String) -> bool: return not s.begins_with("res://.godot/"))
-			packed.sort()
-			sources[p] = {"packed": packed, "loose": loose}
-
-
-## The loose texture sources reachable from `path` (transitive), sorted. `seen` collects every
-## packed source the walk touches — the graph — including `path` itself.
-func _loose(path: String, seen: Dictionary) -> Array:
+		if p.get_extension().to_lower() in _packed:
+			sources[p] = _loose(root, p, {})
+
+
+## The loose texture sources reachable from `path` (transitive), sorted, and the refs the walk reached
+## outside the scan root. `seen` is the walk's visited set, so a cycle (or a diamond) costs one visit;
+## the engine's own products (`res://.godot/…`) are carried by their source, so they are not refs.
+func _loose(root: String, path: String, seen: Dictionary) -> Dictionary:
 	var loose := {}
-	_collect(path, loose, seen)
+	_collect(root, path, loose, seen)
 	var arr := loose.keys()
 	arr.sort()
-	return arr
+	var external := []
+	for s in seen:
+		var ref := String(s)
+		if not ref.begins_with(root) and not ref.begins_with("res://.godot/"):
+			external.append(ref)
+	external.sort()
+	return {"loose": arr, "external": external}
 
 
-func _classify(dep: String, loose: Dictionary, seen: Dictionary) -> void:
+## Classifies one dep: a packed type is walked, anything else with an `.import` sidecar is a loose
+## texture to stage. Returns whether the dep named anything real — a plan's routes are probed in
+## several spellings, so that is what tells `_plan_refs` its shape still resolves.
+func _classify(root: String, dep: String, loose: Dictionary, seen: Dictionary) -> bool:
 	if dep.is_empty():
-		return
-	if dep.get_extension().to_lower() in PACKED:
-		_collect(dep, loose, seen)
-	elif FileAccess.file_exists(dep + ".import"):
+		return false
+	if dep.get_extension().to_lower() in _packed:
+		_collect(root, dep, loose, seen)
+		return true
+	if FileAccess.file_exists(dep + ".import"):
 		loose[dep] = true
+		return true
+	return false
 
 
-func _collect(path: String, loose: Dictionary, seen: Dictionary) -> void:
+func _collect(root: String, path: String, loose: Dictionary, seen: Dictionary) -> void:
 	if seen.has(path):
 		return
 	seen[path] = true
@@ -97,15 +140,29 @@ func _collect(path: String, loose: Dictionary, seen: Dictionary) -> void:
 	if FileAccess.file_exists(imp):
 		var cfg := ConfigFile.new()
 		if cfg.load(imp) == OK:
-			for dst in cfg.get_value("deps", "dest_files", []):
-				_collect(String(dst), loose, seen)
+			for dst in _dest_files(cfg):
+				_collect(root, String(dst), loose, seen)
 	for dep in ResourceLoader.get_dependencies(path):
-		_classify(_res_path(String(dep)), loose, seen)
+		_classify(root, _res_path(String(dep)), loose, seen)
 	# String-valued resource paths are invisible to dependency analysis; scan the
 	# text for loose refs the engine cannot report.
-	if path.get_extension().to_lower() in SCANNED:
+	if path.get_extension().to_lower() in _scanned:
 		for p in _text_refs(path):
-			_classify(p, loose, seen)
+			_classify(root, p, loose, seen)
+	# A scene built from its plan names nothing above: its refs come from the plan itself.
+	if path.get_extension().to_lower() == "gltfx":
+		_plan_refs(path, loose, seen)
+
+
+## An imported source's product(s), read exactly as `@ringozz/godot/preload` reads them: every
+## `deps/dest_files` entry (the real refs live on the product), or — for an importer that writes only
+## that — the single `[remap] path` the source is served as.
+func _dest_files(cfg: ConfigFile) -> Array:
+	var dests: Variant = cfg.get_value("deps", "dest_files", [])
+	if dests is Array and not dests.is_empty():
+		return dests
+	var served: Variant = cfg.get_value("remap", "path", "")
+	return [served] if served is String and not served.is_empty() else []
 
 
 ## `res://` path from a dependency entry (`uid://…::::res://…` or plain).
@@ -124,3 +181,93 @@ func _text_refs(path: String) -> Array:
 	for m in re.search_all(FileAccess.get_file_as_string(path)):
 		refs.append(m.get_string())
 	return refs
+
+
+## A plan's refs, read from the `.gltfx` that carries it (`extras.gltfx.plan`). They are invisible to
+## every source above (a *directory* rather than a route, relative routes, and a host script that
+## reads the JSON instead of a resource edge), so the plan is their only statement. Each ref goes
+## through `_classify`: what has an `.import` sidecar is staged, the header JSONs (which the packs
+## carry) are not.
+##
+## The role names are the plan's own (`core/ground.ts` + `core/heapsMaterial.ts`): an overlay patch's
+## `material.{diffuse,normal,orm}`, a lake/ocean's `water.normal`, and the authored stage's `env.map`,
+## every one served as `<route>.webp` (the host's `_texture_route`). Nothing static can check that
+## reading, so a plan that resolves no ref at all is warned about: that is a schema change, and it
+## would otherwise show up as a scene with no terrain on a host that stages.
+func _plan_refs(path: String, loose: Dictionary, seen: Dictionary) -> void:
+	var doc = JSON.parse_string(FileAccess.get_file_as_string(path))
+	var extras: Variant = doc.get("extras") if doc is Dictionary else null
+	if not extras is Dictionary:
+		return
+	var stamp: Variant = extras.get("gltfx")
+	var plan: Variant = stamp.get("plan") if stamp is Dictionary else null
+	if not plan is Dictionary:
+		# A `.gltfx` with no plan is normal (a plain composition). A plan under *another* namespace
+		# is not: nothing here would stage, and the host would build a scene whose textures were
+		# never shipped — so name the namespace that was stamped instead.
+		for ns in extras:
+			var other: Variant = extras[ns]
+			if ns != "gltfx" and other is Dictionary and other.get("plan") is Dictionary:
+				push_warning("[dump-deps] %s stamps a plan under extras.%s, not extras.gltfx — its refs will not be staged." % [path, ns])
+		return
+
+	var refs := 0
+	# The terrain: the plan names its directory, and the directory is the atlas list.
+	var terrain: Variant = plan.get("terrain")
+	if terrain is Dictionary and terrain.get("dir") is String:
+		refs += _terrain_refs(_plan_base, _plan_base.path_join(String(terrain["dir"])), loose, seen)
+
+	# The rest are texture routes — the ground's patches / the water's maps, and the sky.
+	var ground: Variant = plan.get("ground")
+	if ground is Array:
+		for g in ground:
+			if not g is Dictionary:
+				continue
+			var fields: Variant = g.get("material") if g.get("source") == "overlay" else g.get("water")
+			if fields is Dictionary:
+				for key in ["diffuse", "normal", "orm"]:
+					if _classify_route(_plan_base, fields.get(key), loose, seen):
+						refs += 1
+	var lighting: Variant = plan.get("lighting")
+	if lighting is Dictionary:
+		# A host renders one time of day: the authored stage's env, which the plan mirrors as `env`.
+		var stages: Variant = lighting.get("stages")
+		var env: Variant = stages[0].get("env") if stages is Array and stages.size() > 0 and stages[0] is Dictionary else null
+		if not env is Dictionary:
+			env = lighting.get("env")
+		if _classify_route(_plan_base, env.get("map") if env is Dictionary else null, loose, seen):
+			refs += 1
+
+	if refs == 0:
+		push_warning("[dump-deps] %s carries a plan, but no ref in it resolved — its shape (terrain.dir / a patch's material / a stage's env) may have changed." % path)
+
+
+## A terrain directory **is** its atlas list (every atlas name is top-level in it), so each file is a
+## ref — except a layered container's *layers*: the manifest names them and their bytes live in its
+## imported product, so staging them would ship megabytes nothing reads.
+func _terrain_refs(root: String, dir: String, loose: Dictionary, seen: Dictionary) -> int:
+	var files := DirAccess.get_files_at(dir)
+	var layers := {}
+	for name in files:
+		if name.to_lower().ends_with(".webparray"):
+			for line in FileAccess.get_file_as_string(dir.path_join(name)).split("\n"):
+				var ref := line.strip_edges()
+				if not ref.is_empty() and not ref.begins_with("#"):
+					layers[ref.get_file()] = true
+	var refs := 0
+	for name in files:
+		if not layers.has(name.get_file()) and _classify(root, dir.path_join(name), loose, seen):
+			refs += 1
+	return refs
+
+
+## Classifies a plan's route: relative and unsuffixed, so the served `.webp` spelling is tried too
+## (the host's `_texture_route`). Returns whether it resolved.
+func _classify_route(root: String, route: Variant, loose: Dictionary, seen: Dictionary) -> bool:
+	if not route is String:
+		return false
+	var found := false
+	for suffix in ["", ".webp"]:
+		if _classify(root, root.path_join(route + suffix), loose, seen):
+			found = true
+	return found

package/src/editor.ts

@@ -107,7 +107,7 @@ export async function resolveEditor(): Promise<string> {
 if (import.meta.main) {
 	const command = process.argv[2];
 	if (command === 'pack') {
-		const { buildAssetPacks, parsePackArgs } = await import('./pack.ts');
+		const { buildAssetPacks, parsePackArgs } = await import('./bake.ts');
 		await buildAssetPacks(parsePackArgs(process.argv.slice(3)));
 		process.exit(0);
 	}

package/src/formats.ts

@@ -0,0 +1,78 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// One row per importable source extension, holding everything its four readers need — so adding an
+// extension is one edit here rather than an edit per list, and the lists cannot disagree:
+//
+//  - `cls` — the class the module the preload plugin serves loads it as, and the class the ambient
+//    types for that import resolve to (`assets.d.ts`, the one hand-kept projection, which
+//    `dev/tests/formats.test.ts` compares against these rows). A row with no class is a source nothing
+//    imports: `.gltfxmesh`, which a `.gltfx`'s product references.
+//  - `packed` — its *product* travels in the `.pck`, so the dump recurses through it (an imported
+//    source's own `get_dependencies` is empty — the product carries the refs) instead of staging it
+//    loose. That is why the texture formats are rows here and *not* `packed`: the wasm build decodes no
+//    WebP, so their bytes must stay out of the pack and be staged and transcoded per file.
+//  - `scanned` — its *text* names `res://` paths no resource edge exposes (the engine reports no
+//    dependencies for a script at all), so the dump scans its text for literals.
+//
+// `moduleExtensions` / `packedExtensions` / `scannedExtensions` are those rows projected, which is what
+// the plugin's filter and the dump's two environment lists are built from.
+
+/** One source extension, and what that says about it. */
+export interface Format {
+	/** The class its module loads as; absent when nothing imports one. */
+	cls?: string;
+	/** Its product travels in the `.pck`: walk it, rather than staging it loose. */
+	packed?: boolean;
+	/** Its text names `res://` paths worth a literal scan. */
+	scanned?: boolean;
+}
+
+/** Imported source extension → what it is, and how it is carried. */
+export const FORMATS: Record<string, Format> = {
+	gltf: { cls: 'PackedScene', packed: true, scanned: true },
+	// 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', packed: true },
+	// A shared-mesh document: what one or more `.gltfx` compositions reference. Nothing imports one —
+	// a `.gltfx`'s product is what names it — so it has no class, and is carried by a pack all the same.
+	gltfxmesh: { packed: true },
+	tscn: { cls: 'PackedScene', packed: true, scanned: true },
+	obj: { cls: 'PackedScene', packed: true, scanned: true },
+	gd: { cls: 'GDScript', packed: true, scanned: true },
+	gdshader: { cls: 'Shader', packed: true, scanned: true },
+	gdshaderinc: { cls: 'ShaderInclude', packed: true, scanned: true },
+	tres: { cls: 'Resource', packed: true, scanned: true },
+	po: { cls: 'Translation', packed: true },
+	ttf: { cls: 'FontFile', packed: true },
+	otf: { cls: 'FontFile', packed: true },
+	jpg: { cls: 'CompressedTexture2D' },
+	jpeg: { cls: 'CompressedTexture2D' },
+	png: { cls: 'CompressedTexture2D' },
+	webp: { cls: 'CompressedTexture2D' },
+	svg: { cls: 'CompressedTexture2D' },
+	// 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; its product is what is staged.
+	webparray: { cls: 'CompressedTexture2DArray' },
+	exr: { cls: 'TextureLayered' },
+	hdr: { cls: 'TextureLayered' },
+	wav: { cls: 'AudioStreamWAV' },
+	ogg: { cls: 'AudioStreamOggVorbis' },
+	mp3: { cls: 'AudioStreamMP3' },
+};
+
+/** A path's extension, lowercased (`res://…/Map.TSCN` -> `tscn`). */
+const extOf = (path: string) => path.slice(path.lastIndexOf('.') + 1).toLowerCase();
+
+/** The class an asset path loads as, or `undefined` when it is not an importable asset. */
+export const classOf = (path: string) => FORMATS[extOf(path)]?.cls;
+
+/** The extensions the preload plugin serves a module for: the rows with a class. */
+export const moduleExtensions = Object.keys(FORMATS).filter((ext) => FORMATS[ext].cls);
+
+/** The extensions whose product the `.pck` carries — what the dump walks (`GODOT_DUMP_PACKED`). */
+export const packedExtensions = Object.keys(FORMATS).filter((ext) => FORMATS[ext].packed);
+
+/** The extensions whose text the dump scans for `res://` literals (`GODOT_DUMP_SCANNED`). */
+export const scannedExtensions = Object.keys(FORMATS).filter((ext) => FORMATS[ext].scanned);

package/src/load.ts

@@ -10,6 +10,22 @@ 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,
+	RELEASE,
+	mountClosure,
+	packPath,
+	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 +73,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 +83,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 +116,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 +187,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 +223,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 +254,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 +287,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 +347,113 @@ 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: `at('<name>/<version>/<file>')` → a fetchable URL. */
+export interface PackSource {
+	/** Where a release document and its packs are read (a CDN prefix, or a dev server's directory). */
+	at?: (path: string) => string;
+	/** The app's own pack, configured by the bake's own code: always mounted, its bytes bundled. */
+	boot?: MountedPack;
+}
+
+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 pack document: a URL (a release) over the network, anything else off the filesystem. */
+async function fetchPack(path: string): Promise<string> {
+	const at = packSource.at;
+	if (!at) throw new Error('godot-assets: no pack source — call configurePacks({ at }) first.');
+	const url = at(path);
+	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;
+}
+
+/**
+ * A resolved entry's files, as the loader stages them: the app's own pack addresses a product from its
+ * bundled URLs, a release pack from the version-addressed path the entry was resolved against. This is
+ * the addressing the protocol deliberately does not know — which is why a resolution returns packs and
+ * file names rather than URLs.
+ */
+function stagedFiles(
+	plan: ResolvedEntry,
+	release: Release,
+	boot: MountedPack | undefined,
+	at: (path: 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) : at(packPath(pack, release[pack].version, `${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.');
+	// 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 fetched, and only staging waits on those.
+	const release = parseRelease(await fetchPack(RELEASE));
+	const names = mountClosure(release, pack);
+	const pckUrl = (name: string) => at(packPath(name, release[name].version, pckOf(name)));
+	const boot = packSource.boot;
+	const mounts = [...(boot ? [boot.pck] : []), ...names.map(pckUrl)].map((url) => loadAssetPack(url));
+	const docs = Object.fromEntries(
+		await Promise.all(
+			names.map(async (name): Promise<[string, PackDoc]> => {
+				const { version } = release[name];
+				return [name, parseDoc(await fetchPack(packPath(name, version, PACK_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.
+	const files = stagedFiles(plan, release, boot, at);
+	await Promise.all(mounts);
+	return loadAsset(plan.res, cls, files).load;
+}