@solidrt/3d 0.0.55 → 0.0.56

package/examples/standard.tsx

@@ -0,0 +1,132 @@
+// The standard material: the sphere grid every PBR engine's docs open
+// with - metalness down the rows, roughness across the columns - under a
+// baked sky as background and environment (the skybox example's bake) and
+// a warm sun casting shadows. What to look for: the bare-metal row IS the
+// environment, sharp at the left and blurred toward the right, tinted by
+// the base color and dark wherever the sky is; the dielectric row keeps
+// its diffuse color and shows the sky as a faint gloss, a mirror highlight
+// at the left that widens to the right and brightens toward every
+// silhouette; the rows between blend the two. standard takes lit's base,
+// maps, cutout, shadow, emissive and fog options - only the Blinn-Phong
+// knobs are gone, replaced by metalness/roughness and their packed maps.
+// Light intensities read as lit's: 1 lights a white matte surface to 1.
+// Drag to look around.
+
+import { pct, render } from "@solidrt/core"
+import { createCubeTexture } from "@solidrt/core/gpu"
+import { DirectionalLight, HemisphereLight, Mesh, OrbitCamera, plane, Scene, sphere, standard } from "@solidrt/3d"
+import { normalize } from "@solidrt/3d/math"
+import type { Vec3 } from "@solidrt/3d/math"
+
+// Metalness steps down the rows, roughness across the columns.
+const ROWS = 4
+const COLS = 6
+// Sphere radius and grid pitch, world units.
+const RADIUS = 0.42
+const PITCH = 1.05
+// The spheres' base color, sRGB: a warm red that reads as paint and as metal.
+const COLOR: [number, number, number] = [0.8, 0.25, 0.2]
+// Height of the bottom row's centers above the ground.
+const LIFT = 0.6
+// Face edge of the baked sky in texels.
+const FACE = 128
+// The sun's direction (toward it).
+const SUN: Vec3 = normalize([0.6, 0.45, -0.7])
+// How far out the sun light sits, so its shadow camera covers the grid.
+const SUN_DISTANCE = 12
+// Cosine of the sun disc's angular radius (1.5 degrees).
+const SUN_DISC = Math.cos((1.5 * Math.PI) / 180)
+// Glow falloff exponent around the disc (higher = tighter).
+const SUN_GLOW = 40
+// How quickly the ground band darkens below the horizon (per unit of -y).
+const GROUND_FALL = 4
+
+type Rgb = [number, number, number]
+const ZENITH: Rgb = [0.16, 0.34, 0.74]
+const HORIZON: Rgb = [0.8, 0.87, 0.95]
+const GROUND: Rgb = [0.3, 0.27, 0.24]
+const SUN_COLOR: Rgb = [1, 0.95, 0.82]
+
+let mix = (a: Rgb, b: Rgb, t: number): Rgb => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t]
+
+// The sky's color along a world direction.
+function sky(d: Vec3): Rgb {
+  let y = d[1]
+  let rgb = y >= 0 ? mix(HORIZON, ZENITH, Math.sqrt(y)) : mix(HORIZON, GROUND, Math.min(1, -y * GROUND_FALL))
+  let s = d[0] * SUN[0] + d[1] * SUN[1] + d[2] * SUN[2]
+  if (s > 0) {
+    let g = s > SUN_DISC ? 1 : Math.pow(s, SUN_GLOW)
+    rgb = [rgb[0] + SUN_COLOR[0] * g, rgb[1] + SUN_COLOR[1] * g, rgb[2] + SUN_COLOR[2] * g]
+  }
+  return [Math.min(1, rgb[0]), Math.min(1, rgb[1]), Math.min(1, rgb[2])]
+}
+
+// The world direction whose lookup lands on face i's texel (s, t) - the
+// GL cube-map table, no flip (see skybox.tsx).
+function texelDirection(face: number, s: number, t: number): Vec3 {
+  let a = 2 * s - 1
+  let b = 2 * t - 1
+  let d: Vec3 =
+    face === 0 ? [1, -b, -a] : face === 1 ? [-1, -b, a] : face === 2 ? [a, 1, b] : face === 3 ? [a, -1, -b] : face === 4 ? [a, -b, 1] : [-a, -b, -1]
+  return normalize(d)
+}
+
+function bakeSky(): Uint8Array[] {
+  let faces: Uint8Array[] = []
+  for (let face = 0; face < 6; face++) {
+    let px = new Uint8Array(FACE * FACE * 4)
+    for (let row = 0; row < FACE; row++) {
+      for (let col = 0; col < FACE; col++) {
+        let rgb = sky(texelDirection(face, (col + 0.5) / FACE, (row + 0.5) / FACE))
+        let i = (row * FACE + col) * 4
+        px[i] = Math.round(rgb[0] * 255)
+        px[i + 1] = Math.round(rgb[1] * 255)
+        px[i + 2] = Math.round(rgb[2] * 255)
+        px[i + 3] = 255
+      }
+    }
+    faces.push(px)
+  }
+  return faces
+}
+
+function App() {
+  let cube = createCubeTexture(bakeSky(), FACE, { format: "rgba8-srgb", mipmap: true, label: "sky" })
+  let ball = sphere({ radius: RADIUS, widthSegments: 48, heightSegments: 32 })
+  let ground = standard({ color: [0.32, 0.33, 0.3], roughness: 0.9 })
+  // One material per cell: metalness by row (top row bare metal, bottom
+  // row dielectric), roughness by column (mirror at the left).
+  let cells: { material: ReturnType<typeof standard>; position: Vec3 }[] = []
+  for (let r = 0; r < ROWS; r++) {
+    for (let c = 0; c < COLS; c++) {
+      cells.push({
+        material: standard({ color: COLOR, metalness: 1 - r / (ROWS - 1), roughness: c / (COLS - 1) }),
+        position: [(c - (COLS - 1) / 2) * PITCH, LIFT + (ROWS - 1 - r) * PITCH, 0],
+      })
+    }
+  }
+  let center: Vec3 = [0, LIFT + ((ROWS - 1) * PITCH) / 2, 0]
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)}>
+        <Scene background={{ cube }} environment={{ cube }} samples={4} label="standard-demo">
+          <OrbitCamera target={center} azimuth={0.25} elevation={0.15} distance={9} />
+          <HemisphereLight sky={[0.5, 0.6, 0.8]} ground={[0.3, 0.27, 0.24]} intensity={0.5} />
+          <DirectionalLight
+            position={[SUN[0] * SUN_DISTANCE, SUN[1] * SUN_DISTANCE, SUN[2] * SUN_DISTANCE]}
+            direction={[-SUN[0], -SUN[1], -SUN[2]]}
+            color={SUN_COLOR}
+            intensity={1}
+            castShadow
+          />
+          <Mesh geometry={plane({ width: 16, height: 16 })} material={ground} rotation={[-Math.PI / 2, 0, 0]} />
+          {cells.map(cell => (
+            <Mesh geometry={ball} material={cell.material} position={cell.position} castShadow />
+          ))}
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/sweep-paths.tsx

