lecodes-sdk 2.4.7 → 2.4.9

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.4.7",
+  "version": "2.4.9",
   "files": [
     "src",
     "dist",

package/src/bridges/gl.d.ts

@@ -184,6 +184,10 @@ declare global {
      *  not the roughness-prefiltered `_ibl.ktx` beside it. Optional: hosts that predate it keep the
      *  flat skybox. */
     setSkyboxTexture?(sceneId: u32, fetchId: bytes): void
+    /** Optional. Light the scene from a CUBEMAP texture (a render texture's cube, creator.h setEnvironmentTexture): the
+     *  IBL reflects it, its irradiance and intensity stay; no roughness prefiltering, so only mirror-like reflections are
+     *  right. The engine holds the texture while it lights; setDefaultIbl replaces it. */
+    setEnvironmentTexture?(sceneId: u32, textureId: u32): void
     /** Temporal anti-aliasing (Filament's TAA) for the scene and its overlays: on, MSAA and FXAA are off for the
      *  view; `feedback` = the history's share (0.12 default, higher = less ghosting, less smoothing), `sharpness` =
      *  the post-TAA sharpen (0–1), `upscale` = the fraction the 3D is rendered at and TAA-upscaled from (0.5–1,
@@ -325,6 +329,30 @@ declare global {
      *  re-uploads a sub-rectangle with the creation channel count. Optional (Texture.fromPixels throws). @args data width height channels srgb @count pixelBytes=data @owned GlTexture */
     createTexturePixels?(width: u32, height: u32, channels: u32, data: Uint8Array, srgb: boolean): Handle
     updateTexturePixels?(textureId: u32, x: u32, y: u32, width: u32, height: u32, data: Uint8Array): void
+    /** Optional. A RENDER TEXTURE, what a render view draws into (creator.h createRenderTexture): `flags` bit 1 = CUBEMAP
+     *  (`width` = the edge, `height` ignored), bit 2 = HDR (R11F_G11F_B10F linear light, for lighting); neither = an LDR
+     *  display texture (SRGB8_A8, the tone-mapped picture); bit 4 = PREFILTER, with both others only (flags 7, a
+     *  power-of-two edge of 16 at least): a probe filtered for roughness — the id is the 5-level filtered cube, its views
+     *  draw a raw one behind it, filtered on the GPU at the frame after each completed cube with `samples` samples
+     *  (0 = 256; read for PREFILTER only). Otherwise an ordinary texture id (setUniformTexture, setSceneBackground); its
+     *  texel rows run as OpenGL renders, on every backend (a 2D texture's first row = the picture's bottom). 0xFFFFFFFF
+     *  on failure. @owned GlTexture */
+    createRenderTexture?(width: u32, height: u32, flags: u32, samples: u32): Handle
+    /** Optional. A RENDER VIEW of the scene into a render texture, from node `cameraEntityId` (its world pose, read every
+     *  frame; a cube takes its position only): `layerMask` = the layers it sees (setLayer), `fov` vertical degrees (a cube
+     *  is 90), `flags` bit 1 = no shadows. Drawn each frame its scene is presented, before the scene's own view; freeing the
+     *  texture takes its views with it. 0 on failure. @owned GlRenderView */
+    createRenderView?(sceneId: u32, textureId: u32, cameraEntityId: u32, layerMask: u8, fov: f32, near: f32, far: f32, flags: u32): Handle
+    /** Optional. `everyNth` 1 = every frame, N = one render per N frames drawn, counted afresh from this call (the next
+     *  frame renders); `facesPerFrame` 1..6 for a cube (round-robin). */
+    setRenderViewOptions?(renderViewId: u32, enabled: boolean, everyNth: u32, facesPerFrame: u32): void
+    /** Optional. The view's projection, live (createRenderView's fov / near / far were the initial values): a 2D view's
+     *  vertical fov in degrees and clip planes; a cube ignores `fov` (90) and takes the planes. Unknown id = no-op. */
+    setRenderViewProjection?(renderViewId: u32, fov: f32, near: f32, far: f32): void
+    /** Optional. RGBA8 bytes of a rectangle of a render texture as the next frame leaves it — rows in the texture's order
+     *  (the first is texel row `y`), `face` 0..5 = +X -X +Y -Y +Z -Z of a cube (0 for 2D), an HDR one clamped to 0..1
+     *  (linear); null when refused. A GPU readback, for checks and tools. @custom */
+    readRenderTexturePixels?(textureId: u32, face: u32, x: u32, y: u32, width: u32, height: u32, onDone: (pixels: Uint8Array | null) => void): void
 
     /** A material INSTANCE of these .filamat bytes (an app's own shader, fetched); the material itself is deduplicated by content in the engine. @c createMaterialInstanceFromBytes @owned GlMaterial @throw createMaterial: no .filamat bytes behind this fetch id */
     createMaterial(systemId: bytes): Handle
@@ -355,6 +383,12 @@ declare global {
 
     setVisible(entityId: u32, visible: boolean): void
     isVisible(entityId: u32): boolean
+    /** Optional. Visibility layers: the entity's explicit layer bits (u8), inherited by its subtree down to a
+     *  descendant with its own; 0 clears them (inherit again). Nothing set = 0x01. A view draws a renderable
+     *  when their layers share a bit (the scene's own view sees all). A host without it has no layers. @c setEntityLayer */
+    setLayer?(entityId: u32, mask: u8): void
+    /** Optional. The entity's effective layer bits: its own, else the nearest ancestor's, else 0x01. @c getEntityLayer */
+    getLayer?(entityId: u32): u8
 
     /** @custom */
     createGlb(systemId: bytes, onComplete: (root: Handle | null) => void, onReject: () => void): void

package/src/compile/assetMacro.ts

@@ -22,7 +22,7 @@ export const hasAssetMacro = (src: string): boolean => src.includes("asset(")
  * Not a full lexer: a regex LITERAL containing `asset(` would still be seen as code. That case
  * doesn't occur in practice and behaves exactly as it did before this masking existed.
  */
-const maskNonCode = (src: string, onString?: (start: number, end: number) => void): string => {
+export const maskNonCode = (src: string, onString?: (start: number, end: number) => void): string => {
   const out = src.split("")
   const blank = (from: number, to: number) => {
     for (let k = from; k < to && k < out.length; k++) if (out[k] !== "\n") out[k] = " "
@@ -97,7 +97,7 @@ export const CODE_EXT = /\.([tj]sx?|mjs|cjs|json)$/i
 // What precedes an import specifier: the literal is a module path, never a resource reference.
 const IMPORT_BEFORE = /(?:\bfrom|\bimport|\bimport\s*\(|\brequire\s*\()\s*$/
 
-const normalizePath = (path: string): string => {
+export const normalizePath = (path: string): string => {
   const out: string[] = []
   for (const part of path.split("/")) {
     if (part === "" || part === ".") continue

package/src/compile/bakeMacro.ts

@@ -0,0 +1,243 @@
+// The compile-time `bake('./assets/lightmap/level.bake', { …options })` macro — a level's ONE reference to its bake
+// (gl/Lightmap.ts). `lecodes lightmap bake` writes `<stem>.bake`, a JSON manifest that names every file it wrote next to
+// it (`light[]`, `aux[]`, `direct[]`, `indirect[]`, `probes.file`, `volume.file`, `uv1`). The macro reads that manifest at
+// compile time and rewrites the call IN PLACE to the literal `Lightmap.load` takes, every file an `asset()` call that the
+// asset pass desugars right after — so the files are staged and resolved exactly as asset() ones are:
+//
+//   bake('../assets/range/lightmap/range.bake', { emissiveBake: false })
+//   → { data: asset("/assets/range/lightmap/range.bake"), path: `assets/range/lightmap/range.bake`,
+//       light: [asset("/assets/range/lightmap/range-light.ktx2")], aux: [ … ], probes: asset( … ), volume: asset( … ),
+//       uv1: asset( … ), ...{ emissiveBake: false } }
+//
+// No `.bake` yet (before the first bake) is no error: `{ data: null, path: `…`, light: [], aux: [], ...options }` — the
+// level runs unbaked and says so, and under `lecodes lightmap bake` that path is the target the bake writes. A file the
+// manifest names that is not in the project fails the compile of an entry that reaches the call (the bundler, the way
+// a missing asset() does). The bundler also reports every reached bake() (`bakes`): the CLI's bake target.
+//
+// The path resolves like a bare path literal does: `./` and `../` from the file first, then from the project root; `/x`
+// from the root; `a/b.bake` from the root, then the file. `path` comes out as a TEMPLATE literal on purpose — the bare
+// path pass (collectPathLiterals) would read a quoted `.bake` path as that file's asset. The options must be an object
+// literal; its source text is copied as written (file-local identifiers stay valid: the expansion sits where the call
+// stood), and the expansion keeps the call's line breaks, so the bundle's source map still matches the file.
+//
+// A file that declares its own `bake` (a function, a const, an import) is left alone — real scoping wins, as with
+// font() — and so is a method or function DEFINITION named bake (`bake() { … }`: a block follows its parameters).
+
+import { maskNonCode, normalizePath } from "./assetMacro"
+import { escapeTemplate } from "./assetIconMacro"
+
+/** One `bake()` call: its target and what the manifest named. */
+export type BakeMacroRef = {
+  /** The `.bake`, project-relative (no leading slash) — what the def's `path` says. */
+  path: string
+  /** The manifest is among the compile's files (false = before the first bake). */
+  exists: boolean
+  /** The call's line in its file. */
+  line: number
+  /** The path as written in the call. */
+  written: string
+  /** Root paths the manifest names that are not among the compile's files. */
+  missing: string[]
+  /** Set when the compile has the manifest but no way to read it (no `readResource`): the call compiled unbaked. */
+  unread?: true
+}
+
+/** The manifest's text by its ROOT path (`/assets/lightmap/level.bake`), or null when this compile cannot read it. */
+export type BakeManifestReader = (rootPath: string) => string | null | Promise<string | null>
+
+// A call at a code position (the lookbehind excludes `Lightmap.bake(…)` and `x.bake`); matched over the MASK, so a
+// `bake(` inside a string or a comment is never seen.
+const BAKE_CALL = /(?<![.\w$])bake\s*\(/g
+/** A file that declares/imports its own `bake` — the macro must not touch it. */
+const DECLARES_BAKE = /\b(?:function|const|let|var|class)\s+bake\b|\bimport\s+(?:\{[^}]*\bbake\b[^}]*\}|bake)\s+from\b/
+
+/** What follows the parameters of a definition: an optional return type on the same line, then its block or arrow. */
+const DEFINITION_TAIL = /^\s*(?::[^;{}=()\n]*)?(?:\{|=>)/
+
+/** Cheap pre-check so the scan does not run over every file. */
+export const hasBakeMacro = (src: string): boolean => src.includes("bake")
+
+/** The value of a whole-string literal (`"x"`, `'x'`, plain `` `x` ``), or null if `text` is not one. */
+const stringLiteralValue = (text: string): string | null => {
+  const t = text.trim()
+  if (t.length < 2) return null
+  const q = t[0]
+  if ((q !== "\"" && q !== "'" && q !== "`") || t[t.length - 1] !== q) return null
+  const inner = t.slice(1, -1)
+  if (q === "`" && inner.includes("${")) return null
+  if (/[\r\n]/.test(inner)) return null
+  for (let i = 0; i < inner.length; i++) {
+    if (inner[i] === "\\") { i++; continue }
+    if (inner[i] === q) return null   // two literals, not one
+  }
+  return inner.replace(/\\(.)/g, "$1")
+}
+
+/** Index of the bracket that closes the one at `open` over the mask (strings and comments are blank there), or -1. */
+const closeOf = (mask: string, open: number): number => {
+  let depth = 0
+  for (let i = open; i < mask.length; i++) {
+    const c = mask[i]
+    if (c === "(" || c === "[" || c === "{") depth++
+    else if (c === ")" || c === "]" || c === "}") { depth--; if (depth === 0) return i }
+  }
+  return -1
+}
+
+/** The top-level argument spans of the call whose parens are at `open` / `close`. */
+const argSpans = (mask: string, open: number, close: number): [number, number][] => {
+  const spans: [number, number][] = []
+  let depth = 0
+  let start = open + 1
+  for (let i = open + 1; i < close; i++) {
+    const c = mask[i]
+    if (c === "(" || c === "[" || c === "{") depth++
+    else if (c === ")" || c === "]" || c === "}") depth--
+    else if (c === "," && depth === 0) { spans.push([ start, i ]); start = i + 1 }
+  }
+  spans.push([ start, close ])
+  return spans
+}
+
+const newlines = (s: string): number => {
+  let n = 0
+  for (let i = 0; i < s.length; i++) if (s[i] === "\n") n++
+  return n
+}
+
+const stringArray = (v: unknown): string[] | null =>
+  Array.isArray(v) && v.every((x) => typeof x === "string") ? v as string[] : null
+
+type Manifest = { light: string[], aux: string[], direct?: string[], indirect?: string[], probes?: string, volume?: string, uv1?: string }
+
+/** The file lists of a manifest's JSON — null when it is not one (`light` / `aux` are what every bake writes). */
+const readManifest = (json: unknown): Manifest | null => {
+  if (!json || typeof json !== "object") return null
+  const m = json as Record<string, unknown>
+  const light = stringArray(m.light), aux = stringArray(m.aux)
+  if (!light || !aux) return null
+  const file = (v: unknown): string | undefined =>
+    typeof v === "string" && v !== "" ? v
+    : v && typeof v === "object" && typeof (v as { file?: unknown }).file === "string" ? (v as { file: string }).file
+    : undefined
+  return {
+    light, aux,
+    direct: stringArray(m.direct) ?? undefined,
+    indirect: stringArray(m.indirect) ?? undefined,
+    probes: file(m.probes),
+    volume: file(m.volume),
+    uv1: file(m.uv1),
+  }
+}
+
+/**
+ * Expand every `bake()` call of one file (`filePath`: its root path, `/src/level.scene.ts`). `exists(rootPath)` says
+ * whether the compile has that file, `read(rootPath)` gives a manifest's text. Throws on a malformed call (a dynamic
+ * path, a path that is not a `.bake`, options that are not an object literal) or a manifest that is not one.
+ */
+export const expandBakeMacros = async (
+  src: string, filePath: string, exists: (rootPath: string) => boolean, read?: BakeManifestReader,
+): Promise<{ src: string, bakes: BakeMacroRef[] }> => {
+  if (!hasBakeMacro(src)) return { src, bakes: [] }
+  const strings: [number, number][] = []
+  const mask = maskNonCode(src, (s, e) => { strings.push([ s, e ]) })
+  if (DECLARES_BAKE.test(mask)) return { src, bakes: [] }
+  // an argument's parts: the mask blanks comments AND string literals, `strings` says where the literals were
+  const stringsIn = ([ a, b ]: [number, number]) => strings.filter(([ s, e ]) => s >= a && e <= b)
+  const blankArg = (span: [number, number]): boolean => mask.slice(span[0], span[1]).trim() === "" && stringsIn(span).length === 0
+  const literalOf = (span: [number, number]): string => {
+    const inside = stringsIn(span)
+    if (inside.length === 1 && mask.slice(span[0], span[1]).trim() === "") return src.slice(inside[0][0], inside[0][1])
+    return src.slice(span[0], span[1]).trim()   // a template literal, or no literal at all (the error names it)
+  }
+  const dir = filePath.slice(0, filePath.lastIndexOf("/"))
+  const at = (index: number): string => `${filePath.replace(/^\//, "")}:${newlines(src.slice(0, index)) + 1}`
+  const bakes: BakeMacroRef[] = []
+  const parts: string[] = []
+  let done = 0
+  for (const m of mask.matchAll(BAKE_CALL)) {
+    const start = m.index ?? 0
+    if (start < done) continue   // inside an expanded call's arguments
+    const open = start + m[0].length - 1
+    const close = closeOf(mask, open)
+    if (close < 0) throw new Error(`bake(): unclosed call (${at(start)})`)
+    const spans = argSpans(mask, open, close)
+    const pathText = literalOf(spans[0])
+    const written = stringLiteralValue(pathText)
+    // a DEFINITION named bake (a method, a function, an object's method shorthand): no string literal for a first
+    // argument, and a block after its parameters (past a return type) — `bake() {`, `bake(x: number): void {`
+    if (written === null && DEFINITION_TAIL.test(mask.slice(close + 1, close + 160))) continue
+    if (written === null) throw new Error(`bake() expects a string-literal path like bake('./assets/lightmap/level.bake'), found \`${pathText || "()"}\` (${at(start)})`)
+    if (!/\.bake$/i.test(written)) throw new Error(`bake('${written}'): the path names a .bake file — what \`lecodes lightmap bake\` writes (${at(start)})`)
+    // a trailing comma leaves an empty last span; anything else past the options is one argument too many
+    if (spans.slice(2).some((s) => !blankArg(s))) throw new Error(`bake('${written}'): one path and one options object at most (${at(start)})`)
+    let options: [number, number] | null = null
+    if (spans.length > 1 && !blankArg(spans[1])) {
+      const [ a, b ] = spans[1]
+      const code = mask.slice(a, b)
+      const lead = a + (code.length - code.trimStart().length)
+      const tail = b - (code.length - code.trimEnd().length)
+      if (mask[lead] !== "{" || closeOf(mask, lead) !== tail - 1) {
+        throw new Error(`bake('${written}', options): options must be an object literal like { emissiveBake: false } (${at(start)})`)
+      }
+      options = [ lead, tail ]
+    }
+
+    // the target: as a bare path literal resolves; the first candidate when the file is not there yet
+    const relative = written.startsWith("./") || written.startsWith("../")
+    const rooted = written.startsWith("/")
+    const candidates = rooted ? [ normalizePath(written) ]
+      : relative ? [ normalizePath(`${dir}/${written}`), normalizePath(written) ]
+      : [ normalizePath(written), normalizePath(`${dir}/${written}`) ]
+    const found = candidates.find(exists)
+    const target = found ?? candidates[0]
+    const ref: BakeMacroRef = { path: target.slice(1), exists: found !== undefined, line: newlines(src.slice(0, start)) + 1, written, missing: [] }
+
+    let manifest: Manifest | null = null
+    if (found !== undefined) {
+      const body = read ? await read(found) : null
+      if (body === null) ref.unread = true
+      else {
+        let json: unknown
+        try { json = JSON.parse(body.replace(/^\uFEFF/, "")) } catch (e) {
+          throw new Error(`bake('${written}'): ${ref.path} is not a bake manifest (${e instanceof Error ? e.message : String(e)}) — rebake with \`lecodes lightmap bake\` (${at(start)})`)
+        }
+        manifest = readManifest(json)
+        if (!manifest) throw new Error(`bake('${written}'): ${ref.path} is not a bake manifest (no light / aux pages) — rebake with \`lecodes lightmap bake\` (${at(start)})`)
+      }
+    }
+
+    // every name in the manifest is relative to the .bake's folder
+    const bakeDir = target.slice(0, target.lastIndexOf("/"))
+    const ref1 = (name: string): string => {
+      const p = normalizePath(`${bakeDir}/${name}`)
+      if (!exists(p) && !ref.missing.includes(p)) ref.missing.push(p)
+      return `asset(${JSON.stringify(p)})`
+    }
+    const list = (names: string[]): string => `[${names.map(ref1).join(", ")}]`
+    const fields = [ `path: \`${escapeTemplate(ref.path)}\`` ]
+    if (manifest) {
+      fields.unshift(`data: asset(${JSON.stringify(target)})`)
+      fields.push(`light: ${list(manifest.light)}`, `aux: ${list(manifest.aux)}`)
+      if (manifest.direct) fields.push(`direct: ${list(manifest.direct)}`)
+      if (manifest.indirect) fields.push(`indirect: ${list(manifest.indirect)}`)
+      if (manifest.probes) fields.push(`probes: ${ref1(manifest.probes)}`)
+      if (manifest.volume) fields.push(`volume: ${ref1(manifest.volume)}`)
+      if (manifest.uv1) fields.push(`uv1: ${ref1(manifest.uv1)}`)
+    } else {
+      fields.unshift("data: null")
+      fields.push("light: []", "aux: []")
+    }
+    // the call's line breaks, kept where they were: before the options, and after them
+    const head = `{ ${fields.join(", ")}`
+    const expansion = options
+      ? `${head}, ${"\n".repeat(newlines(src.slice(start, options[0])))}...${src.slice(options[0], options[1])}${"\n".repeat(newlines(src.slice(options[1], close + 1)))} }`
+      : `${head}${"\n".repeat(newlines(src.slice(start, close + 1)))} }`
+    parts.push(src.slice(done, start), expansion)
+    done = close + 1
+    bakes.push(ref)
+  }
+  if (bakes.length === 0) return { src, bakes }
+  parts.push(src.slice(done))
+  return { src: parts.join(""), bakes }
+}

package/src/compile/bundler.ts

@@ -4,6 +4,7 @@ import { createRequire } from "node:module"
 import { dirname, join, relative } from "node:path"
 import { fileURLToPath } from "node:url"
 import { collectAssetMacros, collectPathLiterals, desugarAssetMacros, hasAssetMacro, type AssetMacroRef } from "./assetMacro"
+import { expandBakeMacros, hasBakeMacro, type BakeMacroRef, type BakeManifestReader } from "./bakeMacro"
 import { scanModulesFallback, type ScanModule } from "./detectEntry"
 import { hasAspectExtends, injectAspectNames } from "./aspectMacro"
 import { hasImportStatement, rewriteLibraryImports } from "./libraryImports"
@@ -19,6 +20,10 @@ import { chiselVocab } from "../chisel"
 
 export type MemoryFiles = Record<string, string>
 
+/** A `bake()` the bundle reaches (bakeMacro.ts): the level's `.bake`, project-relative, and whether it exists yet —
+ *  what `lecodes lightmap bake` writes to. */
+export type BundleBake = { path: string, exists: boolean }
+
 /** Locate the SDK inject entry: an explicit override (LECODES_SDK_INJECT — used by the published CLI,
  *  which vendors the SDK source), else the source in-repo. chisel needs the SOURCE tree (not a bundle). */
 const resolveInject = (): string => {
@@ -201,15 +206,20 @@ const bundleProjectChisel = async (
   editor?: boolean,
   libraries?: Record<string, MemoryFiles>,
   inject: string = CLIENT_INJECT,
-): Promise<{ code: string, map: string | null, diagnostics: string[] }> => {
+  readResource?: BakeManifestReader,
+): Promise<{ code: string, map: string | null, diagnostics: string[], bakes: BundleBake[] }> => {
   const entry = normalize(entrypoint)
   const slugs = new Set(Object.keys(libraries ?? {}))
+  // The compile's files by root path (the editor keys them "./x", the CLI "/x") — what bake() resolves against.
+  const rootKeys = new Map(Object.keys(files).map((k) => [ normalize(k), k ]))
   // Per-file source transforms (project files only — SDK aspects declare their own `static aspect`):
   //  - rewrite bare library imports (`from "acme-ui"`) → the injected `/__lib/<slug>/…` tree
+  //  - expand `bake('./x.bake', { … })` → the literal its manifest lists, every file an asset() call (bakeMacro.ts)
   //  - desugar `asset('./x')` → a default import that resolves to the synthetic asset module
   //  - inject `static aspect = '<name>'` from `class … extends Aspect<'<name>', …>`
   const projFiles: MemoryFiles = {}
   const assetRefs: { file: string, ref: AssetMacroRef }[] = []
+  const bakeRefs: { file: string, ref: BakeMacroRef }[] = []
   // What the module scanner sees: import-rewritten, NOT yet asset-desugared (a desugared asset is a
   // default import of a non-module — the fallback scanner drops it, chisel's scan would not).
   const scanSources: MemoryFiles = {}
@@ -219,6 +229,11 @@ const bundleProjectChisel = async (
     if (/\.[tj]sx?$/.test(path)) {
       if (hasImportStatement(src)) src = rewriteLibraryImports(src, slugs)
       scanSources[path] = src
+      if (hasBakeMacro(src)) {
+        const expanded = await expandBakeMacros(src, path, (rootPath) => rootKeys.has(rootPath), readResource)
+        for (const ref of expanded.bakes) bakeRefs.push({ file: path, ref })
+        src = expanded.src
+      }
       // `asset('…')` calls, then the bare path literals that name a resource of the project (the
       // same reference without the macro); both desugar to the import the author could have written.
       const macros = hasAssetMacro(src) ? collectAssetMacros(src, path) : []
@@ -255,8 +270,22 @@ const bundleProjectChisel = async (
     }
   }
 
-  if (assetRefs.length > 0) {
+  // What the entry reaches is checked: a missing asset, a bake whose manifest names a file that is not there. The bakes
+  // it reaches are reported (the CLI's bake target); a manifest this compile could not read compiled unbaked.
+  const bakes: BundleBake[] = []
+  const notes: string[] = []
+  if (assetRefs.length > 0 || bakeRefs.length > 0) {
     const reachable = reachableFrom(entry, scanSources)
+    const reached = bakeRefs.filter(({ file }) => reachable.has(file))
+    const incomplete = reached.filter(({ ref }) => ref.missing.length > 0)
+    if (incomplete.length > 0) {
+      throw new Error(incomplete.map(({ file, ref }) =>
+        `bake('${ref.written}') (${file.replace(/^\//, "")}:${ref.line}): ${ref.path} names files that are not there: ${ref.missing.map((p) => p.replace(/^\//, "")).join(", ")} — rebake with \`lecodes lightmap bake\``).join("\n"))
+    }
+    for (const { file, ref } of reached) {
+      if (!bakes.some((b) => b.path === ref.path)) bakes.push({ path: ref.path, exists: ref.exists })
+      if (ref.unread) notes.push(`${file.replace(/^\//, "")}:${ref.line}: bake('${ref.written}'): this compile cannot read ${ref.path} — the level runs unbaked`)
+    }
     assertAssetsExist(assetRefs.filter(({ file }) => reachable.has(file)), projFiles)
   }
 
@@ -308,9 +337,9 @@ const bundleProjectChisel = async (
   // Non-fatal build-time findings (`path:line:col: message`) — today: particle curve chains the
   // engine would reject at set time. Warn so they're visible in the CLI / server log; the bundle
   // itself is unaffected (chisel leaves an invalid chain as real calls).
-  const diagnostics = parsed.diagnostics ?? []
+  const diagnostics = [ ...notes, ...(parsed.diagnostics ?? []) ]
   for (const d of diagnostics) console.warn(`warning: ${d}`)
-  return { code: parsed.code, map: parsed.map ?? null, diagnostics }
+  return { code: parsed.code, map: parsed.map ?? null, diagnostics, bakes }
 }
 
 /**
@@ -326,7 +355,9 @@ export const bundleProject = async (
 /** Like `bundleProject`, but also returns chisel's source map (and any build-time `diagnostics`).
  *  The map's `sources` are the original module paths and its generated positions are relative to
  *  `code` (line 1 = first line of `code`). Pass `sourcemap: false` to skip map generation entirely —
- *  `map` then comes back null. */
+ *  `map` then comes back null. `readResource` reads a resource's text by its root path — the
+ *  manifest a `bake()` names; without one a bake() compiles unbaked (a diagnostic says so). `bakes`
+ *  = the bake() targets the entry reaches. */
 export const bundleProjectWithMap = async (
   entrypoint: string,
   files: MemoryFiles,
@@ -336,4 +367,5 @@ export const bundleProjectWithMap = async (
   libraries?: Record<string, MemoryFiles>,
   sourcemap = true,
   inject?: string,
-): Promise<{ code: string, map: string | null, diagnostics: string[] }> => bundleProjectChisel(entrypoint, files, format, sourcemap, minify, editor, libraries, inject)
+  readResource?: BakeManifestReader,
+): Promise<{ code: string, map: string | null, diagnostics: string[], bakes: BundleBake[] }> => bundleProjectChisel(entrypoint, files, format, sourcemap, minify, editor, libraries, inject, readResource)

package/src/compile/compileProject.ts

@@ -3,7 +3,8 @@
 // (the backend resolves asset URLs from the DB, the CLI from local metadata — same function, the
 // URLs are passed in as `publicUrl` + per-entry `fileSrc`/`shaders`).
 
-import { bundleProjectWithMap, scanModulesChisel, type MemoryFiles } from "./bundler"
+import { bundleProjectWithMap, scanModulesChisel, type BundleBake, type MemoryFiles } from "./bundler"
+import type { BakeManifestReader } from "./bakeMacro"
 import { detectEntry } from "./detectEntry"
 import { buildHeader } from "./header"
 import { inlineSourceMapComment, offsetSourceMap } from "./sourcemap"
@@ -75,12 +76,17 @@ export type CompileOptions = {
    *  files never reach the client bundle either way; with no URL, calling an endpoint fails with
    *  "server not deployed". */
   serverUrl?: string
+  /** The TEXT of a resource entry by its root path (`/assets/lightmap/level.bake`) — how `bake()` reads the manifest
+   *  it names at compile time (the CLI: the file on disk). Without one, or null for a file, that bake() compiles to an
+   *  unbaked level (a warning says so). */
+  readResource?: BakeManifestReader
 }
 
 /** The bundle + its map SEPARATELY (the platform deploy writes the map as a sibling `.js.map`; the
  *  preview inlines it) plus the entrypoint the compile used. `code` carries the metadata header
- *  unless `header: false`; `map` is already shifted past that header. */
-export type CompileResult = { code: string, map: string | null, entry: string }
+ *  unless `header: false`; `map` is already shifted past that header. `bakes` = the `bake()` targets
+ *  the entry reaches (bakeMacro.ts). */
+export type CompileResult = { code: string, map: string | null, entry: string, bakes: BundleBake[] }
 
 /** The basename a local resource would be looked up by. */
 export const localAssetBase = (path: string): string => path.split(/[\\/]/).pop() ?? path
@@ -253,8 +259,8 @@ export const compileProjectWithMap = async (opts: CompileOptions): Promise<Compi
   }
 
   const files = entriesToFiles(entries, opts)
-  const { code, map } = await bundleProjectWithMap(
-    entry, files, opts.format ?? "esm", opts.minify, opts.editor, opts.libraries, opts.sourcemap ?? true,
+  const { code, map, bakes } = await bundleProjectWithMap(
+    entry, files, opts.format ?? "esm", opts.minify, opts.editor, opts.libraries, opts.sourcemap ?? true, undefined, opts.readResource,
   )
   const plugins = opts.plugins ?? pluginsOfAppJson(entries)
   if (map && opts.onWarning) {
@@ -263,11 +269,11 @@ export const compileProjectWithMap = async (opts: CompileOptions): Promise<Compi
       opts.onWarning(`The app uses ${missing.map(id => `"${id}"`).join(", ")} and app.json does not list ${missing.length === 1 ? "it" : "them"}: a plugin that is not listed is not there — in a shell built from this project and in the browser alike. Add to app.json: "plugins": { ${missing.map(id => `"${id}": "*"`).join(", ")} }`)
     }
   }
-  if (opts.header === false) return { code, map, entry }
+  if (opts.header === false) return { code, map, entry, bakes }
   const header = buildHeader(opts.name, code, { icon: opts.icon, fonts: opts.fontsHeader, icons: opts.iconsHeader, plugins })
   // Shift the map down past the header (prepended before the code).
   const headerLines = (header.match(/\n/g) ?? []).length
-  return { code: header + code, map: map ? offsetSourceMap(map, headerLines) : null, entry }
+  return { code: header + code, map: map ? offsetSourceMap(map, headerLines) : null, entry, bakes }
 }
 
 /** The bundle as ONE string, the map inlined at its end (the shipped/preview form). */

package/src/compile/index.ts

@@ -1,7 +1,8 @@
 // The public entry of the SDK's bundle build system. The backend, CLI, and local renderer import
 // from here instead of re-forking a bundler. (Node + Bun safe — no top-level host globals.)
 
-export { bundleProject, bundleProjectWithMap, scanModulesChisel, CLIENT_INJECT, SERVER_INJECT, type MemoryFiles } from "./bundler"
+export { bundleProject, bundleProjectWithMap, scanModulesChisel, CLIENT_INJECT, SERVER_INJECT, type MemoryFiles, type BundleBake } from "./bundler"
+export { expandBakeMacros, type BakeMacroRef, type BakeManifestReader } from "./bakeMacro"
 export {
   compileServerBundle,
   clientPublishes,

package/src/compile/resourceSlots.ts

@@ -36,10 +36,11 @@ export const resourceSlots = {
   assignments: [ "src", "lut" ],
   /** The keys of an object literal whose value is a file: `.style({ bgImage })`, `UITabs({ id: { icon } })`,
    *  `defineSpriteSheet({ image })`, `defineScene({ nodes: { x: { model } }, env: { ibl, skybox: { texture },
-   *  lightmap: { data, light, … } } })`, `Terrain.create({ layers: [{ albedo }], normals })`, a material's
-   *  `map` / `shader`, `Level.place({ build })`. The value may sit in an array, a ternary or an arrow's body. */
+   *  navmesh: { data } } })`, `Terrain.create({ layers: [{ albedo }], normals })`, a material's `map` / `shader`,
+   *  `Level.place({ build })`. The value may sit in an array, a ternary or an arrow's body. (A level's bake is no
+   *  slot: `bake()` reads its files off the manifest.) */
   keys: [
     "bgImage", "backgroundImage", "icon", "image", "texture", "model", "ibl", "lut", "albedo", "normals",
-    "map", "shader", "build", "data", "light", "aux", "direct", "indirect", "probes", "volume",
+    "map", "shader", "build", "data",
   ],
 }