@solidrt/3d 0.0.54 → 0.0.56

package/README.md

@@ -15,7 +15,7 @@ function App() {
   onFrame(tick => setSpin(tick / 2000))
   return (
     <window>
-      <Scene width={720} height={720}>
+      <Scene>
         <PerspectiveCamera position={[0, 1.5, 3]} lookAt={[0, 0, 0]} />
         <Mesh geometry={box()} material={unlit({ color: [0.9, 0.3, 0.3] })} rotation={[0, spin(), 0]} />
       </Scene>
@@ -30,7 +30,9 @@ per mesh, one shared pipeline per material class, cross-mesh occlusion
 from the shared depth buffer. A static scene costs zero GPU passes - the
 runtime re-renders the target only when something changes - and a moved
 mesh costs one uniform write. By default `<Scene>` composites the target
-as a plain `<texture>` leaf; the `output` prop receives the texture id
+as a plain `<texture>` leaf that fills its parent's box, rendered at the
+leaf's on-screen device-pixel size (give `width`/`height` for a fixed
+target instead); the `output` prop receives the texture id
 and replaces that leaf - place a `<d-texture>`, add paint or pointer
 props, chain a post-effect shader target, or return null and composite
 `scene.texture` yourself.
@@ -68,10 +70,15 @@ however many meshes read it), or per mesh, declaratively via the `params`
 prop on `<Mesh>` or imperatively via `setMeshParams`. `shaderMaterialClass`
 compiles one program and hands out `instance()` materials that differ only
 in params/textures - and with `instanceAttributes` it makes an instanced
-material: `<InstancedMesh records>` (or `createInstancedMesh`) then draws
-the geometry once per interleaved record as ONE draw entry, the shape for
-forests, particles, and every fleet whose per-copy data is a few floats
-(`examples/instanced.tsx`). And
+material. Populations come in two forms: `<InstancedMesh>` with
+`<Instance>` children (or `createInstancedMesh`/`addInstance`) draws the
+geometry once per instance NODE - each a scene node the spatial core
+places, so transitions, picking and pointer events reach every copy with
+no per-frame JS, and the stock materials' `instanced`/`instanceColors`
+give it lighting, shadows and a per-instance tint without GLSL
+(`examples/fleet.tsx`); `<RecordMesh records>` (or `createRecordMesh`)
+draws once per interleaved JS-written record, the shape for particles and
+every fleet only JS can step (`examples/instanced.tsx`). And
 `@solidrt/3d/glsl` exports the lighting pieces (hemisphere, lambert,
 blinn, fresnel, a standard vertex stage) to compose your own lit looks
 from plain template literals.
@@ -89,7 +96,8 @@ one mesh per material), open vertex layouts (`withAttribute` appends any
 named channel to a geometry's interleave, `withColors` is the `aColor`
 vec4 case - tint, baked AO, any four scalars - and materials read channels
 by name), one perspective camera
-with an orbit control (`createOrbitCamera`: drag, pinch/wheel zoom, auto-orbit),
+with an orbit control (`<OrbitCamera>` as a Scene child, or
+`createOrbitCamera` imperatively: drag, pinch/wheel zoom, auto-orbit),
 mesh picking with pointer events, scene backgrounds, transparency, and
 lights (`lit` material with hemisphere ambient, up to four directional
 light nodes, Blinn-Phong highlight and triplanar mapping).

package/examples/README.md

@@ -29,15 +29,76 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   scene's own pass (`<Scene background>`): one target, no stacked
   backdrop texture, no resize plumbing; the source is shader-target
   compatible verbatim.
