@solidrt/3d 0.0.55 → 0.0.56

package/src/environment.ts

@@ -0,0 +1,325 @@
+// Environment helpers: the baked HDR environment loader (the .srte chain
+// `srt tool 3d/environment` writes), the equirectangular-to-cube
+// conversion a fetched LDR panorama needs at runtime, the GPU prefilter
+// that turns a rendered cube (a reflection probe's, a baked sky's) into
+// the roughness chain, and the placeholder cube a scene binds as uEnv
+// while no environment is set. The face passes here render straight into
+// cube draw targets: no readback, no re-upload.
+
+import { file } from "flux:fs"
+import {
+  addDraw,
+  compileShader,
+  createCubeDrawTarget,
+  createCubeTexture,
+  createRenderPipeline,
+  destroyProgram,
+  destroyRenderPipeline,
+  destroyShader,
+  destroyTexture,
+  glsl,
+  limits,
+  linkProgram,
+  removeDraw,
+  renderTarget,
+  setDrawParams,
+} from "@solidrt/core/gpu"
+import type { CreateOptions, DrawId, ProgramId, RenderPipelineId, SamplerOptions, TextureFormatOptions, TextureId } from "@solidrt/core/gpu"
+import { decodeEnvironment, levelRoughness, mipLevels } from "./environment-bake.ts"
+
+/**
+ * Read a baked environment (`srt tool 3d/environment sky.hdr -o
+ * assets/sky.srte`) and upload it: the HDR cube with its GGX-prefiltered
+ * mip chain, as an explicit "rgba16f" chain - no generated mipmaps, so it
+ * works on every device. The id is what `environment={{ cube }}` and
+ * `background={{ cube }}` take (Three's `scene.environment` from an
+ * RGBELoader + PMREMGenerator, Unity's convolved reflection probe, Godot's
+ * radiance map, all done at build time here). Created after an await, so
+ * it is NOT auto-freed: an environment normally lives as long as the app;
+ * destroyTexture it otherwise. The same async shape as loadModel (see
+ * examples/model-load.tsx for the <Loading> pattern).
+ */
+export async function loadEnvironment(path: string, opts?: CreateOptions): Promise<TextureId> {
+  let { size, levels } = decodeEnvironment(await file(path).bytes())
+  return createCubeTexture(levels, size, { ...opts, format: "rgba16f", mipmap: true, label: opts?.label ?? "environment" })
+}
+
+// The GL cube-map table as GLSL (cubeDirection in environment-bake.ts):
+// the world direction whose lookup lands on `face` at (s, t) in 0..1, t =
+// 0 the first row, unnormalized. Every pass that writes a face texel
+// (equirectToCube's, the prefilter's) derives its direction from it, so
+// the face holds what a lookup of that direction returns.
+const CUBE_FACE_DIRECTION = glsl`
+  vec3 cubeFaceDirection(int face, vec2 st) {
+    float a = 2.0 * st.x - 1.0;
+    float b = 2.0 * st.y - 1.0;
+    if (face == 0) return vec3(1.0, -b, -a);
+    if (face == 1) return vec3(-1.0, -b, a);
+    if (face == 2) return vec3(a, 1.0, b);
+    if (face == 3) return vec3(a, -1.0, -b);
+    if (face == 4) return vec3(a, -b, 1.0);
+    return vec3(-a, -b, -1.0);
+  }
+`
+
+// The vertex stage of every face pass: the attributeless covering
+// triangle emitting vUV with t = 0 at the face's first row, so the
+// fragment's texel is (s, t) of the GL cube table - the same vUV the
+// background and shader-target passes carry.
+const FACE_VERTEX = glsl`
+  out vec2 vUV;
+  void main() {
+    vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+    vUV = p;
+    gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+  }
+`
+
+// A face pass: FACE_VERTEX over `fragment`, one pipeline owned by the
+// caller (destroyed through `dispose` once its faces are rendered).
+function facePipeline(fragment: string, label: string): { pipeline: RenderPipelineId; program: ProgramId; dispose(): void } {
+  let vs = compileShader("vertex", FACE_VERTEX, { header: true })
+  let fs = compileShader("fragment", fragment, { header: true })
+  let program = linkProgram(vs, fs, { label })
+  destroyShader(vs)
+  destroyShader(fs)
+  let pipeline = createRenderPipeline(program, { label })
+  return {
+    pipeline,
+    program,
+    dispose() {
+      destroyRenderPipeline(pipeline)
+      destroyProgram(program)
+    },
+  }
+}
+
+// Render the six faces of a cube draw target whose one entry reads uFace:
+// the first five into level 0 explicitly (an explicit level regenerates
+// nothing) and the last plainly, so a mipmapped cube regenerates its
+// chain once.
+function renderFaces(cube: TextureId, entry: DrawId): void {
+  for (let face = 0; face < 6; face++) {
+    setDrawParams(cube, entry, { uFace: face })
+    if (face < 5) renderTarget(cube, face, 0)
+    else renderTarget(cube, face)
+  }
+}
+
+// One face of the cube: the texel's sampling direction from the GL
+// cube-map table. The panorama's center column faces -Z (the
+// camera's default forward; Godot's PanoramaSkyMaterial and Unity's
+// Skybox/Panoramic agree; Three centers +X, a quarter turn away), its top
+// row +Y. At the seam column the uv derivative jumps by a full turn;
+// zeroing that component keeps a mipmapped source from drawing a line.
+// An sRGB source samples decoded and the face is written linear; a cube
+// created at the same format encodes it on write and decodes on sample,
+// so the bytes round-trip.
+const EQUIRECT_FACE = glsl`
+  in vec2 vUV;
+  uniform sampler2D uMap;
+  uniform float uFace;
+  ${CUBE_FACE_DIRECTION}
+  const float PI = 3.14159265358979;
+  // A uv derivative larger than this is the seam wrap, not a real step.
+  const float SEAM_JUMP = 0.5;
+  void main() {
+    vec3 d = normalize(cubeFaceDirection(int(uFace + 0.5), vUV));
+    vec2 uv = vec2(atan(d.x, -d.z) / (2.0 * PI) + 0.5, acos(clamp(d.y, -1.0, 1.0)) / PI);
+    vec2 dx = dFdx(uv);
+    vec2 dy = dFdy(uv);
+    if (abs(dx.x) > SEAM_JUMP) dx.x = 0.0;
+    if (abs(dy.x) > SEAM_JUMP) dy.x = 0.0;
+    fragColor = textureGrad(uMap, uv, dx, dy);
+  }
+`
+
+/**
+ * Convert an equirectangular panorama (an uploaded 2D texture: createImage,
+ * createTexture) into a cube map of `size` x `size` faces, returned as a
+ * cube TextureId ready for a skybox or the environment - Three's
+ * `WebGLCubeRenderTarget.fromEquirectangularTexture`, Unity's cube import
+ * of a lat-long image. The six faces render on the GPU straight into a
+ * cube draw target (no readback, no upload), synchronously. `opts` are
+ * createCubeTexture's (`mipmap: true` for an environment shininess can
+ * blur; `label`; `autoFree: false` to own it), and `format` names the
+ * PANORAMA's format so the cube decodes like it: "rgba8-srgb" for a
+ * photographed sky uploaded as such, "rgba8" (default) for data,
+ * "rgba16f" for an HDR panorama (the cube keeps the range; renderable on
+ * every device with half-float rendering, else it throws - the prefiltered
+ * form of that panorama is `srt tool 3d/environment` plus
+ * loadEnvironment). The panorama's center column faces -Z and its top
+ * row is +Y. Leave its wrap at the default clamp: `repeat` would also
+ * wrap vertically and bleed the poles across the top and bottom rows,
+ * while the clamped seam column costs at most a texel-wide blend at +Z.
+ * Three centers its panoramas on +X: a rotation tuned there differs by a
+ * quarter turn here.
+ */
+export function equirectToCube(map: TextureId, size: number, opts?: CreateOptions & SamplerOptions & TextureFormatOptions): TextureId {
+  if (!Number.isInteger(size) || size < 1) throw new Error("equirectToCube: size must be a positive integer, got " + size)
+  let format = opts?.format ?? "rgba8"
+  if (format !== "rgba8" && format !== "rgba8-srgb" && format !== "rgba16f") {
+    throw new Error('equirectToCube: format must be "rgba8", "rgba8-srgb" or "rgba16f" (the panorama\'s), got ' + format)
+  }
+  let label = opts?.label ?? "equirect"
+  let cube = createCubeDrawTarget(size, null, { ...opts, format, label })
+  let pass = facePipeline(EQUIRECT_FACE, label + "-face")
+  let entry = addDraw(cube, pass.pipeline, { uFace: 0 }, { vertexCount: 3, textures: { uMap: map } })
+  renderFaces(cube, entry)
+  // The faces are pixels now; the pass and its binding of the panorama go.
+  removeDraw(cube, entry)
+  pass.dispose()
+  return cube
+}
+
+// One face of one level of the prefiltered chain: prefilterCube's GGX
+// convolution (environment-bake.ts) as a fragment. The texel's direction
+// is the normal, view and reflection direction at once (N = V = R, every
+// engine's bake), the GGX lobe at uRoughness is importance sampled with a
+// Hammersley set, each sample reading the sharp source cube at the mip
+// level whose texel covers the sample's solid angle (the source carries a
+// generated chain), weighted by the reflected direction's cosine. A
+// roughness of 0 is the base level: a copy.
+const PREFILTER_FACE = glsl`
+  in vec2 vUV;
+  uniform samplerCube uSource;
+  uniform float uFace;
+  uniform float uRoughness;
+  ${CUBE_FACE_DIRECTION}
+  const float PI = 3.14159265358979;
+  // GGX samples per texel: the CPU bake takes 512; reading each sample at
+  // the lod of its solid angle lets a fraction of that converge on the GPU.
+  const int PREFILTER_SAMPLES = 64;
+  // Bias on the source lod a sample reads (Karis: +1 smooths the estimate
+  // without visible extra blur).
+  const float SOURCE_LOD_BIAS = 1.0;
+  // A sample's normal-lobe cosine below this contributes nothing (the lobe
+  // mirrored below the horizon).
+  const float MIN_NOL = 1e-6;
+  // |n.z| above which the tangent frame's helper axis switches to +X.
+  const float POLE = 0.999;
+  // Van der Corput radical inverse: the second Hammersley coordinate.
+  float radicalInverse(uint bits) {
+    bits = (bits << 16u) | (bits >> 16u);
+    bits = ((bits & 0x55555555u) << 1u) | ((bits & 0xAAAAAAAAu) >> 1u);
+    bits = ((bits & 0x33333333u) << 2u) | ((bits & 0xCCCCCCCCu) >> 2u);
+    bits = ((bits & 0x0F0F0F0Fu) << 4u) | ((bits & 0xF0F0F0F0u) >> 4u);
+    bits = ((bits & 0x00FF00FFu) << 8u) | ((bits & 0xFF00FF00u) >> 8u);
+    return float(bits) / 4294967296.0;
+  }
+  void main() {
+    vec3 n = normalize(cubeFaceDirection(int(uFace + 0.5), vUV));
+    if (uRoughness <= 0.0) {
+      fragColor = vec4(textureLod(uSource, n, 0.0).rgb, 1.0);
+      return;
+    }
+    float alpha = uRoughness * uRoughness;
+    float a2 = alpha * alpha;
+    float edge = float(textureSize(uSource, 0).x);
+    // The solid angle of one base-level source texel.
+    float texelAngle = 4.0 * PI / (6.0 * edge * edge);
+    vec3 up = abs(n.z) > POLE ? vec3(1.0, 0.0, 0.0) : vec3(0.0, 0.0, 1.0);
+    vec3 t = normalize(cross(up, n));
+    vec3 b = cross(n, t);
+    vec3 acc = vec3(0.0);
+    float weight = 0.0;
+    for (int i = 0; i < PREFILTER_SAMPLES; i++) {
+      float u1 = (float(i) + 0.5) / float(PREFILTER_SAMPLES);
+      float u2 = radicalInverse(uint(i));
+      float phi = 2.0 * PI * u1;
+      float cosT = sqrt((1.0 - u2) / (1.0 + (a2 - 1.0) * u2));
+      float sinT = sqrt(max(0.0, 1.0 - cosT * cosT));
+      // N = V, so the reflected sample's cosine is 2 cos^2 - 1.
+      float nol = 2.0 * cosT * cosT - 1.0;
+      if (nol <= MIN_NOL) continue;
+      vec3 h = t * (sinT * cos(phi)) + b * (sinT * sin(phi)) + n * cosT;
+      vec3 l = 2.0 * cosT * h - n;
+      float d = cosT * cosT * (a2 - 1.0) + 1.0;
+      float pdf = a2 / (PI * d * d) / 4.0;
+      float sampleAngle = 1.0 / (float(PREFILTER_SAMPLES) * pdf);
+      float lod = max(0.0, 0.5 * log2(sampleAngle / texelAngle) + SOURCE_LOD_BIAS);
+      acc += textureLod(uSource, l, lod).rgb * nol;
+      weight += nol;
+    }
+    fragColor = vec4(acc / weight, 1.0);
+  }
+`
+
+/** A roughness chain rendered on the GPU from a sharp cube (internal: the
+ * reflection probe's and bakeBackground's second half). */
+export type Prefilter = {
+  /** The chain: a mipmapped cube draw target of the source's size, what
+   * the environment samples. */
+  cube: TextureId
+  /** Fill every level of every face from the source's current pixels:
+   * level 0 a copy, each level below convolved at its levelRoughness. */
+  run(): void
+  /** Drop the pass (its pipeline, program and binding of the source) and
+   * hand over the chain, which keeps its pixels: a one-shot bake's end.
+   * The source is free to go afterwards. */
+  finish(): TextureId
+  /** finish() plus the chain itself. */
+  dispose(): void
+}
+
+/** The format of a rendered radiance cube (a probe's faces, its chain, a
+ * baked sky): half float where the device renders it, so the range of a
+ * sun or an emissive survives into reflections as in every engine's HDR
+ * probe, else 8-bit and clamped - the picture degrades, the app runs. Not
+ * a knob: the renderer decides for all probes (Godot), HDR by default
+ * (Unity). */
+export type ProbeFormat = "rgba8" | "rgba16f"
+export function probeFormat(): ProbeFormat {
+  return limits.halfFloatRenderable ? "rgba16f" : "rgba8"
+}
+
+/**
+ * The runtime counterpart of the bake tool's prefilterCube: a mipmapped
+ * cube draw target of `size` and `format` whose chain `run()` fills from
+ * `source`, a `mipmap: true` cube of the same size and format (a cube
+ * draw target rendered sharp), one pass per face per level - 48 small
+ * passes at 128. Three's PMREMGenerator, Unity's and Godot's probe
+ * convolution, on the same roughness-to-level rule as the .srte chain
+ * (levelRoughness), so `standard` reads both alike.
+ */
+export function createPrefilter(size: number, source: TextureId, format: ProbeFormat, label: string): Prefilter {
+  let pass: ReturnType<typeof facePipeline> | null = facePipeline(PREFILTER_FACE, label + "-prefilter")
+  let cube = createCubeDrawTarget(size, null, { mipmap: true, format, autoFree: false, label })
+  let entry = addDraw(cube, pass.pipeline, { uFace: 0, uRoughness: 0 }, { vertexCount: 3, textures: { uSource: source } })
+  let levels = mipLevels(size)
+  let finish = () => {
+    if (pass !== null) {
+      removeDraw(cube, entry)
+      pass.dispose()
+      pass = null
+    }
+    return cube
+  }
+  return {
+    cube,
+    run() {
+      if (pass === null) return
+      for (let level = 0; level < levels; level++) {
+        // The base is a copy whatever the size (a chain of 4 or less has
+        // no ramp: levelRoughness is 1 everywhere), as the CPU bake's is.
+        let roughness = level === 0 ? 0 : levelRoughness(size, level)
+        for (let face = 0; face < 6; face++) {
+          setDrawParams(cube, entry, { uFace: face, uRoughness: roughness })
+          renderTarget(cube, face, level)
+        }
+      }
+    },
+    finish,
+    dispose() {
+      destroyTexture(finish())
+    },
+  }
+}
+
+/** The 1x1 black cube a scene binds as uEnv while it has no environment
+ * (uEnvOn 0 makes the term vanish; the binding only keeps the sampler
+ * complete). Owned by the scene, which destroys it with itself. */
+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 })
+}

