@solidrt/3d 0.0.63 → 0.0.64

package/src/mesh.ts

@@ -3,8 +3,10 @@
 // setter write paths that keep a live scene's draw entries in step. The
 // scene side is reached through the node's SceneHooks (node.ts).
 
-import { createBuffer, destroyBuffer, destroyTexture, writeBuffer } from "@solidrt/core/gpu"
+import { beginBufferWrite, createBuffer, destroyBuffer, destroyTexture, endBufferWrite, transferRecords, writeBuffer } from "@solidrt/core/gpu"
 import type { BufferId, DrawId, ShaderParams, TextureBindings, TextureId, VertexAttribute, VertexBufferLayout } from "@solidrt/core/gpu"
+import { checkCubeKnobs } from "./environment.ts"
+import type { EnvironmentOptions } from "./environment.ts"
 import { geometryBounds, isFloatLayout, layoutKey, layoutStride, plane, vertexBytes, vertexView, VERTEX_FORMATS } from "./geometry.ts"
 import type { AttributeAccess, Geometry } from "./geometry.ts"
 import { INSTANCE_MATRIX_ATTRIBUTES } from "./glsl.ts"
@@ -32,6 +34,15 @@ export type Mesh = SceneNode & {
    * target draws the mesh when its mask intersects this. Not inherited
    * from ancestor Groups (Three's and Godot's rule). Set with setLayers. */
   layers: number
+  /** This mesh's environment instead of the scene's (resolved; set with
+   * setEnvironment): the cube its image-lit and reflective terms sample,
+   * `null` for NONE (a sealed interior under an outdoor sky reflects and
+   * receives no sky), `undefined` (the default) to follow the scene's,
+   * live through scene.setEnvironment. Applied where the material
+   * reflects at all (Material.env - `standard`, `phong` with
+   * `reflectivity`, a custom source composing ENVIRONMENT); on any other
+   * material it is a no-op, so an interior can be masked wholesale. */
+  environment: { cube: TextureId; intensity: number; rotation: number } | null | undefined
   /** Whether every target's frustum gates the mesh (default true, Three's
    * `frustumCulled`): outside it the entry draws nothing. Off for geometry
    * a vertex stage moves beyond its box (a fullscreen quad, a custom
@@ -130,6 +141,31 @@ export type MeshInstances = {
    * shader reads at row gl_InstanceID. Replaced on growth (the entries
    * re-point), freed by disposeInstances. */
   morph: { texture: TextureId; rows: number } | null
+  /** The mesh's instanceOrder resolved against its material's instance
+   * layouts (see InstanceOrderOptions), or null for buffer order. Fixed
+   * at creation; slots as the app writes them never move. */
+  order: ResolvedInstanceOrder | null
+  /** Whether the records were transferred to the engine at creation
+   * (RecordMeshOptions.transfer, or an indexed instanceOrder): no JS-side
+   * mirror exists, the population is write-once, and rewrites/growth/
+   * attribute access throw. Fixed at creation; always false on an
+   * instanced mesh. */
+  transfer: boolean
+  /** Records per drawn instance: 1, or on an indexed instanceOrder the
+   * ids per id-stream record (the entry's instanceCount is
+   * ceil(count / group), see drawCount). Fixed at creation. */
+  group: number
+  /** Data textures the population owns (an indexed population's record
+   * texture and the like, created by whoever built the mesh), freed by
+   * disposeInstances with the buffers. */
+  textures: TextureId[]
+}
+
+/** The draw's instance count for a population: its records over the
+ * records per instance, rounded up (an indexed population's last group
+ * pads with the engine's sentinel ids). */
+export function drawCount(inst: MeshInstances): number {
+  return Math.ceil(inst.count / inst.group)
 }
 
 export type InstanceSlots = { slots: (InstanceNode | null)[]; free: number[] }