+- `skybox.tsx` - a cube-map skybox (`<Scene background={{ cube,
+  rotation }}>`) baked in JS at startup (horizon gradient, sun disc and
+  glow, no image assets), and the same cube as the environment
+  (`environment={{ cube, rotation }}`) mirrored by a chrome sphere
+  (`lit({ reflectivity: 1 })`) and, blurred by shininess, a glossy knot.
+  The sky turns and the sun light turns with it, the `rotation` knobs
+  updating in place; drag to look around.
+- `standard.tsx` - the `standard` material, the sphere grid every PBR
+  engine opens with: metalness down the rows, roughness across the
+  columns, under the skybox example's baked sky as background and
+  environment and a warm sun casting shadows; a bare-metal row shows
+  the environment as tinted reflections, the dielectric row the same
+  sky as a faint face-on gloss. Drag to look around.
+- `environment.tsx` - a baked HDR environment lighting the scene ALONE
+  (no lights, no hemisphere): `loadEnvironment` reads the .srte that
+  `bunx srt tool 3d/environment <panorama>.hdr -o assets/environment.srte`
+  bakes from any equirectangular .hdr (Poly Haven's are CC0; the asset
+  is not committed, bake one first), used as background and environment
+  with ACES tone mapping. A metal row and a red dielectric row, roughness
+  0 to 1 across: the metals are the room, sharp to blurred. Drag to
+  look around.
+- `probe.tsx` - a reflection probe (`scene.createReflectionProbe`): the
+  scene rendered into a cube map from the center of a satin chrome ball,
+  every frame, prefiltered into the roughness chain and set as the
+  environment the ball reflects - six colored walls and four orbiting
+  spheres show in it, blurred by the ball's roughness. Layers keep the
+  ball out of its own probe. Drag to look around.
+- `sky-lit.tsx` - a sky-lit scene (`scene.bakeBackground`): a procedural
+  GLSL sky is the background AND, baked into a prefiltered cube, the
+  environment - no light nodes. Two rows of `standard` spheres, metal and
+  dielectric, roughness 0 to 1 across; the sun disc bakes at 40x (the
+  probe format is half float where the device renders it), so the rough
+  metals carry its energy as a broad highlight. Drag to look around.
 - `sprites.tsx` - sprites: a ring of `"full"` billboard glows that stay
   flat to the screen and `"fixed-y"` cutout trees that only yaw toward
   the camera and stay upright as it climbs, both turned in the vertex
   stage while the camera circles - no per-sprite JS per frame.
-- `instanced.tsx` - instanced meshes: one material class declaring
-  `instanceAttributes`, two `<InstancedMesh>` fleets (400 scattered
-  rocks, a ring of pines) each ONE draw entry and ONE uModel, a spinning
-  group moving both with two matrix writes, and `setInstanceCount` from
-  onFrame breathing the pine population.
+- `instanced.tsx` - record meshes, the JS-written population: one
+  material class declaring `instanceAttributes`, two `<RecordMesh>`
+  fleets (400 scattered rocks, a ring of pines) each ONE draw entry and
+  ONE uModel, a spinning group moving both with two matrix writes, and
+  `setRecordCount` from onFrame breathing the pine population. The class
+  also declares `shadowVertex` (the placement math alone), so both
+  fleets `castShadow` onto the lit ground - the pines' shadows breathe
+  with them.
+- `fleet.tsx` - instanced meshes, the node-backed population: one
+  `<InstancedMesh>` of a thousand `<Instance>` nodes under the stock
+  `lit` material with `instanceColors` (lighting, shadows, fog and a
+  per-instance tint with no GLSL). Every few seconds a signal picks the
+  next formation and the core springs every instance to its place
+  through its `transition` - one signal write, zero JS per frame after
+  it; a tap flips the struck instance's tint (pointer events name the
+  instance; every style write between two frames is one buffer write).
+  Drag to orbit; the `formation` and `state` debug commands drive it
+  headlessly.
+- `first-person.tsx` - a first-person walk: `<FirstPersonCamera>` over
+  a walled courtyard of shadow-casting pillars, WASD/arrows and the pad
+  sticks to walk, mouse look under pointer lock (click locks, Escape
+  releases - the app's calls, not the control's), a drag to look on
+  touch; `clampPosition` keeps the walker inside the walls, the whole of
+  the collision a camera control offers; the `pose` debug command reads
+  and sets the pose headlessly.
+- `collision.tsx` - collision without a physics engine: the same walker
+  as a capsule through `moveAndSlide` over the scene's sweep queries,
+  in a level of walls, a ramp, a platform with a ledge and pillars whose
+  drawn meshes carry the collider layer bit too; gravity as a frame loop
+  that runs only while airborne (Space jumps), pickups lit by one
+  `overlap` per move. Debug commands `walk` (frame-sized steps through
+  the collision), `jump`, `fall` (one airborne step by hand) and `state`
+  drive it headlessly.
 - `scene-views.tsx` - scene views: one scene rendered three times, the
   built-in perspective leaf plus two `scene.createView` targets - a
   top-down ORTHOGRAPHIC map (`ortho` on setCamera) and a side silhouette
