lecodes-sdk 2.4.7 → 2.4.9

package/dist/global.d.ts

@@ -102,6 +102,8 @@ declare global {
   const RTCVideoView: typeof SDK.RTCVideoView
   const Ragdoll: typeof SDK.Ragdoll
   const Ray: typeof SDK.Ray
+  const ReflectionProbe: typeof SDK.ReflectionProbe
+  const RenderTexture: typeof SDK.RenderTexture
   const Replicated: typeof SDK.Replicated
   const Router: typeof SDK.Router
   const RpcError: typeof SDK.RpcError
@@ -293,6 +295,7 @@ declare global {
   type CameraFollow = SDK.CameraFollow
   type CameraMove = SDK.CameraMove
   type CameraNodeDef = SDK.CameraNodeDef
+  type CameraOptions = SDK.CameraOptions
   type CameraPlace = SDK.CameraPlace
   type CameraView = SDK.CameraView
   type Canvas = SDK.Canvas
@@ -387,6 +390,10 @@ declare global {
   type Light = SDK.Light
   type LightDef = SDK.LightDef
   type Lightmap = SDK.Lightmap
+  type LightmapDef = SDK.LightmapDef
+  type LightmapFiles = SDK.LightmapFiles
+  type LightmapOptions = SDK.LightmapOptions
+  type LightmapTransmit = SDK.LightmapTransmit
   type LineLayer = SDK.LineLayer
   type LineLayerOptions = SDK.LineLayerOptions
   type LitMaterialDef = SDK.LitMaterialDef
@@ -521,6 +528,10 @@ declare global {
   type RecordOptions = SDK.RecordOptions
   type RecorderState = SDK.RecorderState
   type Recording = SDK.Recording
+  type ReflectionProbe = SDK.ReflectionProbe
+  type ReflectionProbeOptions = SDK.ReflectionProbeOptions
+  type RenderTexture = SDK.RenderTexture
+  type RenderToTextureOptions = SDK.RenderToTextureOptions
   type Replicated = SDK.Replicated
   type Resource<T> = SDK.Resource<T>
   type ReverbParams = SDK.ReverbParams

package/dist/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 "./types/runtime/misc"
+import type { LightmapDef, LightmapOptions } from "./types/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/dist/types/gl/Camera.d.ts

@@ -1,26 +1,61 @@
 import { Vec3 } from "../math/vec";
 import { Node, type NodeTweenProps } from "./Node";
 import { Ray } from "./Ray";
+import { RenderTexture } from "./RenderTexture";
 import { type TweenMeta } from "../animate/tween/spec";
 import type { Animation } from "../animate/tween/Animation";
-/** Animatable camera props on top of the node transform. */
+/** Animatable camera props on top of the node transform. `fov` / `near` / `far` are the SCENE camera's: on a secondary
+ *  camera they throw (set them directly — they are live — or from `animate({ onUpdate })`). */
 export type CameraTweenProps = NodeTweenProps & {
     fov?: number | number[];
     near?: number | number[];
     far?: number | number[];
 };
+/** `new Camera(options)`: a SECONDARY camera's lens and what its view draws (the scene's own camera is `scene.camera`). */
+export type CameraOptions = {
+    /** Vertical field of view in degrees (default 60). Live: `camera.fov`. */
+    fov?: number;
+    /** Near clip distance in metres (default 0.01). Live: `camera.near`. */
+    near?: number;
+    /** Far clip distance in metres (default 1000). Live: `camera.far`. */
+    far?: number;
+    /** The layers its view draws, a bit mask over `Node.layer` (default 0xff = everything): a renderable is drawn when its
+     *  layers share a bit with these — the player's own body left out of a mirror. Fixed when the view starts. */
+    layers?: number;
+    /** Shadows in its view (default `true`): the view renders shadow maps of its own each time it draws. Fixed when the
+     *  view starts. */
+    shadows?: boolean;
+};
+/** `camera.renderToTexture(options)`: the picture's size. */
+export type RenderToTextureOptions = {
+    /** Texels wide, 1..4096 (default 256). */
+    width?: number;
+    /** Texels tall, 1..4096 (default 256). */
+    height?: number;
+};
 /** Projection every host starts a scene with (creator-gl scene.cpp / the lite core agree on these). */
 export declare const CAMERA_DEFAULTS: {
     fov: number;
     near: number;
     far: number;
 };
+/**
+ * A camera: a Node (position, `lookAt`, parenting — it looks down its −Z) with a lens, `fov` / `near` / `far`. Two kinds:
+ *  - THE SCENE CAMERA, `scene.camera`: made by the Scene, it draws the screen. Its exposure, `projectionMatrix` and the
+ *    ray helpers (`getRay`, `getViewDirection`) are the screen's, and its projection tweens (`animateTo({ fov })`).
+ *  - A SECONDARY camera, `new Camera({ fov, layers, shadows })`: a plain node until `renderToTexture({ width, height })`
+ *    gives it a second view of its scene, drawn into a texture every frame the scene is on show — a rear-view mirror, a
+ *    monitor, a security camera. Place it like any node (`car.add(mirrorCam)`); its lens is live (`mirrorCam.fov = 50`),
+ *    its view's schedule is `enabled` / `everyNth`. A cube of light for reflections is a `ReflectionProbe`.
+ */
 export declare class Camera extends Node {
+    /** The scene this camera draws the screen of (Scene `_attach`); -1 = a secondary camera. */
     private _sceneId;
-    /** Tween `fov` / `near` / `far` (a zoom, a dolly) and the transform — see {@link Node.animateTo}. */
+    /** Tween `fov` / `near` / `far` (a zoom, a dolly — the scene camera's) and the transform — see {@link Node.animateTo}. */
     animateTo(props: CameraTweenProps & TweenMeta): Animation;
     animateFrom(props: CameraTweenProps & TweenMeta): Animation;
-    /** Live projection matrix (updated by the host when the viewport/fov changes). */
+    /** The scene camera's live projection matrix (updated by the host when the viewport / fov changes). A secondary
+     *  camera's stays zero: its projection is `fov` / `near` / `far` at its texture's aspect. */
     readonly projectionMatrix: Float32Array<ArrayBuffer>;
     private _fov;
     private _near;
@@ -31,11 +66,54 @@ export declare class Camera extends Node {
     private _exposure;
     private _ev;
     private _exposureSet;
+    private readonly _layers;
+    private readonly _shadows;
+    private _enabled;
+    private _everyNth;
+    /** A SECONDARY camera (`scene.camera` is the scene's own): a plain node until `renderToTexture`. `options`: its lens
+     *  (live after, through `fov` / `near` / `far`) and what its view draws (`layers`, `shadows` — fixed). */
+    constructor(options?: CameraOptions);
+    /**
+     * Draw this camera's view of its scene into a new 2D texture of `width × height` texels (default 256 × 256): the
+     * tone-mapped picture as the screen would show it (LDR) — `screen.material.map = cam.renderToTexture({ ... })`. The
+     * camera holds it (`camera.texture`).
+     *
+     * THE VIEW starts once the camera is in a scene (added to one, or under a node that is — at once if it already is)
+     * and draws every frame that scene is on show, after the frame's update passes (aspects, physics, animation: this
+     * frame's poses) and before the scene's own picture. It sees the scene's renderables, lights, environment and sky (not
+     * its overlays) from the camera's WORLD pose (scale ignored) through `fov` / `near` / `far` at the texture's aspect,
+     * with the `layers` and `shadows` the camera was made with, at the scene camera's exposure; its post-processing is the
+     * engine's default tone mapping (the scene's grading, bloom and the rest are not mirrored). Moving the camera to
+     * another scene later does not move the view.
+     *
+     * COST: every render is another pass over the scene — with `shadows`, its own shadow maps too. Keep the texture small,
+     * draw less often (`everyNth`), leave out what the view does not need (`layers`), and turn it off out of sight
+     * (`enabled = false`).
+     *
+     * Calling it again REPLACES the texture and the view: the previous view stops at once, its texture keeps its last
+     * picture while something still shows it. Throws on the scene camera, and on a host without render textures (the web
+     * hosts, for now).
+     */
+    renderToTexture(options?: RenderToTextureOptions): RenderTexture;
+    /** The texture `renderToTexture` made — the latest, null before one. */
+    get texture(): RenderTexture | null;
+    /** Whether this secondary camera's view draws (default `true`). Off keeps the last picture in its texture and costs
+     *  nothing — a mirror out of sight; back on, it renders on the next frame drawn. The scene camera always draws (reads
+     *  `true`; setting it throws). */
+    get enabled(): boolean;
+    set enabled(on: boolean);
+    /** Render this secondary camera's view 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. The scene camera draws every frame (reads 1;
+     *  setting it throws). */
+    get everyNth(): number;
+    set everyNth(n: number);
     /** Exposure compensation in stops (default 0): +1 doubles how bright the scene renders, −2
      *  quarters it. The one exposure knob most games need — a dark interior, a flash of white, or eye
      *  adaptation when the sun swings into view (drop it, and the sun stays at the display's peak
      *  while everything else darkens). Scene light follows it; particle `emissive` is post-exposure
-     *  and does not, so a fireball keeps its on-screen brightness. Cheap to animate every frame. */
+     *  and does not, so a fireball keeps its on-screen brightness. Cheap to animate every frame. The
+     *  scene camera's: a secondary camera's view renders at its scene camera's exposure (what is set on
+     *  a secondary camera is kept, unused). */
     /** The camera's EV100 with the compensation in: log2(aperture² / shutterSpeed x 100 / iso) - compensation. Sunny 16 is
      *  ~15; a lit surface of luminance L lands on screen at L / (1.2 x 2^ev100). */
     get ev100(): number;
@@ -43,7 +121,7 @@ export declare class Camera extends Node {
     set exposureCompensation(stops: number);
     /** The physical camera: `aperture` in f-stops, `shutterSpeed` in seconds, `iso`, plus the same
      *  `compensation` in stops — any subset, one call. `camera.setExposure({ iso: 400 })` is two stops
-     *  brighter than the default f/16 · 1/125 · ISO 100. */
+     *  brighter than the default f/16 · 1/125 · ISO 100. The scene camera's (as `exposureCompensation`). */
     setExposure(exposure: {
         aperture?: number;
         shutterSpeed?: number;
@@ -52,15 +130,18 @@ export declare class Camera extends Node {
     }): this;
     /** Hosts that predate the call keep the fixed default (older wasm / native builds). */
     private _applyExposure;
-    /** Vertical field of view in degrees (default 60) — a smaller angle is a longer lens. */
+    /** Vertical field of view in degrees (default 60) — a smaller angle is a longer lens. Live on both kinds: a
+     *  secondary camera's reaches its view at the next render (before `renderToTexture`, the view's starting value). */
     get fov(): number;
     set fov(degrees: number);
+    /** The horizontal field of view in degrees: the scene camera's at the screen's aspect, a secondary camera's at its
+     *  texture's (square before `renderToTexture`). */
     get horizontalFov(): number;
-    /** Near clip distance (default 0.01) — nothing closer than this draws. */
+    /** Near clip distance (default 0.01) — nothing closer than this draws. Live, as `fov`. */
     get near(): number;
     set near(distance: number);
     /** Far clip distance / view range (default 1000) — geometry past it is culled. Shadows keep
-     *  their own (shorter) range, so a long view distance doesn't cost shadow sharpness. */
+     *  their own (shorter) range, so a long view distance doesn't cost shadow sharpness. Live, as `fov`. */
     get far(): number;
     set far(distance: number);
     /** Set any of fov / near / far in one call: `camera.setProjection({ fov: 45, far: 5000 })`. */
@@ -69,8 +150,10 @@ export declare class Camera extends Node {
         near?: number;
         far?: number;
     }): this;
-    /** Hosts that predate the call keep the fixed defaults (older wasm / native builds). */
+    /** Hosts that predate the call keep the fixed defaults (older wasm / native builds); a secondary camera's view keeps
+     *  the projection it started with (warned once). */
     private _applyProjection;
+    private static _warnedViewProjection;
     private _following;
     /** The node the camera currently follows (`follow()`), or null. */
     get following(): Node | null;
@@ -79,7 +162,9 @@ export declare class Camera extends Node {
      * view direction), so movement aspects / animation on that node are camera moves — dolly shots,
      * a cutscene path, a `CameraPlace` in a scene file. A node carrying a `CameraPlace` also hands
      * over its projection (fov / near / far). `follow(null)` releases the camera where it is.
-     * One camera per scene: following a new node stops following the previous one.
+     * Following a new node stops following the previous one, and a node leads one camera at a time.
+     * Either kind: the pose is written as the camera's own transform, so a following secondary
+     * camera is a scene root, not a child.
      */
     follow(target: Node | {
         node: Node;
@@ -87,10 +172,12 @@ export declare class Camera extends Node {
     } | null): this;
     /** The scene view's [width, height] in logical units — the units of the scene's touches
      *  (`clientX` / `clientY`) and of `getRay`, on every host; × `device.pixelRatio` for device px.
-     *  [0, 0] before the scene has a viewport. */
+     *  [0, 0] before the scene has a viewport. The screen's, whichever camera reads it. */
     get displaySize(): [number, number];
-    /** World-space ray direction through a point of the scene view (logical units, as a touch's). */
+    /** World-space ray direction through a point of the scene view (logical units, as a touch's). The scene camera's
+     *  (a secondary camera throws). */
     getViewDirection(screenX: number, screenY: number): Vec3;
-    /** A pick ray from the camera through a point of the scene view (logical units, as a touch's). */
+    /** A pick ray from the camera through a point of the scene view (logical units, as a touch's). The scene camera's
+     *  (a secondary camera throws). */
     getRay(screenX: number, screenY: number): Ray;
 }

package/dist/types/gl/Light.d.ts

@@ -92,6 +92,11 @@ export type SpotOptions = {
     innerAngle?: number;
     /** A spot's shadow is one 2D shadow map (a point light's is a cubemap); off by default. */
     castShadows?: boolean;
+    /**
+     * Where the cone points, as a sun's `direction`: it sets the node's rotation (live as `light.direction`). Default:
+     * the node's forward (-Z) - aim it later with `lookAt` / `eulerAngles`.
+     */
+    direction?: Vec3Like;
 };
 export declare class Light extends Node {
     private _intensity;
@@ -111,8 +116,8 @@ export declare class Light extends Node {
     _innerAngle: number;
     /**
      * A spot light — a flashlight, a headlight, a stage light. It shines along the node's forward (-Z): position
-     * it like any node and aim it with `lookAt`. Real time only: the lightmap bake takes no spot lights, so a spot
-     * lights the baked statics live too.
+     * it like any node and aim it with `direction` or `lookAt`. Real time only: the lightmap bake takes no spot lights,
+     * so a spot lights the baked statics live too.
      */
     static spot(options?: SpotOptions): Light;
     /** A spot's full cone angle in degrees — live (a flashlight's focus). */

package/dist/types/gl/Lightmap.d.ts

@@ -1,15 +1,21 @@
 import { Node } from "./Node";
 import type { Scene } from "./Scene";
-export type LightmapLoadOptions = {
+/** The level's bake / load options: `bake()`'s second argument (an object literal, copied into the def as written). */
+export type LightmapOptions = {
     /** A DEBUG multiplier on the atlas' lux (default 1): the atlas is physical, so this is a knob for looking,
      *  not a look. */
     lightScale?: number;
-    /** The level's own radiance of emission 1.0 for the BAKE (cd / m², `BakeConfig.emissiveNits`): an imported pack's
-     *  emissive values are tuned for a look, not for light - this is where the level says how much its panels really give.
-     *  The CLI's `--emissive-nits` wins over it; without either the camera's exposure decides. */
+    /** 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, tuned for the eye;
+     *  this is where the level says what its panels really 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. The CLI's `--emissive-nits`
+     *  wins over it. A `Material.lit` glow with `emissiveNits` of its own emits those instead. */
     emissiveNits?: number;
-    /** `false` = the emissive surfaces light NOTHING in the bake (the level is lit by its lamps, the panels are decoration)
-     *  while `emissiveNits` still says how bright their glow is drawn. Default true. */
+    /** `false` = the emissive surfaces light NOTHING in the bake - the level is lit by its lamps (a `kind: 'point'` light
+     *  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. The
+     *  OVERRIDE over every surface's own switch (`Material.lit`'s `emissiveBake`, a GLB material's extras
+     *  `{"lecodes":{"emissiveBake":false}}`), which vetoes one material while the rest still light the level. */
     emissiveBake?: boolean;
     /** FOR THE BAKE: materials that let light THROUGH them, by their glTF name (`"name*"` = every name with that start):
      *  the share of a shadow ray that passes, tinted by the material's base colour x map - an awning's warm, patterned light
@@ -24,7 +30,7 @@ export type LightmapLoadOptions = {
      *  or charts. Added to the CLI's `--cube` patterns (both apply). */
     cube?: string[];
 };
-/** one `transmit` entry (LightmapLoadOptions.transmit): the straight share, or both shares */
+/** one `transmit` entry (LightmapOptions.transmit): the straight share, or both shares */
 export type LightmapTransmit = number | {
     through?: number;
     diffuse?: number;
@@ -39,26 +45,34 @@ export type LightmapInfo = {
     total: number;
     missing: string[];
 };
+/** The bake's files as `bake()` reads them off the `.bake` manifest at compile time — each one staged like an asset()
+ *  (every name in the manifest is relative to the `.bake`'s folder). Written by the macro, never by hand. */
 export type LightmapFiles = {
-    data: string;
-    /** The irradiance atlas — one page, or every page in order for a bake that took several. */
-    light: string | string[];
-    /** The aux atlas (sun / sky visibility + light direction), pages like `light`. */
-    aux: string | string[];
+    /** The `.bake` (the manifest) — null until `lecodes lightmap bake` has written it: the level then runs unbaked. */
+    data: string | null;
+    /** Project-relative path of the `.bake`, always set: what the messages name, and where `lecodes lightmap bake` writes. */
+    path: string;
+    /** The irradiance atlas (`<stem>-light[_n].ktx2`), every page in order. */
+    light: string[];
+    /** The aux atlas (`<stem>-aux[_n].ktx2`: sun / sky visibility + light direction), pages like `light`. */
+    aux: string[];
     /** DEBUG: the direct-light-only pages a `--split` bake wrote (`<stem>-direct[_n].ktx2`), for the "direct" view. */
-    direct?: string | string[];
+    direct?: string[];
     /** DEBUG: the bounce-only pages of a `--split` bake (`<stem>-indirect[_n].ktx2`), for the "indirect" view. */
-    indirect?: string | string[];
+    indirect?: string[];
     /** The reflection probes (`<stem>-probes.ktx2`), when the bake placed some (`lecodes lightmap bake --probe-spacing`). */
     probes?: string;
-    /** THE LIGHT GRID for movers (`<stem>.lgrid`, `lecodes lightmap bake --volume`): the baked ambient light of every
-     *  place a mover can be. Absent = movers keep the scene's IBL. */
+    /** THE LIGHT GRID for movers (`<stem>.lgrid`, `lecodes lightmap bake --volume`): 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;
-    /** THE PACKED LIGHTMAP UV1 (`<stem>-uv1.bin`, the .bake's `uv1`): the bake packs every mesh's lightmap charts into a
-     *  square of their own and its rects map that uv1 — the engine swaps it into the models' TEXCOORD_1 first. Required
-     *  when the bake names one. */
+    /** THE PACKED LIGHTMAP UV1 (`<stem>-uv1.bin`): the bake packs every mesh's lightmap charts into a square of their own
+     *  and its rects map that uv1 — the engine swaps it into the models' TEXCOORD_1 before the rects go on. */
     uv1?: string;
 };
+/** What `bake('<path>.bake', options)` compiles to — the files of the bake and the level's options in one literal:
+ *  `env.lightmap` in a scene file, `Lightmap.load`'s argument in a hand-built scene. */
+export type LightmapDef = LightmapFiles & LightmapOptions;
 /** The lightmap material's data views (`Lightmap.debug`); "direct" / "indirect" bind a `--split` bake's pages instead. */
 export type LightmapDebugMode = "off" | "irradiance" | "albedo" | "normal" | "shadingNormal" | "share" | "skyVis" | "atlas" | "direction" | "lux" | "relief" | "direct" | "indirect" | "probe" | "probeMap" | "skyPath" | "probePath";
 export type LightmapDebugParams = {
@@ -103,7 +117,7 @@ export declare class Lightmap {
     private static next;
     private static movers;
     private static volumeOn;
-    /** A MOVER takes its ambient light from the level's baked LIGHT GRID (`env.lightmap.volume`) at the place it is at,
+    /** A MOVER takes its ambient light from the level's baked LIGHT GRID (the bake's `.lgrid`) at the place it is at,
      *  every frame — whatever its shader: the standard glTF one or a custom lit material. Every Model / Mesh under `node`
      *  is marked (a character, a weapon with its parts). A scene file does this itself for every node a Physics aspect or
      *  a CharacterController moves; call it for what CODE spawns — an enemy, a pickup, a projectile. `on = false` hands
@@ -127,14 +141,15 @@ export declare class Lightmap {
     /** The loaded bake's sun (TO the sun ×3, its illuminance rgb, the sun map's levels), null without a sun map. */
     private static sunArgs;
     private static applySun;
-    /** Apply a bake — or, under `lecodes lightmap bake`, run it. Resolves to null when nothing was
-     *  applied (no bake yet, a host without the feature, bake mode). */
+    /** Apply a bake — or, under `lecodes lightmap bake`, run it. `def` is what `bake('<path>.bake', options)` compiled
+     *  to (a scene file's `env.lightmap`). Resolves to null when nothing was applied (no bake yet, a host without the
+     *  feature, bake mode). */
     private static scene;
-    static load(scene: Scene, files: LightmapFiles, options?: LightmapLoadOptions): Promise<LightmapInfo | null>;
+    static load(scene: Scene, def: LightmapDef): Promise<LightmapInfo | null>;
     /** The bake's `<key>@k` records by their node key: a model's meshes (k = the primitive's ordinal in its file). */
     private static recordsOf;
     /** Switch every lightmapped surface to a DATA view (or back with `"off"` / 0). Level-wide, instant —
-     *  except "direct" / "indirect", which load that page set the first time (a `--split` bake listed in the scene). */
+     *  except "direct" / "indirect", which load that page set the first time (a bake made with `--split`). */
     static debug(mode: LightmapDebugMode | number, params?: LightmapDebugParams): void;
     /** Bind another page set of the bound bake to every surface (the "direct" / "indirect" views). */
     private static show;
@@ -152,7 +167,12 @@ export declare class Lightmap {
     static probe(screenX: number, screenY: number): LightmapProbe | null;
     /** A material's colour uniform as "#rrggbbaa" (the float4 uniform path sets its alpha); white without one. */
     private static colorUniform;
-    /** The lightmap material for a static Mesh, from whatever lit material it carried (colour, map, roughness, metallic). */
+    /** The lightmap material for a static Mesh, from whatever lit material it carried (colour, map, roughness, metallic)
+     *  — and its GLOW, so a glowing Mesh looks the same before and after the bake applies: `emissive` (linear) becomes the
+     *  lightmap material's `emissiveFactor` at strength 1; its own `emissiveNits` go over with `emissiveOwn` 1, which the
+     *  level-wide write (`lightmapSetOptions`) leaves alone. A glow without nits takes the level's, like a GLB panel:
+     *  screen-referred under a level of 0 nits, else emission x the level's nits through the exposure — the same as
+     *  before the bake when the level's nits are the camera's (the default). */
     private static meshMaterial;
     private static bake;
 }

package/dist/types/gl/Material.d.ts

@@ -112,12 +112,25 @@ export type ParticlesMaterialOptions = {
      *  length = size + stretch·|velocity|. Default 0.05. */
     stretch?: number;
 };
-/** `Material.lit` options — PBR scalars on top of the color/map pair. */
+/** `Material.lit` options — PBR scalars on top of the color/map pair, and the surface's own glow. */
 export type LitMaterialOptions = MaterialColorOptions & MaterialStateOptions & {
     /** Perceptual roughness, 0 (mirror) … 1 (matte). Unset = the shader's default. */
     roughness?: number;
     /** Metallic factor, 0 (dielectric) … 1 (metal). Unset = the shader's default. */
     metallic?: number;
+    /** The surface's GLOW, added on top of its lit colour: a ceiling panel, a screen, a sign. Any colour (sRGB, like
+     *  `color`); an `[r, g, b]` array may go past 1 — an HDR colour, its hue in sRGB and the excess a linear multiplier
+     *  (`[4, 3.6, 3]` = `[1, 0.9, 0.75]` four times as bright). Unset = no glow. */
+    emissive?: ColorInput;
+    /** The glow's luminance in cd / m² (nits) for `emissive` 1.0 — `#ffffff` at 1600 is a typical ceiling panel. Set,
+     *  the glow is drawn SCENE-referred: through the camera's exposure, as bright as the light it gives the room in a
+     *  bake. Unset (or 0) = SCREEN-referred: the colour is drawn as it is whatever the exposure, and a bake counts it at
+     *  the level's `emissiveNits` (what the camera makes of 1.0 unless the level says otherwise). */
+    emissiveNits?: number;
+    /** `false` = decoration: the glow is drawn, but a lightmap bake does not light the level with it (Unity's "Global
+     *  Illumination: None") — the level's lamps do. Default true: a glowing static lights the level like a lamp. The
+     *  level-wide `bake('…', { emissiveBake: false })` overrides it for every surface. */
+    emissiveBake?: boolean;
 };
 export declare class Material {
     readonly shader: FetchResponse | "unknown";
@@ -139,7 +152,8 @@ export declare class Material {
     set map(value: Texture | Canvas | null);
     /** The material an instance handle is of; a host that carries none under `name` is an error naming it. */
     private static _builtin;
-    /** PBR lit material. */
+    /** PBR lit material. `emissive` / `emissiveNits` / `emissiveBake` are its glow (`LitMaterialOptions`); the uniforms
+     *  are written only for a material that asks for a glow, so a plain lit material never names them. */
     static lit(options?: LitMaterialOptions): Material;
     /** Unlit (flat) material — opaque unless `transparent` asks for alpha blending. */
     static unlit(options?: UnlitMaterialOptions): Material;

package/dist/types/gl/Node.d.ts

@@ -40,6 +40,19 @@ export declare class Node extends AspectHost<NodeEvents> implements CompWriter {
     set name(value: string);
     get visible(): boolean;
     set visible(value: boolean);
+    /**
+     * The node's visibility LAYERS, a bit mask 1..255. The scene's own view draws every layer; a render
+     * view (a secondary `Camera`'s or a `ReflectionProbe`'s, their `layers` option) draws only the
+     * renderables whose layers share a bit with its mask — which is what layers are for: leaving a subtree
+     * out of a second camera (the car out of the reflection probe riding on it, the player's own body out
+     * of a mirror). A node without a layer
+     * of its own takes its nearest ancestor's, else 1, so a car's layer covers everything parented under
+     * it; `0` clears the node's own (inherit again). `visible = false` wins over any layer. Reads the
+     * effective bits. A host without layers draws everything everywhere (reads 1, a write warns once).
+     */
+    get layer(): number;
+    set layer(mask: number);
+    private static _warnedLayer;
     private _sync;
     get matrix(): Mat4;
     set matrix(m: Mat4Like);

package/dist/types/gl/Particles.d.ts

@@ -184,7 +184,7 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
      *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
      *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
     order?: number;
-    /** Sprites take the light of the PLACE each one is in — the level's baked light grid (`env.lightmap.volume`).
+    /** Sprites take the light of the PLACE each one is in — the level's baked light grid (the bake's `.lgrid`).
      *  A sprite is unlit: its colour is the picture, which is right for fire and wrong for dust — a puff kicked up
      *  under an awning glows as if it stood in the sun. With `lit` every particle's colour is multiplied by the light
      *  where it is, relative to the level's OPEN ground: exactly the authored colour out in the sun, the ambient's

package/dist/types/gl/ReflectionProbe.d.ts

@@ -0,0 +1,87 @@
+import { Node } from "./Node";
+import { RenderTexture } 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 declare 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;
+    private readonly _layers;
+    private readonly _shadows;
+    private readonly _near;
+    private readonly _far;
+    private _enabled;
+    private _everyNth;
+    private _facesPerFrame;
+    constructor(options?: ReflectionProbeOptions);
+    /** 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;
+    set enabled(on: boolean);
+    /** 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;
+    set everyNth(n: number);
+    /** 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;
+    set facesPerFrame(n: number);
+}

package/dist/types/gl/RenderTexture.d.ts

@@ -0,0 +1,29 @@
+import { Texture } from "./Texture";
+/**
+ * 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 declare 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;
+    /**
+     * 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?: number): Promise<Uint8Array>;
+}