@@ -10,8 +10,6 @@ import { createSignal, onFrame, pct, render } from "@solidrt/core"
 import { box, DirectionalLight, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, roundRect, Scene, sweep, tube, unlit } from "@solidrt/3d"
 import type { SweepPath } from "@solidrt/3d"
 
-const SIZE = 720
-
 function App() {
   let [spin, setSpin] = createSignal(0)
   onFrame(tick => setSpin(tick / 4000))
@@ -39,8 +37,8 @@ function App() {
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
-        <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="sweep-paths">
+      <view width={pct(100)} height={pct(100)}>
+        <Scene clearColor={[0.07, 0.07, 0.1, 1]} label="sweep-paths">
           <PerspectiveCamera fov={55} position={[0, 1.9, 3.9]} lookAt={[0, 0.35, 0]} />
           <HemisphereLight sky={[0.45, 0.45, 0.45]} ground={[0.22, 0.22, 0.22]} />
           <DirectionalLight direction={[-0.5, -0.8, -0.4]} intensity={0.8} />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.55",
+  "version": "0.0.56",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -18,7 +18,7 @@
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.4",
-    "@solidrt/core": "0.0.55"
+    "@solidjs/signals": "2.0.0-rc.6",
+    "@solidrt/core": "0.0.56"
   }
 }

package/src/camera.ts