@@ -58,8 +119,28 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   the plain box widened to cover the field: one map's texels spread over
   it, blocky everywhere) and the `cascades`/`fly` debug commands set the
   count and the shadow distance and park the flight.
+- `lamps.tsx` - spot and point lights in a dark courtyard: a warm SOFT
+  spot (penumbra 0.4) swinging from a parent group, a fixed HARD spot
+  (penumbra 0.05) aimed by `direction` at a knot on a pedestal, and a
+  blue point bulb orbiting the crates; both spots `castShadow` (a
+  perspective map each), and the header notes the decay-2 intensity
+  scale (candela-like: a lamp 5 units up wants ~40, not ~2).
+- `fog.tsx` - scene fog over a valley of pines between two ridges: a
+  click cycles LINEAR (`{ near, far }`, a clear band then a fade to the
+  far plane), EXP2 (`{ density }`, thickening from the first metre) and
+  HEIGHT (`heightFalloff`: the valley floor fills, the hilltops and sky
+  stay clear), then off; two suns show the material opt-out (`unlit({
+  fog: false })` stays bright, its twin fogs). The `fog` debug command
+  sets the mode and its knobs and `pan` parks the camera.
 - `model.tsx` - a model from a file: `model.glb` (a small rover with
   nested node transforms, a mirrored node, a textured material, a
   transparent dome and a mesh without normals) parsed with `parseGltf`
   from a binary import and built by `createModel` into a Group of named
   parts; clicking a part hides it, clicking the body restores all.
+- `model-load.tsx` - the same rover loaded ASYNC with `loadModel` from
+  `assets/` under a `<Loading>` boundary: the async read lives in a memo,
+  a second memo derives the scene JSX after that read, and the shell
+  stays above the boundary - the two rules that avoid
+  PENDING_ASYNC_UNTRACKED_READ and the suspend-retry element leak. Needs
+  the asset baked into the running app:
+  `bunx srt tool 3d/model examples/model.glb -o assets/model.srtm`.

package/examples/aim.tsx

@@ -25,7 +25,6 @@ import {
 } from "@solidrt/3d"
 import type { MeshNode, Vec3 } from "@solidrt/3d"
 