package/src/first-person.ts

@@ -0,0 +1,306 @@
+// A first-person camera for a scene: a position plus yaw/pitch, with mouse
+// look under pointer lock, drag-to-look without it (the touch path), and
+// walk (or fly) from keys and gamepad sticks - Unity's FirstPersonController
+// shape, look and move in one control, rather than Three's split into
+// PointerLockControls (look only) and a hand-written key loop.
+//
+// Look input has three sources, all summed into the same yaw/pitch:
+// - pointer-move deltas (movementX/movementY) while the pointer is locked,
+//   the desktop mouse-look path; the control never engages the lock itself
+//   (click-to-lock and Escape-to-release are window-level decisions that
+//   stay app code, see lockPointer in @solidrt/core);
+// - a one-finger drag through core's transform recognizer while NOT locked,
+//   so a touch viewport looks around with the arena arbitration the orbit
+//   camera has, and viewport-relative like it;
+// - the right stick, read from core's gamepads() at update time.
+// Move input: WASD/arrows (physical codes AND logical keys, so a layout
+// or a synthetic event without a code both work), Q/E for down/up in fly
+// mode, and the left stick. Walking flattens the forward vector onto the
+// ground plane at fixed height; flying moves along the view direction.
+//
+// Pose is plain mutable state advanced by update(dt) from the app's own
+// onFrame, as in orbit.ts: only `active` is reactive - whether anything is
+// held or deflected, what a frame loop gates on; it derives from the held
+// count and core's gamepads() so a stick moved while the loop is off wakes
+// it - while the pose moves at frame rate and bypasses reactivity. Held
+// keys cannot be polled (there is no key-state accessor in core), so the
+// control tracks them from the down/up pair; an `onBlur` handler drops
+// them all, because the up never arrives once focus has left.
+//
+// Collision is deliberately absent: a camera control cannot know the
+// level. Clamp or reject positions through `clampPosition`.
+//
+// Options are read where they apply, not copied out: `fly`, `moveSpeed`,
+// `lookSpeed`, the pitch clamps, `viewport` and `clampPosition` are
+// re-read from the options object on every input or update, so a caller
+// may change a field (or hand in an object of getters, which is what
+// `<FirstPersonCamera>` does with its props) and the next move sees it -
+// walk and fly are one control, not two mounts. Only the initial pose is
+// copied at creation; later pose changes go through set().
+
+import { createMemo, createSignal } from "@solidjs/signals"
+import { createTransform, gamepads, pointerLocked } from "@solidrt/core"
+import type { KeyEvent, PointerEvent } from "@solidrt/core"
+import type { CameraUpdate } from "./camera.ts"
+import type { Vec3 } from "./math.ts"
+
+// Baseline sensitivities at lookSpeed 1. Mouse look is radians per moved
+// logical pixel under lock (Three's PointerLockControls figure); with a
+// `viewport` the drag is viewport-relative, one viewport height sweeping
+// DRAG_TURNS turns, and without one it falls back to the mouse figure.
+// The stick turns at LOOK_STICK radians/second at full deflection, with
+// a dead zone below which a resting stick reads as zero.
+const LOOK_MOUSE = 0.002
+const DRAG_TURNS = 0.5
+const LOOK_STICK = 2.5
+const STICK_DEADZONE = 0.15
+// Default walking speed, world units per second.
+const MOVE_SPEED = 3
+// Pitch clamps stop short of the poles so the look direction never
+// degenerates against world up.
+const PITCH_LIMIT = Math.PI / 2 - 0.01
+
+/** What a first-person camera drives: a Scene, or one of its Views. */
+export type FirstPersonTarget = { setCamera(update: CameraUpdate): void }
+
+/** The pose fields (position, yaw, pitch) are initial values, copied at
+ * creation and changed through set() afterwards. Every other field is
+ * live: read from this object where it applies, so a change takes effect
+ * on the next input or update. */
+export type FirstPersonCameraOptions = {
+  /** Initial eye position (default [0, 1.6, 0]: standing height at the
+   * origin). */
+  position?: Vec3
+  /** Initial look, radians. Yaw 0 faces -z (the camera default), positive
+   * turns left; pitch 0 is level, positive looks up. */
+  yaw?: number
+  pitch?: number
+  /** Pitch clamps, radians; the defaults stop just short of the poles. */
+  minPitch?: number
+  maxPitch?: number
+  /** Movement speed in world units per second (default 3). */
+  moveSpeed?: number
+  /** Multiplier over the built-in mouse, drag and stick look rates. */
+  lookSpeed?: number
+  /** Walk (default) keeps the height fixed and moves along the ground
+   * projection of the view; fly moves along the view itself and arms Q/E
+   * for down/up (bound either way, inert while walking). Toggling it on a
+   * running control keeps the pose and the held keys. */
+  fly?: boolean
+  /** The viewport a drag lives in: the input element's own laid-out
+   * height (the frame the recognizer's deltas arrive in); makes the drag
+   * viewport-relative. Null while unknown. */
+  viewport?: () => { height: number } | null
+  /** Constrain where a move may put the eye: called with the eye the
+   * move asks for and the eye it starts from (both fresh arrays), returns
+   * the position to use - a level's bounds, a floor height, a collision
+   * controller's `moveAndSlide` over the difference. Look does not
+   * consult it. */
+  clampPosition?: (next: Vec3, current: Vec3) => Vec3
+}
+
+export type FirstPersonPose = {
+  position?: Vec3
+  yaw?: number
+  pitch?: number
+}
+
+export type FirstPersonCamera = {
+  /** Eye position (a fresh array per call). */
+  eye(): Vec3
+  /** Unit look direction for the current pose (a fresh array per call). */
+  forward(): Vec3
+  /** Pose snapshot - the shape debug commands return and set() takes. */
+  pose(): { position: Vec3; yaw: number; pitch: number }
+  /** Merge a pose in (clamps apply); reaches the scene at the next
+   * update(). */
+  set(pose: FirstPersonPose): void
+  /** Whether a movement key is held or a stick deflected - what a frame
+   * loop should run on. Reactive (signal-backed). */
+  active(): boolean
+  /** Integrate held keys and sticks over dt seconds and push any pose
+   * change to the driven camera; returns whether the pose changed. */
+  update(dt: number): boolean
+  /** Spread onto the element that receives input. Keys route through the
+   * focused node, so that element must hold focus (or be the window). */
+  handlers: {
+    onPointerDown(e: PointerEvent): void
+    onPointerMove(e: PointerEvent): void
+    onPointerUp(e: PointerEvent): void
+    onKeyDown(e: KeyEvent): void
+    onKeyUp(e: KeyEvent): void
+    onBlur(): void
+  }
+}
+
+type Move = "forward" | "back" | "left" | "right" | "up" | "down"
+
+// Physical codes first (layout-independent), then the logical keys a
+// synthetic event or an odd layout reports.
+const KEY_MOVES: Record<string, Move> = {
+  KeyW: "forward", ArrowUp: "forward", w: "forward", W: "forward",
+  KeyS: "back", ArrowDown: "back", s: "back", S: "back",
+  KeyA: "left", ArrowLeft: "left", a: "left", A: "left",
+  KeyD: "right", ArrowRight: "right", d: "right", D: "right",
+  KeyE: "up", e: "up", E: "up",
+  KeyQ: "down", q: "down", Q: "down",
+}
+
+let clampNum = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v))
+let deadzone = (v: number) => (Math.abs(v) < STICK_DEADZONE ? 0 : v)
+
+/**
+ * Create a first-person camera driving `camera`'s position and target,
+ * where `camera` is a Scene or one of its Views (fov, near, and far stay
+ * yours via its setCamera). The initial pose applies immediately. In a
+ * component tree, prefer the `<FirstPersonCamera>` component: it wires
+ * scene, input, focus, viewport and the frame loop through the Scene
+ * context.
+ */
+export function createFirstPersonCamera(camera: FirstPersonTarget, options: FirstPersonCameraOptions = {}): FirstPersonCamera {
+  let position: Vec3 = options.position ? [options.position[0], options.position[1], options.position[2]] : [0, 1.6, 0]
+  let yaw = options.yaw ?? 0
+  let pitch = options.pitch ?? 0
+  // Everything below the pose is read from `options` where it applies.
+  let lookSpeed = () => options.lookSpeed ?? 1
+  let clampPitch = () => {
+    pitch = clampNum(pitch, options.minPitch ?? -PITCH_LIMIT, options.maxPitch ?? PITCH_LIMIT)
+  }
+
+  let held = new Set<Move>()
+  let [heldCount, setHeldCount] = createSignal(0)
+  let dirty = false
+
+  let forward = (): Vec3 => {
+    let cp = Math.cos(pitch)
+    return [-Math.sin(yaw) * cp, Math.sin(pitch), -Math.cos(yaw) * cp]
+  }
+  let apply = () => {
+    let f = forward()
+    camera.setCamera({ position: [position[0], position[1], position[2]], target: [position[0] + f[0], position[1] + f[1], position[2] + f[2]] })
+  }
+  let look = (dx: number, dy: number) => {
+    yaw -= dx
+    pitch -= dy
+    clampPitch()
+    dirty = true
+  }
+  let moveBy = (dx: number, dy: number, dz: number) => {
+    let next: Vec3 = [position[0] + dx, position[1] + dy, position[2] + dz]
+    position = options.clampPosition ? options.clampPosition(next, [position[0], position[1], position[2]]) : next
+    dirty = true
+  }
+
+  // The stick axes of every connected pad, summed: a game with one player
+  // sees its one pad, and a pad at rest contributes nothing.
+  let sticks = () => {
+    let s = { moveX: 0, moveY: 0, lookX: 0, lookY: 0 }
+    for (let pad of gamepads()) {
+      if (!pad) continue
+      s.moveX += deadzone(pad.axes.leftX ?? 0)
+      s.moveY += deadzone(pad.axes.leftY ?? 0)
+      s.lookX += deadzone(pad.axes.rightX ?? 0)
+      s.lookY += deadzone(pad.axes.rightY ?? 0)
+    }
+    return s
+  }
+  let active = createMemo(() => {
+    let s = sticks()
+    return heldCount() > 0 || s.moveX !== 0 || s.moveY !== 0 || s.lookX !== 0 || s.lookY !== 0
+  })
+
+  // The unlocked look: a one-finger drag, arena-arbitrated. Two fingers
+  // have no first-person meaning and keep looking.
+  let transform = createTransform({
+    onTransformMove: t => {
+      let vp = options.viewport?.() ?? null
+      let rate = (vp !== null ? (DRAG_TURNS * 2 * Math.PI) / vp.height : LOOK_MOUSE) * lookSpeed()
+      look(t.dx * rate, t.dy * rate)
+      apply()
+      dirty = false
+    },
+  })
+
+  clampPitch()
+  apply()
+
+  return {
+    eye: () => [position[0], position[1], position[2]],
+    forward,
+    pose: () => ({ position: [position[0], position[1], position[2]], yaw, pitch }),
+    active,
+    set(pose) {
+      if (pose.position) position = [pose.position[0], pose.position[1], pose.position[2]]
+      if (pose.yaw !== undefined) yaw = pose.yaw
+      if (pose.pitch !== undefined) pitch = pose.pitch
+      clampPitch()
+      dirty = true
+    },
+    update(dt) {
+      let s = sticks()
+      if (s.lookX !== 0 || s.lookY !== 0) {
+        let rate = LOOK_STICK * lookSpeed() * dt
+        look(s.lookX * rate, s.lookY * rate)
+      }
+      // Key axes: -1..1 per axis, the stick added on top (stick up is -y,
+      // the web convention, so forward is -leftY), then clamped so a key
+      // and a stick together do not exceed full speed.
+      let ahead = clampNum((held.has("forward") ? 1 : 0) - (held.has("back") ? 1 : 0) - s.moveY, -1, 1)
+      let side = clampNum((held.has("right") ? 1 : 0) - (held.has("left") ? 1 : 0) + s.moveX, -1, 1)
+      // One read per update, so a mode toggle lands between steps, never
+      // between the rise and the heading of the same step.
+      let fly = options.fly ?? false
+      let rise = fly ? (held.has("up") ? 1 : 0) - (held.has("down") ? 1 : 0) : 0
+      if (ahead !== 0 || side !== 0 || rise !== 0) {
+        let step = (options.moveSpeed ?? MOVE_SPEED) * dt
+        let f = forward()
+        // Walking projects the view onto the ground plane, so looking down
+        // does not slow the walk; right is always horizontal.
+        let fx = fly ? f[0] : -Math.sin(yaw)
+        let fy = fly ? f[1] : 0
+        let fz = fly ? f[2] : -Math.cos(yaw)
+        let rx = Math.cos(yaw)
+        let rz = -Math.sin(yaw)
+        moveBy((fx * ahead + rx * side) * step, (fy * ahead + rise) * step, (fz * ahead + rz * side) * step)
+      }
+      if (!dirty) return false
+      dirty = false
+      apply()
+      return true
+    },
+    handlers: {
+      onPointerDown(e) {
+        if (!pointerLocked()) transform.handlers.onPointerDown(e)
+      },
+      onPointerMove(e) {
+        if (pointerLocked()) {
+          let rate = LOOK_MOUSE * lookSpeed()
+          look(e.movementX * rate, e.movementY * rate)
+          apply()
+          dirty = false
+        } else {
+          transform.handlers.onPointerMove(e)
+        }
+      },
+      onPointerUp(e) {
+        transform.handlers.onPointerUp(e)
+      },
+      onKeyDown(e) {
+        let move = KEY_MOVES[e.code] ?? KEY_MOVES[e.key]
+        if (!move) return
+        held.add(move)
+        setHeldCount(held.size)
+      },
+      onKeyUp(e) {
+        let move = KEY_MOVES[e.code] ?? KEY_MOVES[e.key]
+        if (!move) return
+        held.delete(move)
+        setHeldCount(held.size)
+      },
+      onBlur() {
+        held.clear()
+        setHeldCount(0)
+      },
+    },
+  }
+}

package/src/geometry.ts

@@ -28,7 +28,7 @@ import type { Quat, TransformUpdate, Vec2, Vec3 } from "./math.ts"
 /** A vertex layout: the named presets, or an explicit attribute list that
  * must begin with the standard prefix (aPos vec3, aNormal vec3, aUV vec2).
  * Absent on a Geometry means "standard". */
-export type VertexLayout = "standard" | "colored" | VertexAttribute[]
+export type VertexLayout = "standard" | "colored" | "skinned" | VertexAttribute[]
 
 const STANDARD_ATTRIBUTES: VertexAttribute[] = [
   { name: "aPos", format: "vec3" },
@@ -38,9 +38,12 @@ const STANDARD_ATTRIBUTES: VertexAttribute[] = [
 
 /** The attribute lists behind the named layouts. Every layout shares the
  * standard prefix, so one shader vocabulary serves all of them. */
-export const VERTEX_LAYOUTS: Record<"standard" | "colored", VertexAttribute[]> = {
+export const VERTEX_LAYOUTS: Record<"standard" | "colored" | "skinned", VertexAttribute[]> = {
   standard: STANDARD_ATTRIBUTES,
   colored: [...STANDARD_ATTRIBUTES, { name: "aColor", format: "vec4" }],
+  // The rigged-model layout: 4 joint indices (as floats - exact to 2^24)
+  // and their weights per vertex, what a skinned vertex stage reads.
+  skinned: [...STANDARD_ATTRIBUTES, { name: "aJoints", format: "vec4" }, { name: "aWeights", format: "vec4" }],
 }
 
 /** Floats per vertex in the "standard" layout (the generators' own write
@@ -53,6 +56,7 @@ const FORMAT_FLOATS: Record<VertexAttribute["format"], number> = { f32: 1, vec2:
 export function layoutAttributes(layout?: VertexLayout): VertexAttribute[] {
   if (layout === undefined || layout === "standard") return VERTEX_LAYOUTS.standard
   if (layout === "colored") return VERTEX_LAYOUTS.colored
+  if (layout === "skinned") return VERTEX_LAYOUTS.skinned
   return layout
 }