@@ -0,0 +1,148 @@
+// The camera record: one per scene target and one per view (the shadow
+// views included), the same state and the same one-shared-write contract
+// everywhere. Split out of scene.ts so the shadow system can place its
+// map cameras through the exact code the scene uses for its own.
+
+import { invert, lookAt as lookAtMatrix, mat4, multiply, orthographic, perspective } from "./math.ts"
+import type { Mat4, Vec3 } from "./math.ts"
+import type { ShaderParams } from "@solidrt/core/gpu"
+
+/** An orthographic projection's view-space extents, in world units (the
+ * same box at every depth). */
+export type OrthoExtent = { left: number; right: number; top: number; bottom: number }
+
+/** A camera snapshot (Scene/View `camera()`): CameraUpdate's fields, all
+ * present. Arrays are copies of the internal state. */
+export type CameraState = {
+  fov: number
+  near: number
+  far: number
+  position: Vec3
+  target: Vec3
+  up: Vec3
+  ortho: OrthoExtent | null
+}
+
+export type CameraUpdate = {
+  /** Vertical field of view in DEGREES (default 60). */
+  fov?: number
+  near?: number
+  far?: number
+  position?: Vec3
+  target?: Vec3
+  up?: Vec3
+  /** An orthographic projection with these extents (`fov` is then
+   * ignored); null returns to perspective. Three's OrthographicCamera as
+   * a camera option: a top-down map, an isometric view, a shadow-map
+   * light. */
+  ortho?: OrthoExtent | null
+}
+
+// `dirty` = the matrices need recomputing (a setCamera or a resize),
+// `pending` = the GPU write is owed to the next sync. The recompute is
+// split from the sync so project()/viewProj() see a fresh matrix right
+// after setCamera, before the microtask runs.
+export type Camera = {
+  fov: number
+  near: number
+  far: number
+  eye: Vec3
+  target: Vec3
+  up: Vec3
+  ortho: OrthoExtent | null
+  /** Mirror the projection's x: the image comes out flipped left to
+   * right. A reflection probe's face cameras set it - a GL cube face is
+   * seen from outside, the x mirror of what a camera sees - and the cube
+   * draw target's pass inverts the winding to match. */
+  mirror: boolean
+  dirty: boolean
+  pending: boolean
+  proj: Mat4
+  view: Mat4
+  viewProj: Mat4
+  invViewProj: Mat4
+}
+
+export function makeCamera(): Camera {
+  return {
+    fov: 60,
+    near: 0.1,
+    far: 100,
+    eye: [0, 0, 3],
+    target: [0, 0, 0],
+    up: [0, 1, 0],
+    ortho: null,
+    mirror: false,
+    dirty: true,
+    pending: false,
+    proj: mat4(),
+    view: mat4(),
+    viewProj: mat4(),
+    invViewProj: mat4(),
+  }
+}
+
+export function cameraState(cam: Camera): CameraState {
+  return {
+    fov: cam.fov,
+    near: cam.near,
+    far: cam.far,
+    position: [cam.eye[0], cam.eye[1], cam.eye[2]],
+    target: [cam.target[0], cam.target[1], cam.target[2]],
+    up: [cam.up[0], cam.up[1], cam.up[2]],
+    ortho: cam.ortho === null ? null : { left: cam.ortho.left, right: cam.ortho.right, top: cam.ortho.top, bottom: cam.ortho.bottom },
+  }
+}
+
+export function updateCamera(cam: Camera, update: CameraUpdate): void {
+  if (update.fov !== undefined) cam.fov = update.fov
+  if (update.near !== undefined) cam.near = update.near
+  if (update.far !== undefined) cam.far = update.far
+  if (update.position) cam.eye = [update.position[0], update.position[1], update.position[2]]
+  if (update.target) cam.target = [update.target[0], update.target[1], update.target[2]]
+  if (update.up) cam.up = [update.up[0], update.up[1], update.up[2]]
+  if (update.ortho !== undefined) {
+    let o = update.ortho
+    cam.ortho = o === null ? null : { left: o.left, right: o.right, top: o.top, bottom: o.bottom }
+  }
+  cam.dirty = true
+}
+
+export function ensureCamera(cam: Camera, width: number, height: number): void {
+  if (!cam.dirty) return
+  cam.dirty = false
+  cam.pending = true
+  let o = cam.ortho
+  if (o === null) perspective(cam.proj, (cam.fov * Math.PI) / 180, width / height, cam.near, cam.far)
+  else orthographic(cam.proj, o.left, o.right, o.top, o.bottom, cam.near, cam.far)
+  if (cam.mirror) {
+    // Negate the clip x row (column-major: elements 0, 4, 8, 12).
+    cam.proj[0] = -cam.proj[0]!
+    cam.proj[4] = -cam.proj[4]!
+    cam.proj[8] = -cam.proj[8]!
+    cam.proj[12] = -cam.proj[12]!
+  }
+  lookAtMatrix(cam.view, cam.eye, cam.target, cam.up)
+  multiply(cam.viewProj, cam.proj, cam.view)
+  invert(cam.invViewProj, cam.viewProj)
+}
+
+// The camera is target state: one shared write, whatever the target holds.
+// Entries are untouched - uModel is camera-independent, and uCamPos is
+// stored even when no current material declares it. The camera basis rides
+// along: the view matrix's first two rows are the camera's world-space
+// right and up (no clip flip - that lives in the projection), so a
+// 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 {
+  let v = cam.view
+  return {
+    uViewProj: cam.viewProj,
+    uInvViewProj: cam.invViewProj,
+    uCamPos: cam.eye,
+    uCamRight: [v[0], v[4], v[8]],
+    uCamUp: [v[1], v[5], v[9]],
+  }
+}

