lecodes-sdk 2.4.7 → 2.4.9

package/src/gl/ReflectionProbe.ts

@@ -0,0 +1,141 @@
+// A reflection probe: a cube of the scene's light drawn around a point, live (creator-gl renderview.cpp: a render view of
+// six faces into an HDR cube render texture; with PREFILTER, Filament's libs/iblprefilter filter after each completed
+// cube). A Node, placed and parented like any; its view starts once the node is in a scene (Node.ts awaitScene) — or at
+// `scene.environment = probe` while it is in none. RenderTexture.ts holds the half it shares with a secondary Camera.
+
+import { Node, awaitScene } from "./Node"
+import { CAMERA_DEFAULTS } from "./Camera"
+import {
+  RenderTexture, RT_FLAG_CUBEMAP, RT_FLAG_HDR, RT_FLAG_PREFILTER, RT_MAX_SIDE, makeRenderTexture, requireRenderTextures, startRenderView,
+} from "./RenderTexture"
+
+/** `new ReflectionProbe(options)`: the cube, what its view draws, and how often. */
+export type ReflectionProbeOptions = {
+  /** The cube's edge, texels per face side (default 128): a power of two, 16..4096, when prefiltered; 1..4096 otherwise.
+   *  A probe is light, not a picture — 64..128 is plenty for a car's reflections. */
+  size?: number
+  /** The layers its view draws, a bit mask over `Node.layer` (default 0xff = everything): leave out the probe's own
+   *  carrier, or the cube is the inside of the car it rides on. Fixed. */
+  layers?: number
+  /** Shadows in its view (default `false`): with them, a full cube renders its own shadow maps six times. Fixed. */
+  shadows?: boolean
+  /** Faces drawn per render, 1..6, round-robin (default 6 = the whole cube) — `probe.facesPerFrame`. */
+  facesPerFrame?: number
+  /** Render once every N frames drawn (default 1 = every frame) — `probe.everyNth`. */
+  everyNth?: number
+  /** Filter the cube for ROUGHNESS (default `true`; `size` a power of two then). Without it the cube has one sharp level:
+   *  under `scene.environment` only mirror-like surfaces (roughness near 0) are right, and the diffuse ambient stays the
+   *  scene's own probe's. With it the GPU filters every completed cube into five roughness levels — a brushed or painted
+   *  body shows its surroundings blurred as much as its roughness says — and the roughest level becomes the diffuse
+   *  ambient: what the probe sees lights matte surfaces too (a red wall tints them red).
+   *
+   *  COST: one filtering per completed cube (every render at `facesPerFrame` 6, every third at 2), on the frame after:
+   *  the cube's mip chain plus a pass per level whose taps are the level's texels × `samples` — for a 64 cube at the
+   *  default 256 samples about 2 million cube taps — and ten small driver submissions on the CPU. `everyNth` /
+   *  `facesPerFrame` space the filterings out. Fixed. */
+  prefilter?: boolean
+  /** The filter's samples per texel, 1..2048 (default 256 — a quarter of Filament's offline default: each sample reads
+   *  the mip that matches its footprint, which keeps a low count smooth; raise it if a mid-roughness surface reads
+   *  blotchy). Smoothness for time; read with `prefilter` only. */
+  samples?: number
+  /** Near clip plane in metres (default 0.01). Fixed. */
+  near?: number
+  /** Far clip plane in metres (default 1000). Fixed. */
+  far?: number
+}
+
+/**
+ * A REFLECTION PROBE: a cube of the scene's light drawn around a point, live — chrome and glass show what is actually
+ * around them, moving objects included. A Node: place it, or parent it (`car.add(probe)` — it rides along); the six faces
+ * look along the world axes from its WORLD position (its rotation and scale are ignored). It draws once it is in a scene
+ * (added to one, or under a node that is), every frame that scene is on show — after the frame's update passes, before
+ * the scene's own picture — in linear HDR light (no tone mapping) at the scene camera's exposure. It sees the scene's
+ * renderables, lights, environment and sky, not its overlays.
+ *
+ * Two ways to use it:
+ *  - `scene.environment = probe`: the scene's reflections come from the cube instead of the scene's own probe
+ *    (`SceneOptions.ibl`) — and, prefiltered (the default), its diffuse ambient too. A probe in no scene yet starts in
+ *    that one.
+ *  - `probe.texture` in a material that samples a cube itself (a custom shader's samplerCubemap): the same cube as a
+ *    `RenderTexture` — when prefiltered, the filtered one, five roughness levels.
+ *
+ * COST: a full render is six passes over the scene, plus (prefiltered) a GPU filtering per completed cube (`prefilter`
+ * says what one costs). Keep `size` small (128 is a lot), spread the cube over frames (`facesPerFrame: 2` = a whole cube
+ * every 3 frames, a third of the cost each), render less often (`everyNth`), leave out what it need not see (`layers` —
+ * its carrier first), keep `shadows` off, and turn it off once a static surrounding is drawn (`enabled = false` keeps the
+ * last cube).
+ *
+ * LIFETIME: the cube and its view live as long as the probe — keep a reference (`scene.environment` holds it too).
+ * Destroying the probe's node stops the view (the cube keeps its last light); moving it to another scene later does not
+ * move the view. Throws on a host without render textures (`createRenderTexture` — the web hosts, for now).
+ */
+export class ReflectionProbe extends Node {
+  /** The cube the probe draws (`cubemap`, linear HDR light) — the filtered one, five roughness levels, when `prefilter`. */
+  readonly texture: RenderTexture
+  /** Filtered for roughness (the `prefilter` option). */
+  readonly prefilter: boolean
+  /** @internal The render view's owned handle (`_view.id` = the engine's view id), null until the view starts: it lives
+   *  exactly as long as this probe holds it. */
+  _view: Handle | null = null
+  private readonly _layers: number
+  private readonly _shadows: boolean
+  private readonly _near: number
+  private readonly _far: number
+  private _enabled = true
+  private _everyNth: number
+  private _facesPerFrame: number
+
+  constructor(options: ReflectionProbeOptions = {}) {
+    requireRenderTextures("new ReflectionProbe")
+    const size = Math.max(1, Math.floor(options.size ?? 128))
+    const prefilter = options.prefilter !== false
+    if (prefilter && (size < 16 || size > RT_MAX_SIDE || (size & (size - 1)) !== 0)) {
+      throw new Error(`new ReflectionProbe: a prefiltered probe's size is a power of two, 16..${RT_MAX_SIDE} (got ${size}) — or prefilter: false`)
+    }
+    super()
+    const samples = prefilter ? Math.max(0, Math.floor(options.samples ?? 0)) : 0
+    this.texture = makeRenderTexture("new ReflectionProbe", size, size, RT_FLAG_CUBEMAP | RT_FLAG_HDR | (prefilter ? RT_FLAG_PREFILTER : 0), samples)
+    this.prefilter = prefilter
+    this._layers = (options.layers ?? 0xff) & 0xff
+    this._shadows = options.shadows === true
+    this._near = options.near ?? CAMERA_DEFAULTS.near
+    this._far = options.far ?? CAMERA_DEFAULTS.far
+    this._everyNth = Math.max(1, Math.floor(options.everyNth ?? 1))
+    this._facesPerFrame = Math.min(6, Math.max(1, Math.floor(options.facesPerFrame ?? 6)))
+    awaitScene(this)
+  }
+
+  /** @internal Node.ts awaitScene / Scene.environment: the probe is in scene `sceneId` — start its view into its cube. */
+  _bindView(sceneId: number): void {
+    if (this._view) return
+    this._view = startRenderView("ReflectionProbe", sceneId, this.texture, this.id, this._layers, 90, this._near, this._far, this._shadows)
+    if (this._view && (!this._enabled || this._everyNth !== 1 || this._facesPerFrame !== 6)) this._sendSchedule()
+  }
+
+  /** Whether the probe draws (default `true`). Off keeps the last cube and costs nothing — a probe that has drawn its
+   *  static surroundings once; back on, it renders on the next frame drawn. */
+  get enabled(): boolean { return this._enabled }
+  set enabled(on: boolean) {
+    this._enabled = on
+    this._sendSchedule()
+  }
+  /** Render once every N frames DRAWN (default 1 = every frame). The count restarts with each change: the next frame
+   *  drawn renders, then one in every N. */
+  get everyNth(): number { return this._everyNth }
+  set everyNth(n: number) {
+    this._everyNth = Math.max(1, Math.floor(n))
+    this._sendSchedule()
+  }
+  /** The cube's faces drawn per render, 1..6 (default 6), round-robin from where the last render stopped: 2 spreads a
+   *  whole cube over 3 renders at a third of the cost each. A prefiltered cube is filtered each time it completes. */
+  get facesPerFrame(): number { return this._facesPerFrame }
+  set facesPerFrame(n: number) {
+    this._facesPerFrame = Math.min(6, Math.max(1, Math.floor(n)))
+    this._sendSchedule()
+  }
+
+  /** @internal Send the whole schedule (`setRenderViewOptions` restarts the count, so the next frame drawn renders). */
+  private _sendSchedule(): void {
+    if (this._view) _creator.setRenderViewOptions?.(this._view.id, this._enabled, this._everyNth, this._facesPerFrame)
+  }
+}

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/host.d.ts

@@ -1,9 +1,11 @@
 // JS-runtime globals provided by the host engine (web viewer / desktop / iOS), NOT by the SDK.
 // Declared only so SDK and user code type-check — never bundled or injected.
 
-// The one SDK type the macros return: an SVG image source, the same `SvgSource` a project has as
-// a global (build-types.ts points this import into dist/types when it copies the file).
+// The SDK types the macros return: an SVG image source, the same `SvgSource` a project has as a
+// global, and the lightmap def `bake()` compiles to (build-types.ts points these imports into
+// dist/types when it copies the file).
 import type { SvgSource } from "./runtime/misc"
+import type { LightmapDef, LightmapOptions } from "./gl/Lightmap"
 
 declare global {
   /** As in the browser, but the delay is REQUIRED (the native runtime throws without it) and no
@@ -50,6 +52,15 @@ declare global {
    *  comments and string literals are text, not macros. */
   function asset(path: string): string
 
+  /** THE LEVEL'S BAKE: `lecodes lightmap bake` writes `<stem>.bake` (a JSON manifest) and the files it names next to
+   *  it. Compile-time macro: the manifest is read, every file it names is staged, and the call becomes the literal
+   *  `Lightmap.load` takes — `env: { lightmap: bake('./assets/lightmap/level.bake') }` in a scene file. The path is a
+   *  string literal, relative to the file that calls it (`./`, `../`), else to the project root. No file yet →
+   *  `{ data: null, path }`: the level runs unbaked and says so; under `lecodes lightmap bake` this is the target the
+   *  bake writes. A file the manifest names that is missing fails the compile. `options` (an object literal, copied
+   *  as written) are the level's bake / load options. */
+  function bake(path: `${string}.bake`, options?: LightmapOptions): LightmapDef
+
   /** Compile-time macro: installs a font and returns its family name — using a font IS declaring
    *  it. A registry id (`font("manrope")`) resolves against the font registry; a project path
    *  (`font("./fonts/Brand.ttf")`) reads family/weight/italic from the file itself. `opts`

package/src/inject.ts

@@ -233,6 +233,7 @@ export type { DynamicBoneCurve, DynamicBoneFloor, DynamicBoneColliders } from ".
 export type { IKTwoBone, IKLookAt } from "./gl/animation/IK"
 export { Light } from "./gl/Light"
 export { Lightmap } from "./gl/Lightmap"
+export type { LightmapDef, LightmapFiles, LightmapOptions, LightmapTransmit } from "./gl/Lightmap"
 export { Foliage } from "./gl/Foliage"
 export type { FoliageOptions, FoliageWind } from "./gl/Foliage"
 export { Terrain } from "./gl/terrain/Terrain"
@@ -251,7 +252,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/scene/defineScene.ts

@@ -52,11 +52,11 @@ import { Mesh } from "../gl/Mesh"
 import { Model } from "../gl/Model"
 import { Physics } from "../gl/physics/Physics"
 import { CharacterController } from "../gl/physics/CharacterController"
-import { Lightmap, type LightmapTransmit } from "../gl/Lightmap"
+import { Lightmap, type LightmapDef } from "../gl/Lightmap"
 import { Foliage, type FoliageOptions } from "../gl/Foliage"
 import { NavMesh } from "../gl/nav/NavMesh"
 import { Terrain, type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/terrain/Terrain"
-import { Light, type SunOptions } from "../gl/Light"
+import { Light, type PointOptions, type SpotOptions, type SunOptions } from "../gl/Light"
 import { Material } from "../gl/Material"
 import { assignMaterialDef, MaterialHandle, resolveMaterialDef, type MaterialDef } from "./material"
 import type { CapsuleOptions, CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
@@ -71,7 +71,13 @@ export type MeshDef =
   | ({ kind: "capsule" } & CapsuleOptions)
   | ({ kind: "plane" } & PlaneOptions)
 
-export type LightDef = { kind: "sun" } & SunOptions
+/** The `light: {}` source block, by `kind` — `Light.sun` / `Light.point` / `Light.spot` with the node's transform: a
+ *  point light's `bakeArea` panel lies in the node's local XZ plane and emits along its local -Y, so `eulerAngles`
+ *  tilts it; a spot shines along the node's -Z (`direction` aims it, as a sun's does). */
+export type LightDef =
+  | ({ kind: "sun" } & SunOptions)
+  | ({ kind: "point" } & PointOptions)
+  | ({ kind: "spot" } & SpotOptions)
 
 /** A stamp: the terrain conforms to another node of this file (a road) at load — see Terrain.conform. */
 export type TerrainStampDef = {
@@ -192,7 +198,7 @@ export type SceneNodeDef = {
    *  `'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`. */
+   *  kit: the `cube` option of `env.lightmap`'s `bake()`. */
   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
@@ -215,55 +221,6 @@ export type SceneCameraDef = CameraProjectionDef & {
   target?: Vec3Like
 }
 
-/** `env.lightmap` — the level's baked lighting (engines/bake): the files `lecodes lightmap bake`
- *  writes. Absent = real-time only. */
-export type SceneLightmapDef = {
-  /** `asset('./assets/lightmap/level.bake')` */
-  data: string
-  /** `asset('./assets/lightmap/level-light.ktx2')` — or, for a bake that took more than one atlas PAGE
-   *  (`lecodes lightmap bake --pages`), every page in order: `[asset('x-light.ktx2'), asset('x-light_1.ktx2')]`. */
-  light: string | string[]
-  /** `asset('./assets/lightmap/level-aux.ktx2')` (pages like `light`) — sun / sky visibility + light direction. */
-  aux: string | string[]
-  /** DEBUG: the page sets a `lecodes lightmap bake --split` wrote (`<stem>-direct[_n].ktx2`, `<stem>-indirect[_n].ktx2`),
-   *  pages like `light` — the `Lightmap.debug("direct" | "indirect")` views bind them in place of `light`. */
-  direct?: string | string[]
-  indirect?: string | string[]
-  /** `asset('./assets/lightmap/level-probes.ktx2')` — the bake's reflection probes (one prefiltered cubemap of the level's
-   *  radiance per probe; every static reflects the nearest). Absent = statics reflect the sky's SH alone. */
-  probes?: string
-  /** FOR THE BAKE: the radiance in cd / m² of emission 1.0 on this level (emissive factor x strength x map) - every lit
-   *  region of an emissive surface bakes as a rectangle lamp. An imported pack's emission is a LOOK (the school's panels
-   *  say 10); this is where the level says what they give: a 1.3 m ceiling panel of ~8000 lm is ~1600 nits. Default: what
-   *  the camera makes of 1.0 (`1.2 x 2^EV100`). 0 = emissive surfaces light nothing. `--emissive-nits` overrides. */
-  emissiveNits?: number
-  /** `false` = the emissive surfaces light nothing in the bake - the level is lit by its lamps (`Light.point` with a
-   *  `bakeArea` next to every panel, the Unity packs' way) and the panels are decoration; `emissiveNits` then only says how
-   *  bright their glow is DRAWN (scene-referred: nits through the camera's exposure). Default true. */
-  emissiveBake?: boolean
-  /** FOR THE BAKE: materials that let light THROUGH them, by glTF material name (`"name*"` = every name with that start) →
-   *  the share of a shadow ray that passes, tinted by the material's base colour x map: `{ mat_awning: 0.3 }` puts the
-   *  awning's warm, patterned light on the sand. The surface stays opaque - baked, drawn as before, a shadow caster.
-   *  `{ 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
-}
-
 /** `env.navmesh` — the level's navigation mesh (see navmesh.md): the file `lecodes navmesh bake`
  *  writes, the agent size it is built for, and the named areas. Absent = no navigation. */
 export type SceneNavmeshDef = {
@@ -276,7 +233,9 @@ export type SceneNavmeshDef = {
 }
 
 export type SceneDef = {
-  env?: SceneOptions & { lightmap?: SceneLightmapDef, navmesh?: SceneNavmeshDef, foliage?: FoliageOptions }
+  /** `lightmap` = the level's baked lighting (engines/bake): `bake('./assets/lightmap/level.bake', { …options })`, the
+   *  macro that reads the bake's manifest at compile time (`LightmapDef`). Absent = real-time only. */
+  env?: SceneOptions & { lightmap?: LightmapDef, navmesh?: SceneNavmeshDef, foliage?: FoliageOptions }
   camera?: SceneCameraDef
   nodes?: Record<string, SceneNodeDef>
 }
@@ -503,12 +462,23 @@ export const createSource = (path: string, def: SceneNodeDef, lightmap: boolean)
   if (def.model !== undefined) return loadModel(def.model, lightmap, !!def.foliage)
   if (def.mesh !== undefined) return createMesh(def.mesh, def.material)
   if (def.terrain !== undefined) return createTerrain(def.terrain, lightmap)
-  if (def.light !== undefined) { const { kind: _k, ...opts } = def.light; return Light.sun(opts) }
+  if (def.light !== undefined) return createLight(path, def.light)
   // make/prefab/camera/group nodes are plain wrappers — make/prefab subtrees mount under them
   // during the build (attachPrefab) or in phase 2 (attachMake); a camera node drives scene.camera
   return new Node()
 }
 
+/** A `light:` block by its kind. The node IS the light: its transform (applyNode) aims a sun / spot and turns a
+ *  point light's `bakeArea` panel (local XZ, emitting along local -Y). */
+const createLight = (path: string, def: LightDef): Light => {
+  switch (def.kind) {
+    case "sun": { const { kind: _k, ...opts } = def; return Light.sun(opts) }
+    case "point": { const { kind: _k, ...opts } = def; return Light.point(opts) }
+    case "spot": { const { kind: _k, ...opts } = def; return Light.spot(opts) }
+  }
+  throw new Error(`Scene node "${path}": light kind "${String((def as { kind?: unknown }).kind)}" is not sun, point or spot`)
+}
+
 /** Edit mode: play the preview pose on a model node (`editor: { clip, time }`) — idempotent, the
  *  harness re-applies it on inspector edits. No clip = back to the rest pose. */
 export const applyEditorPose = (node: Node, pose: { clip?: string, time?: number } | undefined): void => {
@@ -1034,10 +1004,7 @@ 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, uv1: lightmap.uv1 },
-                        { lightScale: lightmap.lightScale, emissiveNits: lightmap.emissiveNits, emissiveBake: lightmap.emissiveBake, transmit: lightmap.transmit, cube: lightmap.cube })
-  }
+  if (lm && lightmap) await Lightmap.load(scene, lightmap)
   // 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)
   if (navmesh && !(EDITOR && isEditMode())) {

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