-const SIZE = 720
 const Y_AXIS: Vec3 = [0, 1, 0]
 
 function App() {
@@ -79,8 +78,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="aim">
+      <view width={pct(100)} height={pct(100)}>
+        <Scene clearColor={[0.07, 0.07, 0.1, 1]} label="aim">
           <PerspectiveCamera fov={55} position={[0, 2.6, 4.6]} lookAt={[0, 0.7, 0]} />
           <Mesh
             geometry={plane({ width: 7, height: 7, label: "floor" })}

package/examples/cascades.tsx

@@ -14,19 +14,27 @@
 // The `cascades` debug command sets the count and the shadow distance
 // (`{ count, distance }`; the range the cascades split, the camera's far
 // by default - pulling it in sharpens every cascade) and `fly` parks the
-// flight (`{ t: seconds }`), so a capture repeats.
-import { createSignal, onFrame, pct, render } from "@solidrt/core"
+// flight (`{ t: seconds }`), so a capture repeats. The field is fogged
+// toward the sky color from FOG_NEAR to FOG_FAR, inside the camera's far
+// plane, so the far pillars sink into the horizon instead of clipping
+// (`examples/fog.tsx` is the fog tour).
+import { createSignal, flush, onFrame, pct, render } from "@solidrt/core"
 import { registerDebug } from "srt:dev"
 import { box, DirectionalLight, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, sphere } from "@solidrt/3d"
 import type { Geometry, Vec3 } from "@solidrt/3d"
 
-const SIZE = 720
 const FIELD = 260
 const FAR = 200
 // The flight: a circle over the field, looking ahead along it.
 const RADIUS = 50
 const HEIGHT = 5
 const PERIOD = 90
+// The sky, shared by the clear and the fog so the horizon has no band.
+const SKY: [number, number, number] = [0.6, 0.72, 0.88]
+// The fog band: clear up to FOG_NEAR, fully sky at FOG_FAR (the far edge
+// of the field is about 150 units out at the flight's radius).
+const FOG_NEAR = 30
+const FOG_FAR = 150
 
 let [cascades, setCascades] = createSignal(3)
 let [distance, setDistance] = createSignal<number | null>(null)
@@ -37,6 +45,7 @@ let parked: number | null = null
 registerDebug("cascades", (args?: Record<string, unknown>) => {
   if (typeof args?.count === "number") setCascades(args.count)
   if (typeof args?.distance === "number" || args?.distance === null) setDistance(args.distance)
+  flush()
   return { cascades: cascades(), distance: distance() }
 })
 registerDebug("fly", (args?: Record<string, unknown>) => {
@@ -46,6 +55,7 @@ registerDebug("fly", (args?: Record<string, unknown>) => {
   } else if (args?.t === null) {
     parked = null
   }
+  flush()
   return { t: time(), parked: parked !== null }
 })
 
@@ -86,8 +96,13 @@ function App() {
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]} onPointerDown={() => setCascades(c => (c % 4) + 1)}>
-        <Scene width={SIZE} height={SIZE} clearColor={[0.6, 0.72, 0.88, 1]} samples={4} label="cascades">
+      <view width={pct(100)} height={pct(100)} onPointerDown={() => setCascades(c => (c % 4) + 1)}>
+        <Scene
+          clearColor={[SKY[0], SKY[1], SKY[2], 1]}
+          fog={{ color: SKY, near: FOG_NEAR, far: FOG_FAR }}
+          samples={4}
+          label="cascades"
+        >
           <PerspectiveCamera fov={50} near={0.5} far={FAR} position={eye()} lookAt={ahead()} />
           <HemisphereLight sky={[0.5, 0.58, 0.7]} ground={[0.25, 0.22, 0.18]} />
           <DirectionalLight

package/examples/collision.tsx

@@ -0,0 +1,250 @@
+// Collision without a physics engine: a capsule-controlled first-person
+// walker in a level of walls, a ramp, a platform with a ledge and a few
+// pillars, all colliding through `moveAndSlide` over the scene's sweep
+// queries. The level meshes carry the COLLIDER layer bit beside the drawn
+// one, so the same geometry draws and collides (a low-poly stand-in would
+// carry COLLIDER alone and stay undrawn); the pickups do not, so the
+// walker passes through them, and one `overlap` per move lights the ones
+// within reach. Walking goes through the camera's `clampPosition` hook;
+// gravity runs a frame loop only while airborne (a jump, a ledge), so a
+// standing scene renders nothing new. WASD/arrows walk, Space jumps,
+// click locks the pointer, Escape releases it. Debug commands: `pose`
+// (read/set), `walk` ({ dx, dz } through the collision), `jump`, `fall`
+// ({ dt }: one airborne step by hand, for headless checks), `state`.
+import { createSignal, lockPointer, onFrame, pct, pointerLocked, render } from "@solidrt/core"
+import type { PointerEvent } from "@solidrt/core"
+import {
+  box,
+  cylinder,
+  DirectionalLight,
+  FirstPersonCamera,
+  HemisphereLight,
+  lit,
+  Mesh,
+  moveAndSlide,
+  PerspectiveCamera,
+  plane,
+  Scene,
+  sphere,
+} from "@solidrt/3d"
+import type { FirstPersonCameraHandle, MeshNode, MoveResult, SceneHandle, Vec3, Volume } from "@solidrt/3d"
+import { registerDebug } from "srt:dev"
+
+// Layer bit the level geometry adds to its drawn layer: what every
+// collision query selects, so pickups (drawn only) never block the walker.
+const COLLIDER = 2
+// The walker: eye height over the feet, the capsule's radius, and where
+// its segment sits relative to the eye (feet + radius up to a hand under
+// the eye).
+const EYE = 1.6
+const RADIUS = 0.3
+const BODY_LOW = -EYE + RADIUS
+const BODY_HIGH = -0.2
+// Vertical dynamics, world units per second (squared for gravity).
+const GRAVITY = 12
+const JUMP_SPEED = 5
+// Largest frame step the fall integrates: a stall must not tunnel the
+// walker through a floor.
+const MAX_FALL_DT = 0.05
+// A pickup lights up within this distance of the feet.
+const REACH = 1.5
+// Level dimensions: floor half extent, wall height, the platform's top
+// and footprint, the ramp's run.
+const FLOOR = 15
+const WALL_HEIGHT = 3
+const PLATFORM_TOP = 1.5
+const PLATFORM_HALF = 3
+const RAMP_RUN = 6
+const RAMP_THICKNESS = 0.3
+// HUD refresh interval in ms.
+const HUD_MS = 100
+// One frame of walking at the default speed, the stride the `walk` debug
+// command takes so its checks match live play.
+const WALK_STEP = 0.05
+
+let bodyAt = (eye: Vec3): Volume => ({ a: [eye[0], eye[1] + BODY_LOW, eye[2]], b: [eye[0], eye[1] + BODY_HIGH, eye[2]], radius: RADIUS })
+let feetOf = (eye: Vec3): Vec3 => [eye[0], eye[1] - EYE, eye[2]]
+
+function App() {
+  let scene!: SceneHandle
+  let camera!: FirstPersonCameraHandle
+  let [hud, setHud] = createSignal("")
+  let [near, setNear] = createSignal<Set<number>>(new Set())
+  // The same set, readable synchronously (a signal read right after its
+  // write still returns the old value): what the debug commands report.
+  let nearNow = new Set<number>()
+  let grounded = true
+  let fallSpeed = 0
+  let stopFall: (() => void) | null = null
+  let pickups: MeshNode[] = []
+
+  let dim = lit({ color: [0.55, 0.45, 0.2] })
+  let bright = lit({ color: [1, 0.85, 0.3], specular: 0.8, shininess: 60 })
+  let ground = lit({ color: [0.48, 0.52, 0.46] })
+  let stone = lit({ color: [0.72, 0.7, 0.66] })
+  let brick = lit({ color: [0.6, 0.34, 0.28] })
+
+  // Every move ends here: the walker's new eye, the ground state, and the
+  // pickups in reach of its feet (an include-list query, so the level
+  // itself never reports).
+  let settle = (eye: Vec3, floor: Vec3 | null) => {
+    grounded = floor !== null
+    let hit = new Set<number>()
+    for (let o of scene.overlap({ center: feetOf(eye), radius: REACH }, { meshes: pickups })) hit.add(pickups.indexOf(o.mesh))
+    nearNow = hit
+    setNear(hit)
+  }
+  // Walking: the camera asks for `next` from `eye`, the collision answers.
+  let clamp = (next: Vec3, eye: Vec3): Vec3 => {
+    let r = moveAndSlide(scene, bodyAt(eye), [next[0] - eye[0], next[1] - eye[1], next[2] - eye[2]], { layers: COLLIDER })
+    let moved: Vec3 = [eye[0] + r.motion[0], eye[1] + r.motion[1], eye[2] + r.motion[2]]
+    settle(moved, r.floor)
+    if (!grounded) fall()
+    return moved
+  }
+  // One airborne step: gravity into the vertical speed, the drop through
+  // the collision, a ceiling bonk kills the rise, a floor ends the fall.
+  let fallStep = (dt: number) => {
+    fallSpeed -= GRAVITY * dt
+    let eye = camera.pose().position
+    let r = moveAndSlide(scene, bodyAt(eye), [0, fallSpeed * dt, 0], { layers: COLLIDER })
+    let moved: Vec3 = [eye[0] + r.motion[0], eye[1] + r.motion[1], eye[2] + r.motion[2]]
+    camera.set({ position: moved })
+    if (r.ceiling && fallSpeed > 0) fallSpeed = 0
+    settle(moved, r.floor)
+    if (grounded) {
+      fallSpeed = 0
+      stopFall?.()
+      stopFall = null
+    }
+  }
+  // Airborne: step the fall frame by frame until a floor takes it.
+  let fall = () => {
+    if (stopFall !== null) return
+    let last: number | null = null
+    stopFall = onFrame(tick => {
+      let now = tick / 1000
+      let dt = last === null ? 0 : Math.max(0, Math.min(now - last, MAX_FALL_DT))
+      last = now
+      fallStep(dt)
+    })
+  }
+  let jump = () => {
+    if (!grounded) return
+    fallSpeed = JUMP_SPEED
+    grounded = false
+    fall()
+  }
+
+  let lastHud = 0
+  onFrame(tick => {
+    if (tick - lastHud < HUD_MS) return
+    lastHud = tick
+    let p = camera.pose().position
+    setHud(
+      `${pointerLocked() ? "locked - Escape releases" : "click to lock"}  WASD walk, Space jump  x ${p[0].toFixed(1)} y ${(p[1] - EYE).toFixed(2)} z ${p[2].toFixed(1)}  ${grounded ? "grounded" : "airborne"}  pickups ${near().size}`,
+    )
+  })
+  registerDebug("pose", (args?: Record<string, unknown>) => {
+    if (args) camera.set(args as Parameters<typeof camera.set>[0])
+    return camera.pose()
+  })
+  registerDebug("walk", (args?: { dx?: number; dz?: number; steps?: number }) => {
+    // Frame-sized steps by default: a level's ramps and snap distances
+    // are tuned for them, not for one long stride.
+    let steps = args?.steps ?? Math.max(1, Math.ceil(Math.hypot(args?.dx ?? 0, args?.dz ?? 0) / WALK_STEP))
+    let last: MoveResult | null = null
+    for (let i = 0; i < steps; i++) {
+      let eye = camera.pose().position
+      let r = moveAndSlide(scene, bodyAt(eye), [(args?.dx ?? 0) / steps, 0, (args?.dz ?? 0) / steps], { layers: COLLIDER })
+      let moved: Vec3 = [eye[0] + r.motion[0], eye[1] + r.motion[1], eye[2] + r.motion[2]]
+      settle(moved, r.floor)
+      camera.set({ position: moved })
+      last = r
+    }
+    if (!grounded) fall()
+    let p = camera.pose().position
+    return { position: p, feet: p[1] - EYE, grounded, wall: last?.wall, ceiling: last?.ceiling, hits: last?.hits.length, pickups: [...nearNow].sort() }
+  })
+  registerDebug("jump", () => {
+    jump()
+    return { grounded, fallSpeed }
+  })
+  registerDebug("fall", (args?: { dt?: number }) => {
+    if (!grounded) fallStep(args?.dt ?? 1 / 60)
+    return { grounded, fallSpeed, position: camera.pose().position }
+  })
+  registerDebug("state", () => ({ grounded, fallSpeed, pickups: [...nearNow].sort() }))
+
+  // The ramp: a thin box whose top face runs from the floor at z = +run/2
+  // up to the platform's top at z = -run/2, so its rotation about x is the
+  // slope and its center sits half a thickness under the top face.
+  let slope = Math.atan2(PLATFORM_TOP, RAMP_RUN)
+  let rampLength = Math.hypot(RAMP_RUN, PLATFORM_TOP)
+  let rampCenter: Vec3 = [0, PLATFORM_TOP / 2 - Math.cos(slope) * (RAMP_THICKNESS / 2), -PLATFORM_HALF - RAMP_RUN / 2 - Math.sin(slope) * (RAMP_THICKNESS / 2)]
+  let walls = [
+    { position: [0, WALL_HEIGHT / 2, -FLOOR - 0.5] as Vec3, size: [FLOOR * 2 + 2, WALL_HEIGHT, 1] as Vec3 },
+    { position: [0, WALL_HEIGHT / 2, FLOOR + 0.5] as Vec3, size: [FLOOR * 2 + 2, WALL_HEIGHT, 1] as Vec3 },
+    { position: [-FLOOR - 0.5, WALL_HEIGHT / 2, 0] as Vec3, size: [1, WALL_HEIGHT, FLOOR * 2] as Vec3 },
+    { position: [FLOOR + 0.5, WALL_HEIGHT / 2, 0] as Vec3, size: [1, WALL_HEIGHT, FLOOR * 2] as Vec3 },
+  ]
+  let pillars: Vec3[] = [
+    [6, WALL_HEIGHT / 2, 4],
+    [-6, WALL_HEIGHT / 2, 4],
+    [8, WALL_HEIGHT / 2, -8],
+  ]
+  let gems: Vec3[] = [
+    [3, 0.4, 6],
+    [-3, 0.4, 2],
+    [7, 0.4, -2],
+    [-8, 0.4, -6],
+    [0, PLATFORM_TOP + 0.4, -PLATFORM_HALF - RAMP_RUN - PLATFORM_HALF],
+  ]
+
+  return (
+    <window
+      onKeyDown={e => {
+        if (e.key === "Escape") lockPointer(false)
+        if (e.key === " " || e.code === "Space") jump()
+      }}
+    >
+      <view
+        width={pct(100)}
+        height={pct(100)}
+        onPointerDown={(e: PointerEvent) => {
+          if (e.pointerType === "mouse") lockPointer(true)
+        }}
+      >
+        <Scene ref={s => (scene = s)} clearColor={[0.6, 0.72, 0.88, 1]} samples={4} label="collision">
+          <PerspectiveCamera fov={70} near={0.1} far={80} />
+          <FirstPersonCamera ref={c => (camera = c)} position={[0, EYE, 10]} clampPosition={clamp} />
+          <HemisphereLight sky={[0.5, 0.56, 0.68]} ground={[0.25, 0.22, 0.18]} />
+          <DirectionalLight color={[1, 0.95, 0.85]} intensity={0.9} position={[8, 14, 6]} direction={[-8, -14, -6]} castShadow shadow={{ mapSize: 2048, normalBias: 0.02, cascades: 3, distance: 40 }} />
+          <Mesh geometry={plane({ width: FLOOR * 2 + 2, height: FLOOR * 2 + 2 })} material={ground} rotation={[-Math.PI / 2, 0, 0]} layers={1 | COLLIDER} />
+          {walls.map(w => (
+            <Mesh geometry={box({ width: w.size[0], height: w.size[1], depth: w.size[2] })} material={brick} position={w.position} layers={1 | COLLIDER} castShadow />
+          ))}
+          <Mesh
+            geometry={box({ width: PLATFORM_HALF * 2, height: PLATFORM_TOP, depth: PLATFORM_HALF * 2 })}
+            material={stone}
+            position={[0, PLATFORM_TOP / 2, -PLATFORM_HALF - RAMP_RUN - PLATFORM_HALF]}
+            layers={1 | COLLIDER}
+            castShadow
+          />
+          <Mesh geometry={box({ width: 2.5, height: RAMP_THICKNESS, depth: rampLength })} material={stone} position={rampCenter} rotation={[slope, 0, 0]} layers={1 | COLLIDER} castShadow />
+          {pillars.map(p => (
+            <Mesh geometry={cylinder({ radiusTop: 0.35, radiusBottom: 0.4, height: WALL_HEIGHT })} material={stone} position={p} layers={1 | COLLIDER} castShadow />
+          ))}
+          {gems.map((g, i) => (
+            <Mesh ref={m => (pickups[i] = m)} geometry={sphere({ radius: 0.25 })} material={near().has(i) ? bright : dim} position={g} castShadow />
+          ))}
+        </Scene>
+        <text position="absolute" left={12} top={12} color="#ffffff" fontSize={14}>
+          {hud()}
+        </text>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/first-person.tsx

@@ -0,0 +1,119 @@
+// A first-person walk: `<FirstPersonCamera>` driving the scene camera from
+// WASD/arrows and the gamepad sticks, mouse look under pointer lock and
+// drag-to-look without it. Click the scene to lock the pointer (the scene
+// leaf takes focus on the same click, which routes the keys to the
+// control), Escape releases it; on a touch screen a drag looks around and
+// the left stick of a pad walks. Movement runs a frame loop only while a
+// key is held or a stick deflected - a still scene renders nothing new.
+// `clampPosition` keeps the walker inside the courtyard walls, the whole
+// of the collision an app gets from a camera control. The `pose` debug
+// command reads and sets the pose for headless checks.
+import { createSignal, lockPointer, onFrame, pct, pointerLocked, render } from "@solidrt/core"
+import type { PointerEvent } from "@solidrt/core"
+import { box, cylinder, DirectionalLight, FirstPersonCamera, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene } from "@solidrt/3d"
+import type { FirstPersonCameraHandle, Vec3 } from "@solidrt/3d"
+import { registerDebug } from "srt:dev"
+
+// Half extent of the walkable courtyard in world units; the walls stand
+// just outside it.
+const COURT = 9
+// How far inside the walls the eye may go.
+const WALL_GAP = 0.6
+// Standing eye height.
+const EYE = 1.6
+// Pillar ring radius and count.
+const RING = 5
+const PILLARS = 8
+// The sun's shadow is cascaded: a first-person eye sits 1.6 units over
+// the floor, where one box map over the whole courtyard (32 units / 2048
+// texels = 1.6 cm) shows every texel as a 10-pixel stair. Three cascades
+// fitted to slices of the view give the near slice millimetre texels;
+// the distance caps the far one at the courtyard's diagonal.
+const SHADOW_CASCADES = 3
+const SHADOW_DISTANCE = 30
+// PCF radius in map texels: the 3x3 hardware-tap kernel that hides the
+// remaining stair of the near cascade's texels.
+const SHADOW_RADIUS = 2
+// HUD refresh interval in ms: the pose readout is slow UI state, not a
+// per-frame binding.
+const HUD_MS = 100
+
+let clampNum = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v))
+let inside = (p: Vec3): Vec3 => [clampNum(p[0], -COURT + WALL_GAP, COURT - WALL_GAP), EYE, clampNum(p[2], -COURT + WALL_GAP, COURT - WALL_GAP)]
+
+function App() {
+  let camera!: FirstPersonCameraHandle
+  let [hud, setHud] = createSignal("")
+  let lastHud = 0
+  onFrame(tick => {
+    if (tick - lastHud < HUD_MS) return
+    lastHud = tick
+    let p = camera.pose()
+    setHud(
+      `${pointerLocked() ? "locked - Escape releases" : "click to lock"}  x ${p.position[0].toFixed(1)} z ${p.position[2].toFixed(1)}  yaw ${p.yaw.toFixed(2)} pitch ${p.pitch.toFixed(2)}`,
+    )
+  })
+  registerDebug("pose", (args?: Record<string, unknown>) => {
+    if (args) camera.set(args as Parameters<typeof camera.set>[0])
+    return camera.pose()
+  })
+
+  let ground = lit({ color: [0.5, 0.52, 0.48] })
+  let stone = lit({ color: [0.75, 0.72, 0.66] })
+  let brick = lit({ color: [0.6, 0.32, 0.26] })
+  let gold = lit({ color: [0.9, 0.75, 0.3], specular: 0.5, shininess: 40 })
+
+  let pillars = Array.from({ length: PILLARS }, (_, i) => {
+    let a = (i / PILLARS) * Math.PI * 2
+    return [Math.sin(a) * RING, Math.cos(a) * RING] as const
+  })
+  let walls = [
+    { position: [0, 1.5, -COURT - 0.5] as Vec3, size: [COURT * 2 + 2, 3, 1] as Vec3 },
+    { position: [0, 1.5, COURT + 0.5] as Vec3, size: [COURT * 2 + 2, 3, 1] as Vec3 },
+    { position: [-COURT - 0.5, 1.5, 0] as Vec3, size: [1, 3, COURT * 2] as Vec3 },
+    { position: [COURT + 0.5, 1.5, 0] as Vec3, size: [1, 3, COURT * 2] as Vec3 },
+  ]
+
+  return (
+    <window
+      onKeyDown={e => {
+        if (e.key === "Escape") lockPointer(false)
+      }}
+    >
+      <view
+        width={pct(100)}
+        height={pct(100)}
+        onPointerDown={(e: PointerEvent) => {
+          if (e.pointerType === "mouse") lockPointer(true)
+        }}
+      >
+        <Scene clearColor={[0.6, 0.72, 0.88, 1]} samples={4} label="first-person">
+          <PerspectiveCamera fov={70} near={0.1} far={60} />
+          <FirstPersonCamera ref={c => (camera = c)} position={[0, EYE, 7]} clampPosition={inside} />
+          <HemisphereLight sky={[0.5, 0.56, 0.68]} ground={[0.25, 0.22, 0.18]} />
+          <DirectionalLight
+            color={[1, 0.95, 0.85]}
+            intensity={0.9}
+            position={[6, 10, 4]}
+            direction={[-6, -10, -4]}
+            castShadow
+            shadow={{ mapSize: 2048, normalBias: 0.02, radius: SHADOW_RADIUS, cascades: SHADOW_CASCADES, distance: SHADOW_DISTANCE }}
+          />
+          <Mesh geometry={plane({ width: COURT * 2 + 2, height: COURT * 2 + 2 })} material={ground} rotation={[-Math.PI / 2, 0, 0]} />
+          {walls.map(w => (
+            <Mesh geometry={box({ width: w.size[0], height: w.size[1], depth: w.size[2] })} material={brick} position={w.position} castShadow />
+          ))}
+          {pillars.map(([x, z]) => (
+            <Mesh geometry={cylinder({ radiusTop: 0.3, radiusBottom: 0.35, height: 3 })} material={stone} position={[x, 1.5, z]} castShadow />
+          ))}
+          <Mesh geometry={box({ width: 1.2, height: 1.2, depth: 1.2 })} material={gold} position={[0, 0.6, 0]} castShadow />
+        </Scene>
+        <text position="absolute" left={12} top={12} color="#ffffff" fontSize={14}>
+          {hud()}
+        </text>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)