package/src/clip.ts

@@ -0,0 +1,96 @@
+// Pure clip sampling - the mixer's core, split out so it runs with no
+// scene or engine (checks under flux, custom drivers, a future bake-side
+// resample). Everything here is plain array math over ModelChannel data.
+
+import { quatNormalize, quatSlerp } from "./math.ts"
+import type { Quat } from "./math.ts"
+import type { ModelChannel } from "./gltf.ts"
+
+/**
+ * Sample one channel at `time` (seconds, clamped to the key range) into
+ * `out` - 3 floats for position/scale, 4 for rotation. Pure array math:
+ * step holds the earlier key, linear lerps (rotation slerps the shortest
+ * path), cubic evaluates the glTF CUBICSPLINE Hermite (rotation
+ * renormalized, per spec).
+ */
+export function sampleChannel(channel: ModelChannel, time: number, out: number[]): void {
+  let times = channel.times
+  let values = channel.values
+  let keys = times.length
+  let elements = channel.path === "rotation" ? 4 : 3
+  let stride = channel.interpolation === "cubic" ? elements * 3 : elements
+  // The value element offset within a key: cubic keys are [in, value, out].
+  let mid = channel.interpolation === "cubic" ? elements : 0
+  if (keys === 0) return
+  if (time <= times[0]! || keys === 1) {
+    for (let e = 0; e < elements; e++) out[e] = values[mid + e]!
+    return
+  }
+  if (time >= times[keys - 1]!) {
+    let at = (keys - 1) * stride + mid
+    for (let e = 0; e < elements; e++) out[e] = values[at + e]!
+    return
+  }
+  // The key pair around `time`: binary search for the last key at or
+  // before it.
+  let lo = 0
+  let hi = keys - 1
+  while (hi - lo > 1) {
+    let m = (lo + hi) >> 1
+    if (times[m]! <= time) lo = m
+    else hi = m
+  }
+  let t0 = times[lo]!
+  let t1 = times[hi]!
+  let span = t1 - t0
+  let s = span > 0 ? (time - t0) / span : 0
+  let a = lo * stride + mid
+  let b = hi * stride + mid
+  switch (channel.interpolation) {
+    case "step":
+      for (let e = 0; e < elements; e++) out[e] = values[a + e]!
+      return
+    case "linear":
+      if (channel.path === "rotation") {
+        readQuat(SAMPLE_A, values, a)
+        readQuat(SAMPLE_B, values, b)
+        quatSlerp(SAMPLE_A, SAMPLE_A, SAMPLE_B, s)
+        for (let e = 0; e < 4; e++) out[e] = SAMPLE_A[e]!
+      } else {
+        for (let e = 0; e < elements; e++) out[e] = values[a + e]! + (values[b + e]! - values[a + e]!) * s
+      }
+      return
+    case "cubic": {
+      // glTF's Hermite: p(s) = h00 v0 + h10 d b0 + h01 v1 + h11 d a1,
+      // where b0 is key lo's OUT-tangent and a1 key hi's IN-tangent
+      // (per-second, so they scale by the span d).
+      let s2 = s * s
+      let s3 = s2 * s
+      let h00 = 2 * s3 - 3 * s2 + 1
+      let h10 = s3 - 2 * s2 + s
+      let h01 = -2 * s3 + 3 * s2
+      let h11 = s3 - s2
+      let outTan = lo * stride + elements * 2
+      let inTan = hi * stride
+      for (let e = 0; e < elements; e++) {
+        out[e] = h00 * values[a + e]! + h10 * span * values[outTan + e]! + h01 * values[b + e]! + h11 * span * values[inTan + e]!
+      }
+      if (channel.path === "rotation") {
+        readQuat(SAMPLE_A, out, 0)
+        quatNormalize(SAMPLE_A, SAMPLE_A)
+        for (let e = 0; e < 4; e++) out[e] = SAMPLE_A[e]!
+      }
+      return
+    }
+  }
+}
+
+const SAMPLE_A: Quat = [0, 0, 0, 1]
+const SAMPLE_B: Quat = [0, 0, 0, 1]
+
+function readQuat(out: Quat, values: ArrayLike<number>, at: number): void {
+  out[0] = values[at]!
+  out[1] = values[at + 1]!
+  out[2] = values[at + 2]!
+  out[3] = values[at + 3]!
+}

