lecodes-sdk 2.4.6 → 2.4.8

package/src/gl/RenderTexture.ts

@@ -0,0 +1,93 @@
+// A texture a render view draws into (creator-gl renderview.cpp; creator.h createRenderTexture / createRenderView /
+// setRenderViewOptions / setRenderViewProjection / readRenderTexturePixels). Only the texture: the view drawing into it
+// belongs to what made it — a secondary Camera (`camera.renderToTexture`, a 2D picture) or a ReflectionProbe (a cube) —
+// which holds the view's owned handle, its schedule and its projection. The helpers below are those two makers' shared
+// half: the host's texture, and the view started once their node is in a scene (Node.ts awaitScene).
+
+import { Texture } from "./Texture"
+
+/** @internal `_creator.createRenderTexture` flags (creator.h CREATOR_RENDER_TEXTURE_*). */
+export const RT_FLAG_CUBEMAP = 1
+/** @internal */
+export const RT_FLAG_HDR = 2
+/** @internal */
+export const RT_FLAG_PREFILTER = 4
+/** @internal `_creator.createRenderView` flags bit: no shadow maps in this view (creator.h CREATOR_RENDER_VIEW_SHADOWS_OFF). */
+const VIEW_FLAG_SHADOWS_OFF = 1
+/** @internal The longest side the host takes (creator.h createRenderTexture). */
+export const RT_MAX_SIDE = 4096
+
+/**
+ * A texture a render view draws into — made by `camera.renderToTexture({ width, height })` (a 2D picture: the
+ * tone-mapped image as the screen would show it) or by a `ReflectionProbe` (`probe.texture`: a cube of linear HDR light).
+ * It IS a `Texture`: a 2D one goes wherever an image does (`material.map` — a monitor, a rear-view mirror), a cube
+ * wherever a cubemap does (`scene.environment` takes the probe itself).
+ *
+ * ROW ORDER: a 2D render texture's first texel row is the BOTTOM of the camera's picture (OpenGL's order, on every
+ * backend) — an image's first row is its top. A mesh whose v runs UP its face (`Mesh.plane`) shows it upright as is; one
+ * laid out like a glTF (v down) samples it with v flipped. A cube face is laid out as every GPU's cube lookup reads it.
+ *
+ * LIFETIME: the texture lives while something holds it — the camera or probe that made it (each keeps its texture), a
+ * material showing it — and keeps its last picture when its view stops (`enabled = false`, the camera's next
+ * `renderToTexture`, the camera gone).
+ */
+export class RenderTexture extends Texture {
+  /** A cube (a `ReflectionProbe`'s) rather than a 2D picture (a `Camera`'s). A cube's `width` and `height` are both its
+   *  edge. */
+  readonly cubemap: boolean
+
+  /** @internal Made by `Camera.renderToTexture` and `ReflectionProbe` (through `makeRenderTexture`): the size, the
+   *  kind and the texture's owned handle. */
+  constructor(width: number, height: number, cubemap: boolean, texture: Handle) {
+    super(width, height, texture)
+    this.cubemap = cubemap
+  }
+
+  /**
+   * RGBA8 bytes (`width × height × 4`) of a rectangle of the texture as the NEXT frame drawn leaves it — a GPU
+   * readback, for checks and tools, not a per-frame path. Rows come in the texture's own order: the first is texel row
+   * `y`, which for a 2D texture counts from the picture's BOTTOM. `face` 0..5 = +X −X +Y −Y +Z −Z of a cube (0 for a 2D
+   * picture). A camera's (LDR) texture gives its stored sRGB bytes, a probe's (HDR) its linear light clamped to 0..1 —
+   * a prefiltered probe its sharpest level. Rejects on a host without the call, or when the host refuses the read (the
+   * rectangle outside the texture, the engine gone first).
+   */
+  readPixels(x: number, y: number, width: number, height: number, face = 0): Promise<Uint8Array> {
+    if (!_creator.readRenderTexturePixels) return Promise.reject(new Error("RenderTexture.readPixels: this host has no readRenderTexturePixels"))
+    return new Promise<Uint8Array>((resolve, reject) => {
+      _creator.readRenderTexturePixels!(this._h.id, face, x, y, width, height, (pixels) => {
+        if (pixels) resolve(pixels)
+        else reject(new Error(`RenderTexture.readPixels: the host refused (${x}, ${y}) ${width}×${height} of face ${face}`))
+      })
+    })
+  }
+}
+
+/** @internal Throw for `who` on a host without render textures (createRenderTexture + createRenderView). */
+export const requireRenderTextures = (who: string): void => {
+  if (!_creator.createRenderTexture || !_creator.createRenderView) {
+    throw new Error(`${who}: this host has no render textures (createRenderTexture) — the web hosts do not yet`)
+  }
+}
+
+/** @internal The host's render texture (`flags` RT_FLAG_*; a cube's `height` is its `width`), or a throw naming `who`. */
+export const makeRenderTexture = (who: string, width: number, height: number, flags: number, samples = 0): RenderTexture => {
+  requireRenderTextures(who)
+  const cube = (flags & RT_FLAG_CUBEMAP) !== 0
+  const texture = _creator.createRenderTexture!(width, cube ? 0 : height, flags, samples)
+  if (!texture || texture.id === 0xFFFFFFFF) {
+    throw new Error(`${who}: the host refused a ${cube ? `cube of ${width}` : `${width}×${height}`} render texture (sides 1..${RT_MAX_SIDE})`)
+  }
+  return new RenderTexture(width, cube ? width : height, cube, texture)
+}
+
+/** @internal Start a render view of scene `sceneId` into `texture` from entity `poseId` (createRenderView), or warn for
+ *  `who` and give null — the host refuses an overlay scene. */
+export const startRenderView = (
+  who: string, sceneId: number, texture: RenderTexture, poseId: number,
+  layers: number, fov: number, near: number, far: number, shadows: boolean,
+): Handle | null => {
+  const view = _creator.createRenderView!(sceneId, texture._h.id, poseId, layers & 0xff, fov, near, far, shadows ? 0 : VIEW_FLAG_SHADOWS_OFF)
+  if (view && view.id !== 0) return view
+  console.warn(`[${who}] the host made no render view in scene ${sceneId} (an overlay scene has none) — its texture stays empty`)
+  return null
+}

