lecodes-sdk 2.4.7 → 2.4.8

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.4.7",
+  "version": "2.4.8",
   "files": [
     "src",
     "dist",

package/src/bridges/gl.d.ts

@@ -184,6 +184,10 @@ declare global {
      *  not the roughness-prefiltered `_ibl.ktx` beside it. Optional: hosts that predate it keep the
      *  flat skybox. */
     setSkyboxTexture?(sceneId: u32, fetchId: bytes): void
+    /** Optional. Light the scene from a CUBEMAP texture (a render texture's cube, creator.h setEnvironmentTexture): the
+     *  IBL reflects it, its irradiance and intensity stay; no roughness prefiltering, so only mirror-like reflections are
+     *  right. The engine holds the texture while it lights; setDefaultIbl replaces it. */
+    setEnvironmentTexture?(sceneId: u32, textureId: u32): void
     /** Temporal anti-aliasing (Filament's TAA) for the scene and its overlays: on, MSAA and FXAA are off for the
      *  view; `feedback` = the history's share (0.12 default, higher = less ghosting, less smoothing), `sharpness` =
      *  the post-TAA sharpen (0–1), `upscale` = the fraction the 3D is rendered at and TAA-upscaled from (0.5–1,
@@ -325,6 +329,30 @@ declare global {
      *  re-uploads a sub-rectangle with the creation channel count. Optional (Texture.fromPixels throws). @args data width height channels srgb @count pixelBytes=data @owned GlTexture */
     createTexturePixels?(width: u32, height: u32, channels: u32, data: Uint8Array, srgb: boolean): Handle
     updateTexturePixels?(textureId: u32, x: u32, y: u32, width: u32, height: u32, data: Uint8Array): void
+    /** Optional. A RENDER TEXTURE, what a render view draws into (creator.h createRenderTexture): `flags` bit 1 = CUBEMAP
+     *  (`width` = the edge, `height` ignored), bit 2 = HDR (R11F_G11F_B10F linear light, for lighting); neither = an LDR
+     *  display texture (SRGB8_A8, the tone-mapped picture); bit 4 = PREFILTER, with both others only (flags 7, a
+     *  power-of-two edge of 16 at least): a probe filtered for roughness — the id is the 5-level filtered cube, its views
+     *  draw a raw one behind it, filtered on the GPU at the frame after each completed cube with `samples` samples
+     *  (0 = 256; read for PREFILTER only). Otherwise an ordinary texture id (setUniformTexture, setSceneBackground); its
+     *  texel rows run as OpenGL renders, on every backend (a 2D texture's first row = the picture's bottom). 0xFFFFFFFF
+     *  on failure. @owned GlTexture */
+    createRenderTexture?(width: u32, height: u32, flags: u32, samples: u32): Handle
+    /** Optional. A RENDER VIEW of the scene into a render texture, from node `cameraEntityId` (its world pose, read every
+     *  frame; a cube takes its position only): `layerMask` = the layers it sees (setLayer), `fov` vertical degrees (a cube
+     *  is 90), `flags` bit 1 = no shadows. Drawn each frame its scene is presented, before the scene's own view; freeing the
+     *  texture takes its views with it. 0 on failure. @owned GlRenderView */
+    createRenderView?(sceneId: u32, textureId: u32, cameraEntityId: u32, layerMask: u8, fov: f32, near: f32, far: f32, flags: u32): Handle
+    /** Optional. `everyNth` 1 = every frame, N = one render per N frames drawn, counted afresh from this call (the next
+     *  frame renders); `facesPerFrame` 1..6 for a cube (round-robin). */
+    setRenderViewOptions?(renderViewId: u32, enabled: boolean, everyNth: u32, facesPerFrame: u32): void
+    /** Optional. The view's projection, live (createRenderView's fov / near / far were the initial values): a 2D view's
+     *  vertical fov in degrees and clip planes; a cube ignores `fov` (90) and takes the planes. Unknown id = no-op. */
+    setRenderViewProjection?(renderViewId: u32, fov: f32, near: f32, far: f32): void
+    /** Optional. RGBA8 bytes of a rectangle of a render texture as the next frame leaves it — rows in the texture's order
+     *  (the first is texel row `y`), `face` 0..5 = +X -X +Y -Y +Z -Z of a cube (0 for 2D), an HDR one clamped to 0..1
+     *  (linear); null when refused. A GPU readback, for checks and tools. @custom */
+    readRenderTexturePixels?(textureId: u32, face: u32, x: u32, y: u32, width: u32, height: u32, onDone: (pixels: Uint8Array | null) => void): void
 
     /** A material INSTANCE of these .filamat bytes (an app's own shader, fetched); the material itself is deduplicated by content in the engine. @c createMaterialInstanceFromBytes @owned GlMaterial @throw createMaterial: no .filamat bytes behind this fetch id */
     createMaterial(systemId: bytes): Handle
@@ -355,6 +383,12 @@ declare global {
 
     setVisible(entityId: u32, visible: boolean): void
     isVisible(entityId: u32): boolean
+    /** Optional. Visibility layers: the entity's explicit layer bits (u8), inherited by its subtree down to a
+     *  descendant with its own; 0 clears them (inherit again). Nothing set = 0x01. A view draws a renderable
+     *  when their layers share a bit (the scene's own view sees all). A host without it has no layers. @c setEntityLayer */
+    setLayer?(entityId: u32, mask: u8): void
+    /** Optional. The entity's effective layer bits: its own, else the nearest ancestor's, else 0x01. @c getEntityLayer */
+    getLayer?(entityId: u32): u8
 
     /** @custom */
     createGlb(systemId: bytes, onComplete: (root: Handle | null) => void, onReject: () => void): void

package/src/gl/Camera.ts

@@ -1,20 +1,49 @@
-// The scene camera — a Node (so position / lookAt / transform all work) plus projection reads and
-// screen↔world ray helpers. Created and attached by Scene. Ported from worker/src/components/Camera.ts.
+// A camera — a Node (so position / lookAt / transform all work) plus its lens. The scene camera is created and attached
+// by Scene (`_attach`: its projection, exposure and the screen↔world ray helpers are the screen's); a SECONDARY camera is
+// `new Camera(options)`, a plain node until `renderToTexture` gives it a render view of its scene (RenderTexture.ts,
+// creator-gl renderview.cpp), started once the node is in a scene (Node.ts awaitScene). Ported from
+// worker/src/components/Camera.ts.
 
 import { Vec3 } from "../math/vec"
 import { Aspect } from "../core/Aspect"
-import { Node, type NodeTweenProps } from "./Node"
+import { Node, awaitScene, type NodeTweenProps } from "./Node"
 import { Ray } from "./Ray"
+import { RenderTexture, makeRenderTexture, startRenderView } from "./RenderTexture"
 import { DOM_GL_CAMERA, floatValue, type TweenChannel, 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
+}
+
 /** @internal `camera.follow(node)`: copies the node's world pose onto the camera every LATE frame
  *  (order 1000 — after every other aspect has moved things). One per camera; lives on the target. */
 export class CameraFollowRig extends Aspect<"__cameraFollow"> {
@@ -31,16 +60,33 @@ export class CameraFollowRig extends Aspect<"__cameraFollow"> {
 /** Projection every host starts a scene with (creator-gl scene.cpp / the lite core agree on these). */
 export const CAMERA_DEFAULTS = { fov: 60, near: 0.01, far: 1000 }
 
+/** A texture side: a whole number, 1 at least (the host refuses more than 4096). */
+const side = (n: number): number => Math.max(1, Math.floor(n))
+
+/**
+ * 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 class Camera extends Node {
+  /** The scene this camera draws the screen of (Scene `_attach`); -1 = a secondary camera. */
   private _sceneId = -1
 
-  /** 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}. */
   override animateTo(props: CameraTweenProps & TweenMeta): Animation { return super.animateTo(props) }
   override animateFrom(props: CameraTweenProps & TweenMeta): Animation { return super.animateFrom(props) }
-  /** @internal The projection channels address the SCENE (one camera per scene on the host). */
+  /** @internal The projection channels address the SCENE (one camera per scene on the host): a render view's
+   *  projection has no tween writer, so a secondary camera's throw. */
   override _tweenChannel(prop: string): TweenChannel | null {
     if (prop === "fov" || prop === "near" || prop === "far") {
-      const id = () => (this._sceneId < 0 ? 0 : this._sceneId + 1)   // scene ids start at 0; 0 = unaddressable
+      if (this._sceneId < 0) {
+        throw new Error(`Camera: a secondary camera's "${prop}" is not animatable (the tween core drives the scene camera's projection only) — set camera.${prop} directly, it is live: per frame, or animate({ from, to, onUpdate: (v) => { camera.${prop} = v } })`)
+      }
+      const id = () => this._sceneId + 1   // scene ids start at 0; 0 = unaddressable
       const commit = (v: unknown) => {
         if (prop === "fov") this._fov = v as number
         else if (prop === "near") this._near = v as number
@@ -51,11 +97,12 @@ export class Camera extends Node {
     }
     return super._tweenChannel(prop)
   }
-  /** 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 = new Float32Array(16)
 
-  // Projection the app asked for (host defaults until it does). The host owns the aspect and
-  // re-applies these on every viewport change, so they are set, not maintained.
+  // Projection the app asked for (host defaults until it does). The scene camera's host owns the aspect and re-applies
+  // these on every viewport change, so they are set, not maintained; a secondary camera's are its view's.
   private _fov = CAMERA_DEFAULTS.fov
   private _near = CAMERA_DEFAULTS.near
   private _far = CAMERA_DEFAULTS.far
@@ -69,7 +116,29 @@ export class Camera extends Node {
   private _ev = 0
   private _exposureSet = false
 
-  /** @internal — Scene wires the camera to its native scene id + projection callback. */
+  // A secondary camera's view (renderToTexture): what it draws with, fixed when it starts, and its schedule.
+  private readonly _layers: number
+  private readonly _shadows: boolean
+  private _enabled = true
+  private _everyNth = 1
+  /** @internal The texture `renderToTexture` made (held: it lives as long as the camera does). */
+  _texture: RenderTexture | null = null
+  /** @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 camera holds it. */
+  _view: Handle | null = null
+
+  /** 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 = {}) {
+    super()
+    if (options.fov !== undefined) this._fov = options.fov
+    if (options.near !== undefined) this._near = options.near
+    if (options.far !== undefined) this._far = options.far
+    this._layers = (options.layers ?? 0xff) & 0xff
+    this._shadows = options.shadows !== false
+  }
+
+  /** @internal — Scene wires the camera to its native scene id + projection callback: the SCENE camera. */
   _attach(sceneId: number): void {
     this._sceneId = sceneId
     _creator.attachCameraToAR(sceneId, this.id, (mat) => {
@@ -79,11 +148,90 @@ export class Camera extends Node {
     if (this._exposureSet) this._applyExposure()
   }
 
+  /** @internal What only the scene camera has (the screen's ray helpers): a clear throw on a secondary camera. */
+  private _sceneOnly(what: string): void {
+    if (this._sceneId < 0) throw new Error(`camera.${what}: the scene camera's (scene.camera) — a secondary camera has no screen to pick through`)
+  }
+  /** @internal What only a secondary camera has (a render view): a clear throw on the scene camera. */
+  private _secondaryOnly(what: string): void {
+    if (this._sceneId >= 0) throw new Error(`camera.${what}: the scene camera draws the screen, every frame its scene is on show — a second view is a new Camera() with renderToTexture`)
+  }
+
+  /**
+   * 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 {
+    this._secondaryOnly("renderToTexture")
+    const texture = makeRenderTexture("camera.renderToTexture", side(options.width ?? 256), side(options.height ?? 256), 0)
+    if (this._view) {   // replaced: the old view stops now; its handle goes with this reference
+      _creator.setRenderViewOptions?.(this._view.id, false, 1, 6)
+      this._view = null
+    }
+    this._texture = texture
+    awaitScene(this)
+    return texture
+  }
+
+  /** @internal Node.ts awaitScene: the camera is in scene `sceneId` — start its view into its texture. */
+  _bindView(sceneId: number): void {
+    const texture = this._texture
+    if (this._view || !texture) return
+    this._view = startRenderView("camera", sceneId, texture, this.id, this._layers, this._fov, this._near, this._far, this._shadows)
+    if (this._view && (!this._enabled || this._everyNth !== 1)) this._sendSchedule()
+  }
+
+  /** The texture `renderToTexture` made — the latest, null before one. */
+  get texture(): RenderTexture | null { return this._texture }
+
+  /** 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 { return this._enabled }
+  set enabled(on: boolean) {
+    this._secondaryOnly("enabled")
+    this._enabled = on
+    this._sendSchedule()
+  }
+  /** 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 { return this._everyNth }
+  set everyNth(n: number) {
+    this._secondaryOnly("everyNth")
+    this._everyNth = 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, 6)
+  }
+
   /** 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 {
@@ -99,7 +247,7 @@ export class Camera extends Node {
 
   /** 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, iso?: number, compensation?: number }): this {
     if (exposure.aperture !== undefined) this._exposure.aperture = exposure.aperture
     if (exposure.shutterSpeed !== undefined) this._exposure.shutterSpeed = exposure.shutterSpeed
@@ -117,17 +265,25 @@ export class Camera extends Node {
     _creator.setCameraExposure?.(this._sceneId, e.aperture, e.shutterSpeed, e.iso * 2 ** this._ev)
   }
 
-  /** Vertical field of view in degrees (default 60) — a smaller angle is a longer lens. */
-  get fov(): number { return _creator.getCameraFov(this._sceneId, 0) }
+  /** 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 { return this._sceneId >= 0 ? _creator.getCameraFov(this._sceneId, 0) : this._fov }
   set fov(degrees: number) { this._fov = degrees; this._projSet = true; this._applyProjection() }
-  get horizontalFov(): number { return _creator.getCameraFov(this._sceneId, 1) }
+  /** 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 {
+    if (this._sceneId >= 0) return _creator.getCameraFov(this._sceneId, 1)
+    const t = this._texture
+    const aspect = t ? t.width / t.height : 1
+    return Math.atan(Math.tan(this._fov * Math.PI / 360) * aspect) * 360 / Math.PI
+  }
 
-  /** 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 { return this._near }
   set near(distance: number) { this._near = distance; this._projSet = true; this._applyProjection() }
 
   /** 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 { return this._far }
   set far(distance: number) { this._far = distance; this._projSet = true; this._applyProjection() }
 
@@ -141,11 +297,22 @@ export class Camera extends Node {
     return 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(): void {
-    if (this._sceneId < 0 || typeof _creator.setCameraProjection !== "function") return
+    if (this._sceneId < 0) {
+      if (!this._view) return   // remembered: the view starts with it
+      if (_creator.setRenderViewProjection) _creator.setRenderViewProjection(this._view.id, this._fov, this._near, this._far)
+      else if (!Camera._warnedViewProjection) {
+        Camera._warnedViewProjection = true
+        console.warn("[camera] this host has no setRenderViewProjection — a secondary camera keeps the projection its view started with")
+      }
+      return
+    }
+    if (typeof _creator.setCameraProjection !== "function") return
     _creator.setCameraProjection(this._sceneId, this._fov, this._near, this._far)
   }
+  private static _warnedViewProjection = false
   private _following: Node | null = null
   /** The node the camera currently follows (`follow()`), or null. */
   get following(): Node | null { return this._following }
@@ -155,7 +322,9 @@ export 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, applyTo(camera: Camera): void } | null): this {
     const node = target === null ? null : target instanceof Node ? target : target.node
@@ -175,22 +344,26 @@ export class Camera extends Node {
 
   /** 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] {
     const s = _creator.getDisplaySize()
     return [ s[0], s[1] ]
   }
 
-  /** 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 {
-    if (this._sceneId < 0) throw new Error("Camera is not attached to a scene")
+    this._sceneOnly("getViewDirection")
     const v = new Float32Array(3)
     _creator.getCameraViewDirection(this._sceneId, screenX, screenY, v)
     return new Vec3(v[0], v[1], v[2])
   }
 
-  /** 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 {
+    this._sceneOnly("getRay")
     return new Ray(this.worldPosition, this.getViewDirection(screenX, screenY))
   }
 }
+

package/src/gl/Node.ts

@@ -94,6 +94,43 @@ const findNodeByWalk = (rootId: number, name: string): number => {
 // Scratch for the world-position read-back in _setOwnedPosition (one per module, never handed out).
 const worldScratch = new Float32Array(3)
 
+/** @internal The scene a node is in: the one `scene.add` put it or its nearest such ancestor in (`_inScene`), -1 = none
+ *  yet. A scene's nodes are pinned, so the walk meets the very wrappers `scene.add` stamped. */
+export const sceneIdOf = (node: Node): number => {
+  if (node._inScene >= 0) return node._inScene
+  for (let id = _creator.getParent(node.id); id !== 0; id = _creator.getParent(id)) {
+    const n = nodes.get(id)
+    if (n && n._inScene >= 0) return n._inScene
+  }
+  return -1
+}
+
+/** @internal A node whose render view starts once the node is in a scene (a secondary Camera's `renderToTexture`, a
+ *  ReflectionProbe): `_bindView(sceneId)` starts it if it has none. */
+export type ViewBinder = Node & { _bindView(sceneId: number): void }
+// The binders waiting for a scene, WEAKLY: a view never placed must not pin its node. Tried whenever the scene graph
+// grows (bindPendingViews) — an empty set costs that call one size check.
+const pendingViews = new Set<WeakRef<ViewBinder>>()
+/** @internal Start `binder`'s view now if its node is in a scene, else at the scene.add / node.add that puts it in one.
+ *  One try per placement: a view the host refuses (an overlay scene) warns and is not retried. */
+export const awaitScene = (binder: ViewBinder): void => {
+  const sceneId = sceneIdOf(binder)
+  if (sceneId >= 0) binder._bindView(sceneId)
+  else pendingViews.add(new WeakRef(binder))
+}
+/** @internal The scene graph grew (scene.add, node.add, setParent): start the waiting views whose node is in a scene now. */
+export const bindPendingViews = (): void => {
+  if (pendingViews.size === 0) return
+  for (const ref of pendingViews) {
+    const binder = ref.deref()
+    if (!binder) { pendingViews.delete(ref); continue }
+    const sceneId = sceneIdOf(binder)
+    if (sceneId < 0) continue
+    pendingViews.delete(ref)
+    binder._bindView(sceneId)
+  }
+}
+
 export class Node extends AspectHost<NodeEvents> implements CompWriter {
   /** @internal The entity's owned handle (`_h.id` = the entity id; DEAD_HANDLE once destroyed). An
    *  engine-created entity (a glTF part, an anchor) is wrapped from its number and pinned as the
@@ -101,6 +138,9 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
   _h: Handle
   /** Native entity id. */
   get id(): number { return this._h.id }
+  /** @internal The id of the scene `scene.add` put this node in (-1 = none; `scene.remove` clears it) — how a render
+   *  view finds its scene (sceneIdOf). */
+  _inScene = -1
 
   private _matrix?: Float32Array
   private _worldMatrix?: Float32Array
@@ -132,6 +172,25 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
   set name(value: string) { _creator.setName(this.id, value) }
   get visible(): boolean { return _creator.isVisible(this.id) }
   set visible(value: boolean) { _creator.setVisible(this.id, value) }
+  /**
+   * 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 { return _creator.getLayer ? _creator.getLayer(this.id) : 1 }
+  set layer(mask: number) {
+    if (_creator.setLayer) _creator.setLayer(this.id, mask & 0xff)
+    else if (!Node._warnedLayer) {
+      Node._warnedLayer = true
+      console.warn("[node] this host has no setLayer — node layers are ignored, every view draws everything")
+    }
+  }
+  private static _warnedLayer = false
 
   // --- local transform ---
   // Native owns the authoritative matrix. `_sync()` reads it into a per-node scratch buffer on EVERY
@@ -317,6 +376,7 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
   /** Parent the given nodes under this one. */
   add(...children: Node[]): this {
     for (const c of children) { _creator.setParent(c.id, this.id, false); nodes.pin(c) }
+    bindPendingViews()
     return this
   }
   setParent(parent: Node | null, worldPositionStays = false): this {
@@ -326,6 +386,7 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
     } else {
       _creator.setParent(this.id, parent.id, worldPositionStays)
       nodes.pin(this)
+      bindPendingViews()
     }
     return this
   }

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)
+  }
+}