package/src/collision.ts

@@ -0,0 +1,199 @@
+// A kinematic character move over the scene's volume queries: Godot's
+// CharacterBody3D.move_and_slide and Unity's CharacterController.Move as
+// one pure function. Sweep the body along its motion, stop a skin short
+// of the first contact, slide the rest along the contact plane, repeat a
+// few times - with the two passes both engines wrap around that loop: a
+// depenetration first (a body that starts inside something is pushed out
+// before it moves) and a floor snap after (a body walking down a ramp is
+// pulled back onto it instead of stepping into the air). Per body per
+// frame that is the input read and this one call; the geometry runs in
+// the spatial core.
+//
+// Pure on purpose: no node, no velocity state. It takes a volume where the
+// body IS and the motion it WANTS, and returns the motion it gets plus
+// what it touched - the first-person camera (which has no node) composes
+// it in clampPosition, and a node-driven body applies the result with
+// setTransform. Gravity is the caller's: fold it into `motion`; a walkable
+// floor absorbs the vertical part (a body does not creep down a slope it
+// can stand on), a steep one slides it.
+
+import type { Vec3 } from "./math.ts"
+import type { Impact, QueryOptions, Scene, Volume } from "./scene.ts"
+
+/** Gap the body keeps from every surface, world units (Unity's skinWidth,
+ * Godot's safe_margin): what keeps float error from sinking a resting body
+ * into its floor. */
+const SKIN = 0.01
+/** Contacts within this angle of `up` are floor: 45 degrees, Godot's
+ * floor_max_angle and Unity's slopeLimit. */
+const FLOOR_MAX_ANGLE = Math.PI / 4
+/** Most contacts one call slides along before it stops where it is
+ * (Godot's max_slides). */
+const MAX_SLIDES = 6
+/** How far below the body a floor is pulled to while it is not rising
+ * (Godot's floor_snap_length). */
+const FLOOR_SNAP = 0.1
+/** Passes of the depenetration loop, one contact set pushed out per pass
+ * (Godot's recovery attempts). */
+const MAX_RECOVERIES = 4
+/** Motion below which a slide stops: nothing left worth sweeping. */
+const MIN_MOVE = 1e-6
+/** Floor of the approach cosine the skin is divided by to retreat along
+ * the motion: a grazing contact retreats a few skins, not the whole step. */
+const SKIN_MIN_COS = 0.1
+
+const UP: Vec3 = [0, 1, 0]
+
+/** What moveAndSlide needs of a scene. */
+export type MoveScene = Pick<Scene, "sweep" | "overlap">
+
+export type MoveOptions = QueryOptions & {
+  /** The direction floors face (default [0, 1, 0]). */
+  up?: Vec3
+  /** Largest angle (radians) between a contact normal and `up` that still
+   * counts as floor (default 45 degrees). Steeper contacts are walls, and
+   * the body slides down them. */
+  floorMaxAngle?: number
+  /** Most contacts one call slides along (default 6). */
+  maxSlides?: number
+  /** Gap kept from every surface, world units (default 0.01). */
+  skin?: number
+  /** How far below the body a floor is pulled to when the motion does not
+   * rise (default 0.1; 0 disables): what keeps a walker on a ramp going
+   * down, and what decides `floor` at the end of the move - a body that
+   * ends higher than this above its floor is airborne, whatever it
+   * touched on the way. A rising motion (a jump) never snaps. */
+  floorSnap?: number
+}
+
+export type MoveResult = {
+  /** The displacement the body gets: add it to the body's position. */
+  motion: Vec3
+  /** The unit normal of the floor the body ends the move on - within
+   * `floorSnap` below it, snapped onto - else null (airborne, or on a
+   * slope too steep to stand on). With `floorSnap: 0` it is a floor met
+   * during the move instead. */
+  floor: Vec3 | null
+  /** Whether a wall (a contact steeper than a floor and flatter than a
+   * ceiling) or a ceiling was met. */
+  wall: boolean
+  ceiling: boolean
+  /** Every contact met, in order, the floor snap's last. */
+  hits: Impact[]
+}
+
+/**
+ * Move a body `motion` through the scene's colliders, sliding along what
+ * it hits (Godot's move_and_slide, Unity's CharacterController.Move): a
+ * capsule for a character, a sphere for a ball, a box for a crate. The
+ * body first pushes out of anything it starts inside, then sweeps and
+ * slides up to `maxSlides` times, then, unless the motion rises, snaps
+ * down onto a floor within `floorSnap` - the floor it reports is the one
+ * it ends on. Colliders are whatever `opts`
+ * selects (`layers`/`meshes`, as for sweep): pass the collision layer,
+ * or the body's own mesh answers for its own walls.
+ *
+ * Gravity is the caller's: fold the fall into `motion` each frame, zero
+ * it while `floor` is set (the snap keeps reporting the floor while the
+ * body stands still), and a walkable floor absorbs the vertical part -
+ * `motion` only ever moves the body along a floor it stands on, never
+ * down it.
+ */
+export function moveAndSlide(scene: MoveScene, volume: Volume, motion: Vec3, opts: MoveOptions = {}): MoveResult {
+  let up = opts.up ?? UP
+  let floorCos = Math.cos(opts.floorMaxAngle ?? FLOOR_MAX_ANGLE)
+  let maxSlides = opts.maxSlides ?? MAX_SLIDES
+  let skin = opts.skin ?? SKIN
+  let snap = opts.floorSnap ?? FLOOR_SNAP
+  let query: QueryOptions = { layers: opts.layers, meshes: opts.meshes }
+  let offset: Vec3 = [0, 0, 0]
+  let hits: Impact[] = []
+  let floor: Vec3 | null = null
+  let wall = false
+  let ceiling = false
+
+  // Depenetration: every contact's push-out, each only as far as the
+  // pushes so far have not already covered along its normal, so two
+  // walls of a corner do not push twice.
+  for (let pass = 0; pass < MAX_RECOVERIES; pass++) {
+    let push: Vec3 = [0, 0, 0]
+    let any = false
+    for (let c of scene.overlap(shifted(volume, offset), query)) {
+      if (c.depth <= 0) continue
+      any = true
+      let extra = c.depth + skin - dot(push, c.normal)
+      if (extra > 0) push = add(push, scale(c.normal, extra))
+    }
+    if (!any) break
+    offset = add(offset, push)
+  }
+
+  let remaining: Vec3 = [motion[0], motion[1], motion[2]]
+  for (let slide = 0; slide < maxSlides; slide++) {
+    let len = Math.hypot(remaining[0], remaining[1], remaining[2])
+    if (len < MIN_MOVE) break
+    let hit = scene.sweep(shifted(volume, offset), remaining, query)[0]
+    if (hit === undefined) {
+      offset = add(offset, remaining)
+      break
+    }
+    hits.push(hit)
+    let dir = scale(remaining, 1 / len)
+    let n = hit.normal
+    // Stop where the gap to the surface, measured along its normal, is
+    // one skin; the sweep guarantees the approach is positive.
+    let retreat = skin / Math.max(-dot(dir, n), SKIN_MIN_COS)
+    let advance = Math.max(hit.time * len - retreat, 0)
+    offset = add(offset, scale(dir, advance))
+    remaining = scale(dir, len - advance)
+    let rise = dot(n, up)
+    if (rise >= floorCos) {
+      // A floor takes the vertical part (the fall, a landing) and passes
+      // the horizontal part along its plane.
+      floor = n
+      let level = sub(remaining, scale(up, dot(remaining, up)))
+      remaining = sub(level, scale(n, dot(level, n)))
+    } else {
+      if (rise <= -floorCos) ceiling = true
+      else wall = true
+      remaining = sub(remaining, scale(n, dot(remaining, n)))
+    }
+  }
+
+  // Where the body ends decides the floor: a contact met on the way
+  // (a ramp's top before a big step past its crest) is not one to stand
+  // on unless it is still within reach below.
+  if (snap > 0 && dot(motion, up) <= 0) {
+    floor = null
+    let hit = scene.sweep(shifted(volume, offset), scale(up, -snap), query)[0]
+    if (hit !== undefined && dot(hit.normal, up) >= floorCos) {
+      hits.push(hit)
+      let retreat = skin / Math.max(dot(hit.normal, up), SKIN_MIN_COS)
+      offset = add(offset, scale(up, -Math.max(hit.time * snap - retreat, 0)))
+      floor = hit.normal
+    }
+  }
+  return { motion: offset, floor, wall, ceiling, hits }
+}
+
+/** The volume displaced by `d`. */
+function shifted(volume: Volume, d: Vec3): Volume {
+  if ("center" in volume) return { ...volume, center: add(volume.center, d) }
+  return { ...volume, a: add(volume.a, d), b: add(volume.b, d) }
+}
+
+function add(a: Vec3, b: Vec3): Vec3 {
+  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]]
+}
+
+function sub(a: Vec3, b: Vec3): Vec3 {
+  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]]
+}
+
+function scale(v: Vec3, s: number): Vec3 {
+  return [v[0] * s, v[1] * s, v[2] * s]
+}
+
+function dot(a: Vec3, b: Vec3): number {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+}