@@ -213,6 +249,7 @@ export function createMesh(geometry: Geometry, material: Material): Mesh {
   mesh.renderOrder = 0
   mesh.castShadow = false
   mesh.layers = 1
+  mesh.environment = undefined
   mesh.frustumCulled = true
   mesh.cullMargin = 0
   mesh._cullJoints = null
@@ -341,6 +378,55 @@ function makeStream(layout: VertexAttribute[], capacity: number, blank: Uint8Arr
   return stream
 }
 
+// The indexed order's stream: the id buffer the core writes whole with the
+// sorted record indices (ceil(capacity / group) instance records of
+// `group` u32 ids each; it starts zeroed and the entry's attach seeds the
+// first sort), the records handed to the core's order mirror as the key
+// source. No JS mirror exists, as under transfer.
+function makeIndexStream(layout: VertexAttribute[], capacity: number, group: number, records: Uint8Array, label: string | undefined): InstanceStream {
+  let stride = layoutStride(layout)
+  let stream: InstanceStream = {
+    layout,
+    stride,
+    buffer: createBuffer(Math.ceil(capacity / group) * stride, { autoFree: false, label }),
+    data: new Uint8Array(0),
+    blank: new Uint8Array(stride),
+    dirty: null,
+    _view: new DataView(new ArrayBuffer(0)),
+    _floats: false,
+    _components: layoutComponents(layout),
+    _fields: [],
+  }
+  transferRecords(stream.buffer, records)
+  return stream
+}
+
+// The transfer form's stream: records go to the engine at creation and no
+// JS mirror exists (data stays a zero-length view; the operations that
+// would read or write it throw on the transfer flag first). An ordered
+// stream hands the records to the core's order mirror - the entry's
+// attach publishes the first gather, so the buffer starts zeroed; an
+// unordered one is its own upload, the buffer created with the records.
+function makeTransferredStream(layout: VertexAttribute[], records: Uint8Array, ordered: boolean, label: string | undefined): InstanceStream {
+  let stride = layoutStride(layout)
+  let stream: InstanceStream = {
+    layout,
+    stride,
+    buffer: ordered
+      ? createBuffer(records.byteLength, { autoFree: false, label })
+      : createBuffer(records, { autoFree: false, label }),
+    data: new Uint8Array(0),
+    blank: new Uint8Array(stride),
+    dirty: null,
+    _view: new DataView(new ArrayBuffer(0)),
+    _floats: isFloatLayout(layout),
+    _components: layoutComponents(layout),
+    _fields: [],
+  }
+  if (ordered) transferRecords(stream.buffer, records)
+  return stream
+}
+
 // Encode `values` (one per component, in layout order, as the shader
 // sees them) into record `i` of a stream: one typed-array set over an
 // all-float layout (the values ARE the bytes), the codecs otherwise.
@@ -380,6 +466,155 @@ function markRecords(mesh: Mesh, stream: InstanceStream, lo: number, hi: number)
   mesh._scene?._setRecords(mesh)
 }
 
