@ringozz/godot 4.7.2-661 → 4.7.2-676

package/src/dump-deps.gd

@@ -1,38 +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.
 ##
-## A third source, because neither above can see it: a **level built from its plan**
+## 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.
+## 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/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://)
+## 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:
@@ -42,6 +56,16 @@ 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:
 		var root := String(r).rstrip("/") + "/"
@@ -54,6 +78,11 @@ func _initialize() -> void:
 	quit()
 
 
+## 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)
@@ -65,34 +94,40 @@ func _scan(root: String, path: String, sources: Dictionary) -> void:
 		_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(root, 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(root: String, 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(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(root: String, 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:
+		return false
+	if dep.get_extension().to_lower() in _packed:
 		_collect(root, dep, loose, seen)
-	elif FileAccess.file_exists(dep + ".import"):
+		return true
+	if FileAccess.file_exists(dep + ".import"):
 		loose[dep] = true
+		return true
+	return false
 
 
 func _collect(root: String, path: String, loose: Dictionary, seen: Dictionary) -> void:
@@ -105,18 +140,29 @@ func _collect(root: String, path: String, loose: Dictionary, seen: Dictionary) -
 	if FileAccess.file_exists(imp):
 		var cfg := ConfigFile.new()
 		if cfg.load(imp) == OK:
-			for dst in cfg.get_value("deps", "dest_files", []):
+			for dst in _dest_files(cfg):
 				_collect(root, String(dst), loose, seen)
 	for dep in ResourceLoader.get_dependencies(path):
 		_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(root, p, loose, seen)
-	# A level built from its plan names nothing above: its refs come from the plan itself.
+	# 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(root, path, loose, seen)
+		_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).
@@ -137,23 +183,39 @@ func _text_refs(path: String) -> Array:
 	return refs
 
 
-## A level's refs, read from the plan its `.gltfx` carries (`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.
-func _plan_refs(root: String, path: String, loose: Dictionary, seen: Dictionary) -> void:
+## 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
-	var stamp: Variant = extras.get("gltfx") if extras 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:
-		_terrain_refs(root, root.path_join(String(terrain["dir"])), loose, seen)
+		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")
@@ -164,7 +226,8 @@ func _plan_refs(root: String, path: String, loose: Dictionary, seen: Dictionary)
 			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"]:
-					_classify_route(root, fields.get(key), loose, seen)
+					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`.
@@ -172,13 +235,17 @@ func _plan_refs(root: String, path: String, loose: Dictionary, seen: Dictionary)
 		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")
-		_classify_route(root, env.get("map") if env is Dictionary else null, loose, seen)
+		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) -> void:
+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:
@@ -187,13 +254,20 @@ func _terrain_refs(root: String, dir: String, loose: Dictionary, seen: Dictionar
 				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()):
-			_classify(root, dir.path_join(name), loose, seen)
+		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.
-func _classify_route(root: String, route: Variant, loose: Dictionary, seen: Dictionary) -> void:
-	if route is String:
-		for suffix in ["", ".webp"]:
-			_classify(root, root.path_join(route + suffix), loose, seen)
+## 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,10 +107,15 @@ 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);
 	}
+	if (command === 'clean') {
+		const { cleanProject } = await import('./bake.ts');
+		cleanProject();
+		process.exit(0);
+	}
 	const exe = await resolveEditor();
 	const result = spawnSync(exe, process.argv.slice(2), { stdio: 'inherit', env: { ...process.env, GODOT_NODE_WRAPPER: '1' } });
 	process.exit(result.status ?? 1);

package/src/export_presets.example.cfg

@@ -7,9 +7,9 @@
 ; (see `dump-deps.gd`), not read from the pack. `export_filter="all_resources"`
 ; ignores `include_filter` — scope with `exclude_filter` only.
 ;
-; The bake always splits — one pack per scene (`Pack: <scene>`) plus a shared one — and
-; derives those presets from this one, pruning them again after exporting. Don't write
-; them by hand.
+; The bake rewrites this preset's `exclude_filter` once per pack (the boot pack, then one per
+; content pack) and puts the file back when it finishes, so the export carries exactly one scope.
+; Don't write those scopes by hand.
 
 [preset.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);