@solidrt/3d 0.0.63 → 0.0.65

package/examples/fog.tsx

@@ -16,11 +16,12 @@
 // command sets the mode and its knobs (`{ mode: "linear" | "exp2" |
 // "height" | "off", near, far, density, height, falloff }`) and returns
 // the state; `pan` parks the camera (`{ t: seconds }`), so a capture
-// repeats.
+// repeats; `suns` is the two suns' world positions and `project`
+// (`{ point }`) is where a world point is on screen, for a pixel probe.
 import { createSignal, flush, onFrame, pct, render } from "@solidrt/core"
 import { registerDebug } from "srt:dev"
 import { cone, cylinder, DirectionalLight, HemisphereLight, phong, Mesh, PerspectiveCamera, plane, Scene, sphere, unlit } from "@solidrt/3d"
-import type { FogOptions, Vec3 } from "@solidrt/3d"
+import type { FogOptions, SceneHandle, Vec3 } from "@solidrt/3d"
 
 const FAR = 400
 // The sky, shared by the clear and the fog so the horizon has no band.
@@ -36,6 +37,10 @@ const LINEAR_FAR = FAR
 const DENSITY = 0.006
 const HEIGHT = 10
 const HEIGHT_FALLOFF = 0.12
+// The two suns, side by side on the far ridge: the left one opts out of
+// the fog, the right one fogs like everything else.
+const SUN_LIT: Vec3 = [-30, 100, -220]
+const SUN_FOGGED: Vec3 = [30, 100, -220]
 
 type Mode = "linear" | "exp2" | "height" | "off"
 const MODES: Mode[] = ["linear", "exp2", "height", "off"]
@@ -48,6 +53,7 @@ let [height, setHeight] = createSignal(HEIGHT)
 let [falloff, setFalloff] = createSignal(HEIGHT_FALLOFF)
 let [time, setTime] = createSignal(0)
 let parked: number | null = null
+let scene: SceneHandle | null = null
 
 let num = (v: unknown, set: (n: number) => void) => {
   if (typeof v === "number") set(v)
@@ -73,6 +79,13 @@ registerDebug("pan", (args?: Record<string, unknown>) => {
   flush()
   return { t: time(), parked: parked !== null }
 })
+registerDebug("suns", () => ({ lit: SUN_LIT, fogged: SUN_FOGGED }))
+registerDebug("project", (args?: Record<string, unknown>) => {
+  if (scene === null) throw new Error("project: the scene is not mounted")
+  let point = args?.point
+  if (!Array.isArray(point) || point.length !== 3 || !point.every(v => typeof v === "number")) throw new Error("project: pass { point: [x, y, z] }")
+  return scene.project(point as Vec3)
+})
 
 function fog(): FogOptions | undefined {
   switch (mode()) {
@@ -148,7 +161,7 @@ function App() {
   return (
     <window>
       <view width={pct(100)} height={pct(100)} onPointerDown={() => setMode(m => MODES[(MODES.indexOf(m) + 1) % MODES.length] ?? "linear")}>
-        <Scene clearColor={[SKY[0], SKY[1], SKY[2], 1]} fog={fog()} samples={4} label="fog">
+        <Scene ref={s => (scene = s)} clearColor={[SKY[0], SKY[1], SKY[2], 1]} fog={fog()} samples={4} label="fog">
           <PerspectiveCamera fov={55} near={0.5} far={FAR} position={EYE} lookAt={lookAt()} />
           <HemisphereLight sky={[0.55, 0.62, 0.75]} ground={[0.28, 0.24, 0.2]} />
           <DirectionalLight color={[0.9, 0.85, 0.75]} rotation={[-0.9, 0.6, 0]} />
@@ -162,8 +175,8 @@ function App() {
               <Mesh geometry={crown} material={needles} position={[p.position[0], p.position[1] + p.size * 0.3 + p.size * 0.5, p.position[2]]} scale={[p.size * 0.9, p.size, p.size * 0.9]} />
             </>
           ))}
-          <Mesh geometry={sun} material={sunLit} position={[-30, 100, -220]} />
-          <Mesh geometry={sun} material={sunFogged} position={[30, 100, -220]} />
+          <Mesh geometry={sun} material={sunLit} position={SUN_LIT} />
+          <Mesh geometry={sun} material={sunFogged} position={SUN_FOGGED} />
         </Scene>
       </view>
     </window>

package/examples/model-load.tsx

@@ -3,7 +3,7 @@
 // bundle - the shape every app with real content ends up needing. Bake
 // the asset once and drop it in your app's assets tree:
 //
-//   bunx srt tool 3d/model examples/model.glb -o assets/model.srtm
+//   bun run srt tool 3d/model examples/model.glb -o assets/model.srtm
 //
 // (loadGltf("assets/model.glb") has the exact same async shape; the bake
 // just removes the runtime parse.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.63",
+  "version": "0.0.65",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -9,6 +9,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./model": "./src/model-data.ts",
+    "./splat": "./src/splat-data.ts",
     "./math": "./src/math.ts",
     "./glsl": "./src/glsl.ts"
   },
@@ -18,8 +19,11 @@
     "examples/",
     "AGENTS.md"
   ],
+  "devDependencies": {
+    "@solidrt/test": "0.0.65"
+  },
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.9",
-    "@solidrt/core": "0.0.63"
+    "@solidjs/signals": "2.0.0-rc.13",
+    "@solidrt/core": "0.0.65"
   }
 }

package/src/camera.ts

@@ -135,8 +135,11 @@ export function ensureCamera(cam: Camera, width: number, height: number): void {
 // billboard needs no reconstruction from uViewProj. The inverse rides too:
 // uInvViewProj carries a clip position back to world, which is how the
 // background slot (and any shader declaring it) gets a world-space ray
-// per pixel without knowing the projection.
-export function cameraParams(cam: Camera): ShaderParams {
+// per pixel without knowing the projection. The target's pixel size rides
+// as uViewport (the size the camera's aspect came from), so a pixel-space
+// footprint (the splat material) needs no app write and is per target -
+// each view feeds its own.
+export function cameraParams(cam: Camera, width: number, height: number): ShaderParams {
   let v = cam.view
   return {
     uViewProj: cam.viewProj,
@@ -144,5 +147,6 @@ export function cameraParams(cam: Camera): ShaderParams {
     uCamPos: cam.eye,
     uCamRight: [v[0], v[4], v[8]],
     uCamUp: [v[1], v[5], v[9]],
+    uViewport: [width, height],
   }
 }

package/src/components/directional-light.tsx

@@ -13,6 +13,9 @@ export type DirectionalLightProps = 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
   /** Render a shadow map from this light (any directional light may;
    * each is a pass). Its shadow camera sits at the light's WORLD
    * position, so give a casting light a `position` above the scene. */
@@ -32,6 +35,7 @@ export let DirectionalLight: VoidComponent<DirectionalLightProps> = props => {
       direction: props.direction,
       color: props.color,
       intensity: props.intensity,
+      layers: props.layers,
       castShadow: props.castShadow,
       shadow: props.shadow,
     }),
@@ -39,8 +43,8 @@ export let DirectionalLight: VoidComponent<DirectionalLightProps> = props => {
   add(ctx.parent, light)
   syncNode(light, props)
   createEffect(
-    () => [props.direction, props.color, props.intensity, props.castShadow, props.shadow] as const,
-    ([direction, color, intensity, castShadow, shadow]) => setLight(light, { direction, color, intensity, castShadow, shadow }),
+    () => [props.direction, props.color, props.intensity, props.layers, props.castShadow, props.shadow] as const,
+    ([direction, color, intensity, layers, castShadow, shadow]) => setLight(light, { direction, color, intensity, layers, castShadow, shadow }),
   )
   untrack(() => props.ref)?.(light)
   onCleanup(() => destroy(light))

package/src/components/hemisphere-light.tsx

@@ -6,17 +6,25 @@ import { createHemisphereLight, setLight } from "../light.ts"
 import type { HemisphereLight as HemisphereLightNode } from "../light.ts"
 import type { Vec3 } from "../math.ts"
 
-export type HemisphereLightProps = { sky?: Vec3; ground?: Vec3; intensity?: number; ref?: (light: HemisphereLightNode) => void }
+export type HemisphereLightProps = {
+  sky?: Vec3
+  ground?: Vec3
+  intensity?: number
+  /** Layer filter bitmask, default all bits set: a mesh outside it gets
+   * no hemisphere term. */
+  layers?: number
+  ref?: (light: HemisphereLightNode) => void
+}
 
 /** The scene's ambient term as a node (createHemisphereLight); one per
  * scene, the last mounted wins. */
 export let HemisphereLight: VoidComponent<HemisphereLightProps> = props => {
   let ctx = useContext(SceneContext)
-  let light = untrack(() => createHemisphereLight({ sky: props.sky, ground: props.ground, intensity: props.intensity }))
+  let light = untrack(() => createHemisphereLight({ sky: props.sky, ground: props.ground, intensity: props.intensity, layers: props.layers }))
   add(ctx.parent, light)
   createEffect(
-    () => [props.sky, props.ground, props.intensity] as const,
-    ([sky, ground, intensity]) => setLight(light, { sky, ground, intensity }),
+    () => [props.sky, props.ground, props.intensity, props.layers] as const,
+    ([sky, ground, intensity, layers]) => setLight(light, { sky, ground, intensity, layers }),
   )
   untrack(() => props.ref)?.(light)
   onCleanup(() => destroy(light))

package/src/components/index.ts

@@ -33,6 +33,8 @@ export { InstancedLod, Lod } from "./lod.tsx"
 export type { InstancedLodProps, LodProps } from "./lod.tsx"
 export { RecordMesh } from "./record-mesh.tsx"
 export type { RecordMeshProps } from "./record-mesh.tsx"
+export { SplatMesh } from "./splat-mesh.tsx"
+export type { SplatMeshProps } from "./splat-mesh.tsx"
 export { PerspectiveCamera } from "./perspective-camera.tsx"
 export type { PerspectiveCameraProps } from "./perspective-camera.tsx"
 export { OrbitCamera } from "./orbit-camera.tsx"

package/src/components/instanced-mesh.tsx

@@ -8,7 +8,7 @@ import type { PopulatedMeshProps } from "./mesh.tsx"
 import { add, destroy, setMorphWeights } from "../node.ts"
 import type { MorphWeights, SceneNode } from "../node.ts"
 import { addInstance, createInstancedMesh, disposeInstances, setCastShadow, setGeometry, setInstanceStyle } from "../mesh.ts"
-import type { InstancedMesh as InstancedMeshNode, InstanceNode } from "../mesh.ts"
+import type { InstancedMesh as InstancedMeshNode, InstanceNode, InstanceOrderOptions } from "../mesh.ts"
 import type { Geometry } from "../geometry.ts"
 import type { Material } from "../material.ts"
 
@@ -30,6 +30,10 @@ export type InstancedMeshProps = Omit<PopulatedMeshProps, "onPointerEnter" | "on
    * transparent sort. Optional here - instances pick by themselves, and
    * without it the mesh culls by the union of their boxes. */
   bounds?: ArrayLike<number>
+  /** Draw the records in key order, decided core-side (fixed at
+   * creation; see InstanceOrderOptions): back-to-front for a transparent
+   * population, an explicit sort field for a stepped one. */
+  instanceOrder?: InstanceOrderOptions
   /** Debug label for the record buffers. */
   label?: string
   /** The node the instance records are relative to (default the mesh;
@@ -63,7 +67,7 @@ export let InstancedMeshContext = createContext<InstancedMeshNode | null>(null)
 export let InstancedMesh: ParentComponent<InstancedMeshProps> = props => {
   let ctx = useContext(SceneContext)
   let mesh = untrack(() =>
-    createInstancedMesh(props.geometry, props.material, { capacity: props.capacity, bounds: props.bounds, anchor: props.anchor, label: props.label }),
+    createInstancedMesh(props.geometry, props.material, { capacity: props.capacity, bounds: props.bounds, anchor: props.anchor, instanceOrder: props.instanceOrder, label: props.label }),
   )
   add(ctx.parent, mesh)
   createEffect(

package/src/components/mesh.tsx

@@ -5,8 +5,9 @@ import { syncNode } from "./node-props.ts"
 import type { TransformProps, PointerEventProps } from "./node-props.ts"
 import { add, destroy, setMorphWeights } from "../node.ts"
 import type { MorphWeights } from "../node.ts"
-import { createMesh, setCastShadow, setCulling, setGeometry, setLayers, setMaterial, setMeshParams, setRenderOrder } from "../mesh.ts"
+import { createMesh, setCastShadow, setCulling, setEnvironment, setGeometry, setLayers, setMaterial, setMeshParams, setRenderOrder } from "../mesh.ts"
 import type { Mesh as MeshNode } from "../mesh.ts"
+import type { EnvironmentOptions } from "../environment.ts"
 import type { ShaderParams } from "@solidrt/core/gpu"
 import type { Geometry } from "../geometry.ts"
 import type { Material } from "../material.ts"
@@ -29,6 +30,12 @@ export type MeshProps = TransformProps & PointerEventProps & {
    * draws the mesh when its mask intersects this. Not inherited from
    * ancestor Groups. */
   layers?: number
+  /** This mesh's environment instead of the scene's (setEnvironment as a
+   * prop): `null` removes the environment term - the sealed-interior
+   * pair to masked lights - a `{ cube, intensity?, rotation? }` samples
+   * that cube, absent follows the scene. Rebuilds the mesh's entries on
+   * change: a state switch, not a per-frame dial. */
+  environment?: EnvironmentOptions | null
   /** Frustum culling switch (setCulling as a prop; default true). */
   frustumCulled?: boolean
   /** World units the culled box grows by (setCulling as a prop; default 0). */
@@ -71,6 +78,10 @@ export function syncMesh(mesh: MeshNode, props: Omit<MeshProps, "geometry" | "ma
     () => props.layers,
     l => setLayers(mesh, l ?? 1),
   )
+  createEffect(
+    () => props.environment,
+    e => setEnvironment(mesh, e),
+  )
   createEffect(
     () => [props.frustumCulled, props.cullMargin] as const,
     ([culled, margin]) => setCulling(mesh, { frustumCulled: culled !== false, cullMargin: margin ?? 0 }),

package/src/components/point-light.tsx

@@ -11,6 +11,9 @@ import type { Vec3 } from "../math.ts"
 export type PointLightProps = TransformProps & {
   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
   /** Falloff exponent; default 2 (inverse square). */
@@ -34,6 +37,7 @@ export let PointLight: VoidComponent<PointLightProps> = props => {
     createPointLight({
       color: props.color,
       intensity: props.intensity,
+      layers: props.layers,
       distance: props.distance,
       decay: props.decay,
       castShadow: props.castShadow,
@@ -43,8 +47,8 @@ export let PointLight: VoidComponent<PointLightProps> = props => {
   add(ctx.parent, light)
   syncNode(light, props)
   createEffect(
-    () => [props.color, props.intensity, props.distance, props.decay, props.castShadow, props.shadow] as const,
-    ([color, intensity, distance, decay, castShadow, shadow]) => setLight(light, { color, intensity, distance, decay, castShadow, shadow }),
+    () => [props.color, props.intensity, props.layers, props.distance, props.decay, props.castShadow, props.shadow] as const,
+    ([color, intensity, layers, distance, decay, castShadow, shadow]) => setLight(light, { color, intensity, layers, distance, decay, castShadow, shadow }),
   )
   untrack(() => props.ref)?.(light)
   onCleanup(() => destroy(light))

package/src/components/record-mesh.tsx

@@ -5,7 +5,7 @@ import { syncMesh } from "./mesh.tsx"
 import type { PopulatedMeshProps } from "./mesh.tsx"
 import { add, destroy } from "../node.ts"
 import { createRecordMesh, disposeInstances, setCastShadow, setGeometry, setRecordCount, setRecords } from "../mesh.ts"
-import type { RecordMesh as RecordMeshNode } from "../mesh.ts"
+import type { InstanceOrderOptions, RecordMesh as RecordMeshNode } from "../mesh.ts"
 import type { Geometry } from "../geometry.ts"
 import type { Material } from "../material.ts"
 
@@ -25,6 +25,14 @@ export type RecordMeshProps = PopulatedMeshProps & {
    * creation. Without them the mesh has no picking leaf, so pointer events
    * never target it. */
   bounds?: ArrayLike<number>
+  /** Draw the records in key order, decided core-side (fixed at
+   * creation; see InstanceOrderOptions): back-to-front for a transparent
+   * population, an explicit sort field for a JS-stepped one. */
+  instanceOrder?: InstanceOrderOptions
+  /** Transfer the records to the engine at creation (fixed; see
+   * RecordMeshOptions.transfer): the write-once form - no JS mirror, so
+   * a later `records` value throws instead of rewriting. */
+  transfer?: boolean
   /** Draw into the scene's shadow map (setCastShadow as a prop); default
    * false. Needs a `castShadow` light AND a material class declaring
    * `shadowVertex` (the depth pass with the instance placement) - the
@@ -39,7 +47,11 @@ export type RecordMeshProps = PopulatedMeshProps & {
 export let RecordMesh: VoidComponent<RecordMeshProps> = props => {
   let ctx = useContext(SceneContext)
   let mesh = untrack(() =>
-    createRecordMesh(props.geometry, props.material, props.records, props.count, { bounds: props.bounds }),
+    createRecordMesh(props.geometry, props.material, props.records, props.count, {
+      bounds: props.bounds,
+      instanceOrder: props.instanceOrder,
+      transfer: props.transfer,
+    }),
   )
   add(ctx.parent, mesh)
   createEffect(

package/src/components/scene.tsx

@@ -3,7 +3,7 @@ import type { Element, ParentComponent, PointerFeed, TextureId } from "@solidrt/
 import { SceneContext } from "./context.tsx"
 import { createScene } from "../scene.ts"
 import { feedPointer } from "../scene-pointer.ts"
-import type { BloomOptions, EnvironmentOptions, FogOptions, ResolveInput, Scene as SceneHandle, SkyboxOptions, ToneMapping } from "../scene.ts"
+import type { BlendSpace, BloomOptions, EnvironmentOptions, FogOptions, ResolveInput, Scene as SceneHandle, SkyboxOptions, ToneMapping } from "../scene.ts"
 import type { ScenePointerEvent, SceneTapEvent, SceneWheelEvent } from "../node.ts"
 import type { CameraUpdate } from "../camera.ts"
 
@@ -75,6 +75,12 @@ export type SceneProps = ScenePointerProps & {
   toneMapping?: ToneMapping
   /** Output exposure (scene.setExposure), default 1. Reactive. */
   exposure?: number
+  /** The buffer's blend space (SceneOptions.blendSpace), default
+   * "linear"; fixed at creation. "display" blends sRGB-encoded values
+   * in an rgba8 buffer that is itself the displayed image - the mode a
+   * splat capture is faithful in - and rejects resolve, bloom,
+   * toneMapping and exposure. */
+  blendSpace?: BlendSpace
   /** The scene target's layer mask (scene.setLayers as a prop; default 1):
    * the scene draws the meshes whose `layers` intersect it. Reactive. */
   layers?: number
@@ -175,6 +181,7 @@ export let Scene: ParentComponent<SceneProps> = props => {
       fog: props.fog,
       toneMapping: props.toneMapping,
       exposure: props.exposure,
+      blendSpace: props.blendSpace,
       resolve: props.resolve,
       bloom: props.bloom,
       layers: props.layers,

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/geometry.ts

@@ -37,7 +37,7 @@
 // format's codec.
 //
 // Pure module by design - geometry is data, and every function here is
-// array math (the check rig checks/geometry-check.ts runs it headless on
+// array math (tests/geometry.test.ts runs it headless on
 // flux). The GPU buffer step lives in geometry-gpu.ts.
 
 import type { Topology, VertexAttribute, VertexFormat } from "@solidrt/core/gpu"