+/**
+ * Draw a population's records in key order, decided core-side - the
+ * engine's instance order riding the mesh's record streams
+ * (createInstancedMesh and createRecordMesh both take it). Record slots
+ * never move: the app keeps writing slot i forever, and the engine
+ * gathers the records into key order as they publish.
+ *
+ * `position` names an instance attribute (float32x3 or float32x4) whose
+ * first three floats are a position in the mesh's local space: records
+ * draw by their depth along the scene camera's view direction, which the
+ * core feeds itself whenever the camera or the mesh turns meaningfully -
+ * zero per-frame JS, and a parked camera costs nothing. `descending:
+ * true` draws farthest first, the transparent blend order. The order
+ * follows the scene's OWN camera: one buffer holds one order, so views
+ * draw the same records in that order, and a mesh masked out of the
+ * scene target keeps its last order. `retain: true` opts a write-once
+ * population (a splat cloud) into the engine's retained copy: a camera
+ * turn re-sorts and republishes core-side with no publish from here, and
+ * an order-preserving turn uploads nothing.
+ *
+ * `field` names a float32 instance attribute: records draw by that value
+ * as the app wrote it (an age, an explicit sort key), re-ordered when
+ * the records publish.
+ *
+ * An ordered mesh gives up partial record publishes: any write sends the
+ * live record set whole, gathered (a byte range has no stable position
+ * under a permutation).
+ *
+ * The INDEXED form (`records`) is for a population whose records live in
+ * a data texture the shader fetches by record index (a splat cloud):
+ * `records` is the layout of the records createRecordMesh received -
+ * `position` names a float32x3/x4 attribute IN THAT LAYOUT - and the
+ * material's one instance buffer is the ID STREAM, uint32/uint32x4
+ * attributes the engine fills with the sorted record indices, K ids per
+ * instance record so one drawn instance covers K records (the
+ * geometry repeats K times; `gl_VertexID` picks the id). The records go
+ * to the engine at creation (transfer implied, retain by nature) as the
+ * sort's key source; the app uploads the same bytes as its texture. A
+ * re-sort then uploads 4 bytes per record instead of the record, and
+ * the last instance's group past `count` carries 0xFFFFFFFF, which the
+ * shader culls before fetching.
+ */
+export type InstanceOrderOptions =
+  | (({ position: string; retain?: boolean } | { field: string }) & {
+      /** Largest key first - back-to-front for a position key. Default false. */
+      descending?: boolean
+    })
+  | {
+      /** The position attribute of the record layout below. */
+      position: string
+      /** The layout of the handed-off records the shader fetches by
+       * index; the material's instance buffer is the id stream. */
+      records: VertexAttribute[]
+      /** Largest key first - back-to-front. Default false. */
+      descending?: boolean
+    }
+
+/** The instanceOrder resolved against the material's instance layouts at
+ * creation: the key stream's layout key (the entry's pipeline buffer is
+ * found by it at attach, exactly as buffer bindings are), the key's
+ * float offset inside one record, and the declared knobs. */
+export type ResolvedInstanceOrder = {
+  key: string
+  floats: number
+  position: boolean
+  descending: boolean
+  retain: boolean
+  /** The index materialization (InstanceOrderOptions' `records` form):
+   * the handed-off record's byte stride; null for gathered records. */
+  indices: { stride: number } | null
+}
+
+// Resolve an instanceOrder option against the material's instance
+// layouts: the named attribute must exist in one of them, hold floats of
+// the key's shape, and start on a 4-byte boundary of its record. The
+// indexed form resolves the key in the given record layout instead, and
+// the material's one instance buffer must be whole u32 ids.
+function resolveInstanceOrder(order: InstanceOrderOptions | undefined, buffers: VertexBufferLayout[], site: string): ResolvedInstanceOrder | null {
+  if (order === undefined) return null
+  if ("records" in order) {
+    if (buffers.length !== 1) {
+      throw new Error(site + ": an indexed instanceOrder takes a material with one instance buffer (the id stream); this one declares " + buffers.length)
+    }
+    let ids = buffers[0]!.attributes
+    for (let a of ids) {
+      if (!a.format.startsWith("uint32")) throw new Error(site + ": the id stream's attribute '" + a.name + "' must be uint32, uint32x2, uint32x3 or uint32x4 (whole record ids), got " + a.format)
+    }
+    let stride = layoutStride(order.records)
+    if (stride === 0 || stride % 4 !== 0) throw new Error(site + ": the indexed record layout is " + stride + " bytes; records must be whole floats")
+    let at = 0
+    for (let a of order.records) {
+      if (a.name === order.position) {
+        if (a.format !== "float32x3" && a.format !== "float32x4") {
+          throw new Error(site + ": instanceOrder position attribute '" + a.name + "' must be float32x3 or float32x4, got " + a.format)
+        }
+        if (at % 4 !== 0) throw new Error(site + ": instanceOrder key attribute '" + a.name + "' starts at byte " + at + " of its record; the key must start on a 4-byte boundary")
+        return { key: layoutKey(ids), floats: at / 4, position: true, descending: order.descending === true, retain: true, indices: { stride } }
+      }
+      at += VERTEX_FORMATS[a.format].bytes
+    }
+    throw new Error(site + ": instanceOrder names attribute '" + order.position + "', which the record layout does not declare")
+  }
+  let position = "position" in order
+  let name = position ? (order as { position: string }).position : (order as { field: string }).field
+  if (!position && (order as { retain?: boolean }).retain !== undefined) {
+    throw new Error(site + ": instanceOrder retain applies to a position key; a field key re-orders when its records publish")
+  }
+  for (let b of buffers) {
+    let at = 0
+    for (let a of b.attributes) {
+      if (a.name === name) {
+        if (position && a.format !== "float32x3" && a.format !== "float32x4") {
+          throw new Error(site + ": instanceOrder position attribute '" + name + "' must be float32x3 or float32x4, got " + a.format)
+        }
+        if (!position && a.format !== "float32") {
+          throw new Error(site + ": instanceOrder field attribute '" + name + "' must be float32, got " + a.format)
+        }
+        if (at % 4 !== 0) {
+          throw new Error(site + ": instanceOrder key attribute '" + name + "' starts at byte " + at + " of its record; the key must start on a 4-byte boundary")
+        }
+        return {
+          key: layoutKey(b.attributes),
+          floats: at / 4,
+          position,
+          descending: order.descending === true,
+          retain: position && (order as { retain?: boolean }).retain === true,
+          indices: null,
+        }
+      }
+      at += VERTEX_FORMATS[a.format].bytes
+    }
+  }
+  throw new Error(site + ": instanceOrder names attribute '" + name + "', which no instance buffer of the material declares")
+}
+
+/**
+ * Whether a material still carries the layout an ordered mesh keys on
+ * (the key stream must be one of the buffers the entry binds). Throws
+ * naming `site`; checked beside the instance pairing at add().
+ */
+export function checkOrderPairing(material: Material, inst: MeshInstances, site: string): void {
+  if (inst.order === null) return
+  let buffers = material.instanceBuffers ?? []
+  let key = inst.order.key
+  if (!buffers.some(b => layoutKey(b.attributes) === key)) {
+    throw new Error(site + ": the material declares no instance buffer with the mesh's instanceOrder key layout (" + key + ")")
+  }
+}
+
 /** What both population kinds take. */
 type PopulationOptions = {
   /** LOCAL bounds covering the population ([minX, minY, minZ, maxX, maxY,
@@ -392,6 +627,10 @@ type PopulationOptions = {
    * follows them) and sorts by its node position; a record mesh is never
    * culled and never picked. */
   bounds?: ArrayLike<number>
+  /** Draw the records in key order, decided core-side (see
+   * InstanceOrderOptions): back-to-front for a transparent population, an
+   * explicit sort field for a JS-stepped one. Fixed at creation. */
+  instanceOrder?: InstanceOrderOptions
   /** Debug label for the record buffer. */
   label?: string
 }
