lecodes-sdk 2.4.5 → 2.4.7

package/src/scene/defineScene.ts

@@ -188,8 +188,12 @@ export type SceneNodeDef = {
   /** Baked lighting (a scene with `env.lightmap`): is this model/mesh node a lightmap STATIC — a
    *  receiver and an occluder in the bake, real-time shadow casting off once the bake applies?
    *  Default: static unless a `Physics` aspect moves the node (`dynamic` — Physics' default — or
-   *  `kinematic`). Set it only to override that rule; prefab subtrees inherit the verdict. */
-  lightmap?: boolean
+   *  `kinematic`). Set it only to override that rule; prefab subtrees inherit the verdict.
+   *  `'cube'` = a static whose every mesh bakes as AMBIENT CUBES instead of atlas texels — an occluder (its shadow and
+   *  bounce stay in the bake) lit where it stands, the way the bake treats small and thin props on its own: a pipe run, a
+   *  fence, a prop whose lightmap seams show. A prefab marked `'cube'` bakes its statics that way too. By name for a whole
+   *  kit: `env.lightmap.cube`. */
+  lightmap?: boolean | "cube"
   /** `model` nodes: vegetation — load through the FOLIAGE tier (wind, touch bending, per-copy tint; see
    *  `Foliage`). `{ fade: [start, end] }` also thins the cards out over that distance range (m) and drops the
    *  copy past `end` — for ground cover. The fade is per ASSET: every node of the same GLB shares it. */
@@ -243,10 +247,19 @@ export type SceneLightmapDef = {
    *  `{ through, diffuse }` splits it: `through` goes straight (the picture of the map), `diffuse` is scattered by the
    *  fibres (the underside glows, a soft fill with no picture) - dense canvas: `{ through: 0.08, diffuse: 0.25 }`. */
   transmit?: Record<string, LightmapTransmit>
+  /** FOR THE BAKE: CUBES BY NAME — regular expressions (ECMAScript, case-sensitive) searched in every baked mesh's key
+   *  (`<node path>@<ordinal>`): `['SM_pipe', 'SM_fence']` bakes every pipe and fence node as ambient cubes instead of atlas
+   *  texels, like a node's `lightmap: 'cube'`. The CLI's `--cube` adds to these. */
+  cube?: string[]
   /** `asset('./assets/lightmap/level.lgrid')` — THE LIGHT GRID for movers: every node a Physics aspect or a
    *  CharacterController moves (and what code marks with `Lightmap.track`) takes its ambient light from the bake at the
    *  place it is at, whatever its shader. Absent = movers keep the scene's IBL. */
   volume?: string
+  /** `asset('./assets/lightmap/level-uv1.bin')` — THE PACKED LIGHTMAP UV1 the bake's rects map: it packs every mesh's
+   *  lightmap charts into a square of their own instead of the unwrap's (once per mesh, whatever model holds it), and the
+   *  engine swaps this into the models' TEXCOORD_1 before the rects go on. Required when the bake wrote one (the .bake's `uv1`): without it the statics
+   *  read the wrong texels, so the bake is not applied. */
+  uv1?: string
   /** A DEBUG multiplier on the atlas' lux (default 1). */
   lightScale?: number
 }
@@ -430,12 +443,13 @@ const createMesh = async (def: MeshDef, material?: MaterialDef): Promise<Mesh> =
 
 // ---- baked lighting (env.lightmap) ---------------------------------------------------------------
 // Statics are derived, not declared: a model/mesh node bakes unless a Physics aspect moves it
-// (`dynamic` — Physics' default — or `kinematic`); `lightmap: true | false` on the node overrides.
-// Keys are node paths (prefab internals: `wrapper/inner`), so lightmap.bake stays readable and a
-// rename honestly invalidates the rect. make() subtrees are code — they register themselves with
+// (`dynamic` — Physics' default — or `kinematic`); `lightmap: true | false | 'cube'` on the node overrides ('cube': a static
+// baked as ambient cubes, its prefab internals too — LightmapCtx.cube).
+// Keys are node paths (prefab internals: `wrapper/inner`; a model's meshes are records `<path>@<ordinal>` of their own), so
+// lightmap.bake stays readable and a rename honestly invalidates the rect. make() subtrees are code — they register themselves with
 // Lightmap.add. Edit mode never bakes or applies (the editor shows real-time shadows).
 
