@solidrt/3d 0.0.51 → 0.0.52

package/src/material.ts

@@ -1,5 +1,7 @@
-// Materials pair GLSL with pipeline state, deduped hard: one program and
-// one render pipeline per material CLASS (unlit color, unlit textured),
+// Materials pair GLSL with pipeline state, deduped hard: one program per
+// material CLASS (unlit color, unlit textured), and one render pipeline
+// per vertex layout the class meets (a pipeline is program + attribute
+// list, so the program never recompiles for a wider geometry),
 // created lazily at first use and kept for the app's lifetime. A material
 // INSTANCE is just the per-entry uniform values (and sampler bindings) it
 // contributes when a mesh becomes a draw entry - so a thousand meshes with
@@ -25,6 +27,7 @@ import {
   destroyShader,
   glsl,
   linkProgram,
+  programAttributes,
 } from "@solidrt/core/gpu"
 import type {
   BlendMode,
@@ -33,29 +36,34 @@ import type {
   RenderPipelineId,
   ShaderParams,
   ShaderStageId,
+  TextureBindings,
   TextureId,
   Topology,
   VertexAttribute,
 } from "@solidrt/core/gpu"
-import { VERTEX_LAYOUTS } from "./geometry.ts"
+import { layoutAttributes, layoutKey, layoutSlot } from "./geometry.ts"
 import type { VertexLayout } from "./geometry.ts"
+import { BLINN_SPECULAR, HEMISPHERE, LAMBERT, LIT_VERTEX, LIT_VERTEX_COLORED, MAX_LIGHTS, SHADOW, SHADOW_LOOKUP, SHADOW_SLOTS } from "./glsl.ts"
 
 export type Material = {
-  /** The pipeline this material draws with (lazily created). */
-  pipeline(): RenderPipelineId
+  /** The pipeline this material draws with for geometry of `layout`
+   * (lazily created, one per layout met). */
+  pipeline(layout: VertexLayout | undefined): RenderPipelineId
   /** Per-entry uniform values this material contributes at addDraw. */
   params: ShaderParams
   /** Per-entry sampler bindings, when the material samples textures. */
-  textures?: Record<string, TextureId>
+  textures?: TextureBindings
   /** True when the vertex stage declares `uNormal`: the scene then writes
    * the world matrix's inverse-transpose alongside uModel for meshes using
    * this material (set automatically by shaderMaterial). */
   normalMatrix?: boolean
-  /** The vertex layout the pipeline is built for; absent means "standard".
-   * shaderMaterial sets "colored" when the vertex stage reads `aColor`. A
-   * mesh whose geometry layout differs is rejected at add() - the strides
-   * disagree, so a mismatch would render garbage, not just miss a channel. */
-  layout?: VertexLayout
+  /** The vertex attributes the linked program reads from the geometry
+   * (name and format, per the engine's reflection of the compiled program,
+   * instance attributes excluded). Links the program on first call. A mesh
+   * whose geometry layout lacks any of them is rejected at add(); extra
+   * channels in the geometry are fine (inactive attributes keep the
+   * stride). */
+  attributes(): VertexAttribute[]
   /** True when the pipeline blends over (blend "alpha", depthWrite off):
    * the scene draws this material's meshes after every opaque one, sorted
    * back-to-front by mesh origin, and re-sorts them when the camera moves. */
@@ -106,30 +114,42 @@ const FRAGMENT_MAP_SRC = glsl`
 `
 
 let sharedVertex: ShaderStageId | undefined
-let pipelines: Partial<Record<UnlitClass, RenderPipelineId>> = {}
+let programs: Partial<Record<UnlitClass, ProgramId>> = {}
+let pipelines = new Map<string, RenderPipelineId>()
 
-// One pipeline per unlit CLASS: fragment kind x transparency, since blend
-// state is pipeline state.
+// One program per unlit CLASS: fragment kind x transparency. Blend state is
+// pipeline state and so is the attribute list, so the pipeline is keyed by
+// class and vertex layout.
 type UnlitClass = "color" | "map" | "color-transparent" | "map-transparent"
 
-function pipelineFor(cls: UnlitClass): RenderPipelineId {
-  let existing = pipelines[cls]
+function programFor(cls: UnlitClass): ProgramId {
+  let program = programs[cls]
+  if (program === undefined) {
+    if (sharedVertex === undefined) sharedVertex = compileShader("vertex", VERTEX_SRC, { header: true })
+    let fragment = compileShader("fragment", cls.startsWith("color") ? FRAGMENT_COLOR_SRC : FRAGMENT_MAP_SRC, {
+      header: true,
+    })
+    program = linkProgram(sharedVertex, fragment, { label: "scene-unlit-" + cls })
+    programs[cls] = program
+  }
+  return program
+}
+
+function pipelineFor(cls: UnlitClass, layout: VertexLayout | undefined): RenderPipelineId {
+  let key = cls + "|" + layoutKey(layout)
+  let existing = pipelines.get(key)
   if (existing !== undefined) return existing
-  if (sharedVertex === undefined) sharedVertex = compileShader("vertex", VERTEX_SRC, { header: true })
+  let program = programFor(cls)
   let transparent = cls.endsWith("-transparent")
-  let fragment = compileShader("fragment", cls.startsWith("color") ? FRAGMENT_COLOR_SRC : FRAGMENT_MAP_SRC, {
-    header: true,
-  })
-  let program = linkProgram(sharedVertex, fragment, { label: "scene-unlit-" + cls })
   let pipeline = createRenderPipeline(program, {
-    attributes: VERTEX_LAYOUTS.standard,
+    attributes: layoutAttributes(layout),
     depth: true,
     depthWrite: transparent ? false : undefined,
     blend: transparent ? "alpha" : undefined,
     cull: "back",
     label: "scene-unlit-" + cls,
   })
-  pipelines[cls] = pipeline
+  pipelines.set(key, pipeline)
   return pipeline
 }
 
@@ -153,15 +173,287 @@ export function unlit(opts: UnlitOptions = {}): Material {
   let a = color.length === 4 ? color[3] : 1
   let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
   let transparent = opts.transparent === true
-  if (opts.map !== undefined) {
-    return {
-      pipeline: () => pipelineFor(transparent ? "map-transparent" : "map"),
-      params: { uColor },
-      textures: { uMap: opts.map },
-      transparent,
+  let cls: UnlitClass = opts.map !== undefined ? (transparent ? "map-transparent" : "map") : transparent ? "color-transparent" : "color"
+  return {
+    pipeline: layout => pipelineFor(cls, layout),
+    attributes: () => programAttributes(programFor(cls)),
+    params: { uColor },
+    textures: opts.map !== undefined ? { uMap: opts.map } : undefined,
+    transparent,
+  }
+}
+
+export type LitOptions = UnlitOptions & {
+  /** Multiply the base by the geometry's per-vertex aColor (withColors
+   * geometry; add() throws without it). */
+  vertexColors?: boolean
+  /** Blinn-Phong highlight strength, 0..1 (default 0: pure diffuse). */
+  specular?: number
+  /** Highlight tightness, wide sheen (~8) to mirror dot (~150); default 30. */
+  shininess?: number
+  /** Sample `map` by WORLD position instead of UV - the value is the
+   * texture repeats per world unit - blended across the three axis planes
+   * by the normal. Tiles generated geometry at one density regardless of
+   * each part's size or UVs; the map must be created with
+   * `wrap: "repeat"`. */
+  triplanar?: number
+  /**
+   * Receive the scene's directional shadows (default true, like Godot and
+   * Three): each casting light's term is multiplied by its shadow-map
+   * factor (SHADOW in `@solidrt/3d/glsl`). `false` opts out - a material
+   * that must never darken (an emissive surface, a far skybox) - and
+   * drops the map sample from its program. A material option, not a
+   * node flag as in Three, because the material picks the program (like
+   * vertexColors and triplanar; Godot's `disable_receive_shadows`); in a
+   * scene with no `castShadow` light the receiving variant draws exactly
+   * like the opted-out one. Custom materials receive by declaring the
+   * scene's shadow set (see SHADOW's doc) and composing `shadow` per light.
+   */
+  receiveShadow?: boolean
+}
+
+// The lit fragment is composed from the same exported pieces an app
+// composes by hand, per flag: map x vertexColors x triplanar x shadow x
+// transparent. Lights arrive through the scene's shared params
+// (light nodes); the base color, map and highlight are per entry. The
+// shadow set is shared too and indexed like the lights: slot i is
+// directional light i's map, matrix and biases (target-level, bound by
+// the scene), uShadowCast[i] says whether it casts; SHADOW_LOOKUP turns
+// the index into the factor.
+function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, shadow: boolean): string {
+  return glsl`
+    in vec3 vWorldPos;
+    in vec3 vNormal;
+    in vec2 vUv;
+    ${vertexColors ? "in vec4 vColor;" : ""}
+    uniform vec4 uColor;
+    ${map ? "uniform sampler2D uMap;" : ""}
+    uniform float uSpecular;
+    uniform float uShininess;
+    ${triplanar ? "uniform float uTriplanar;" : ""}
+    uniform vec3 uCamPos;
+    uniform vec3 uHemiSky;
+    uniform vec3 uHemiGround;
+    uniform int uLightCount;
+    uniform vec3 uLightDir[${MAX_LIGHTS}];
+    uniform vec3 uLightColor[${MAX_LIGHTS}];
+    ${
+      shadow
+        ? `${SHADOW_SLOTS}
+    ${SHADOW}
+    ${SHADOW_LOOKUP}`
+        : ""
+    }
+    ${HEMISPHERE}
+    ${LAMBERT}
+    ${BLINN_SPECULAR}
+
+    void main() {
+      vec3 n = normalize(vNormal);
+      vec4 base = uColor;
+      ${
+        map
+          ? triplanar
+            ? `vec3 w = pow(abs(n), vec3(4.0));
+      w /= w.x + w.y + w.z;
+      vec3 p = vWorldPos * uTriplanar;
+      base *= texture(uMap, p.yz) * w.x + texture(uMap, p.xz) * w.y + texture(uMap, p.xy) * w.z;`
+            : "base *= texture(uMap, vUv);"
+          : ""
+      }
+      ${vertexColors ? "base *= vColor;" : ""}
+      vec3 v = normalize(uCamPos - vWorldPos);
+      vec3 light = hemisphere(n, uHemiSky, uHemiGround);
+      vec3 spec = vec3(0.0);
+      for (int i = 0; i < ${MAX_LIGHTS}; i++) {
+        if (i >= uLightCount) break;
+        vec3 l = uLightDir[i];
+        ${
+          shadow ? "float s = lightShadow(i, vWorldPos, n);" : "float s = 1.0;"
+        }
+        light += uLightColor[i] * lambert(n, l) * s;
+        spec += uLightColor[i] * blinnSpecular(n, v, l, uShininess) * s;
+      }
+      fragColor = vec4(base.rgb * light + spec * uSpecular * base.a, base.a);
     }
+  `
+}
+
+let litClasses = new Map<string, ShaderMaterialClass>()
+
+/**
+ * A lit material: hemisphere ambient plus the scene's directional lights
+ * (DirectionalLight nodes), Lambert diffuse, optional
+ * Blinn-Phong highlight. Same options as unlit (color, map, transparent)
+ * plus vertexColors, specular/shininess and triplanar mapping. One program
+ * per option combination, one pipeline per vertex layout met, shared by
+ * every instance - a thousand lit meshes still share one pipeline. No
+ * lights set means black except for the hemisphere term, which also
+ * starts at zero: set at least one of the two.
+ */
+export function lit(opts: LitOptions = {}): Material {
+  let color = opts.color ?? [1, 1, 1]
+  let a = color.length === 4 ? color[3] : 1
+  let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
+  let map = opts.map !== undefined
+  let vertexColors = opts.vertexColors === true
+  let triplanar = map && opts.triplanar !== undefined
+  let transparent = opts.transparent === true
+  let shadow = opts.receiveShadow !== false
+  let key = [map, vertexColors, triplanar, transparent, shadow].join("|")
+  let cls = litClasses.get(key)
+  if (cls === undefined) {
+    cls = shaderMaterialClass({
+      vertex: vertexColors ? LIT_VERTEX_COLORED : LIT_VERTEX,
+      fragment: litFragment(map, vertexColors, triplanar, shadow),
+      transparent,
+      label: "scene-lit-" + key,
+    })
+    litClasses.set(key, cls)
   }
-  return { pipeline: () => pipelineFor(transparent ? "color-transparent" : "color"), params: { uColor }, transparent }
+  let material = cls.instance({
+    params: triplanar
+      ? { uColor, uSpecular: opts.specular ?? 0, uShininess: opts.shininess ?? 30, uTriplanar: opts.triplanar! }
+      : { uColor, uSpecular: opts.specular ?? 0, uShininess: opts.shininess ?? 30 },
+    textures: map ? { uMap: opts.map! } : undefined,
+  })
+  return material
+}
+
+// The shadow depth pass: position only, no color of interest (the target's
+// depth texture is the output; the color write is the pipeline's minimum).
+// Front faces culled, Three's shadowSide default: the map holds each
+// caster's BACK surface, so a receiving front face at the same depth
+// compares lit without a bias and acne needs no fighting on closed meshes.
+const SHADOW_DEPTH_VERTEX = glsl`
+  in vec3 aPos;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+  void main() {
+    gl_Position = uViewProj * uModel * vec4(aPos, 1.0);
+  }
+`
+
+const SHADOW_DEPTH_FRAGMENT = glsl`
+  void main() {
+    fragColor = vec4(1.0);
+  }
+`
+
+let shadowDepth: Material | undefined
+
+/** The override material of a scene's shadow view (internal): one class
+ * for the app, built on first use. */
+export function shadowDepthMaterial(): Material {
+  if (shadowDepth === undefined) {
+    shadowDepth = shaderMaterialClass({
+      vertex: SHADOW_DEPTH_VERTEX,
+      fragment: SHADOW_DEPTH_FRAGMENT,
+      cull: "front",
+      label: "scene-shadow-depth",
+    }).instance()
+  }
+  return shadowDepth
+}
+
+export type SpriteOptions = UnlitOptions & {
+  /** Which way the quad turns to face the camera. `"full"` (default,
+   * Three's Sprite): both axes follow the view, the quad is always flat
+   * to the screen. `"fixed-y"` (Godot's BILLBOARD_FIXED_Y): only the yaw
+   * follows the camera, the quad stays upright on world y - trees and
+   * standing characters, the classic sprite. */
+  billboard?: "full" | "fixed-y"
+}
+
+// The billboard vertex stages: the unit quad's corners placed along the
+// camera axes at the mesh's world position, with the quad's size read
+// off uModel's column lengths so `scale` sizes the sprite like any mesh.
+// The rotation part of uModel is otherwise ignored (the camera decides
+// the facing). Fixed-y takes the yaw from the camera-to-center direction
+// flattened onto XZ; straight above or below there is no yaw to take, so
+// the quad falls back to facing +z rather than dividing by zero.
+const SPRITE_VERTEX_SRC = glsl`
+  in vec3 aPos;
+  in vec2 aUV;
+  out vec2 vUv;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+  uniform vec3 uCamRight;
+  uniform vec3 uCamUp;
+
+  void main() {
+    vec3 center = uModel[3].xyz;
+    vec2 size = vec2(length(uModel[0].xyz), length(uModel[1].xyz));
+    vec3 world = center + uCamRight * (aPos.x * size.x) + uCamUp * (aPos.y * size.y);
+    gl_Position = uViewProj * vec4(world, 1.0);
+    vUv = aUV;
+  }
+`
+
+const SPRITE_FIXED_Y_VERTEX_SRC = glsl`
+  in vec3 aPos;
+  in vec2 aUV;
+  out vec2 vUv;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+  uniform vec3 uCamPos;
+
+  void main() {
+    vec3 center = uModel[3].xyz;
+    vec2 size = vec2(length(uModel[0].xyz), length(uModel[1].xyz));
+    vec3 toCam = uCamPos - center;
+    toCam.y = 0.0;
+    float len = length(toCam);
+    vec3 right = len > 1e-6 ? vec3(toCam.z, 0.0, -toCam.x) / len : vec3(1.0, 0.0, 0.0);
+    vec3 world = center + right * (aPos.x * size.x) + vec3(0.0, aPos.y * size.y, 0.0);
+    gl_Position = uViewProj * vec4(world, 1.0);
+    vUv = aUV;
+  }
+`
+
+let spriteClasses = new Map<string, ShaderMaterialClass>()
+
+/**
+ * A sprite material: unlit color/map on a quad that turns to face the
+ * camera in the vertex stage (the shared uCamRight/uCamUp basis, or
+ * uCamPos for fixed-y), so a thousand sprites cost no per-frame JS. Draw
+ * it with createSprite / `<Sprite>`, which supply the unit quad; on other
+ * geometry the vertex stage still flattens every vertex onto the camera
+ * plane. Unlike unlit, `transparent` defaults to TRUE - sprites are cutouts
+ * far more often than not (Three's SpriteMaterial default) - pass false
+ * for an opaque one. Culling is off: a camera-facing quad has no back.
+ */
+export function sprite(opts: SpriteOptions = {}): Material {
+  let color = opts.color ?? [1, 1, 1]
+  let a = color.length === 4 ? color[3] : 1
+  let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
+  let map = opts.map !== undefined
+  let transparent = opts.transparent !== false
+  let fixedY = opts.billboard === "fixed-y"
+  let key = [map, transparent, fixedY].join("|")
+  let cls = spriteClasses.get(key)
+  if (cls === undefined) {
+    cls = shaderMaterialClass({
+      vertex: fixedY ? SPRITE_FIXED_Y_VERTEX_SRC : SPRITE_VERTEX_SRC,
+      fragment: map ? FRAGMENT_MAP_SRC : FRAGMENT_COLOR_SRC,
+      transparent,
+      cull: "none",
+      label: "scene-sprite-" + key,
+    })
+    spriteClasses.set(key, cls)
+  }
+  return cls.instance({ params: { uColor }, textures: map ? { uMap: opts.map! } : undefined })
+}
+
+/** The attributes `material` reads that `layout` does not carry (name and
+ * format) - empty when the pair is drawable. */
+export function missingAttributes(material: Material, layout: VertexLayout | undefined): VertexAttribute[] {
+  let missing: VertexAttribute[] = []
+  for (let attr of material.attributes()) {
+    let slot = layoutSlot(layout, attr.name)
+    if (slot === null || slot.format !== attr.format) missing.push(attr)
+  }
+  return missing
 }
 
 // Mirrors the engine's own preamble rule: a source carrying its own
@@ -222,11 +514,14 @@ export type ShaderMaterialClassOptions = {
    * normals, correct under non-uniform scale - and `uniform vec3 uCamPos`
    * the camera's world position, shared like uViewProj (the specular /
    * fresnel view vector: `uCamPos - worldPos`). Declare any of the
-   * layout's `in` attributes (aPos vec3, aNormal vec3, aUV vec2);
-   * undeclared ones are skipped. Reading `in vec4 aColor` opts the
-   * material into the "colored" 12-float layout - the per-vertex data
-   * channel (tint, baked AO, any four scalars); its meshes then need
-   * withColors() geometry, and a layout mismatch throws at add().
+   * geometry's `in` attributes by name (the standard aPos vec3, aNormal
+   * vec3, aUV vec2, or any channel appended with withAttribute);
+   * undeclared ones are skipped. What the program READS is the engine's
+   * word (reflected from the linked program, so an `in` the compiler
+   * dropped does not count); one the mesh's geometry layout does not
+   * carry (name and format) throws at add() - so `in vec4 aColor` needs
+   * withColors() geometry. The class builds one pipeline per layout its
+   * meshes bring, the program compiles once.
    * `@solidrt/3d/glsl` exports a standard
    * vertex stage and lighting pieces built on exactly this contract.
    */
@@ -267,7 +562,7 @@ export type ShaderMaterialInstanceOptions = {
   /** Uniform seeds beyond the standard set; update per mesh later with
    * setMeshParams. */
   params?: ShaderParams
-  textures?: Record<string, TextureId>
+  textures?: TextureBindings
 }
 
 export type ShaderMaterialOptions = ShaderMaterialClassOptions & ShaderMaterialInstanceOptions
@@ -308,25 +603,36 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
     }
   }
   let program: ProgramId | undefined
-  let pipeline: RenderPipelineId | undefined
+  let pipelines = new Map<string, RenderPipelineId>()
   // Attributes live in the vertex stage only, so unlike the uNormal scan
   // there is nothing to look for in the fragment source.
-  let layout: VertexLayout = /\baColor\b/.test(opts.vertex) ? "colored" : "standard"
   let normalMatrix = /\buNormal\b/.test(opts.vertex) || /\buNormal\b/.test(opts.fragment)
   let transparent = opts.transparent ?? (opts.blend !== undefined && opts.blend !== "none")
   let depth = opts.depth ?? true
   // An empty list declares nothing - same as absent (the engine requires an
   // instance buffer exactly when attributes are declared).
   let instanceAttributes = opts.instanceAttributes?.length ? opts.instanceAttributes.map(a => ({ ...a })) : undefined
-  let pipelineFor = (): RenderPipelineId => {
-    if (pipeline === undefined) {
+  let programFor = (): ProgramId => {
+    if (program === undefined) {
       let vs = compileShader("vertex", opts.vertex, { header: needsHeader(opts.vertex) })
       let fs = compileShader("fragment", opts.fragment, { header: needsHeader(opts.fragment) })
       program = linkProgram(vs, fs, { label: opts.label })
       destroyShader(vs)
       destroyShader(fs)
-      pipeline = createRenderPipeline(program, {
-        attributes: VERTEX_LAYOUTS[layout],
+    }
+    return program
+  }
+  // What the program reads from the GEOMETRY: the engine's reflection of
+  // the linked program minus the per-instance names (those come from the
+  // record buffer, declared on the pipeline beside the layout).
+  let attributes = (): VertexAttribute[] =>
+    programAttributes(programFor()).filter(a => !instanceAttributes?.some(i => i.name === a.name))
+  let pipelineFor = (layout: VertexLayout | undefined): RenderPipelineId => {
+    let key = layoutKey(layout)
+    let pipeline = pipelines.get(key)
+    if (pipeline === undefined) {
+      pipeline = createRenderPipeline(programFor(), {
+        attributes: layoutAttributes(layout),
         instanceAttributes,
         depth,
         // depthWrite needs a depth buffer, so the transparent default
@@ -337,18 +643,17 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
         topology: opts.topology,
         label: opts.label,
       })
+      pipelines.set(key, pipeline)
     }
     return pipeline
   }
   return {
     instance(inst = {}) {
-      return { normalMatrix, layout, transparent, instanceAttributes, pipeline: pipelineFor, params: inst.params ?? {}, textures: inst.textures }
+      return { normalMatrix, attributes, transparent, instanceAttributes, pipeline: pipelineFor, params: inst.params ?? {}, textures: inst.textures }
     },
     dispose() {
-      if (pipeline !== undefined) {
-        destroyRenderPipeline(pipeline)
-        pipeline = undefined
-      }
+      for (let pipeline of pipelines.values()) destroyRenderPipeline(pipeline)
+      pipelines.clear()
       if (program !== undefined) {
         destroyProgram(program)
         program = undefined

package/src/math.ts

@@ -191,6 +191,24 @@ export function perspective(out: Mat4, fovy: number, aspect: number, near: numbe
   return out
 }
 
+/**
+ * Orthographic projection with the same y-down clip flip BAKED IN as
+ * perspective() (row two negated): view-space x in [left, right] and y in
+ * [bottom, top] fill the target at any depth, [near, far] maps to depth
+ * like perspective. The camera's `ortho` option; the flip lives here for
+ * the reason given at perspective().
+ */
+export function orthographic(out: Mat4, left: number, right: number, top: number, bottom: number, near: number, far: number): Mat4 {
+  let lr = 1 / (left - right)
+  let bt = 1 / (bottom - top)
+  let nf = 1 / (near - far)
+  out[0] = -2 * lr; out[1] = 0; out[2] = 0; out[3] = 0
+  out[4] = 0; out[5] = 2 * bt; out[6] = 0; out[7] = 0
+  out[8] = 0; out[9] = 0; out[10] = 2 * nf; out[11] = 0
+  out[12] = (left + right) * lr; out[13] = -(top + bottom) * bt; out[14] = (far + near) * nf; out[15] = 1
+  return out
+}
+
 // Quaternions, the rotation the scene actually stores. Euler triples are a
 // boundary format only - authoring (setTransform's `rotation`, the
 // components' `rotation` prop) and reading back (getRotation) - so the order
@@ -579,3 +597,54 @@ export function lookAt(out: Mat4, eye: Vec3, target: Vec3, up: Vec3): Mat4 {
   out[15] = 1
   return out
 }
+
+/**
+ * Entry distance of a ray against a box: the smallest t >= 0 with
+ * origin + t * direction inside [min, max] (0 when the origin starts
+ * inside), or -1 for a miss. The direction need not be normalized - t is
+ * in units of its length, which is what keeps a ray transformed into a
+ * mesh's local space reporting world distances.
+ */
+export function rayBoxDistance(
+  ox: number, oy: number, oz: number,
+  dx: number, dy: number, dz: number,
+  minX: number, minY: number, minZ: number,
+  maxX: number, maxY: number, maxZ: number,
+): number {
+  let tNear = 0
+  let tFar = Infinity
+  // Per axis: a zero direction component never crosses the slab, so the
+  // origin must already be inside it (the multiply-by-inverse shortcut
+  // turns that case into NaN, hence the explicit branch).
+  if (dx === 0) {
+    if (ox < minX || ox > maxX) return -1
+  } else {
+    let inv = 1 / dx
+    let t1 = (minX - ox) * inv
+    let t2 = (maxX - ox) * inv
+    if (t1 > t2) { let t = t1; t1 = t2; t2 = t }
+    if (t1 > tNear) tNear = t1
+    if (t2 < tFar) tFar = t2
+  }
+  if (dy === 0) {
+    if (oy < minY || oy > maxY) return -1
+  } else {
+    let inv = 1 / dy
+    let t1 = (minY - oy) * inv
+    let t2 = (maxY - oy) * inv
+    if (t1 > t2) { let t = t1; t1 = t2; t2 = t }
+    if (t1 > tNear) tNear = t1
+    if (t2 < tFar) tFar = t2
+  }
+  if (dz === 0) {
+    if (oz < minZ || oz > maxZ) return -1
+  } else {
+    let inv = 1 / dz
+    let t1 = (minZ - oz) * inv
+    let t2 = (maxZ - oz) * inv
+    if (t1 > t2) { let t = t1; t1 = t2; t2 = t }
+    if (t1 > tNear) tNear = t1
+    if (t2 < tFar) tFar = t2
+  }
+  return tFar >= tNear ? tNear : -1
+}