package/src/gl/Scene.ts

@@ -18,8 +18,9 @@ import { Camera } from "./Camera"
 import { SceneAudio } from "./audio/SceneAudio"
 import { Material } from "./Material"
 import { PostProcessing, type PostProcessingOptions } from "./postProcessing"
+import { ReflectionProbe } from "./ReflectionProbe"
 import { Texture } from "./Texture"
-import { Node, nodes } from "./Node"
+import { Node, bindPendingViews, nodes, sceneIdOf } from "./Node"
 import { glState } from "./state"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
 
@@ -176,6 +177,12 @@ export class Scene implements Presentable {
   /** @internal what `environmentIntensity` currently asks for — the accessor's backing field, so it
    *  answers on hosts whose engine has no live setter too. */
   _environmentIntensity = 20000
+  /** @internal The probe the constructor named for `setDefaultIbl` (-1 = none: the project-wide
+   *  `ibl.ktx`) — re-sent when `environment` goes back to null. */
+  _iblId = -1
+  /** @internal What `environment` lights the scene from (null = the scene's own probe). Holding it
+   *  keeps the probe — its cube and the view drawing into it — alive while it lights. */
+  _environment: ReflectionProbe | null = null
   readonly camera: Camera
   /** The listener + global 3D audio knobs (docs/audio-plan.md). */
   readonly audio: SceneAudio = new SceneAudio()
@@ -226,6 +233,7 @@ export class Scene implements Presentable {
       // "no probe named", which leaves the host on the project-wide `ibl.ktx` (the old behaviour).
       const src = typeof options.ibl === "string" ? options.ibl : undefined
       const iblId = src === undefined ? -1 : src.startsWith("id:") ? Number(src.slice(3)) : _creatorFetch.local(src)
+      this._iblId = iblId
       _creator.setDefaultIbl(this._id, options.environmentIntensity ?? 20000, iblId)
     }
     this._environmentIntensity = options.ibl === false ? 0 : (options.environmentIntensity ?? 20000)
@@ -341,6 +349,44 @@ export class Scene implements Presentable {
     }
   }
   private static _warnedEnvIntensity = false