package/src/color.ts

@@ -0,0 +1,32 @@
+// The sRGB transfer functions (IEC 61966-2-1) in JS, the JS half of the
+// package's color contract: every [r, g, b] color option - material
+// color and emissive, light color, hemisphere sky and ground, fog color -
+// is sRGB-encoded, what a color picker shows, and the library decodes it to
+// linear light when it writes the uniform (Three's ColorManagement,
+// Godot's inspector colors, Unity's linear color space all do the same).
+// Shading then runs in linear light and the fragment's output stage
+// (OUTPUT in ./glsl) encodes the result back. Values written straight to
+// a uniform (scene.setParams, setMeshParams) and vertex colors are linear,
+// as in every engine; encode or decode them here when they come from a
+// picker.
+
+/** Decode one sRGB-encoded component (0..1) to linear light. Above 1 the
+ * curve continues, so an intensity folded into a color survives. */
+export function srgbToLinear(c: number): number {
+  if (c <= 0.04045) return c / 12.92
+  return Math.pow((c + 0.055) / 1.055, 2.4)
+}
+
+/** Encode one linear-light component to sRGB: the inverse of srgbToLinear. */
+export function linearToSrgb(c: number): number {
+  if (c <= 0.0031308) return c * 12.92
+  return 1.055 * Math.pow(c, 1 / 2.4) - 0.055
+}
+
+/** A copy of an [r, g, b] or [r, g, b, a] color with its rgb decoded to
+ * linear light; alpha is coverage, never encoded, and passes through. */
+export function linearColor(color: readonly number[]): number[] {
+  let out = color.slice()
+  for (let i = 0; i < 3 && i < out.length; i++) out[i] = srgbToLinear(out[i]!)
+  return out
+}