@@ -421,7 +660,20 @@ export type InstancedMeshOptions = PopulationOptions & {
 /** A record mesh's bounds are also its ONLY picking leaf: records are
  * opaque data, so without them the mesh never picks and pointer events
  * never target it. */
-export type RecordMeshOptions = PopulationOptions
+export type RecordMeshOptions = PopulationOptions & {
+  /** Transfer the records to the engine at creation - the write-once
+   * form for a large population (a baked splat cloud): the engine keeps
+   * the one CPU-side copy, and the mesh keeps NO mirror, so the records
+   * are resident once instead of twice and the creation bytes are free
+   * to drop the moment this returns. The population is write-once by
+   * contract: setRecords, updateRecords, instanceAttribute and growth
+   * throw; setRecordCount (an ordered mesh republishes the prefix
+   * core-side), setVisible, transforms, re-attach and disposeInstances
+   * all still work. Takes a single-stream material; with an
+   * instanceOrder the engine's retained copy is implied (`retain` is
+   * forced on). Default false. */
+  transfer?: boolean
+}
 
 function copyBounds(bounds: ArrayLike<number> | undefined, site: string): Float32Array | null {
   if (bounds === undefined) return null
@@ -522,6 +774,10 @@ export function createInstancedMesh(geometry: Geometry, material: Material, opts
     anchor: opts?.anchor ?? null,
     levels: null,
     morph: populationMorph(geometry, capacity, opts?.label),
+    order: resolveInstanceOrder(opts?.instanceOrder, buffers, "createInstancedMesh"),
+    transfer: false,
+    group: 1,
+    textures: [],
   }
   return mesh
 }
@@ -602,6 +858,7 @@ export function setInstanceStyle(instance: InstanceNode, values: ArrayLike<numbe
 export function instanceAttribute(mesh: InstancedMesh | RecordMesh, name: string): AttributeAccess | null {
   let inst: MeshInstances | null = mesh._instances
   if (inst === null) throw new Error("instanceAttribute: the mesh's instances are disposed")
+  if (inst.transfer) throw new Error("instanceAttribute: the records were transferred at creation (transfer: true) - there is no mirror to read or write")
   for (let s of inst.streams) {
     let i = s.layout.findIndex(a => a.name === name)
     if (i >= 0) return s._fields[i]!
@@ -625,6 +882,7 @@ export type UpdateRecordsOptions = { stream?: number; first?: number; count?: nu
 export function updateRecords(mesh: InstancedMesh | RecordMesh, options: UpdateRecordsOptions = {}): void {
   let inst: MeshInstances | null = mesh._instances
   if (inst === null) throw new Error("updateRecords: the mesh's instances are disposed")
+  if (inst.transfer) throw new Error("updateRecords: the records were transferred at creation (transfer: true) - there is no mirror to publish from")
   let index = options.stream ?? 0
   let stream = inst.streams[index]
   if (!Number.isInteger(index) || stream === undefined) {
@@ -639,10 +897,25 @@ export function updateRecords(mesh: InstancedMesh | RecordMesh, options: UpdateR
 }
 
 /** Publish a mesh's pending record writes, one buffer write per dirty
- * stream (the scene calls it from its sync). */
+ * stream (the scene calls it from its sync). An ordered mesh publishes
+ * the LIVE record set whole through the write lease - the engine gathers
+ * it into key order during the copy, and a byte range has no stable
+ * position under a permutation (writeBuffer throws on an ordered buffer). */
 export function publishRecords(mesh: Mesh): void {
   let inst = mesh._instances
   if (inst === null) return
+  if (inst.order !== null) {
+    for (let s of inst.streams) {
+      if (s.dirty === null) continue
+      s.dirty = null
+      let bytes = inst.count * s.stride
+      if (bytes === 0) continue
+      let block = beginBufferWrite(s.buffer)
+      new Uint8Array(block.buffer, 0, bytes).set(vertexBytes(s.data).subarray(0, bytes))
+      endBufferWrite(s.buffer, bytes)
+    }
+    return
+  }
   for (let s of inst.streams) {
     if (s.dirty === null) continue
     let [lo, hi] = s.dirty
@@ -651,6 +924,18 @@ export function publishRecords(mesh: Mesh): void {
   }
 }
 
+/** @internal Mark every stream's live records dirty, so the next sync
+ * republishes the population whole: an ordered mesh (re-)entering a
+ * scene seeds the entry's freshly built engine-side order registry from
+ * the JS mirrors. */
+export function markLiveRecords(mesh: Mesh): void {
+  let inst = mesh._instances
+  // A transferred mesh has no mirror; the engine's own (buffer-lifetime)
+  // mirror seeds a re-attached entry instead.
+  if (inst === null || inst.count === 0 || inst.transfer) return
+  for (let s of inst.streams) markRecords(mesh, s, 0, inst.count * s.stride)
+}
+
 /**
  * Add an instance to an instanced mesh: a scene node placed by `update`
  * (position/rotation/quaternion/scale; absent keys at their identity)
@@ -739,6 +1024,7 @@ export function reparentInstance(instance: InstanceNode, parent: SceneNode): voi
 // are freed.
 function growInstances(mesh: InstancedMesh | RecordMesh, next: number): void {
   let inst: MeshInstances = mesh._instances
+  if (inst.transfer) throw new Error("growInstances: a transferred population is fixed at its creation records")
   let previous = inst.capacity
   inst.capacity = next
   let freed: BufferId[] = []
@@ -785,11 +1071,42 @@ export function createRecordMesh(
   opts?: RecordMeshOptions,
 ): RecordMesh {
   let buffers = instancedBuffers(material, "createRecordMesh")
-  let capacity = recordCount(records, buffers[0]!.attributes, "createRecordMesh")
+  let order = resolveInstanceOrder(opts?.instanceOrder, buffers, "createRecordMesh")
+  let indices = order?.indices ?? null
+  if (indices !== null && opts?.transfer === false) {
+    throw new Error("createRecordMesh: an indexed instanceOrder hands the records to the engine by nature; transfer cannot be false")
+  }
+  let transfer = opts?.transfer === true || indices !== null
+  if (transfer && buffers.length !== 1) {
+    throw new Error(
+      "createRecordMesh: transfer takes a single-stream material; this one declares " + buffers.length + " instance buffers (further streams need the partial writes transfer gives up)",
+    )
+  }
+  // Under an indexed order the records are laid out by the order's record
+  // layout, not the material's (whose one buffer is the id stream).
+  let capacity: number
+  if (indices !== null) {
+    if (records.byteLength === 0 || records.byteLength % indices.stride !== 0) {
+      throw new Error("createRecordMesh: records hold " + records.byteLength + " bytes, not a positive whole number of " + indices.stride + "-byte records")
+    }
+    capacity = records.byteLength / indices.stride
+  } else {
+    capacity = recordCount(records, buffers[0]!.attributes, "createRecordMesh")
+  }
+  // A transferred order always retains: the engine's mirror is the ONE
+  // record copy, what re-attaches seed from and count changes republish
+  // (a field key gets the same retention, engine-side only).
+  if (transfer && order !== null && !order.retain) order = { ...order, retain: true }
   let mesh = createMesh(geometry, material) as RecordMesh
+  let group = indices !== null ? layoutStride(buffers[0]!.attributes) / 4 : 1
   mesh._instances = {
     matrix: null,
-    streams: buffers.map((b, i) => makeStream(b.attributes, capacity, null, streamLabel(opts?.label, i))),
+    streams:
+      indices !== null
+        ? [makeIndexStream(buffers[0]!.attributes, capacity, group, vertexBytes(records), streamLabel(opts?.label, 0))]
+        : transfer
+          ? [makeTransferredStream(buffers[0]!.attributes, vertexBytes(records), order !== null, streamLabel(opts?.label, 0))]
+          : buffers.map((b, i) => makeStream(b.attributes, capacity, null, streamLabel(opts?.label, i))),
     capacity,
     label: opts?.label,
     count: Math.max(0, Math.min(Math.floor(count ?? capacity), capacity)),
@@ -798,8 +1115,12 @@ export function createRecordMesh(
     anchor: null,
     levels: null,
     morph: null,
+    order,
+    transfer,
+    group,
+    textures: [],
   }
-  copyRecords(mesh, records, capacity)
+  if (!transfer) copyRecords(mesh, records, capacity)
   return mesh
 }
 
@@ -829,6 +1150,7 @@ function copyRecords(mesh: RecordMesh, records: ArrayBufferView, written: number
  */
 export function setRecords(mesh: RecordMesh, records: ArrayBufferView, count?: number): void {
   let inst = mesh._instances
+  if (inst.transfer) throw new Error("setRecords: the records were transferred at creation (transfer: true) - the population is write-once; mount a new mesh for new records")
   let written = recordCount(records, inst.streams[0]!.layout, "setRecords")
   if (written > inst.capacity) growInstances(mesh, Math.max(written, inst.capacity * 2))
   copyRecords(mesh, records, written)
@@ -842,6 +1164,12 @@ export function setRecordCount(mesh: RecordMesh, count: number): void {
   let n = Math.max(0, Math.min(Math.floor(count), inst.capacity))
   if (n === inst.count) return
   inst.count = n
+  // Ordered records draw the first n GATHERED records, so a count change
+  // republishes the live set - a shrink would otherwise keep drawing the
+  // old population's nearest records, a growth its stale tail. A
+  // transferred mesh has no mirror to publish from; the engine follows
+  // the entry's instance count into its own mirror's prefix instead.
+  if (inst.order !== null && !inst.transfer && n > 0) for (let s of inst.streams) markRecords(mesh, s, 0, n * s.stride)
   mesh._scene?._setCount(mesh)
 }
 
@@ -882,6 +1210,7 @@ export function disposeInstances(mesh: InstancedMesh | RecordMesh): void {
   if (inst.matrix !== null) destroyBuffer(inst.matrix)
   for (let s of inst.streams) destroyBuffer(s.buffer)
   if (inst.morph !== null) destroyTexture(inst.morph.texture)
+  for (let t of inst.textures) destroyTexture(t)
   ;(mesh as Mesh)._instances = null
 }
 
@@ -919,6 +1248,32 @@ export function setCastShadow(mesh: Mesh, cast: boolean): void {
   for (let l of mesh._instances?.levels ?? []) if (l !== mesh) setCastShadow(l, cast)
 }
 
+/**
+ * Give the mesh an environment of its own, or none: `null` removes the
+ * environment term entirely - a sealed interior under an outdoor sky,
+ * where light `layers` mask the sun but cannot mask image lighting -
+ * `{ cube, intensity?, rotation? }` samples that cube instead of the
+ * scene's (an interior probe's chain, a baked room), and `undefined`
+ * (the default) follows the scene's, live through scene.setEnvironment.
+ * Unity's reflectionProbeUsage Off and Three's `material.envMap`, per
+ * MESH, because materials are shared and interiors are mesh-grained
+ * here. Applied where the material reflects at all (Material.env); a
+ * no-op on any other material. The mesh's entries are rebuilt, so this
+ * is a state change (a camera crossing a doorway), not a frame-rate
+ * dial. A reflection probe drawing this mesh never samples its own cube
+ * through it (the black placeholder stands in, the same-pass rule).
+ */
+export function setEnvironment(mesh: Mesh, environment: EnvironmentOptions | null | undefined): void {
+  let next = environment == null ? environment : { cube: environment.cube, ...checkCubeKnobs(environment, "setEnvironment") }
+  let a = mesh.environment
+  let same = next == null || a == null ? next === a : next.cube === a.cube && next.intensity === a.intensity && next.rotation === a.rotation
+  if (same) return
+  mesh.environment = next
+  rebuildEntry(mesh)
+  // An instanced LOD's levels reflect what the population reflects.
+  for (let l of mesh._instances?.levels ?? []) if (l !== mesh) setEnvironment(l, environment)
+}
+
 /** Frustum culling per mesh: `frustumCulled` (default true) switches the
  * gate, `cullMargin` (world units, default 0) grows the tested box. */
 export function setCulling(mesh: Mesh, options: { frustumCulled?: boolean; cullMargin?: number }): void {

package/src/node.ts

@@ -163,6 +163,9 @@ export type SceneHooks = {
   _setLayers(mesh: Mesh): void
   /** A light's castShadow/shadow options changed. */
   _shadowChanged(light: CastingLight): void
+  /** A light's layers mask changed: re-filter its shadow views' casters
+   * (the uniform rewrite rides the _lightChanged that follows). */
+  _lightLayersChanged(light: Light): void
   _reorder(mesh: Mesh): void
   /** The node's transform changed (for the sort and light bookkeeping). */
   _moved(node: SceneNode): void

package/src/scene-shadows.ts

@@ -80,8 +80,9 @@ export type ShadowSystemDeps<V extends ShadowView> = {
   targetSize(): { width: number; height: number }
   /** Base debug label ("scene" by default). */
   label: string
-  /** Make one shadow view: a tile of `into` drawing `filter`'s meshes
-   * with the depth override (the scene's makeView). */
+  /** Make one shadow view for `light`: a tile of `into` drawing the
+   * casting meshes the light's layers admit with the depth override (the
+   * scene's makeView derives the caster filter and the layer mask). */
   makeView(
     vopts: {
       width: number
@@ -93,7 +94,7 @@ export type ShadowSystemDeps<V extends ShadowView> = {
       clearColor: [number, number, number, number]
       label: string
     },
-    filter: (mesh: Mesh) => boolean,
+    light: CastingLight,
   ): V
   disposeView(view: V): void
   /** The light set changed shape: the scene owes a writeLights. */
@@ -203,9 +204,9 @@ export function makeShadowSystem<V extends ShadowView>(deps: ShadowSystemDeps<V>
     deps.schedule()
   }
   // A caster's views: one square tile of the shadow atlas per map,
-  // drawing the casting meshes with the depth override from that map's
-  // frustum. The light rewrite writes the rects in the light's slots on
-  // every receiving target.
+  // drawing the casting meshes the light's layers admit with the depth
+  // override from that map's frustum. The light rewrite writes the rects
+  // in the light's slots on every receiving target.
   let createShadow = (light: CastingLight, rects: ShadowRect[]) => {
     let atlas = shadowAtlas!
     let views = rects.map(rect =>
@@ -220,7 +221,7 @@ export function makeShadowSystem<V extends ShadowView>(deps: ShadowSystemDeps<V>
           clearColor: [1, 1, 1, 1],
           label: deps.label + "-shadow",
         },
-        m => m.castShadow,
+        light,
       ),
     )
     shadows.set(light, { light, views, lastWorld: mat4(), dirty: true, rects })