+
+  /**
+   * Light the scene from a live REFLECTION PROBE (ReflectionProbe.ts) — a cube drawn around the probe's position, the
+   * probe riding the car / standing in the room: chrome and glass show what is actually around them, moving objects
+   * included. `null` gives the light back to the scene's own probe (`SceneOptions.ibl`, at `environmentIntensity`;
+   * re-installing it reloads the probe — a switch, not a per-frame call). A probe in no scene yet starts its view in this
+   * one; one already in another scene draws only while that scene is on show.
+   *
+   * Prefiltered (the default), the probe gives the reflections at every roughness — a car body, painted metal blur it as
+   * they should — and the diffuse ambient too (then `environmentIntensity` no longer changes it); it costs a GPU
+   * filtering per completed cube (`ReflectionProbeOptions.prefilter`). `prefilter: false` gives one sharp level:
+   * mirror-like surfaces (roughness near 0) are right, rougher ones read the sharp cube too, and only the reflections
+   * change — the diffuse ambient keeps the scene's own probe's shape at `environmentIntensity`.
+   *
+   * A probe that draws while it lights reads what it writes — fine on OpenGL; a Vulkan backend may want two probes in
+   * turn (a prefiltered probe never does: it lights from the filtered copy). Leave the probe's own carrier out of its view
+   * (`layers`), or the cube is the inside of the car. Warns once on a host without the call.
+   */
+  get environment(): ReflectionProbe | null { return this._environment }
+  set environment(probe: ReflectionProbe | null) {
+    if (probe !== null && !(probe instanceof ReflectionProbe)) {
+      throw new Error("scene.environment: a ReflectionProbe (new ReflectionProbe({ size: 128 })) or null")
+    }
+    if (probe === this._environment) return
+    this._environment = probe
+    if (probe && sceneIdOf(probe) < 0) probe._bindView(this._id)   // in no scene yet: its view starts in this one
+    if (!_creator.setEnvironmentTexture) {
+      if (!Scene._warnedEnvTexture) {
+        Scene._warnedEnvTexture = true
+        console.warn("[scene] this host has no setEnvironmentTexture — environment stays the scene's own probe")
+      }
+      return
+    }
+    if (probe) _creator.setEnvironmentTexture(this._id, probe.texture._h.id)
+    else _creator.setDefaultIbl(this._id, this._environmentIntensity, this._iblId)   // installing a probe frees the cube's light
+  }
+  private static _warnedEnvTexture = false
+
   /** The scene's stencil buffer on / off (see `SceneOptions.stencil`). */
   setStencil(enabled: boolean): void {
     if (_creator.setSceneStencil) _creator.setSceneStencil(this._id, enabled)
@@ -348,12 +394,18 @@ export class Scene implements Presentable {
   }
 
   add(...list: Node[]): this {
-    for (const n of list) { _creator.addEntityToScene(this._id, n.id); nodes.pin(n) }   // the scene owns it now
+    for (const n of list) {
+      _creator.addEntityToScene(this._id, n.id)
+      nodes.pin(n)          // the scene owns it now
+      n._inScene = this._id // what a render view under it starts in (Node.ts sceneIdOf)
+    }
+    bindPendingViews()
     return this
   }
   remove(...list: Node[]): this {
     for (const n of list) {
       _creator.removeEntityFromScene(this._id, n.id)
+      if (n._inScene === this._id) n._inScene = -1
       if (!_creator.entityIsOwned(n.id)) nodes.unpin(n.id)   // loose again: its handle owns it
     }
     return this

package/src/inject.ts

@@ -251,7 +251,11 @@ export type { ScatterPlacement, ScatterOptions } from "./gl/Scatter"
 export type { InstanceTransform } from "./gl/InstancedMesh"
 export { Texture } from "./gl/Texture"
 export type { TextureLoadOptions } from "./gl/Texture"
+export { RenderTexture } from "./gl/RenderTexture"
 export { Camera } from "./gl/Camera"
+export type { CameraOptions, RenderToTextureOptions } from "./gl/Camera"
+export { ReflectionProbe } from "./gl/ReflectionProbe"
+export type { ReflectionProbeOptions } from "./gl/ReflectionProbe"
 export { Ray } from "./gl/Ray"
 export { Plane } from "./gl/Plane"
 export { Noise } from "./gl/Noise"

package/src/math/vec.ts

@@ -1,6 +1,6 @@
 // Fluent 2D / 3D vectors — the SDK's user-facing vector math (no gl-matrix, no out-params, no imports).
 //
-// Design (see PLAN.md): a vector is a *mutable little struct* — `v.x = 3`, `v.set(x, y, z)` mutate in
+// Design: a vector is a *mutable little struct* — `v.x = 3`, `v.set(x, y, z)` mutate in
 // place — but every *method* is PURE: `a.add(b)` returns a NEW vector and never touches `a`. So chains
 // (`dir.normalize().scale(s)`) can't clobber their source, and the immutable-method style is the most
 // amenable to a future escape-analysis / scalar-replacement compiler pass. Backing is plain number

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/ui/tree.ts

@@ -93,6 +93,7 @@ export const OWNED_KIND_ENTITY_2D = 5
 export const OWNED_KIND_MEDIA = 6
 export const OWNED_KIND_TWEEN = 7
 export const OWNED_KIND_CANVAS = 8
+export const OWNED_KIND_GL_RENDER_VIEW = 9
 
 // PanDirection (creator-pkg.h) — the low byte of a track answer.
 import { DEAD_HANDLE } from "../core/pins"

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.6"
+export const SDK_VERSION = "2.4.8"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {