@solidrt/3d 0.0.62 → 0.0.64

package/src/components/splat-mesh.tsx

@@ -0,0 +1,50 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { syncMesh } from "./mesh.tsx"
+import type { PopulatedMeshProps } from "./mesh.tsx"
+import { add, destroy } from "../node.ts"
+import { disposeInstances, setRecordCount } from "../mesh.ts"
+import { createSplatMesh } from "../splat.ts"
+import type { SplatMesh as SplatMeshNode, SplatMeshOptions } from "../splat.ts"
+import type { SplatData } from "../splat-data.ts"
+
+export type SplatMeshProps = PopulatedMeshProps & {
+  /** The baked cloud (loadSplat). Write-once: the records went to the
+   * engine and the data textures at creation, so treat the SplatData as
+   * consumed and swap clouds by remounting (a keyed <Show>), not by a new
+   * `data` value. */
+  data: SplatData
+  /** How many splats draw; default all. Records are importance-sorted at
+   * bake, so the first n are the scene at n - the LOD/bench dial (rounded
+   * up to whole groups of SPLAT_GROUP). */
+  count?: number
+  /** A custom splat material (see SplatMeshOptions); fixed at creation. */
+  material?: SplatMeshOptions["material"]
+  ref?: (mesh: SplatMeshNode) => void
+}
+
+/** A baked splat cloud in the scene (createSplatMesh as a component): an
+ * ordinary record mesh in the indexed form, drawn back to front by the
+ * core-side order with the scene feeding the view direction - no
+ * per-frame JS anywhere. The id buffer, the engine's record copy and the
+ * data textures are component-owned and freed on unmount. */
+export let SplatMesh: VoidComponent<SplatMeshProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() => createSplatMesh(props.data, { count: props.count, material: props.material }))
+  add(ctx.parent, mesh)
+  createEffect(
+    () => props.count,
+    c => {
+      if (c !== undefined) setRecordCount(mesh, c)
+    },
+    { defer: true },
+  )
+  syncMesh(mesh, props)
+  untrack(() => props.ref)?.(mesh)
+  onCleanup(() => {
+    destroy(mesh)
+    disposeInstances(mesh)
+  })
+  return null
+}

package/src/components/spot-light.tsx

@@ -14,6 +14,9 @@ export type SpotLightProps = TransformProps & {
   direction?: Vec3
   color?: Vec3
   intensity?: number
+  /** Layer filter bitmask, default all bits set: the light lights and
+   * shadows only the meshes whose `layers` intersect it. */
+  layers?: number
   /** Falloff cutoff in world units (0 = no cutoff). */
   distance?: number
   /** Cone half-angle in DEGREES, (0, 90]; default 60 (degrees like
@@ -43,6 +46,7 @@ export let SpotLight: VoidComponent<SpotLightProps> = props => {
       direction: props.direction,
       color: props.color,
       intensity: props.intensity,
+      layers: props.layers,
       distance: props.distance,
       angle: props.angle,
       penumbra: props.penumbra,
@@ -55,9 +59,9 @@ export let SpotLight: VoidComponent<SpotLightProps> = props => {
   syncNode(light, props)
   createEffect(
     () =>
-      [props.direction, props.color, props.intensity, props.distance, props.angle, props.penumbra, props.decay, props.castShadow, props.shadow] as const,
-    ([direction, color, intensity, distance, angle, penumbra, decay, castShadow, shadow]) =>
-      setLight(light, { direction, color, intensity, distance, angle, penumbra, decay, castShadow, shadow }),
+      [props.direction, props.color, props.intensity, props.layers, props.distance, props.angle, props.penumbra, props.decay, props.castShadow, props.shadow] as const,
+    ([direction, color, intensity, layers, distance, angle, penumbra, decay, castShadow, shadow]) =>
+      setLight(light, { direction, color, intensity, layers, distance, angle, penumbra, decay, castShadow, shadow }),
   )
   untrack(() => props.ref)?.(light)
   onCleanup(() => destroy(light))

package/src/environment.ts

@@ -324,3 +324,58 @@ export function createEnvironmentPlaceholder(label: string): TextureId {
   let black = new Uint8Array([0, 0, 0, 255])
   return createCubeTexture([black, black, black, black, black, black], 1, { autoFree: false, label })
 }
+
+/**
+ * An environment: a cube map every image-lit and reflective term samples
+ * (scene.setEnvironment for the scene's, `Mesh.environment` for one
+ * mesh's own). The same three fields as a skybox, and typically the same
+ * cube - Three's `scene.environment` with `environmentIntensity` and
+ * `environmentRotation`; Unity's environment reflections source, Godot's
+ * reflected light from the sky.
+ */
+export type EnvironmentOptions = {
+  /** A cube map (loadEnvironment's baked chain; equirectToCube for an LDR
+   * panorama; createCubeTexture with `mipmap: true` for a hand-baked
+   * sky), faces in +X, -X, +Y, -Y, +Z, -Z order, looked up like the
+   * skybox (no flip). A 2D texture id throws. */
+  cube: TextureId
+  /** Multiplier on the reflected color, >= 0; default 1. */
+  intensity?: number
+  /** Turn about world y in RADIANS (default 0), the skybox's convention:
+   * the environment turns as a node with rotation [0, r, 0] would. */
+  rotation?: number
+}
+
+// The uniform turn a rotated cube map is looked up through: the INVERSE
+// of the sky's turn, because a lookup along view direction v must find
+// the texel that sat at R(-r) v before the sky turned by +r.
+export function cubeTurn(rotation: number): number[] {
+  let c = Math.cos(rotation)
+  let n = Math.sin(rotation)
+  // prettier-ignore
+  return [
+    c, 0, n, 0,
+    0, 1, 0, 0,
+    -n, 0, c, 0,
+    0, 0, 0, 1,
+  ]
+}
+
+export function checkCubeKnobs(o: { intensity?: number; rotation?: number }, site: string): { intensity: number; rotation: number } {
+  let intensity = o.intensity ?? 1
+  let rotation = o.rotation ?? 0
+  if (!Number.isFinite(intensity) || intensity < 0) throw new Error(site + ": intensity must be a finite number >= 0, got " + intensity)
+  if (!Number.isFinite(rotation)) throw new Error(site + ": rotation must be a finite angle in radians, got " + rotation)
+  return { intensity, rotation }
+}
+
+// The params an environment compiles to (null = off: uEnvOn 0 makes the
+// phong weight vanish and uEnvIntensity 0 zeroes the radiance and
+// irradiance; the set ENVIRONMENT in `@solidrt/3d/glsl` declares them).
+// Target params for the scene's environment, entry params for a mesh's
+// own - the same names, and the entry's beat the target's.
+export function environmentParams(env: EnvironmentOptions | null, site: string): Record<string, number | number[]> {
+  if (env === null) return { uEnvIntensity: 0, uEnvRotation: cubeTurn(0), uEnvOn: 0 }
+  let k = checkCubeKnobs(env, site)
+  return { uEnvIntensity: k.intensity, uEnvRotation: cubeTurn(k.rotation), uEnvOn: 1 }
+}

package/src/glsl.ts

@@ -368,9 +368,12 @@ export const PBR = glsl`
  * unit vector TOWARD a directional light; a spot's axis toward the
  * light; unused for a point), `uLightPos[i]` (a spot's or point's world
  * position; unused for a directional), `uLightColor[i]` (rgb, intensity
- * folded in) and `uLightParams[i]` (cosInner, cosOuter, distance, decay
+ * folded in), `uLightParams[i]` (cosInner, cosOuter, distance, decay
  * - the cone cosines a spot fades between, the falloff cutoff and
- * exponent a spot or point attenuates by; unused for a directional).
+ * exponent a spot or point attenuates by; unused for a directional) and
+ * `uLightMask[i]` (the light's `layers` filter bitmask, all bits by
+ * default - lightVector skips a light whose mask misses the mesh's
+ * `uLayers`, see LIGHT_LOOKUP).
  * Compose it before LIGHT_LOOKUP; the stock lit program is the shape.
  */
 export const LIGHT_SLOTS = glsl`
@@ -380,6 +383,7 @@ export const LIGHT_SLOTS = glsl`
   uniform vec3 uLightPos[${MAX_LIGHTS}];
   uniform vec3 uLightColor[${MAX_LIGHTS}];
   uniform vec4 uLightParams[${MAX_LIGHTS}];
+  uniform int uLightMask[${MAX_LIGHTS}];
   const int LIGHT_DIRECTIONAL = 0;
   const int LIGHT_SPOT = 1;
   const int LIGHT_POINT = 2;
@@ -395,13 +399,24 @@ export const LIGHT_SLOTS = glsl`
  * spot's additionally faded across its cone from cosInner to cosOuter.
  * Zero means the light cannot reach the fragment - skip its shadow
  * lookup and its terms (the stock lit program does exactly that).
+ * The first test is the LAYER gate: a light whose `uLightMask[i]`
+ * misses the mesh's `uLayers` (the per-entry membership bitmask the
+ * scene seeds from `mesh.layers` and follows through setLayers) cannot
+ * reach it at all - Unity's cullingMask, Godot's light_cull_mask. Both
+ * operands are uniforms, so the branch is coherent per draw.
  */
 export const LIGHT_LOOKUP = glsl`
   // Floors the falloff divisors so a fragment at the light's own
   // position stays finite (Three's punctual-light rule).
   const float FALLOFF_MIN = 0.01;
 
+  uniform int uLayers;
+
   float lightVector(int i, vec3 worldPos, out vec3 l) {
+    if ((uLightMask[i] & uLayers) == 0) {
+      l = vec3(0.0);
+      return 0.0;
+    }
     if (uLightType[i] == LIGHT_DIRECTIONAL) {
       l = uLightDir[i];
       return 1.0;
@@ -523,6 +538,36 @@ export const SRGB = glsl`
   }
 `
 
+/**
+ * The buffer's blend space (SceneOptions.blendSpace): `uBlendSpace` is 0
+ * in a linear-light scene (the default; every scene writes it, since a
+ * shared program's uniform keeps the last drawn value across targets)
+ * and 1 in a display-space one, where the buffer holds sRGB-encoded
+ * display pixels and BLENDING runs on encoded values - what a capture
+ * trained against sRGB compositing expects. `vec3 blendSpaceOutput(vec3
+ * rgb, float alpha)` is the branch a buffer-writing fragment ends with:
+ * premultiplied linear in, and out either the same value (linear scene)
+ * or the un-premultiplied color clamped, encoded and re-premultiplied
+ * (display scene). Every stock fragment composes it through sceneOutput
+ * (and the skybox on its own); a CUSTOM fragment written for a
+ * display-space scene must end with it too, or its output blends in the
+ * wrong space. The encode carries its own name (not SRGB's
+ * linearToSrgb) so composing this set never collides with a fragment
+ * that also composes SRGB.
+ */
+export const BLEND_SPACE = glsl`
+  uniform float uBlendSpace;
+  vec3 blendSpaceEncode(vec3 c) {
+    c = clamp(c, 0.0, 1.0);
+    return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, c));
+  }
+  vec3 blendSpaceOutput(vec3 rgb, float alpha) {
+    if (uBlendSpace < 0.5) return rgb;
+    vec3 c = alpha > 0.0 ? rgb / alpha : rgb;
+    return blendSpaceEncode(c) * alpha;
+  }
+`
+
 /**
  * The LOD cross-fade: `uLodFade` is (threshold, side) - the scene writes
  * the band position of the level this entry draws (see createLod's
@@ -1079,7 +1124,8 @@ export type SceneSourceOptions = {
  *   vec4 sceneOutput(vec3 rgb, float alpha, vec3 position);
  *
  * `sceneLight` is light i seen from a world point: `dir` the unit vector
- * TOWARD it, `color` its rgb already attenuated (falloff, cone) and
+ * TOWARD it, `color` its rgb already attenuated (falloff, cone), layer
+ * masked (a light whose `layers` misses the mesh's, see LIGHT_LOOKUP) and
  * shadowed - zero when it cannot reach the fragment, and then no shadow
  * tap was spent. It is the accessor a custom light model loops over to
  * `uLightCount` (URP's GetAdditionalLight, Godot's light() inputs), and
@@ -1095,12 +1141,17 @@ export type SceneSourceOptions = {
  * stage carries the world position in.
  *
  * `sceneOutput` is the tail every library fragment ends with: fog over
- * the premultiplied color, clamped at zero, and that is the pixel the
- * scene buffer holds - LINEAR light, unclamped above (a sun disc of 40
- * stays 40 in a half-float buffer). Exposure, tone mapping and the sRGB
- * encode happen once per pixel in the target's resolve pass (RESOLVE),
- * never in a scene fragment: a fragment that writes fragColor directly
- * writes linear premultiplied light too.
+ * the premultiplied color, clamped at zero, then the blend-space branch
+ * (BLEND_SPACE), and that is the pixel the scene buffer holds. In a
+ * linear scene (the default) that is LINEAR light, unclamped above (a
+ * sun disc of 40 stays 40 in a half-float buffer), and exposure, tone
+ * mapping and the sRGB encode happen once per pixel in the target's
+ * resolve pass (RESOLVE), never in a scene fragment. In a display-space
+ * scene (SceneOptions.blendSpace) the tail encodes here instead, the
+ * buffer holds display pixels and there is no resolve. A fragment that
+ * writes fragColor directly follows the same contract: linear
+ * premultiplied light in a linear scene, blendSpaceOutput's result in a
+ * display-space one.
  *
  *   ${SCENE}
  *   void main() {
@@ -1125,6 +1176,7 @@ export function sceneSource(o: SceneSourceOptions = {}): string {
       lights
         ? `uniform vec3 uHemiSky;
     uniform vec3 uHemiGround;
+    uniform int uHemiMask;
     ${LIGHT_SLOTS}
     ${LIGHT_LOOKUP}`
         : ""
@@ -1147,10 +1199,11 @@ export function sceneSource(o: SceneSourceOptions = {}): string {
     ${env ? ENVIRONMENT : ""}
     ${fog ? FOG : ""}
     ${lights ? sceneShadeSource(receiveShadow, env) : ""}
+    ${BLEND_SPACE}
 
     vec4 sceneOutput(vec3 rgb, float alpha, vec3 position) {
       ${fog === "additive" ? "rgb = fogAdditive(rgb, position, uCamPos);" : fog ? "rgb = fog(rgb, alpha, position, uCamPos);" : ""}
-      return vec4(max(rgb, vec3(0.0)), alpha);
+      return vec4(blendSpaceOutput(max(rgb, vec3(0.0)), alpha), alpha);
     }
   `
 }
@@ -1160,8 +1213,9 @@ export const SCENE = sceneSource()
 
 // The light accessor and the two shade functions, over the sets
 // sceneSource composed before them. A light that cannot reach the point
-// is skipped whole (no shadow tap, no terms), the gate the stock lit
-// program always had.
+// - out of falloff, outside its cone, or layer-masked off the mesh - is
+// skipped whole (no shadow tap, no terms), the gate the stock lit
+// program always had. The hemisphere masks the same way (uHemiMask).
 function sceneShadeSource(receiveShadow: boolean, env: boolean): string {
   return glsl`
     struct SceneLight {
@@ -1180,7 +1234,7 @@ function sceneShadeSource(receiveShadow: boolean, env: boolean): string {
     vec3 shadeBlinn(Surface s, vec3 position) {
       vec3 n = s.normal;
       vec3 v = normalize(uCamPos - position);
-      vec3 light = hemisphere(n, uHemiSky, uHemiGround);
+      vec3 light = (uHemiMask & uLayers) != 0 ? hemisphere(n, uHemiSky, uHemiGround) : vec3(0.0);
       light += s.ambient;
       vec3 spec = vec3(0.0);
       for (int i = 0; i < ${MAX_LIGHTS}; i++) {
@@ -1201,7 +1255,7 @@ function sceneShadeSource(receiveShadow: boolean, env: boolean): string {
       vec3 v = normalize(uCamPos - position);
       vec3 diffuseColor = s.base.rgb * (1.0 - s.metalness);
       vec3 f0 = mix(vec3(DIELECTRIC_F0) * s.base.a, s.base.rgb, s.metalness);
-      vec3 light = hemisphere(n, uHemiSky, uHemiGround);
+      vec3 light = (uHemiMask & uLayers) != 0 ? hemisphere(n, uHemiSky, uHemiGround) : vec3(0.0);
       ${env ? "light += envIrradiance(n);" : ""}
       light += s.ambient;
       vec3 spec = vec3(0.0);

package/src/index.ts

@@ -7,8 +7,8 @@
 
 export { add, createGroup, destroy, getMorphNames, getMorphWeights, getRotation, getTransform, lookAt, remove, setMorphWeights, setTransform, setTransition, setVisible, worldPosition } from "./node.ts"
 export type { LodConfig, MorphWeights, NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneEventBase, SceneNode, ScenePointerEvent, ScenePointerListener, SceneTapEvent, SceneWheelEvent, TransformUpdate, TransitionEndEvent } from "./node.ts"
-export { addInstance, createInstancedMesh, createMesh, createRecordMesh, createSprite, disposeInstances, setCastShadow, setCulling, setDrawRange, setGeometry, setInstanceStyle, setLayers, setMaterial, setMeshParams, setRecordCount, setRecords, setRenderOrder, instanceAttribute, updateRecords, INSTANCE_FLOATS } from "./mesh.ts"
-export type { InstancedMesh as InstancedMeshNode, InstancedMeshOptions, InstanceNode, InstanceSlots, InstanceStream, Mesh as MeshNode, MeshInstances, RecordMesh as RecordMeshNode, RecordMeshOptions, UpdateRecordsOptions } from "./mesh.ts"
+export { addInstance, createInstancedMesh, createMesh, createRecordMesh, createSprite, disposeInstances, setCastShadow, setCulling, setDrawRange, setEnvironment, setGeometry, setInstanceStyle, setLayers, setMaterial, setMeshParams, setRecordCount, setRecords, setRenderOrder, instanceAttribute, updateRecords, INSTANCE_FLOATS } from "./mesh.ts"
+export type { InstancedMesh as InstancedMeshNode, InstancedMeshOptions, InstanceNode, InstanceOrderOptions, InstanceSlots, InstanceStream, Mesh as MeshNode, MeshInstances, RecordMesh as RecordMeshNode, RecordMeshOptions, UpdateRecordsOptions } from "./mesh.ts"
 export { createDirectionalLight, createHemisphereLight, createPointLight, createSpotLight, setLight } from "./light.ts"
 // The shader-source caps, also on the /glsl subpath next to the sources they size.
 export { MAX_CASCADES, MAX_LIGHTS, MAX_SHADOW_MAPS } from "./glsl.ts"
@@ -31,7 +31,7 @@ export { createInstancedLod, createLod, setLod } from "./lod.ts"
 export type { InstancedLodLevel, InstancedLodOptions, LodLevel, LodOptions } from "./lod.ts"
 export { createScene, resolveParams } from "./scene.ts"
 export { feedPointer } from "./scene-pointer.ts"
-export type { BloomOptions, Capsule, EnvironmentOptions, FogOptions, Hit, Impact, MoveOptions, MoveResult, OrientedBox, Overlap, QueryOptions, ReflectionProbe, ReflectionProbeOptions, ResolveInput, ResolveOptions, Scene as SceneHandle, SceneHandlers, SceneOptions, ScreenRay, SkyboxOptions, Sphere, ToneMapping, ViewHandle, ViewOptions, Volume } from "./scene.ts"
+export type { BlendSpace, BloomOptions, Capsule, EnvironmentOptions, FogOptions, Hit, Impact, MoveOptions, MoveResult, OrientedBox, Overlap, QueryOptions, ReflectionProbe, ReflectionProbeOptions, ResolveInput, ResolveOptions, Scene as SceneHandle, SceneHandlers, SceneOptions, ScreenRay, SkyboxOptions, Sphere, ToneMapping, ViewHandle, ViewOptions, Volume } from "./scene.ts"
 export { moveAndSlide } from "./collision.ts"
 export type { MoveScene } from "./collision.ts"
 export { bufferFormat, equirectToCube, loadEnvironment } from "./environment.ts"
@@ -49,7 +49,7 @@ export { extrude, lathe, pathFrames, polygon, sweep, tube } from "./sweep.ts"
 export type { ExtrudeOptions, LatheOptions, PathFrames, PathPoint, SweepPath, TubeOptions } from "./sweep.ts"
 export { phong, shaderMaterial, shaderMaterialClass, sprite, standard, unlit } from "./material.ts"
 export type { LitOptions, Material, PhongOptions, ShaderMaterialClass, ShaderMaterialClassOptions, ShaderMaterialInstanceOptions, ShaderMaterialOptions, SpriteOptions, StandardOptions, UnlitOptions } from "./material.ts"
-export { DirectionalLight, FirstPersonCamera, Group, HemisphereLight, Instance, InstancedLod, InstancedMesh, Lod, Mesh, OrbitCamera, PerspectiveCamera, PointLight, RecordMesh, Scene, SpotLight, Sprite, View3d, useScene, Shot, Shots } from "./components/index.ts"
+export { DirectionalLight, FirstPersonCamera, Group, HemisphereLight, Instance, InstancedLod, InstancedMesh, Lod, Mesh, OrbitCamera, PerspectiveCamera, PointLight, RecordMesh, Scene, SplatMesh, SpotLight, Sprite, View3d, useScene, Shot, Shots } from "./components/index.ts"
 export type {
   CameraTarget,
   DirectionalLightProps,
@@ -69,6 +69,7 @@ export type {
   RecordMeshProps,
   ScenePointerProps,
   SceneProps,
+  SplatMeshProps,
   SpotLightProps,
   SpriteProps,
   TransformProps,
@@ -81,6 +82,10 @@ export type { ModelChannel, ModelClip, ModelData, ModelExtras, ModelMaterial, Mo
 export { decodeModel, encodeModel } from "./model-file.ts"
 export { createModel, loadGltf, loadModel } from "./model.ts"
 export type { Model, ModelMaps, ModelOptions } from "./model.ts"
+export { decodeSplat, encodeSplat, parseSplat, SPLAT_ATTRIBUTES, SPLAT_RECORD_BYTES, SPLAT_RECORD_TEXELS, SPLAT_SH_TEXELS, SPLAT_TEXEL_BYTES } from "./splat-data.ts"
+export type { ParseSplatOptions, SplatData, SplatFormat } from "./splat-data.ts"
+export { createSplatMesh, loadSplat, splatMaterialClass, splatVertexSource, SPLAT_FRAGMENT, SPLAT_GROUP, SPLAT_ID_ATTRIBUTES } from "./splat.ts"
+export type { SplatMesh as SplatMeshNode, SplatMeshOptions } from "./splat.ts"
 export { bindSkeleton } from "./skeleton.ts"
 export type { BindSkeletonOptions } from "./skeleton.ts"
 export { createMixer } from "./mixer.ts"

package/src/light.ts

@@ -4,9 +4,14 @@
 
 import { MAX_CASCADES } from "./glsl.ts"
 import type { Vec3 } from "./math.ts"
+import { checkMask } from "./mesh.ts"
 import { makeNode } from "./node.ts"
 import type { SceneNode } from "./node.ts"
 
+// The default light layers mask: every bit set, so a light lights every
+// mesh unless told otherwise (the Unity and Godot default).
+const ALL_LAYERS = 0xffffffff
+
 /** The orthographic frustum a casting light renders its shadow map from,
  * in the light's own space (x right, y up, looking along its direction),
  * Three's DirectionalLightShadow camera. Everything outside it is lit. */
@@ -68,6 +73,10 @@ export type DirectionalLight = SceneNode & {
   /** Linear [r, g, b] 0..1. */
   color: Vec3
   intensity: number
+  /** Layer filter bitmask (default all bits set): the light lights and
+   * shadows only the meshes whose `layers` intersect it - Unity's
+   * cullingMask, Godot's light_cull_mask. Write through setLight. */
+  layers: number
   /** Render a shadow map from this light (any directional light may;
    * each map is a full extra pass over the casting meshes); meshes with
    * `castShadow` draw into it, `lit` materials read it (unless
@@ -91,6 +100,9 @@ export type SpotLight = SceneNode & {
   /** Linear [r, g, b] 0..1. */
   color: Vec3
   intensity: number
+  /** Layer filter bitmask (default all bits set; DirectionalLight.layers
+   * is the contract). */
+  layers: number
   /** Falloff cutoff in world units; the light is zero past it (0 = no
    * cutoff, Three's rule). */
   distance: number
@@ -146,6 +158,9 @@ export type PointLight = SceneNode & {
   /** Linear [r, g, b] 0..1. */
   color: Vec3
   intensity: number
+  /** Layer filter bitmask (default all bits set; DirectionalLight.layers
+   * is the contract). */
+  layers: number
   /** Falloff cutoff in world units (0 = no cutoff). */
   distance: number
   /** Falloff exponent (default 2). */
@@ -169,6 +184,10 @@ export type HemisphereLight = SceneNode & {
   sky: Vec3
   ground: Vec3
   intensity: number
+  /** Layer filter bitmask (default all bits set; DirectionalLight.layers
+   * is the contract): a mesh outside it gets no hemisphere term (its own
+   * `Surface.ambient` still applies). */
+  layers: number
 }
 
 export type Light = DirectionalLight | SpotLight | PointLight | HemisphereLight
@@ -185,6 +204,9 @@ export type DirectionalLightOptions = {
   direction?: Vec3
   color?: Vec3
   intensity?: number
+  /** Layer filter bitmask, default all bits set (the light lights and
+   * shadows only meshes whose `layers` intersect it). */
+  layers?: number
   castShadow?: boolean
   /** Shadow-map options, merged key by key (setLight keeps unmentioned ones). */
   shadow?: ShadowOptions
@@ -193,6 +215,8 @@ export type SpotLightOptions = {
   direction?: Vec3
   color?: Vec3
   intensity?: number
+  /** Layer filter bitmask, default all bits set. */
+  layers?: number
   distance?: number
   angle?: number
   penumbra?: number
@@ -204,13 +228,21 @@ export type SpotLightOptions = {
 export type PointLightOptions = {
   color?: Vec3
   intensity?: number
+  /** Layer filter bitmask, default all bits set. */
+  layers?: number
   distance?: number
   decay?: number
   castShadow?: boolean
   /** Shadow-map options, merged key by key (setLight keeps unmentioned ones). */
   shadow?: SpotShadowOptions
 }
-export type HemisphereLightOptions = { sky?: Vec3; ground?: Vec3; intensity?: number }
+export type HemisphereLightOptions = {
+  sky?: Vec3
+  ground?: Vec3
+  intensity?: number
+  /** Layer filter bitmask, default all bits set. */
+  layers?: number
+}
 
 // Every light may cast; the bound is the shadow-slot budget
 // (MAX_SHADOW_MAPS in glsl.ts, exported from the root with MAX_LIGHTS and
@@ -248,7 +280,14 @@ function mergeShadow(into: DirectionalLight["shadow"], update: ShadowOptions): v
   if (update.bias !== undefined) into.bias = update.bias
   if (update.normalBias !== undefined) into.normalBias = update.normalBias
   if (update.radius !== undefined) into.radius = checkRadius(update.radius)
-  if (update.camera !== undefined) Object.assign(into.camera, update.camera)
+  if (update.camera !== undefined) {
+    // Only the keys with a value: an undefined one is absent and keeps
+    // the extent, which the light projection reads as is.
+    for (let key of Object.keys(update.camera) as (keyof ShadowCamera)[]) {
+      let value = update.camera[key]
+      if (value !== undefined) into.camera[key] = value
+    }
+  }
   if (update.cascades !== undefined) {
     let n = update.cascades
     if (!Number.isInteger(n) || n < 1 || n > MAX_CASCADES) throw new Error("shadow.cascades must be an integer from 1 to " + MAX_CASCADES)
@@ -282,6 +321,7 @@ export function createDirectionalLight(opts: DirectionalLightOptions = {}): Dire
   light.direction = [...(opts.direction ?? [0, -1, 0])] as Vec3
   light.color = [...(opts.color ?? [1, 1, 1])] as Vec3
   light.intensity = opts.intensity ?? 1
+  light.layers = opts.layers !== undefined ? checkMask(opts.layers, "createDirectionalLight") : ALL_LAYERS
   light.castShadow = opts.castShadow === true
   light.shadow = { mapSize: 1024, bias: 0, normalBias: 0, radius: 1, camera: { left: -5, right: 5, top: 5, bottom: -5, near: 0.5, far: 500 }, cascades: 1, distance: null, splits: null }
   if (opts.shadow !== undefined) mergeShadow(light.shadow, opts.shadow)
@@ -295,6 +335,7 @@ export function createSpotLight(opts: SpotLightOptions = {}): SpotLight {
   light.direction = [...(opts.direction ?? [0, -1, 0])] as Vec3
   light.color = [...(opts.color ?? [1, 1, 1])] as Vec3
   light.intensity = opts.intensity ?? 1
+  light.layers = opts.layers !== undefined ? checkMask(opts.layers, "createSpotLight") : ALL_LAYERS
   light.distance = opts.distance ?? 0
   light.angle = opts.angle ?? 60
   light.penumbra = opts.penumbra ?? 0
@@ -321,6 +362,7 @@ export function createPointLight(opts: PointLightOptions = {}): PointLight {
   light.type = "point"
   light.color = [...(opts.color ?? [1, 1, 1])] as Vec3
   light.intensity = opts.intensity ?? 1
+  light.layers = opts.layers !== undefined ? checkMask(opts.layers, "createPointLight") : ALL_LAYERS
   light.distance = opts.distance ?? 0
   light.decay = opts.decay ?? 2
   light.castShadow = opts.castShadow === true
@@ -335,12 +377,13 @@ export function createHemisphereLight(opts: HemisphereLightOptions = {}): Hemisp
   light.sky = [...(opts.sky ?? [1, 1, 1])] as Vec3
   light.ground = [...(opts.ground ?? [0.2, 0.2, 0.2])] as Vec3
   light.intensity = opts.intensity ?? 1
+  light.layers = opts.layers !== undefined ? checkMask(opts.layers, "createHemisphereLight") : ALL_LAYERS
   return light
 }
 
 /** The write path for a light's own fields (color, intensity, direction,
- * the cone and falloff, or sky/ground); absent keys keep their value.
- * Its placement goes through setTransform like any node.
+ * layers, the cone and falloff, or sky/ground); absent keys keep their
+ * value. Its placement goes through setTransform like any node.
  * Frame-rate-safe. */
 export function setLight(light: DirectionalLight, update: DirectionalLightOptions): void
 export function setLight(light: SpotLight, update: SpotLightOptions): void
@@ -351,6 +394,15 @@ export function setLight(
   update: DirectionalLightOptions & SpotLightOptions & PointLightOptions & HemisphereLightOptions,
 ): void {
   if (update.intensity !== undefined) light.intensity = update.intensity
+  if (update.layers !== undefined) {
+    let mask = checkMask(update.layers, "setLight")
+    if (mask !== light.layers) {
+      light.layers = mask
+      // A casting light's shadow views re-filter their casters by the new
+      // mask (a re-attach, never a tile rebuild - the maps stay).
+      light._scene?._lightLayersChanged(light)
+    }
+  }
   if (light.type === "directional") {
     if (update.direction !== undefined) light.direction = [...update.direction] as Vec3
     if (update.color !== undefined) light.color = [...update.color] as Vec3

package/src/material.ts

@@ -52,6 +52,7 @@ import {
   phongFragment,
   litShadowFragment,
   litVertex,
+  BLEND_SPACE,
   SKIN_DECLS,
   SKIN_MATRIX,
   standardFragment,
@@ -140,6 +141,20 @@ export type Material = {
    * an entry under a fading LOD level switches hard at the band's
    * midpoint. */
   lodFade?: boolean
+  /** True when a stage declares `uLayers` (read from the source, like
+   * lodFade; every lit source composing LIGHT_LOOKUP does): the scene
+   * then seeds and follows the mesh's `layers` bitmask on entries drawn
+   * with this material, which is what lightVector masks lights against.
+   * Like the other declared-uniform flags, a source that declares
+   * uLayers without using it is rejected at add(). */
+  layered?: boolean
+  /** True when the fragment declares `uEnv` (read from the source, like
+   * layered; every source composing ENVIRONMENT does - `standard`
+   * always, `phong` with `reflectivity`): the scene then applies a
+   * mesh's own `environment` to entries drawn with this material. On a
+   * material without it the mesh's environment is a no-op, never an
+   * error - "no reflection" is already true. */
+  env?: boolean
   /** Present on materials that own their pipeline (shaderMaterial). */
   dispose?(): void
 }
@@ -1112,9 +1127,10 @@ export const SKYBOX_FRAGMENT = glsl`
   uniform samplerCube uSky;
   uniform float uSkyIntensity;
   uniform mat4 uSkyRotation;
+  ${BLEND_SPACE}
   void main() {
     vec3 dir = mat3(uSkyRotation) * normalize(vRay);
-    fragColor = vec4(max(texture(uSky, dir).rgb * uSkyIntensity, vec3(0.0)), 1.0);
+    fragColor = vec4(blendSpaceOutput(max(texture(uSky, dir).rgb * uSkyIntensity, vec3(0.0)), 1.0), 1.0);
   }
 `
 
@@ -1324,6 +1340,13 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   let morphed = /\buMorphs\b/.test(opts.vertex)
   // The LOD cross-fade is a fragment-stage discard (Material.lodFade).
   let lodFade = /\buLodFade\b/.test(opts.fragment)
+  // A source mentioning uLayers masks lights by the mesh's layers
+  // (Material.layered); either stage may light, so both are scanned.
+  let layered = /\buLayers\b/.test(opts.vertex) || /\buLayers\b/.test(opts.fragment)
+  // A source mentioning uEnv reflects the environment (Material.env; the
+  // \b keeps uEnvIntensity and friends from matching, but ENVIRONMENT
+  // always declares the sampler itself).
+  let env = /\buEnv\b/.test(opts.fragment)
   let transparent = opts.transparent ?? (opts.blend !== undefined && opts.blend !== "none")
   let cutout = opts.cutout === true
   let depth = opts.depth ?? true
@@ -1424,6 +1447,8 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
         skinned,
         morphed,
         lodFade,
+        layered,
+        env,
         attributes,
         transparent,
         cutout,