lecodes-sdk 2.4.6 → 2.4.8

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
@@ -521,6 +524,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/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/Lightmap.d.ts

@@ -18,6 +18,11 @@ export type LightmapLoadOptions = {
      *  `{ through, diffuse }` adds the share the fibres SCATTER - the cloth's underside glows like a matte panel and lights
      *  what is under it by the solid angle it fills, 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 record's key
+     *  (`<node key>@<ordinal>`: `"SM_pipe"` takes every pipe node, `"@1$"` the second mesh of each): a record that matches
+     *  leaves the atlas like a small or thin one — an occluder lit by ambient cubes baked where it stands — whatever its size
+     *  or charts. Added to the CLI's `--cube` patterns (both apply). */
+    cube?: string[];
 };
 /** one `transmit` entry (LightmapLoadOptions.transmit): the straight share, or both shares */
 export type LightmapTransmit = number | {
@@ -49,6 +54,10 @@ export type LightmapFiles = {
     /** 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. */
     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. */
+    uv1?: string;
 };
 /** 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";
@@ -69,6 +78,14 @@ export type LightmapProbe = {
     world: [number, number, number];
     distance: number;
 };
+/** `Lightmap.add`'s options */
+export type LightmapAddOptions = {
+    /** Bake it as AMBIENT CUBES instead of atlas texels: an occluder (its shadow and bounce stay in the atlas) whose own
+     *  light is baked where it stands — the way the bake treats small and thin objects (`--min-texels`, `--thin-texels`),
+     *  here by hand: a pipe run, a fence, a prop whose charts show their seams. A long one takes a slab of cubes per metre
+     *  (`--object-slab`). Default false. */
+    cube?: boolean;
+};
 export declare class Lightmap {
     /** True while `lecodes lightmap bake` runs the app — skip menus and build the scene straight away. */
     static get baking(): boolean;
@@ -81,8 +98,8 @@ export declare class Lightmap {
      *  both receivers and occluders in the bake (a model without lightmap UVs, or with materials the lightmap shader
      *  declines — alpha cards — is an occluder alone; a terrain is ONE rect, built with `Material.terrainLightmap()`).
      *  `key` names the entry in the .bake (default: the node's name + a running number, `container#3`); pass one when
-     *  names are not stable. */
-    static add(node: Node, key?: string): Node;
+     *  names are not stable. `{ cube: true }` bakes it as ambient cubes instead of atlas texels (`LightmapAddOptions`). */
+    static add(node: Node, key?: string, options?: LightmapAddOptions): Node;
     private static next;
     private static movers;
     private static volumeOn;
@@ -93,6 +110,10 @@ export declare class Lightmap {
      *  the subtree back to the scene's IBL. Safe before the level's bake has loaded. */
     static track(node: Node, on?: boolean): void;
     private static loadVolume;
+    /** THE PACKED UV1 the bake's rects map (the .bake's `uv1`), into the host BEFORE any rect is applied: the host swaps it
+     *  into the models' TEXCOORD_1 as their rects go on. A bake without one clears the last (the models' own uv1 back).
+     *  False = the bake needs it and it cannot be had - its rects would read the wrong texels. */
+    private static loadUv1;
     /** Forget every registration (a scene rebuild). */
     static clear(): void;
     /** THE MOVERS' SUN SHADOWS ON THE BAKED STATICS (a bot, a barrel, the player's rifle darkening the ground under
@@ -110,8 +131,8 @@ export declare class Lightmap {
      *  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>;
-    /** The bake's `<key>#k` instances by their base key: the parts of a GLB unwrapped in groups (k = extras.lightmapGroup). */
-    private static groupsOf;
+    /** 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). */
     static debug(mode: LightmapDebugMode | number, params?: LightmapDebugParams): void;

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

@@ -12,8 +12,8 @@ export interface TrianglePick {
     mesh: string;
     primitive: number;
     material: string;
-    /** the node's lightmap group (scene-file extras), when it has one */
-    lightmapGroup?: number;
+    /** the primitive's index over its file's meshes: the lightmap bake's record `<key>@<ordinal>` */
+    lightmapOrdinal: number;
     /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
     triangle: number;
     backface: boolean;
@@ -83,8 +83,8 @@ export declare class Model extends Node {
             total?: number;
         }) => void;
         /** Baked lighting (engines/bake). `true` = a STATIC: loads through the lightmap material so
-         *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 — `lecodes assets doctor
-         *  --lightmap-uv`) and takes nothing from the real-time lights once the bake applies. Omitted / `false` =
+         *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 —
+         *  `lecodes assets unwrap`, which `lightmap bake` runs itself on raw GLBs) and takes nothing from the real-time lights once the bake applies. Omitted / `false` =
          *  the standard shader, lit real-time (movers). Hosts without lightmap support ignore it. */
         lightmap?: boolean;
         /** Vegetation: load through the FOLIAGE tier (see `Foliage`) — wind, touch bending, distance fade,

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/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>;
+}

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

@@ -8,6 +8,7 @@ import { Camera } from "./Camera";
 import { SceneAudio } from "./audio/SceneAudio";
 import { Material } from "./Material";
 import { PostProcessing, type PostProcessingOptions } from "./postProcessing";
+import { ReflectionProbe } from "./ReflectionProbe";
 import { Node } from "./Node";
 /** `SceneOptions.taa` / `scene.setAntialias("taa", 4, taa)`: the temporal anti-aliasing knobs. */
 export type TaaOptions = {
@@ -187,6 +188,26 @@ export declare class Scene implements Presentable {
     get environmentIntensity(): number;
     set environmentIntensity(lux: number);
     private static _warnedEnvIntensity;
+    /**
+     * 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;
+    set environment(probe: ReflectionProbe | null);
+    private static _warnedEnvTexture;
     /** The scene's stencil buffer on / off (see `SceneOptions.stencil`). */
     setStencil(enabled: boolean): void;
     add(...list: Node[]): this;

package/dist/types/inject.d.ts

@@ -148,7 +148,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/dist/types/scene/defineScene.d.ts

@@ -130,8 +130,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. */
@@ -184,10 +188,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;
 };

package/dist/types/ui/tree.d.ts

@@ -72,5 +72,6 @@ export declare const OWNED_KIND_ENTITY_2D = 5;
 export declare const OWNED_KIND_MEDIA = 6;
 export declare const OWNED_KIND_TWEEN = 7;
 export declare const OWNED_KIND_CANVAS = 8;
+export declare const OWNED_KIND_GL_RENDER_VIEW = 9;
 import { DEAD_HANDLE } from "../core/pins";
 export { DEAD_HANDLE };

package/dist/types/version.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "2.4.6";
+export declare const SDK_VERSION = "2.4.8";
 /** The major of a semver string, or null when it is not one. */
 export declare const sdkMajor: (version: string | null | undefined) => number | null;
 /** The `// sdk: <version>` line of a compiled bundle's header (sdk/src/compile/header.ts), read from