@solidrt/3d 0.0.50 → 0.0.52

package/demos/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "jsx": "preserve",
+    "jsxImportSource": "@solidrt/core",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["@solidrt/flux-types"]
+  },
+  "include": ["src"]
+}

package/examples/README.md

@@ -9,8 +9,14 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   and pipeline sharing, and the one-signal onFrame drive.
 - `sweep-paths.tsx` - swept solids along polylines: a flat strap folding
   over a crate (bare path points crease on the mitred bends) and a coiled
-  tube (smooth-tagged helix, one continuous mesh), lit via the exported
-  GLSL so the creased-vs-smooth normals actually show.
+  tube (smooth-tagged helix, one continuous mesh), lit so the
+  creased-vs-smooth normals actually show.
+- `lit.tsx` - the lit material and light nodes: `<HemisphereLight>` plus
+  a warm key `<DirectionalLight>` turning inside a spinning `<Group>` and
+  a fixed cool fill,
+  a glossy sphere (specular/shininess), a transparent glass sphere, and
+  one checker map shared by a UV-mapped cube (stretched per face) and
+  two triplanar meshes tiling it at one world density.
 - `aim.tsx` - the rotation verbs, one pointer each tracking an orbiting
   target: `lookAt` for a +z solid, `quatFromTo` for aiming a y-axis cone,
   and a `quatSlerp` damped follow that visibly lags; all driven from