-type LightmapCtx = { prefix: string }
+type LightmapCtx = { prefix: string, cube?: boolean }
 
 // A CharacterController moves its node as surely as a dynamic body does (2026-09-11: the hero's
 // capsule was read as static, so its sword baked a shadow into the terrain at the spawn point).
@@ -446,7 +460,7 @@ const movesByPhysics = (def: SceneNodeDef): boolean =>
 
 /** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule).
  *  Children of a mover are movers too — buildNodes carries that down, this is the node's own verdict. */
-export const isLightmapStatic = (def: SceneNodeDef): boolean => def.lightmap ?? !movesByPhysics(def)
+export const isLightmapStatic = (def: SceneNodeDef): boolean => def.lightmap !== undefined ? def.lightmap !== false : !movesByPhysics(def)
 
 /** A terrain node: from its file or a fresh flat grid; textures load before the node appears (like a
  *  mesh's material). Stamps and holes apply later in buildNodes, once every target node exists. */
@@ -905,7 +919,8 @@ const buildNodes = async (
     // the path is derived from def keys BEFORE any await, so it is deterministic even though
     // Promise.all makes build completion (and record insertion) order nondeterministic
     const path = parentPath === "" ? name : `${parentPath}/${name}`
-    const lmStatic = lm !== null && (nd.lightmap ?? (!parentMoves && isLightmapStatic(nd)))
+    const lmStatic = lm !== null && (nd.lightmap !== undefined ? nd.lightmap !== false : !parentMoves && isLightmapStatic(nd))
+    const lmCube = lmStatic && (nd.lightmap === "cube" || lm!.cube === true)
     // a mover in a level with a light volume reads the volume (models: the engine binds it; meshes: registered below)
     const node = await createSource(path, nd, lmStatic)
     // a `mount` def parents to an internal part of the parent asset — safe here: the parent's
@@ -914,13 +929,13 @@ const buildNodes = async (
     // Draw-set membership is separate from parenting (see docs/3d/node.md) — every def node joins.
     scene.add(node)
     applyNode(node, name, nd)   // engine-side name stays the bare sibling segment
-    if (lmStatic && (node instanceof Model || node instanceof Mesh)) Lightmap._register(node, lm!.prefix + path)
-    else if (lmStatic && nd.terrain !== undefined) Lightmap._registerGround(node, lm!.prefix + path)
+    if (lmStatic && (node instanceof Model || node instanceof Mesh)) Lightmap._register(node, lm!.prefix + path, lmCube)
+    else if (lmStatic && nd.terrain !== undefined) Lightmap._registerGround(node, lm!.prefix + path, lmCube)
     // the top of a moving subtree: everything under it reads the level's light grid (Lightmap.track walks it at load)
     if (lm !== null && !lmStatic && !parentMoves) moverRoots.push(node)
     if (EDITOR && isEditMode()) addEditorMarker(node, nd)
     // a prefab under a static wrapper bakes; under a mover its internals stay movers (volume-lit)
-    if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack, lmStatic ? { prefix: `${lm!.prefix}${path}/` } : null)
+    if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack, lmStatic ? { prefix: `${lm!.prefix}${path}/`, cube: lmCube } : null)
     pending.push({ path, node, def: nd })
     nodes[path] = node
     await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node, path, parentMoves || (lm !== null && !lmStatic))))
@@ -1020,8 +1035,8 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
 
   // the level is complete: apply the bake — or, under `lecodes lightmap bake`, run it
   if (lm && lightmap) {
-    await Lightmap.load(scene, { data: lightmap.data, light: lightmap.light, aux: lightmap.aux, direct: lightmap.direct, indirect: lightmap.indirect, probes: lightmap.probes, volume: lightmap.volume },
-                        { lightScale: lightmap.lightScale, emissiveNits: lightmap.emissiveNits, emissiveBake: lightmap.emissiveBake, transmit: lightmap.transmit })
+    await Lightmap.load(scene, { data: lightmap.data, light: lightmap.light, aux: lightmap.aux, direct: lightmap.direct, indirect: lightmap.indirect, probes: lightmap.probes, volume: lightmap.volume, uv1: lightmap.uv1 },
+                        { lightScale: lightmap.lightScale, emissiveNits: lightmap.emissiveNits, emissiveBake: lightmap.emissiveBake, transmit: lightmap.transmit, cube: lightmap.cube })
   }
   // navigation: load the baked mesh — or, under `lecodes navmesh bake`, dump the level's collision
   // geometry for it (the static bodies exist by now; edit mode never loads it — v1)

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.4.5"
+export const SDK_VERSION = "2.4.7"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {