lecodes-cli 2.4.8 → 2.4.10

package/src/commands/lightmap.ts

@@ -1,8 +1,8 @@
-import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, readSync, rmSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
-import { basename, dirname, join, relative, resolve } from "node:path"
+import { basename, dirname, join, relative, resolve, sep } from "node:path"
 import { deflateSync } from "node:zlib"
-import { buildBundle, type BundleResource } from "./compile"
+import { buildBundle, type BundleBakeTarget, type BundleResource } from "./compile"
 import { readAppConfigAt } from "./app/shared"
 import { runDesktopRender } from "../hosts/desktopRenderer"
 import { loadPeer } from "../hosts/peerInstall"
@@ -17,8 +17,11 @@ import { bundleFlags, bundleOptions, localProject } from "./shared"
  *             scene is complete — the SDK calls `_creator.lightmapBake` instead of loading: the host describes
  *             every registered static to creator-bake, which traces the sun, the sky and the lamps on the
  *             GPU (--tracer: OptiX on NVIDIA, else Vulkan ray query on any card with hardware ray tracing) and
- *             writes <out>/<name>.bake + <name>-light[_n].ktx2 + <name>-aux[_n].ktx2 itself
- *             (no toktx, no PNG intermediates). "[lightmap] done" is the success marker.
+ *             writes the files itself (no toktx, no PNG intermediates). "[lightmap] done" is the success marker.
+ *             THE TARGET is the level's own `bake('<path>.bake')` (the SDK's bakeMacro): the compile reports every
+ *             bake() the entry reaches, the files land next to that `.bake` — the manifest that names them, which the
+ *             next compile reads. Nothing has to exist before the first bake; `--out` writes elsewhere, `--name`
+ *             picks the level when the entry reaches several.
  *   stats     the per-instance numbers a .bake carries (mean lux, sun / sky visibility, texels, rect)
  *   diff      the noise of a bake per instance: two bakes with different --seed compared texel by texel
  *   inspect   PNGs from the float layers a `bake --debug-dir` kept: whole pages or one instance's rect
@@ -75,38 +78,44 @@ const cubePatternsOf = (argv: string[]): string[] => {
   return out.filter((p) => p !== "")
 }
 
-/** A .bake with no pages and no scale: enough for the compiler to stage the files and for Lightmap.load to
- *  no-op with a "rebake" warning. The two KTX2 placeholders are 4x4 pages of the right formats. */
-const placeholderBake = (stem: string): string => JSON.stringify({ version: 4, placeholder: true, size: 4, pages: 0, texel: 0, lightScale: 0, light: [ `${stem}-light.ktx2` ], aux: [ `${stem}-aux.ktx2` ], instances: [] }) + "\n"
-const ktx2Placeholder = (vkFormat: number): Buffer => {
-  // one 4x4 level, no supercompression; BC6H (143) = one 16-byte block of zeros, RGBA8 (37) = 64 bytes
-  const raw = Buffer.alloc(vkFormat === 143 ? 16 : 64)
-  const dfdSize = 44
-  const dfdOffset = 80 + 24
-  const b = Buffer.alloc(dfdOffset + dfdSize + raw.length)
-  Buffer.from([ 0xAB, 0x4B, 0x54, 0x58, 0x20, 0x32, 0x30, 0xBB, 0x0D, 0x0A, 0x1A, 0x0A ]).copy(b, 0)
-  let o = 12
-  for (const v of [ vkFormat, 1, 4, 4, 0, 0, 1, 1, 0 ]) { b.writeUInt32LE(v, o); o += 4 }
-  b.writeUInt32LE(dfdOffset, o); b.writeUInt32LE(dfdSize, o + 4); o += 8
-  b.writeUInt32LE(0, o); b.writeUInt32LE(0, o + 4); o += 8
-  b.writeBigUInt64LE(0n, o); b.writeBigUInt64LE(0n, o + 8); o += 16
-  b.writeBigUInt64LE(BigInt(dfdOffset + dfdSize), o); b.writeBigUInt64LE(BigInt(raw.length), o + 8); b.writeBigUInt64LE(BigInt(raw.length), o + 16); o += 24
-  b.writeUInt32LE(dfdSize, o)
-  raw.copy(b, dfdOffset + dfdSize)
-  return b
+/** The stem of a `.bake` path: `assets/lightmap/level.bake` → `level`. */
+const stemOf = (path: string): string => basename(path).replace(/\.bake$/i, "")
+
+/** The bake target among the bake() calls the bundle reaches: the only one, or the one `--name` names. */
+const pickTarget = (bakes: BundleBakeTarget[], name: string | undefined, entry: string): BundleBakeTarget => {
+  if (bakes.length === 0) throw new CliError(`${entry} reaches no bake(): the level's scene file says where its bake goes — add \`env: { lightmap: bake('./assets/lightmap/level.bake') }\` (a hand-built scene: \`Lightmap.load(scene, bake('./assets/lightmap/level.bake'))\`).`)
+  const listed = bakes.map((b) => `${stemOf(b.path)} (${b.path})`).join(", ")
+  if (name === undefined) {
+    if (bakes.length > 1) throw new CliError(`${entry} reaches ${bakes.length} bake() calls: ${listed} — pass --name <stem> to pick the level to bake.`)
+    return bakes[0]
+  }
+  const named = bakes.filter((b) => stemOf(b.path) === name)
+  if (named.length === 0) throw new CliError(`--name ${name}: ${entry} reaches no bake() of that stem — it reaches ${listed}.`)
+  if (named.length > 1) throw new CliError(`--name ${name}: two bake() targets share that stem (${named.map((b) => b.path).join(", ")}) — rename one.`)
+  return named[0]
 }
-const ensurePlaceholders = (outDir: string, stem: string): void => {
-  const missing = (f: string): boolean => !existsSync(f) || statSync(f).size === 0
-  const bake = join(outDir, `${stem}.bake`)
-  if (missing(bake)) writeFileSync(bake, placeholderBake(stem))
-  const light = join(outDir, `${stem}-light.ktx2`), aux = join(outDir, `${stem}-aux.ktx2`), probes = join(outDir, `${stem}-probes.ktx2`)
-  if (missing(light)) writeFileSync(light, ktx2Placeholder(143))
-  if (missing(aux)) writeFileSync(aux, ktx2Placeholder(37))
-  if (missing(probes)) writeFileSync(probes, ktx2Placeholder(143))   // a scene may list the probes before the first bake wrote them
-  const grid = join(outDir, `${stem}.lgrid`)
-  if (missing(grid)) writeFileSync(grid, "NONE")   // ... and the light grid: the engine refuses it with a "rebake" line
-  const uv1 = join(outDir, `${stem}-uv1.bin`)
-  if (missing(uv1)) writeFileSync(uv1, "NONE")     // ... and the packed uv1: a placeholder .bake names none, so nothing reads it
+
+/** Every `.bake` under the project (node_modules and the `.lightmap` debug dirs aside), project-relative. */
+const findBakes = (root: string): string[] => {
+  const SKIP = new Set([ "node_modules", ".lightmap", ".git", ".lecodes" ])
+  const out: string[] = []
+  const walk = (dir: string): void => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) { if (!SKIP.has(e.name)) walk(join(dir, e.name)) }
+      else if (/\.bake$/i.test(e.name)) out.push(relative(root, join(dir, e.name)).replace(/\\/g, "/"))
+    }
+  }
+  walk(root)
+  return out.sort()
+}
+
+/** `--bake` of stats / diff / inspect: the flag, else the project's one `.bake`. */
+const bakeFileOf = (root: string, flag: string | undefined): string => {
+  if (flag) return resolve(root, flag)
+  const found = findBakes(root)
+  if (found.length === 0) throw new CliError("No .bake in the project — run `lecodes lightmap bake` first.")
+  if (found.length > 1) throw new CliError(`The project has ${found.length} bakes (${found.join(", ")}) — pass --bake <file>.`)
+  return resolve(root, found[0])
 }
 
 // ---- the unwrap pre-step --------------------------------------------------------------------------
@@ -163,6 +172,9 @@ const unwrapReferenced = async (js: string, resources: BundleResource[], root: s
   if (raw.length === 0) { note(`Lightmap uvs: the ${glbs.length} GLB(s) the app references carry them`); return }
   note(`Unwrapping ${raw.length} of the ${glbs.length} GLB(s) the app references — no lightmap uvs; written in place (--no-unwrap skips)…`)
   const assets = await loadPeer<typeof import("lecodes-assets/cli")>("lecodes-assets", "cli", { for: "lecodes lightmap bake (lightmap uvs)" })
+  if (typeof assets.unwrapGlbFiles !== "function") {
+    throw new CliError("The lecodes-assets this CLI loaded has no unwrapGlbFiles (it predates the bake's unwrap) — `lecodes update` moves it forward; --no-unwrap bakes the GLBs as they are.")
+  }
   const t0 = performance.now()
   const rel = (f: string): string => relative(root, f).replace(/\\/g, "/")
   const reports = await assets.unwrapGlbFiles(raw, {
@@ -179,23 +191,23 @@ const unwrapReferenced = async (js: string, resources: BundleResource[], root: s
 const bake = defineCommand({
   name: "bake",
   summary: "Bake the sun, the sky and the lamps into a lux atlas for the level's statics",
-  description: "Runs the app in bake mode in lecodes-bake — the windowless host with the bake built in (no physics, 2D, audio, net or navmesh), downloaded on first use like the desktop host; LECODES_BAKE_EXE points at a local build (hosts/desktop build.ps1 -Bake). The statics are what the app registers with Lightmap.add (a scene file does it for every node no Physics aspect moves), the bake fires at its Lightmap.load call. Writes <out>/<name>.bake + <name>-light[_n].ktx2 (irradiance, BC6H) + <name>-aux[_n].ktx2 (sky visibility, the directional share and direction of the light) + <name>-probes.ktx2 (the reflection probes: a cubemap of the level's radiance per probe, prefiltered per roughness; --probe-spacing 0 = none). Needs a GPU with hardware ray tracing (--tracer).\n\nLightmap UVs: the GLBs the app references that have none (TEXCOORD_1) are unwrapped first, IN PLACE \u2014 the same as lecodes assets unwrap, run on just those files; a file that has them is left alone, --no-unwrap skips the step. A whole level in one GLB that wants --groups / --zone is unwrapped by hand first (lecodes assets unwrap --help).",
+  description: "Runs the app in bake mode in lecodes-bake — the windowless host with the bake built in (no physics, 2D, audio, net or navmesh), downloaded on first use like the desktop host; LECODES_BAKE_EXE points at a local build (hosts/desktop build.ps1 -Bake). The statics are what the app registers with Lightmap.add (a scene file does it for every node no Physics aspect moves), the bake fires at its Lightmap.load call. Needs a GPU with hardware ray tracing (--tracer).\n\nWhere: the level's own bake('<dir>/<stem>.bake') — env: { lightmap: bake('./assets/lightmap/level.bake') } in a scene file, the path relative to that file — names the target; nothing has to exist before the first bake. Writes into <dir>: <stem>.bake (the manifest: it names every file below, and the next compile reads it — nothing to paste into the scene) + <stem>-light[_n].ktx2 (irradiance, BC6H, a page per _n) + <stem>-aux[_n].ktx2 (sky visibility, the directional share and direction of the light) + <stem>-probes.ktx2 (the reflection probes: a cubemap of the level's radiance per probe, prefiltered per roughness; --probe-spacing 0 = none) + <stem>.lgrid (the light grid the movers read; --volume 0 = none) + <stem>-uv1.bin (the packed lightmap uv1 the rects map) + with --split <stem>-direct[_n].ktx2 / <stem>-indirect[_n].ktx2.\n\nLightmap UVs: the GLBs the app references that have none (TEXCOORD_1) are unwrapped first, IN PLACE \u2014 the same as lecodes assets unwrap, run on just those files; a file that has them is left alone, --no-unwrap skips the step. A whole level in one GLB that wants --groups / --zone is unwrapped by hand first (lecodes assets unwrap --help).",
   flags: {
-    out: str("where the atlas lands", { value: "<dir>", default: "assets/lightmap" }),
-    name: str("file stem — one per baked level", { value: "<stem>", default: "lightmap" }),
+    out: str("write the files into this folder instead of next to the level's .bake (a second seed for `lightmap diff`)", { value: "<dir>" }),
+    name: str("bake the level whose bake() names <stem>.bake — when the entry reaches several", { value: "<stem>" }),
     ...bundleFlags,
-    entry: str("the file that builds the scene and calls Lightmap.load", { value: "<file>", default: "main.ts" }),
+    entry: str("the file that opens the level (it reaches the bake() that names the target)", { value: "<file>", default: "main.ts" }),
     size: num("atlas page edge (texels)", { default: 4096 }),
     texel: num("texel size (m); the bake coarsens only when the pages are full", { default: 0.05 }),
     pages: num("atlas pages to fill before the bake coarsens the texel", { default: 4 }),
     "sun-rays": num("shadow rays into the sun's disc per texel", { default: 64 }),
-    "sky-rays": num("hemisphere rays per texel (the sky's irradiance and visibility). 2048 (2026-09-16): shadow rays are cheap (the school's direct pass 2 s a page) and a texel deep in a corridor sees the sky through a far window with 1 ray in 256 — every hit was 410 lux", { default: 2048 }),
-    "light-rays": num("shadow rays per lamp per texel (64: at 32 the school's lamp layer read 43 % noise between two seeds, the ceilings and doors next to a lamp 48 %)", { default: 64 }),
-    "bounce-rays": num("bounce paths per texel; 0 = direct light only. 128 (2026-09-16): a dark room's floor in the school reads 240 % noise at 64, 160 % at 128, 130 % at 256 — the last doubling costs 2x the bake time for little", { default: 128 }),
+    "sky-rays": num("hemisphere rays per texel (the sky's irradiance and visibility). 2048 (2026-09-16): shadow rays are cheap (an interior level's direct pass: 2 s a page) and a texel deep in a corridor sees the sky through a far window with 1 ray in 256 — every hit was 410 lux", { default: 2048 }),
+    "light-rays": num("shadow rays per lamp per texel (64: at 32 an interior level's lamp layer read 43 % noise between two seeds, the ceilings and doors next to a lamp 48 %)", { default: 64 }),
+    "bounce-rays": num("bounce paths per texel; 0 = direct light only. 128 (2026-09-16): a dark room's floor of an interior level reads 240 % noise at 64, 160 % at 128, 130 % at 256 — the last doubling costs 2x the bake time for little", { default: 128 }),
     bounces: num("path vertices at most (Russian roulette from the third); 0 = direct light only", { default: 3 }),
     "patch-samples": num("next-event samples per texel over the BRIGHT PATCHES of a first direct pass (sunlit floors, the ceiling around a lamp) — what keeps the bounce in dark rooms from arriving as impulses (every path vertex takes one more); 0 = the cosine paths alone", { default: 64 }),
-    split: bool("also write <name>-direct[_n].ktx2 / <name>-indirect[_n].ktx2 — the pages the \"direct\" / \"indirect\" views bind (list them as env.lightmap.direct / .indirect)"),
-    denoise: str("the AI denoiser (--denoiser) over: indirect = the bounce alone (the range 2026-09-16: bounce noise 57 % -> 23 % of the mean, per-instance means unchanged), no-sun = + the sky and the lamps (the sky through a small opening: 0..3 hits of 256 rays, a texel is one of four values), all = + the sun (its shadow edges too: a sunlit pillar's mean moved 6 %), none. School, two seeds: no-sun took the sky 1.8 % -> 0.5 %, the lamps 43 % -> 21 %", { value: "<none|indirect|no-sun|all>", default: "no-sun" }),
+    split: bool("also write <stem>-direct[_n].ktx2 / <stem>-indirect[_n].ktx2 — the pages the \"direct\" / \"indirect\" views bind (the manifest names them)"),
+    denoise: str("the AI denoiser (--denoiser) over: indirect = the bounce alone (an interior level, 2026-09-16: bounce noise 57 % -> 23 % of the mean, per-instance means unchanged), no-sun = + the sky and the lamps (the sky through a small opening: 0..3 hits of 256 rays, a texel is one of four values), all = + the sun (its shadow edges too: a sunlit pillar's mean moved 6 %), none. An interior level, two seeds: no-sun took the sky 1.8 % -> 0.5 %, the lamps 43 % -> 21 %", { value: "<none|indirect|no-sun|all>", default: "no-sun" }),
     tracer: str("which GPU API traces: auto = OptiX where an NVIDIA driver with OptiX opens, else Vulkan ray query — any card with hardware ray tracing (RTX, Radeon RX 6000+, Arc) with its driver alone; optix / vulkan by name (the bake fails when it cannot open)", { value: "<auto|optix|vulkan>", default: "auto" }),
     denoiser: str("which AI denoiser --denoise runs: auto = OptiX's on an NVIDIA card, else Intel Open Image Denoise (its CUDA / HIP / CPU device, the DLLs next to the host); optix / oidn by name. Independent of --tracer; one that cannot open is a warning and the pages stay as traced", { value: "<auto|optix|oidn>", default: "auto" }),
     "light-radius": num("lamps: the emitter's radius (m) — soft shadows, no 1/d² singularity", { default: 0.05 }),
@@ -209,13 +221,13 @@ const bake = defineCommand({
     "probe-indoor": bool("keep only the probes under a roof — those whose open share of the sphere (rays from the point that meet nothing) is at most 15 %, holes in the geometry or not: outdoor statics reflect the sky through their baked sky visibility instead — an environment map without the ground, but no outdoor probe can reach indoors and the atlas shrinks"),
     "probe-layout": str("rooms = every indoor point of the grid slides to the middle of its room and the points of one room merge: one probe per room, far from the walls, its box the room (stations every ~8 m along a room over 12 m), outdoor points stay on the grid; grid = everything stays on the grid. Either way the pages carry which probes each block of texels sees (rays at bake time)", { value: "<rooms|grid>", default: "rooms" }),
     "min-texels": num("instances smaller than this many ATLAS TEXELS along every axis (x --texel: 12 at 5 cm = 0.6 m) get no place in the atlas: they still cast their baked shadow and bounce, their own light is baked where they stand (six sides, no atlas texels) — cartridges, boxes, pipe elbows, a fire extinguisher: a baked shadow does not read on them and their tight charts are where the seams are. 0 = everything bakes; --dry-run lists what falls under it", { default: 12 }),
-    "thin-texels": num("ROUND AND NARROW objects leave the atlas like --min-texels: an instance none of whose lightmap charts is wider than this many texels across its short side (at --texel) — a railing's tubes, a cable, a pipe run, blinds, a gun barrel. A strip of 1-3 texels around a tube cannot hold the light's change around it and its uv seam shows as a step (the range's railing: two texels 5 mm apart on the seam, one lit, one shadowed); the ambient cube baked where it stands is smooth. A flat object has a wide chart somewhere and stays. 0 = off; --dry-run lists what falls under it", { default: 4 }),
-    cube: str("BAKE AS CUBES BY NAME: a regular expression (ECMAScript, case-sensitive) searched in every record's key — <node path>@<ordinal>, one record per mesh of a model, so SM_pipe takes every pipe node and @1$ the second mesh of each. A record that matches leaves the atlas like a --min-texels / --thin-texels one, whatever its size or charts: an occluder whose own light is baked where it stands as ambient cubes (in slabs along a long one, --object-slab) — a pipe run, a fence, a prop whose lightmap seams show. Repeat the flag (--cube SM_pipe --cube SM_fence) or join with | in one (--cube \"SM_pipe|SM_fence\", quoted for the shell); a pattern that starts with - goes as --cube=<regex>. The scene's env.lightmap.cube adds its own patterns, a node's lightmap: 'cube' marks one node by hand; --dry-run lists what matches", { value: "<regex>" }),
+    "thin-texels": num("ROUND AND NARROW objects leave the atlas like --min-texels: an instance none of whose lightmap charts is wider than this many texels across its short side (at --texel) — a railing's tubes, a cable, a pipe run, blinds, a gun barrel. A strip of 1-3 texels around a tube cannot hold the light's change around it and its uv seam shows as a step (a railing: two texels 5 mm apart on the seam, one lit, one shadowed); the ambient cube baked where it stands is smooth. A flat object has a wide chart somewhere and stays. 0 = off; --dry-run lists what falls under it", { default: 4 }),
+    cube: str("BAKE AS CUBES BY NAME: a regular expression (ECMAScript, case-sensitive) searched in every record's key — <node path>@<ordinal>, one record per mesh of a model, so SM_pipe takes every pipe node and @1$ the second mesh of each. A record that matches leaves the atlas like a --min-texels / --thin-texels one, whatever its size or charts: an occluder whose own light is baked where it stands as ambient cubes (in slabs along a long one, --object-slab) — a pipe run, a fence, a prop whose lightmap seams show. Repeat the flag (--cube SM_pipe --cube SM_fence) or join with | in one (--cube \"SM_pipe|SM_fence\", quoted for the shell); a pattern that starts with - goes as --cube=<regex>. The level's bake() option cube adds its own patterns, a node's lightmap: 'cube' marks one node by hand; --dry-run lists what matches", { value: "<regex>" }),
     "object-slab": num("A LONG object the atlas left out (--min-texels, --thin-texels, --cube) takes its light in SLABS of this many metres along the longest axis of its bounds — round(length / this) ambient cubes, 16 at most — a 6 m pipe run, a railing along a wall: one end under a lamp, the other in the dark, where one cube gave all of it the mean. The shader blends the two slabs around each pixel along that axis. 0 = one cube an object", { value: "<m>", default: 1 }),
     "emissive-nits": num("EMISSIVE SURFACES LIGHT THE LEVEL: cd/m² of emission 1.0 (emissive factor x strength x map) — every lit region of an emissive surface (a panel drawn in a ceiling's texture, a screen, a sign) bakes as a rectangle lamp. Default: what the level's camera makes of 1.0, 1.2 x 2^EV100, so a panel lights as brightly as it looks. 0 = emissive surfaces light nothing"),
     "detail-texels": num("A SMALL SURFACE GETS A FINER TEXEL: an instance whose surface is under this many atlas texels (area / texel²) is laid out denser by sqrt(this / its texels), 3x at most — a pipe of 1 m is ~300 texels at 5 cm, its charts a few texels wide and every chart edge a step; at 2000 it bakes at ~2 cm. 0 = off", { default: 2000 }),
-    volume: num("THE LIGHT GRID for movers: the cell size in metres (0.75 of it tall) — per cell in free space the baked ambient light (sky, lamps, every bounce; not the direct sun, which stays real-time on movers), links between cells a ray connects so nothing blends through a wall; written as <name>.lgrid, list it as env.lightmap.volume. 0 = none", { default: 1 }),
-    "probe-box": str("only grid cells whose centre lies inside this world box get a probe: x0,y0,z0,x1,y1,z1 in metres — keeps probes off a roof top the player never sees (the range: 79 probes above a ceiling with holes where the fixtures were bled the sky onto the walls). Default: the receivers' bounds", { value: "<x0,y0,z0,x1,y1,z1>" }),
+    volume: num("THE LIGHT GRID for movers: the cell size in metres (0.75 of it tall) — per cell in free space the baked ambient light (sky, lamps, every bounce; not the direct sun, which stays real-time on movers), links between cells a ray connects so nothing blends through a wall; written as <stem>.lgrid. 0 = none", { default: 1 }),
+    "probe-box": str("only grid cells whose centre lies inside this world box get a probe: x0,y0,z0,x1,y1,z1 in metres — keeps probes off a roof top the player never sees (79 probes above a ceiling with holes where the fixtures were bled the sky onto the walls of a level). Default: the receivers' bounds", { value: "<x0,y0,z0,x1,y1,z1>" }),
     "debug-dir": str("keep the float layers per page (PFM) here for `lightmap inspect` — gigabytes per level; a `.lightmap/` dir inside the project is skipped by the compile scan, anywhere else must be outside the project", { value: "<dir>" }),
     "dry-run": bool("only the atlas LAYOUT: pages, texel size, the largest rects — no tracing, nothing written (seconds, not minutes; the host still loads the level)"),
     frames: num("host frames to run before giving up — load headroom", { default: 900 }),
@@ -226,13 +238,15 @@ const bake = defineCommand({
     logs: bool("forward the host's output"),
     "no-unwrap": bool("leave the referenced GLBs as they are: no lightmap unwrap of those without TEXCOORD_1 (they bake without lightmap uvs)"),
   },
-  examples: [ "lecodes lightmap bake", "lecodes lightmap bake --entry school.ts --name school --texel 0.04 --pages 4 --debug-dir .lightmap/school --logs" ],
+  examples: [
+    "lecodes lightmap bake",
+    "lecodes lightmap bake --dry-run --logs",
+    "lecodes lightmap bake --entry level2.ts --texel 0.04 --debug-dir .lightmap/level2 --logs",
+  ],
   run: async ({ flags, argv }) => {
     const { root } = localProject()
-    const outDir = resolve(root, flags.out)
-    const stem = flags.name
     const cube = cubePatternsOf(argv)
-    if (!/^[A-Za-z0-9_-]+$/.test(stem)) throw new CliError(`--name wants a plain file stem (letters, digits, - and _), got "${stem}".`)
+    if (flags.name !== undefined && !/^[A-Za-z0-9_.-]+$/.test(flags.name)) throw new CliError(`--name wants the stem of a .bake (its file name without .bake), got "${flags.name}".`)
     const entryFile = flags.entry
     if (!existsSync(resolve(root, entryFile))) {
       throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the scene and calls Lightmap.load).`)
@@ -241,9 +255,12 @@ const bake = defineCommand({
     if (!["none", "indirect", "no-sun", "all"].includes(flags.denoise)) throw new CliError(`--denoise wants none, indirect, no-sun or all, got "${flags.denoise}".`)
     if (!["auto", "optix", "vulkan"].includes(flags.tracer)) throw new CliError(`--tracer wants auto, optix or vulkan, got "${flags.tracer}".`)
     if (!["auto", "optix", "oidn"].includes(flags.denoiser)) throw new CliError(`--denoiser wants auto, optix or oidn, got "${flags.denoiser}".`)
+    // where the files go is the level's bake() (the SDK resolves `<root>/<its path>` at the bake call); `--out` overrides
+    // the folder, `--name` picks the level
     const cfg = {
-      outDir: outDir.replace(/\\/g, "/"),
-      stem,
+      root: root.replace(/\\/g, "/"),
+      ...(flags.out ? { outDir: resolve(root, flags.out).replace(/\\/g, "/") } : {}),
+      ...(flags.name !== undefined ? { stem: flags.name } : {}),
       size: range("size", flags.size, 256, 16384),
       texel: range("texel", flags.texel, 0.001, 2),
       pages: range("pages", flags.pages, 1, 16),
@@ -288,25 +305,26 @@ const bake = defineCommand({
     const entryPath = "/.lightmap-entry.ts"
     const entryText = `globalThis.__lecodesLightmap = ${JSON.stringify(cfg)}\nimport ${JSON.stringify(importPath)}\n`
 
-    // The bake files must exist BEFORE the compile: the scene references them through asset(), and a
-    // missing asset is a broken bundle. The first bake starts from placeholders the real files overwrite.
-    mkdirSync(outDir, { recursive: true })
-    ensurePlaceholders(outDir, stem)
-    if (debugDir) mkdirSync(debugDir, { recursive: true })
-
     const desktopRenderer = "gl" as const   // lecodes-bake is the GL tree on Filament's NOOP backend: `_creator.backend` "desktop" fetches the GL shaders
-    const { js, resources } = await buildBundle(bundleOptions(flags), {
+    const { js, resources, bakes } = await buildBundle(bundleOptions(flags), {
       localAssets: true, desktopRenderer,
       extraEntries: [{ path: entryPath, type: "text", text: entryText }],
       entryOverride: entryPath,
     })
+    // the target: the bake() the entry reaches (the compile reported it; before the first bake it compiled unbaked)
+    const target = pickTarget(bakes, flags.name, entryFile)
+    const stem = stemOf(target.path)
+    const outDir = flags.out ? resolve(root, flags.out) : dirname(target.absPath)
+    mkdirSync(outDir, { recursive: true })
+    if (debugDir) mkdirSync(debugDir, { recursive: true })
+    note(`Target: ${relative(root, join(outDir, `${stem}.bake`)).replace(/\\/g, "/")}${target.exists ? "" : " (the first bake: nothing there yet)"}${flags.out ? " (--out)" : ""}`)
     if (!flags["no-unwrap"]) await unwrapReferenced(js, resources, root, cfg.texel)
 
     // The host writes the bake itself; the PNG the render driver insists on goes to a scratch dir.
     const scratch = mkdtempSync(join(tmpdir(), "lecodes-lightmap-"))
     const outPng = join(scratch, "frame.png")
     const bounce = cfg.bounceRays > 0 && cfg.bounces > 0 ? `, ${cfg.bounceRays} bounce paths of ${cfg.bounces}${cfg.patchSamples > 0 ? ` + ${cfg.patchSamples} patch samples` : ""}${cfg.denoise !== "none" ? `, denoised (${cfg.denoise})` : ", raw"}` : ", no bounce"
-    note(`Baking up to ${cfg.pages} × ${cfg.size}² at ${(cfg.texel * 100).toFixed(1)} cm texels (${cfg.sunRays} sun + ${cfg.skyRays} sky + ${cfg.lightRays} lamp rays${bounce}) → ${relative(root, outDir) || "."}/${stem}.*…`)
+    note(`Baking up to ${cfg.pages} × ${cfg.size}² at ${(cfg.texel * 100).toFixed(1)} cm texels (${cfg.sunRays} sun + ${cfg.skyRays} sky + ${cfg.lightRays} lamp rays${bounce}) → ${relative(root, outDir).split(sep).join("/") || "."}/${stem}.*…`)
     let output = ""
     if (flags["dry-run"]) process.env.CBK_LAYOUT_ONLY = "1"   // the host inherits it: creator-bake stops after the layout
     try {
@@ -337,17 +355,14 @@ const bake = defineCommand({
     }
     if (/\[lightmap\] done/.test(output)) {
       const data = readBake(join(outDir, `${stem}.bake`))
-      const rel = (f: string): string => relative(root, join(outDir, f)).replace(/\\/g, "/")
-      const assets = (files: string[]): string => files.length === 1 ? `asset('<rel>/${rel(files[0])}')` : `[${files.map((f) => `asset('<rel>/${rel(f)}')`).join(", ")}]`
       const splitFiles = data.direct && data.indirect ? ` + ${data.direct.join(", ")} + ${data.indirect.join(", ")}` : ""
-      const splitDef = data.direct && data.indirect ? `, direct: ${assets(data.direct)}, indirect: ${assets(data.indirect)}` : ""
       const probeFiles = data.probes ? ` + ${data.probes.file} (${data.probes.count} probe(s) of ${data.probes.size}² at ${data.probes.spacing} m)` : ""
       const gridFile = data.volume ? ` + ${data.volume.file} (light grid ${data.volume.n.join(" x ")}, ${data.volume.valid} cell(s) in free space)` : ""
-      const probeDef = (data.probes ? `, probes: asset('<rel>/${rel(data.probes.file)}')` : "") + (data.volume ? `, volume: asset('<rel>/${rel(data.volume.file)}')` : "")
-        + (data.uv1 ? `, uv1: asset('<rel>/${rel(data.uv1)}')` : "")
-      const uv1File = data.uv1 ? ` + ${data.uv1} (the packed lightmap uv1 — list it as env.lightmap.uv1, the rects map it)` : ""
-      logErr(c.green(`✓ baked → ${relative(root, outDir) || "."}/${stem}.bake + ${data.light.join(", ")} + ${data.aux.join(", ")}${splitFiles}${probeFiles}${gridFile}${uv1File}`))
-      logErr(c.dim(`  scene file: env.lightmap: { data: asset('<rel>/${rel(`${stem}.bake`)}'), light: ${assets(data.light)}, aux: ${assets(data.aux)}${splitDef}${probeDef} }  — asset() paths are relative to the scene file`))
+      const uv1File = data.uv1 ? ` + ${data.uv1} (the packed lightmap uv1)` : ""
+      logErr(c.green(`✓ baked → ${relative(root, outDir).replace(/\\/g, "/") || "."}/${stem}.bake + ${data.light.join(", ")} + ${data.aux.join(", ")}${splitFiles}${probeFiles}${gridFile}${uv1File}`))
+      logErr(c.dim(flags.out
+        ? `  written to --out: the level's bake() still reads ${target.path}`
+        : `  the manifest names them: the next compile of ${entryFile} stages them (bake('…') in the scene reads it)`))
       if (debugDir) logErr(c.dim(`  debug layers: ${relative(root, debugDir)} (lecodes lightmap inspect --bake ${relative(root, join(outDir, `${stem}.bake`)).replace(/\\/g, "/")} --debug-dir ${relative(root, debugDir).replace(/\\/g, "/")})`))
       return
     }
@@ -369,15 +384,16 @@ const stats = defineCommand({
   summary: "The per-instance numbers a .bake carries: mean lux, sun / sky visibility, texels, rect",
   description: "Reads the .bake alone (no debug layers needed). One row per receiver, sorted by mean lux unless --sort says otherwise; --key filters by a regular expression over the keys.",
   flags: {
-    bake: str("the .bake file", { value: "<file>", default: "assets/lightmap/lightmap.bake" }),
+    bake: str("the .bake file (default: the project's one .bake)", { value: "<file>" }),
     key: str("only instances whose key matches this regular expression", { value: "<regex>" }),
     sort: str("row order", { value: "<lux|key|texels|sun|sky>", default: "lux" }),
     limit: num("rows to print (0 = all)", { default: 60 }),
   },
-  examples: [ "lecodes lightmap stats --bake assets/school/lightmap/school.bake --key Wall", "lecodes lightmap stats --sort sky --limit 0" ],
+  examples: [ "lecodes lightmap stats --key Wall", "lecodes lightmap stats --bake assets/level2/lightmap/level2.bake --sort sky --limit 0" ],
   run: ({ flags }) => {
     const { root } = localProject()
-    const data = readBake(resolve(root, flags.bake))
+    const bakeFile = bakeFileOf(root, flags.bake)
+    const data = readBake(bakeFile)
     const re = flags.key ? new RegExp(flags.key) : null
     let rows = data.instances.filter((i) => i.receiver && (!re || re.test(i.key)))
     const sorters: Record<string, (a: BakeInstance, b: BakeInstance) => number> = {
@@ -392,7 +408,7 @@ const stats = defineCommand({
     rows = rows.sort(sorter)
     const total = rows.length
     if (flags.limit > 0) rows = rows.slice(0, flags.limit)
-    log(`${basename(flags.bake)}: ${data.pages} page(s) of ${data.size}, ${(data.texel * 100).toFixed(2)} cm texels, ${data.texels ?? "?"} texels, lightScale ${data.lightScale}`)
+    log(`${basename(bakeFile)}: ${data.pages} page(s) of ${data.size}, ${(data.texel * 100).toFixed(2)} cm texels, ${data.texels ?? "?"} texels, lightScale ${data.lightScale}`)
     log(`${"key".padEnd(48)} ${"page".padStart(4)} ${"rect".padStart(20)} ${"texels".padStart(8)} ${"lux".padStart(9)} ${"sun".padStart(6)} ${"sky".padStart(6)} ${"dir".padStart(6)}`)
     for (const r of rows) {
       const rect = r.rect ? `${r.rect[0]},${r.rect[1]} ${r.rect[2]}x${r.rect[3]}` : ""
@@ -412,7 +428,7 @@ const diff = defineCommand({
   summary: "The noise of a bake, per instance: two bakes that differ only by --seed, compared texel by texel",
   description: "Bake the level twice with different --seed (and --out / --debug-dir, so the second does not overwrite the first — a `.lightmap/` dir inside the project is skipped by the compile scan). Both must share the layout (same instances, rects and pages — a seed changes nothing else). Per instance: the mean of the layer, the noise as the RMS of (a − b) / √2 over the mean, in %, and the share of texels that differ by more than half their mean. Sorted by noise unless --sort says otherwise.",
   flags: {
-    bake: str("the first .bake", { value: "<file>", default: "assets/lightmap/lightmap.bake" }),
+    bake: str("the first .bake (default: the project's one .bake)", { value: "<file>" }),
     "debug-dir": str("where the first bake kept its PFM layers", { value: "<dir>", default: ".lightmap" }),
     bake2: str("the second .bake (another --seed)", { value: "<file>" }),
     "debug-dir2": str("where the second bake kept its PFM layers", { value: "<dir>" }),
@@ -423,19 +439,21 @@ const diff = defineCommand({
     limit: num("rows to print (0 = all)", { default: 40 }),
   },
   examples: [
-    "lecodes lightmap bake --entry range.ts --name range --seed 2 --out .lightmap/range-seed2/bake --debug-dir .lightmap/range-seed2 --logs",
-    "lecodes lightmap diff --bake assets/range/lightmap/range.bake --debug-dir .lightmap/range --bake2 .lightmap/range-seed2/bake/range.bake --debug-dir2 .lightmap/range-seed2 --layer bounce",
+    "lecodes lightmap bake --debug-dir .lightmap/seed1 --logs",
+    "lecodes lightmap bake --seed 2 --out .lightmap/seed2/bake --debug-dir .lightmap/seed2 --logs",
+    "lecodes lightmap diff --debug-dir .lightmap/seed1 --bake2 .lightmap/seed2/bake/level.bake --debug-dir2 .lightmap/seed2 --layer bounce",
   ],
   run: ({ flags }) => {
     const { root } = localProject()
     if (!flags.bake2 || !flags["debug-dir2"]) throw new CliError("--bake2 and --debug-dir2 name the second bake (another --seed).")
-    const a = readBake(resolve(root, flags.bake)), b = readBake(resolve(root, flags.bake2))
+    const bakeFile = bakeFileOf(root, flags.bake)
+    const a = readBake(bakeFile), b = readBake(resolve(root, flags.bake2))
     if (a.size !== b.size || a.pages !== b.pages) throw new CliError(`The bakes differ in layout (${a.pages} × ${a.size} vs ${b.pages} × ${b.size}) — a diff needs the same scene baked twice with another --seed.`)
     const ra = a.instances.filter((i) => i.receiver), rb = b.instances.filter((i) => i.receiver)
     if (ra.length !== rb.length || ra.some((i, k) => i.key !== rb[k].key || i.page !== rb[k].page || String(i.rect) !== String(rb[k].rect))) {
       throw new CliError("The bakes list different instances or rects — a diff needs the same scene baked twice with another --seed.")
     }
-    const stemA = basename(flags.bake, ".bake"), stemB = basename(flags.bake2, ".bake")
+    const stemA = basename(bakeFile, ".bake"), stemB = basename(flags.bake2, ".bake")
     const dirA = resolve(root, flags["debug-dir"]), dirB = resolve(root, flags["debug-dir2"])
     const layer = flags.layer
     if (![ "irradiance", "bounce", "sun", "sky", "lamps" ].includes(layer)) throw new CliError(`--layer: expected irradiance, bounce, sun, sky or lamps, got ${JSON.stringify(layer)}`)
@@ -559,7 +577,7 @@ const inspect = defineCommand({
   summary: "PNGs from a bake's debug layers: whole pages, or one instance's rect enlarged",
   description: "Reads the PFM float layers `bake --debug-dir` kept next to the .bake's rects. Without --key: one PNG per page and layer with every rect outlined. With --key: the matching instances' rects (plus a margin) enlarged by --scale, one PNG per instance and layer. Lux layers are shown as log10 over --lux-range (or linear over --white); vectors as x0.5+0.5.",
   flags: {
-    bake: str("the .bake file", { value: "<file>", default: "assets/lightmap/lightmap.bake" }),
+    bake: str("the .bake file (default: the project's one .bake)", { value: "<file>" }),
     "debug-dir": str("where the bake kept its PFM layers", { value: "<dir>", default: ".lightmap" }),
     out: str("where the PNGs go", { value: "<dir>", default: ".lightmap/png" }),
     key: str("instances whose key matches this regular expression (default: whole pages)", { value: "<regex>" }),
@@ -570,10 +588,10 @@ const inspect = defineCommand({
     white: num("linear mode: the lux shown as white (0 = log mode)", { default: 0 }),
     limit: num("instances to render with --key (0 = all)", { default: 24 }),
   },
-  examples: [ "lecodes lightmap inspect --bake assets/school/lightmap/school.bake --debug-dir .lightmap/school", "lecodes lightmap inspect --key 'Wall_05' --layer irradiance,sun,sky,lamps --scale 6" ],
+  examples: [ "lecodes lightmap inspect --debug-dir .lightmap/level", "lecodes lightmap inspect --key 'Wall_05' --layer irradiance,sun,sky,lamps --scale 6" ],
   run: ({ flags }) => {
     const { root } = localProject()
-    const bakeFile = resolve(root, flags.bake)
+    const bakeFile = bakeFileOf(root, flags.bake)
     const data = readBake(bakeFile)
     const stem = basename(bakeFile).replace(/\.bake$/, "")
     const dbg = resolve(root, flags["debug-dir"])

package/src/compile/projectCompile.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { createRequire } from "node:module"
 import { dirname, join } from "node:path"
 import type { FileKind } from "../project/manifest"
@@ -6,8 +6,8 @@ import { distRoot } from "../hosts/distRoot"
 import { installPeers } from "../hosts/peerInstall"
 import { peerDirInPrefix } from "../hosts/peers"
 import {
-  compileProject as sdkCompileProject, compileServerBundle, detectEntry, isServerPath, scanModulesChisel, localAssetNames, ENTRY_CONVENTION,
-  type CompileServerOptions,
+  compileProjectWithMap as sdkCompileProjectWithMap, compileServerBundle, detectEntry, inlineSourceMapComment, isServerPath, scanModulesChisel,
+  localAssetNames, ENTRY_CONVENTION, type BundleBake, type CompileServerOptions,
 } from "lecodes-sdk/compile"
 
 // Every project compiles through the SDK's one import-free compiler, which bundles with chisel (the
@@ -106,9 +106,23 @@ export const ambiguousEntryWarning = (entries: { path: string, type?: string, te
   return `Ambiguous entrypoint: nothing imports ${roots.join(", ")} — picked ${entry}. Rename your entry to main.ts (or pass --entry).`
 }
 
-export const compileProject = (opts: CompileOptions): Promise<string> =>
-  sdkCompileProject({
+/** A file of the compile by its root path (`/assets/lightmap/level.bake`) — how `bake()` reads the manifest it names:
+ *  the entries' own files on disk. */
+const resourceReader = (entries: CompileEntry[]) => {
+  const byRoot = new Map(entries.map((e) => [ "/" + e.path.replace(/\\/g, "/").replace(/^[./]+/, ""), e ]))
+  return (rootPath: string): string | null => {
+    const e = byRoot.get(rootPath)
+    if (e?.text !== undefined) return e.text
+    try { return e?.absPath ? readFileSync(e.absPath, "utf8") : null } catch { return null }
+  }
+}
+
+/** The bundle (its map inlined, the shipped / preview form) and the `bake()` targets it reaches — the target of
+ *  `lecodes lightmap bake`. */
+export const compileProjectBundle = async (opts: CompileOptions): Promise<{ js: string, bakes: BundleBake[] }> => {
+  const { code, map, bakes } = await sdkCompileProjectWithMap({
     entries: opts.entries.map((e) => ({ path: e.path, type: e.type as any, text: e.text, fileSrc: e.fileSrc, remote: e.remote, shaders: e.shaders, shadersLocal: e.shadersLocal })),
+    readResource: resourceReader(opts.entries),
     name: opts.name,
     publicUrl: opts.publicUrl,
     entryOverride: opts.entryOverride,
@@ -123,6 +137,10 @@ export const compileProject = (opts: CompileOptions): Promise<string> =>
     onWarning: opts.onWarning,
     serverUrl: opts.serverUrl,
   })
+  return { js: map ? `${code}\n${inlineSourceMapComment(map)}` : code, bakes }
+}
+
+export const compileProject = async (opts: CompileOptions): Promise<string> => (await compileProjectBundle(opts)).js
 
 /** Does the project have a server side (`*.server.ts` files)? */
 export const hasServerFiles = (entries: CompileEntry[]): boolean =>

package/src/compile/sceneCompile.ts

@@ -54,8 +54,9 @@ export const compileSceneEditor = async (opts: {
       // the same /project/* mount — see the fallback below when matc isn't available
       entries.push({ path, type: "shader", text: readFileSync(file.absPath, "utf8"), absPath: file.absPath })
     } else {
-      // Binary assets resolve to URLs the scene server serves from the project folder (/project/*).
-      entries.push({ path, type: "resource", fileSrc: "/project/" + rel(file.path) })
+      // Binary assets resolve to URLs the scene server serves from the project folder (/project/*);
+      // absPath lets a bake() read its manifest
+      entries.push({ path, type: "resource", fileSrc: "/project/" + rel(file.path), absPath: file.absPath })
     }
   }
 

package/src/hosts/peerInstall.ts

@@ -3,7 +3,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 import { pathToFileURL } from "node:url"
 import pkg from "../../package.json"
-import { peerDirInPrefix, peersDir, peerVersionGlobal } from "./peers"
+import { peerDirInPrefix, peersDir, peerVersionGlobal, peerVersionPrefix } from "./peers"
+import { semverNewer } from "./releases"
 import { archiveSpec } from "./archives"
 import { commandLine, installGlobalArgv, installIntoArgv, ownManager, pickManager } from "./packageManager"
 import { CliError, c, confirm, log, note } from "../cli"
@@ -124,6 +125,13 @@ const resolveEntry = (pkgDir: string, subpath?: string): string => {
   return join(pkgDir, rel)
 }
 
+/** The runtime set's peers that are npm's: the CLI calls their API (lightmap bake's unwrapGlbFiles), so one
+ *  OLDER than this CLI is a "not a function" deep inside a command — re-installed at this CLI's range, never
+ *  loaded. (The set's archive, lecodes-headless, is installed by its url at exactly this version.) */
+const SET_ON_NPM = new Set(["lecodes-assets"])
+const olderThanCli = (name: string, version: string | null): boolean =>
+  SET_ON_NPM.has(name) && version !== null && semverNewer(version, pkg.version) > 0
+
 const isNotFound = (e: unknown, spec: string): boolean => {
   const code = (e as { code?: string })?.code
   const msg = e instanceof Error ? e.message : String(e)
@@ -146,17 +154,25 @@ export async function loadPeer<T>(name: string, subpath: string | undefined, opt
 export async function loadPeer<T>(name: string, subpath: string | undefined, opts: LoadPeerOptions & { install: false }): Promise<T | null>
 export async function loadPeer<T>(name: string, subpath: string | undefined, opts: LoadPeerOptions): Promise<T | null> {
   const spec = subpath ? `${name}/${subpath}` : name
+  // what the user installed by hand wins — unless it is older than the API this CLI calls
+  const byHand = peerVersionGlobal(name, spec)
+  if (olderThanCli(name, byHand)) {
+    throw new CliError(`${name} ${byHand} (installed by hand) is older than this CLI (${pkg.version}) needs — update it: ${commandLine(ownManager(), installGlobalArgv(ownManager(), [await peerSpec(name)]))}`)
+  }
   try {
     return (await import(spec)) as T
   } catch (e) {
     if (!isNotFound(e, spec)) throw e
   }
   const dir = peerDirInPrefix(name)
-  if (!existsSync(join(dir, "package.json"))) {
+  const installed = peerVersionPrefix(name)
+  const stale = olderThanCli(name, installed)
+  if (installed === null || stale) {
     if (opts.install === false) return null
     // A global install of a DIFFERENT version than the probe expects would have resolved above; here
     // the peer is nowhere. (Globally installed but broken → the error above was not "not found".)
-    if (peerVersionGlobal(name, spec) !== null) throw new CliError(`${name} is installed but "${spec}" can't be loaded from it — reinstall it: ${commandLine(ownManager(), installGlobalArgv(ownManager(), [await peerSpec(name)]))}`)
+    if (installed === null && peerVersionGlobal(name, spec) !== null) throw new CliError(`${name} is installed but "${spec}" can't be loaded from it — reinstall it: ${commandLine(ownManager(), installGlobalArgv(ownManager(), [await peerSpec(name)]))}`)
+    if (stale) note(`${name} ${installed} in ${peersDir()} is older than this CLI (${pkg.version}) — installing the one it needs`)
     await installPeers(companions(name), opts.for)
   }
   return (await import(pathToFileURL(resolveEntry(dir, subpath)).href)) as T