@@ -23,3 +29,29 @@ 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.
+- `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.
+- `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
+  drawn with an `overrideMaterial`; one spinning group, one signal, every
+  target fed by the core's one flush.
+- `shadows.tsx` - directional shadow maps from three casting lights: a
+  `castShadow` sun swinging through its arc (one setTransform per frame
+  on the light node), a fixed cool fill and a low rim light, `castShadow`
+  meshes turning in a group throwing three crossing shadows each, the
+  ground and the casters receiving through plain `lit` (the default);
+  each shadow camera follows its light's world matrix, each map is
+  rendered by an internal view.
+- `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.

package/examples/aim.tsx

@@ -74,16 +74,16 @@ function App() {
     setTransform(lazy, { quaternion: aimQ })
   })
 
-  let ball = sphere(0.22)
-  let pointer = cone(0.3, 0.9)
+  let ball = sphere({ radius: 0.22 })
+  let pointer = cone({ radius: 0.3, height: 0.9 })
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <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">
           <PerspectiveCamera fov={55} position={[0, 2.6, 4.6]} lookAt={[0, 0.7, 0]} />
           <Mesh
-            geometry={plane(7, 7, "floor")}
+            geometry={plane({ width: 7, height: 7, label: "floor" })}
             material={unlit({ color: [0.16, 0.17, 0.22] })}
             rotation={[-Math.PI / 2, 0, 0]}
           />
@@ -93,7 +93,7 @@ function App() {
             ref={n => (target = n)}
           />
           <Mesh
-            geometry={tube([[0, 0, 0], [0, 0, 1.1]], 0.09, 10, "rod")}
+            geometry={tube([[0, 0, 0], [0, 0, 1.1]], { radius: 0.09, radialSegments: 10, label: "rod" })}
             material={unlit({ color: [0.85, 0.3, 0.3] })}
             position={[-1.4, 0.5, 0]}
             ref={n => (rod = n)}

package/examples/instanced.tsx

@@ -0,0 +1,158 @@
+// Instanced meshes: one draw entry covering a whole population. A material
+// class declares `instanceAttributes`, createInstancedMesh (here via the
+// <InstancedMesh> component) supplies one interleaved record per instance,
+// and the vertex stage reads each record through the matching `in`
+// variables. Two meshes share the one class: 400 scattered "rocks" and a
+// breathing ring of "pines" - each is ONE entry and ONE uModel however
+// many instances it draws, so the spinning group below moves both fleets
+// with two matrix writes per frame.
+//
+// setInstanceCount is the population dial (the pines breathe); records are
+// data, not matrices - position/scale/tint here, whatever your shader
+// wants in general. The explicit `bounds` cover the scatter so picking
+// still works (one conservative box around the population; omit bounds and
+// the mesh simply never picks).
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { glsl } from "@solidrt/core/gpu"
+import {
+  box,
+  cone,
+  Group,
+  InstancedMesh,
+  Mesh,
+  PerspectiveCamera,
+  plane,
+  Scene,
+  setInstanceCount,
+  shaderMaterialClass,
+  unlit,
+} from "@solidrt/3d"
+import type { InstancedMeshNode } from "@solidrt/3d"
+import { HEMISPHERE } from "@solidrt/3d/glsl"
+
+const SIZE = 720
+
+const INSTANCE_VERTEX = glsl`
+  in vec3 aPos;
+  in vec3 aNormal;
+  in vec3 iPos;
+  in float iScale;
+  in vec3 iTint;
+  out vec3 vNormal;
+  out vec3 vTint;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+
+  void main() {
+    vec3 p = aPos * iScale + iPos;
+    gl_Position = uViewProj * uModel * vec4(p, 1.0);
+    vNormal = mat3(uModel) * aNormal;
+    vTint = iTint;
+  }
+`
+
+const INSTANCE_FRAGMENT = glsl`
+  in vec3 vNormal;
+  in vec3 vTint;
+  ${HEMISPHERE}
+
+  void main() {
+    vec3 c = vTint * hemisphere(normalize(vNormal), vec3(1.05, 1.0, 0.95), vec3(0.35, 0.32, 0.3));
+    fragColor = vec4(c, 1.0);
+  }
+`
+
+// One record per instance, interleaved in attribute order: 7 floats.
+const STRIDE = 7
+
+// A deterministic scatter (no per-run surprises when eyeballing).
+function rocks(count: number): Float32Array {
+  let records = new Float32Array(count * STRIDE)
+  let a = 0
+  for (let i = 0; i < count; i++) {
+    a += 2.399963 // golden angle: an even spiral scatter
+    let r = 0.35 + 3.4 * Math.sqrt((i + 0.5) / count)
+    let s = 0.05 + 0.11 * ((i * 7) % 10) / 10
+    let o = i * STRIDE
+    records[o] = Math.cos(a) * r
+    records[o + 1] = s / 2
+    records[o + 2] = Math.sin(a) * r
+    records[o + 3] = s
+    records[o + 4] = 0.55 + 0.3 * ((i * 3) % 5) / 5
+    records[o + 5] = 0.5 + 0.2 * ((i * 11) % 7) / 7
+    records[o + 6] = 0.45
+  }
+  return records
+}
+
+function pines(count: number): Float32Array {
+  let records = new Float32Array(count * STRIDE)
+  for (let i = 0; i < count; i++) {
+    let a = (i / count) * Math.PI * 2
+    let s = 0.5 + 0.25 * ((i * 5) % 8) / 8
+    let o = i * STRIDE
+    records[o] = Math.cos(a) * 2.4
+    records[o + 1] = s / 2
+    records[o + 2] = Math.sin(a) * 2.4
+    records[o + 3] = s
+    records[o + 4] = 0.15
+    records[o + 5] = 0.4 + 0.25 * ((i * 3) % 6) / 6
+    records[o + 6] = 0.2
+  }
+  return records
+}
+
+const PINE_COUNT = 48
+
+function App() {
+  let [spin, setSpin] = createSignal(0)
+  let pinesMesh!: InstancedMeshNode
+  onFrame(tick => {
+    setSpin(tick / 6000)
+    // The population dial: draw the first N records. The buffer holds the
+    // full ring; only the draw range moves, one setDrawRange per change.
+    let n = Math.round(PINE_COUNT * (0.5 + 0.5 * Math.sin(tick / 900)))
+    if (pinesMesh) setInstanceCount(pinesMesh, n)
+  })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.08, 0.1, 1]} label="instanced">
+          <PerspectiveCamera fov={55} position={[0, 3.2, 5.4]} lookAt={[0, 0.2, 0]} />
+          <Mesh geometry={plane({ width: 9, height: 9, label: "meadow" })} material={unlit({ color: [0.16, 0.18, 0.16] })} rotation={[-Math.PI / 2, 0, 0]} />
+          <Group rotation={[0, spin(), 0]}>
+            <InstancedMesh
+              geometry={box({ label: "rock" })}
+              material={instancedLook.instance()}
+              records={rocks(400)}
+              bounds={[-3.9, 0, -3.9, 3.9, 0.2, 3.9]}
+            />
+            <InstancedMesh
+              geometry={cone({ radius: 0.3, height: 1, radialSegments: 10, label: "pine" })}
+              material={instancedLook.instance()}
+              records={pines(PINE_COUNT)}
+              bounds={[-2.8, 0, -2.8, 2.8, 0.8, 2.8]}
+              ref={m => (pinesMesh = m)}
+            />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+// One class, one compiled pipeline; each mesh gets its own instance() so
+// per-mesh uniforms stay independent (none are used here).
+let instancedLook = shaderMaterialClass({
+  vertex: INSTANCE_VERTEX,
+  fragment: INSTANCE_FRAGMENT,
+  instanceAttributes: [
+    { name: "iPos", format: "vec3" },
+    { name: "iScale", format: "f32" },
+    { name: "iTint", format: "vec3" },
+  ],
+  label: "instanced-look",
+})
+
+render(() => <App />)

package/examples/lit.tsx

@@ -0,0 +1,66 @@
+// The lit material and the scene's lights. lit() is the standard look -
+// hemisphere ambient, the scene's directional lights, Lambert diffuse,
+// optional Blinn-Phong highlight - with the same color/map/transparent
+// options as unlit. Lights are NODES: <HemisphereLight> plus up to four
+// <DirectionalLight>s, here a warm key inside a spinning <Group> (a
+// parent's rotation turns the light, no per-frame direction math) and a
+// fixed cool fill; however many meshes, a light change is one shared
+// uniform write. The three boxes share one checker map: the
+// UV-mapped one stretches it per face (every generator emits 0..1 UVs),
+// the two triplanar ones tile it at one world density whatever their
+// size - the reason triplanar is an option on lit.
+
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { createTexture } from "@solidrt/core/gpu"
+import { box, DirectionalLight, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, Scene, sphere, torusKnot, plane } from "@solidrt/3d"
+
+const SIZE = 720
+
+function checker(): ReturnType<typeof createTexture> {
+  let n = 64
+  let data = new Uint8Array(n * n * 4)
+  for (let y = 0; y < n; y++) {
+    for (let x = 0; x < n; x++) {
+      let v = ((x >> 3) + (y >> 3)) & 1 ? 235 : 120
+      data.set([v, v, v, 255], (y * n + x) * 4)
+    }
+  }
+  return createTexture(data, n, n, { wrap: "repeat", mipmap: true })
+}
+
+function App() {
+  let [t, setT] = createSignal(0)
+  onFrame(tick => setT(tick / 1000))
+
+  let map = checker()
+  let uvMapped = lit({ map })
+  let tiled = lit({ map, triplanar: 2 })
+  let glossy = lit({ color: [0.85, 0.3, 0.25], specular: 0.6, shininess: 60 })
+  let matte = lit({ color: [0.3, 0.55, 0.85] })
+  let glass = lit({ color: [0.9, 0.95, 1, 0.35], specular: 1, shininess: 120, transparent: true })
+
+  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]} samples={4} label="lit">
+          <PerspectiveCamera fov={50} position={[0, 2.6, 5]} lookAt={[0, 0.4, 0]} />
+          <HemisphereLight sky={[0.35, 0.38, 0.45]} ground={[0.12, 0.1, 0.08]} />
+          <Group rotation={[0, t(), 0]}>
+            <DirectionalLight direction={[0.7, -0.8, 0]} color={[1, 0.92, 0.8]} intensity={0.9} />
+          </Group>
+          <DirectionalLight direction={[0.6, -0.3, 0.5]} color={[0.4, 0.5, 0.8]} intensity={0.35} />
+          <Mesh geometry={plane({ width: 8, height: 8 })} material={tiled} rotation={[-Math.PI / 2, 0, 0]} />
+          <Group rotation={[0, t() / 4, 0]}>
+            <Mesh geometry={box({ width: 0.8, height: 0.8, depth: 0.8 })} material={uvMapped} position={[-1.6, 0.4, 0]} />
+            <Mesh geometry={box({ width: 1.6, height: 0.5, depth: 0.8 })} material={tiled} position={[0, 0.25, 1.2]} />
+            <Mesh geometry={sphere({ radius: 0.5 })} material={glossy} position={[1.5, 0.5, 0]} />
+            <Mesh geometry={torusKnot({ radius: 0.35, tube: 0.12 })} material={matte} position={[0, 0.9, -1]} />
+            <Mesh geometry={sphere({ radius: 0.45 })} material={glass} position={[0, 0.45, 0]} />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/model.tsx

@@ -0,0 +1,51 @@
+// A model from a file: model.glb (a small authored scene - a rover with a
+// node tree of nested transforms, a mirrored node, a textured material, a
+// transparent dome and a mesh shipped without normals) parsed at runtime
+// with parseGltf and turned into a Group of meshes by createModel. The
+// glb rides in the bundle as a binary import; a model under assets/ goes
+// through loadGltf (same parser, read with flux:fs) or, baked once with
+// `srt tool 3d/model`, through loadModel (no parsing at all). Every part
+// keeps its node name and is an ordinary mesh: pointer events, transforms
+// and materials work per part.
+
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { add, createModel, DirectionalLight, Group, HemisphereLight, parseGltf, PerspectiveCamera, Scene, setVisible } from "@solidrt/3d"
+import type { SceneNode } from "@solidrt/3d"
+import modelBytes from "./model.glb" with { type: "binary" }
+
+const SIZE = 720
+
+function App() {
+  let [t, setT] = createSignal(0)
+  onFrame(tick => setT(tick / 1000))
+
+  // Parse + upload once; the model is plain scene data from here on.
+  let model = createModel(parseGltf(modelBytes), { label: "rover" })
+  let b = model.bounds
+  let center: [number, number, number] = [(b[0]! + b[3]!) / 2, (b[1]! + b[4]!) / 2, (b[2]! + b[5]!) / 2]
+  let radius = Math.hypot(b[3]! - b[0]!, b[4]! - b[1]!, b[5]! - b[2]!) / 2
+
+  // Parts are named after the glTF nodes: a click hides that part, a
+  // click on the body brings everything back.
+  for (let part of model.parts) {
+    part.mesh.onPointerDown = () => {
+      if (part.name === "body") for (let p of model.parts) setVisible(p.mesh, true)
+      else setVisible(part.mesh, false)
+    }
+  }
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.1, 0.11, 0.14, 1]} samples={4} label="model">
+          <PerspectiveCamera fov={40} position={[center[0] + radius * 1.4, center[1] + radius * 1.1, center[2] + radius * 2.2]} lookAt={center} />
+          <HemisphereLight sky={[0.45, 0.5, 0.6]} ground={[0.2, 0.17, 0.14]} />
+          <DirectionalLight direction={[0.5, -0.8, 0.3]} color={[1, 0.95, 0.85]} intensity={0.9} />
+          <Group rotation={[0, t() / 3, 0]} ref={(g: SceneNode) => add(g, model)} />
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/pick.tsx

@@ -62,15 +62,15 @@ function Pickable(p: { name: string; color: Color; geometry: Geometry; position:
 }
 
 function App() {
-  let floor = plane(8, 8, "floor")
+  let floor = plane({ width: 8, height: 8, label: "floor" })
   let crate = box()
-  let ball = sphere(0.45)
-  let spike = cone(0.45, 1)
-  let ring = torus(0.4, 0.14)
+  let ball = sphere({ radius: 0.45 })
+  let spike = cone({ radius: 0.45, height: 1 })
+  let ring = torus({ radius: 0.4, tube: 0.14 })
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
         <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="pick">
           <PerspectiveCamera fov={55} position={[0, 2.6, 5]} lookAt={[0, 0.4, 0]} />
           <Mesh geometry={floor} material={unlit({ color: [0.15, 0.16, 0.2] })} rotation={[-Math.PI / 2, 0, 0]} />

package/examples/scene-background.tsx

@@ -28,12 +28,12 @@ let BACKDROP = glsl`
 function App() {
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
         <Scene width={SIZE} height={SIZE} background={BACKDROP} label="backdrop-demo">
           <PerspectiveCamera fov={55} position={[0, 1.8, 4.4]} lookAt={[0, 0.4, 0]} />
-          <Mesh geometry={torusKnot(0.7, 0.2, 128, 16)} material={unlit({ color: [0.85, 0.55, 0.25] })} position={[0, 0.9, 0]} />
+          <Mesh geometry={torusKnot({ radius: 0.7, tube: 0.2, tubularSegments: 128, radialSegments: 16 })} material={unlit({ color: [0.85, 0.55, 0.25] })} position={[0, 0.9, 0]} />
           <Mesh geometry={box()} material={unlit({ color: [0.3, 0.5, 0.8] })} position={[-1.5, 0.4, -0.5]} scale={0.8} />
-          <Mesh geometry={sphere(0.4)} material={unlit({ color: [0.4, 0.75, 0.45] })} position={[1.5, 0.4, -0.5]} />
+          <Mesh geometry={sphere({ radius: 0.4 })} material={unlit({ color: [0.4, 0.75, 0.45] })} position={[1.5, 0.4, -0.5]} />
         </Scene>
       </view>
     </window>

package/examples/scene-basic.tsx

@@ -21,12 +21,12 @@ function App() {
   // use one cube geometry (one vertex/index buffer pair on the GPU), and
   // every mesh here shares the one unlit-color pipeline.
   let cube = box()
-  let floor = plane(6, 6, "floor")
-  let ball = sphere(0.35)
+  let floor = plane({ width: 6, height: 6, label: "floor" })
+  let ball = sphere({ radius: 0.35 })
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
         <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="scene-basic">
           <PerspectiveCamera fov={55} position={[0, 1.6, 3.6]} lookAt={[0, 0.3, 0]} />
           <Mesh

package/examples/scene-post-effect.tsx

@@ -39,12 +39,12 @@ function App() {
   onFrame(tick => setSpin(tick / 2000))
 
   let cube = box()
-  let floor = plane(6, 6, "floor")
-  let ball = sphere(0.35)
+  let floor = plane({ width: 6, height: 6, label: "floor" })
+  let ball = sphere({ radius: 0.35 })
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
         <Scene
           width={RENDER}
           height={RENDER}

package/examples/scene-views.tsx

@@ -0,0 +1,95 @@
+// One scene, three renderings: the built-in leaf from a perspective
+// camera, plus two `scene.createView` targets - a top-down ORTHOGRAPHIC
+// map (`ortho` on setCamera) and a side silhouette drawn with an
+// `overrideMaterial`. The group spins from ONE signal: each mesh is one
+// core node whose flush writes its world matrix into every target's entry
+// at once, so the extra views cost the app nothing per frame (and the
+// light set fans out to them too - the map is lit like the main view).
+// Views die with the scene.
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { box, DirectionalLight, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, sphere, unlit } from "@solidrt/3d"
+import type { SceneHandle } from "@solidrt/3d"
+
+const MAIN = 720
+const SIDE = 360
+
+function App() {
+  let [spin, setSpin] = createSignal(0)
+  onFrame(tick => setSpin(tick / 2000))
+
+  let cube = box()
+  let floor = plane({ width: 6, height: 6, label: "floor" })
+  let ball = sphere({ radius: 0.35 })
+  // `ref` runs before `output`, so the handle is set when the views are
+  // created there; both callbacks run once, untracked - no signals needed.
+  let scene!: SceneHandle
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[MAIN + SIDE, MAIN]}>
+        <Scene
+          width={MAIN}
+          height={MAIN}
+          clearColor={[0.07, 0.07, 0.1, 1]}
+          label="scene-views"
+          ref={s => (scene = s)}
+          output={tex => {
+            // The map: straight down from y = 10, world -z toward the top of
+            // the leaf, seven world units across at any depth.
+            let map = scene.createView({ width: SIDE, height: SIDE, clearColor: [0.05, 0.08, 0.06, 1], label: "map" })
+            map.setCamera({
+              position: [0, 10, 0],
+              target: [0, 0, 0],
+              up: [0, 0, -1],
+              ortho: { left: -3.5, right: 3.5, top: 3.5, bottom: -3.5 },
+              near: 0.1,
+              far: 20,
+            })
+            // The silhouette: every mesh drawn flat amber, from the side. The
+            // floor is edge-on here, a single line at the bottom.
+            let side = scene.createView({
+              width: SIDE,
+              height: SIDE,
+              clearColor: [0.1, 0.06, 0.05, 1],
+              overrideMaterial: unlit({ color: [0.95, 0.75, 0.3] }),
+              label: "silhouette",
+            })
+            side.setCamera({
+              position: [6, 1, 0],
+              target: [0, 0.6, 0],
+              ortho: { left: -2.4, right: 2.4, top: 2.4, bottom: -2.4 },
+              near: 0.1,
+              far: 20,
+            })
+            return (
+              <view flexDirection="row" width={MAIN + SIDE} height={MAIN}>
+                <texture src={tex} width={MAIN} height={MAIN} />
+                <view flexDirection="column" width={SIDE} height={MAIN}>
+                  <texture src={map.texture} width={SIDE} height={SIDE} />
+                  <texture src={side.texture} width={SIDE} height={SIDE} />
+                </view>
+              </view>
+            )
+          }}
+        >
+          <PerspectiveCamera fov={55} position={[0, 1.6, 3.6]} lookAt={[0, 0.3, 0]} />
+          <HemisphereLight sky={[0.6, 0.7, 0.9]} ground={[0.25, 0.2, 0.15]} intensity={0.6} />
+          <DirectionalLight direction={[-0.5, -1, -0.3]} color={[1, 0.95, 0.85]} intensity={0.9} />
+          <Mesh geometry={floor} material={lit({ color: [0.3, 0.32, 0.38] })} rotation={[-Math.PI / 2, 0, 0]} />
+          <Group rotation={[0, spin(), 0]}>
+            <Mesh geometry={cube} material={lit({ color: [0.85, 0.3, 0.3] })} position={[0, 0.5, 0]} />
+            <Mesh
+              geometry={cube}
+              material={lit({ color: [0.9, 0.8, 0.35] })}
+              position={[-1.1, 0.7, 0]}
+              scale={[0.5, 1.4, 0.5]}
+            />
+            <Mesh geometry={ball} material={lit({ color: [0.35, 0.65, 0.9] })} position={[1.1, 0.35, 0]} />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/shadows.tsx

@@ -0,0 +1,86 @@
+// Directional shadow maps: three `castShadow` lights, `castShadow` meshes
+// and `lit` materials, which receive shadows by default. The warm sun
+// swings through its arc from onFrame - ONE setTransform on the light
+// node per frame; the scene re-places its shadow camera from the light's
+// world matrix, so its shadows sweep across the ground while the casters
+// turn inside their group. A cool fill from the opposite side and a low
+// rim light stand still, so every caster throws three shadows that cross
+// as the sun moves (each casting light is its own map and pass, capped
+// by MAX_LIGHTS). Three's vocabulary throughout: `castShadow` on the
+// light and on meshes, `shadow.mapSize/bias/normalBias/camera` on the
+// light; the one divergence is that opting OUT of receiving is a material
+// option (`lit({ receiveShadow: false })`, Godot's split), because the
+// material picks the program (like vertexColors and triplanar).
+//
+// Placement matters for a casting light: its shadow camera sits at the
+// light's WORLD position looking along its direction, so the sun is
+// positioned above the scene (a light at the origin would shadow nothing
+// above it). The light frustum is `shadow.camera`, +-5 world units by
+// default - anything outside it is lit.
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { box, cylinder, DirectionalLight, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, setTransform, sphere, torusKnot } from "@solidrt/3d"
+import type { DirectionalLightNode } from "@solidrt/3d"
+
+const SIZE = 720
+
+function App() {
+  let [t, setT] = createSignal(0)
+  let sun!: DirectionalLightNode
+  onFrame(tick => {
+    setT(tick / 1000)
+    // The sun's arc: east to west over the scene, always pointing at the
+    // origin. The direction is the node's local -y, so aiming is a
+    // rotation about z; the position rides the same arc so the shadow
+    // camera stays above the casters.
+    let a = Math.sin(tick / 4000) * 1.0
+    setTransform(sun, { position: [Math.sin(a) * 6, Math.cos(a) * 6, 2], rotation: [0.32, 0, -a] })
+  })
+
+  let ground = lit({ color: [0.55, 0.58, 0.6] })
+  let red = lit({ color: [0.85, 0.3, 0.25] })
+  let blue = lit({ color: [0.3, 0.55, 0.85] })
+  let gold = lit({ color: [0.9, 0.75, 0.3], specular: 0.5, shininess: 40 })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.55, 0.65, 0.8, 1]} samples={4} label="shadows">
+          <PerspectiveCamera fov={45} position={[0, 4, 7]} lookAt={[0, 0.5, 0]} />
+          <HemisphereLight sky={[0.45, 0.5, 0.6]} ground={[0.2, 0.18, 0.15]} />
+          <DirectionalLight
+            ref={l => (sun = l)}
+            color={[1, 0.95, 0.85]}
+            intensity={0.8}
+            castShadow
+            shadow={{ mapSize: 1024, normalBias: 0.02, camera: { near: 1, far: 20 } }}
+          />
+          <DirectionalLight
+            color={[0.45, 0.6, 0.9]}
+            intensity={0.5}
+            position={[-5, 5, -4]}
+            direction={[5, -5, 4]}
+            castShadow
+            shadow={{ normalBias: 0.02, camera: { near: 1, far: 20 } }}
+          />
+          <DirectionalLight
+            color={[0.9, 0.5, 0.35]}
+            intensity={0.45}
+            position={[5, 2, -5]}
+            direction={[-5, -2, 5]}
+            castShadow
+            shadow={{ mapSize: 512, normalBias: 0.03, camera: { near: 1, far: 20 } }}
+          />
+          <Mesh geometry={plane({ width: 10, height: 10 })} material={ground} rotation={[-Math.PI / 2, 0, 0]} />
+          <Group rotation={[0, t() / 3, 0]}>
+            <Mesh geometry={box({ width: 1, height: 1, depth: 1 })} material={red} position={[-1.6, 0.5, 0]} castShadow />
+            <Mesh geometry={sphere({ radius: 0.6 })} material={blue} position={[1.5, 0.6, 0]} castShadow />
+            <Mesh geometry={torusKnot({ radius: 0.4, tube: 0.14 })} material={gold} position={[0, 1.3, 0]} castShadow />
+            <Mesh geometry={cylinder({ radiusTop: 0.12, radiusBottom: 0.12, height: 1.6 })} material={gold} position={[0, 0.8, 0]} castShadow />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)