@solidrt/3d 0.0.56 → 0.0.57

package/src/collision.ts

@@ -1,199 +1,20 @@
-// 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.
-
+// The kinematic character move, Godot's CharacterBody3D.move_and_slide
+// and Unity's CharacterController.Move as one pure function: 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,
+// a node-driven body applies the result with setTransform. The loop
+// itself (depenetration, sweep, slide, floor snap) runs in the spatial
+// core as scene.moveAndSlide; this is its free-function spelling.
+
+import type { MoveOptions, MoveResult, Scene, Volume } from "./scene.ts"
 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 MoveScene = Pick<Scene, "moveAndSlide">
 
-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.
- */
+/** Move a body `motion` through the scene's colliders, sliding along what
+ * it hits: scene.moveAndSlide as a function (see it for the contract). */
 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]
+  return scene.moveAndSlide(volume, motion, opts)
 }

package/src/components/context.tsx

@@ -0,0 +1,35 @@
+import { createContext, useContext } from "@solidrt/core"
+import type { Element, PointerFeed } from "@solidrt/core"
+import type { SceneNode } from "../node.ts"
+import type { Scene as SceneHandle } from "../scene.ts"
+import type { CameraState, CameraUpdate } from "../camera.ts"
+
+/** The camera state a camera control drives: the scene, or a view (both
+ * expose setCamera and camera()). */
+export type CameraTarget = { setCamera(update: CameraUpdate): void; camera(): CameraState }
+
+export type SceneCtx = { scene: SceneHandle; parent: SceneNode; viewport: CameraTarget; pointer: PointerFeed | null }
+export let SceneContext = createContext<SceneCtx>()
+
+/**
+ * The enclosing scene, parent node, viewport and pointer feed - the
+ * imperative escape hatch inside a component subtree (throws outside a
+ * `<Scene>`). `viewport` and `pointer` are the nearest OWNER's: the
+ * scene, or inside a `<View3d>` that view - what the camera-control
+ * components drive, and the feed the owner's `pointer` prop handed in
+ * (null when none was: the owner's leaf then feeds no gestures). The
+ * same shape as @solidrt/2d's useSpriteLayer.
+ */
+export function useScene(): SceneCtx {
+  return useContext(SceneContext)
+}
+
+// The scene context for a node component's children. Solid's provider is
+// a root and two memos over the children, paid even when there are none,
+// so it is built only when the JSX has children: the compiler emits the
+// `children` getter only then, so the test is structural, not a read
+// (probes/3d-instance-mount-bench.tsx has the per-row cost).
+export function provide(ctx: SceneCtx, parent: SceneNode, props: { children?: Element }): Element | undefined {
+  if (!("children" in props)) return undefined
+  return <SceneContext value={{ scene: ctx.scene, parent, viewport: ctx.viewport, pointer: ctx.pointer }}>{props.children}</SceneContext>
+}

package/src/components/directional-light.tsx

@@ -0,0 +1,48 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { syncNode } from "./node-props.ts"
+import type { TransformProps } from "./node-props.ts"
+import { add, remove } from "../node.ts"
+import { createDirectionalLight, setLight } from "../light.ts"
+import type { DirectionalLight as DirectionalLightNode, ShadowOptions } from "../light.ts"
+import type { Vec3 } from "../math.ts"
+
+export type DirectionalLightProps = TransformProps & {
+  /** Travel direction in the node's local space; default [0, -1, 0]. */
+  direction?: Vec3
+  color?: Vec3
+  intensity?: number
+  /** Render a shadow map from this light (any directional light may;
+   * each is a pass). Its shadow camera sits at the light's WORLD
+   * position, so give a casting light a `position` above the scene. */
+  castShadow?: boolean
+  /** Shadow-map options (mapSize, bias, normalBias, camera frustum,
+   * cascades, distance), merged key by key. */
+  shadow?: ShadowOptions
+  ref?: (light: DirectionalLightNode) => void
+}
+
+/** A directional light node (createDirectionalLight): a parent Group's
+ * rotation turns it; up to MAX_LIGHTS per scene, in mount order. */
+export let DirectionalLight: VoidComponent<DirectionalLightProps> = props => {
+  let ctx = useContext(SceneContext)
+  let light = untrack(() =>
+    createDirectionalLight({
+      direction: props.direction,
+      color: props.color,
+      intensity: props.intensity,
+      castShadow: props.castShadow,
+      shadow: props.shadow,
+    }),
+  )
+  add(ctx.parent, light)
+  syncNode(light, props)
+  createEffect(
+    () => [props.direction, props.color, props.intensity, props.castShadow, props.shadow] as const,
+    ([direction, color, intensity, castShadow, shadow]) => setLight(light, { direction, color, intensity, castShadow, shadow }),
+  )
+  untrack(() => props.ref)?.(light)
+  onCleanup(() => remove(light))
+  return null
+}

package/src/components/first-person-camera.tsx

@@ -0,0 +1,72 @@
+import { createEffect, merge, onFrame, untrack, useContext } from "@solidrt/core"
+import type { InputMap, VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { createFirstPersonCamera } from "../first-person.ts"
+import type { FirstPersonAxes, FirstPersonCamera as FirstPersonCameraHandle, FirstPersonCameraOptions } from "../first-person.ts"
+
+// Cap on the frame loop's per-frame dt in seconds, the same guard as the
+// orbit's: a resumed app must not teleport the walker.
+const MAX_WALK_DT = 0.1
+
+export type FirstPersonCameraProps = FirstPersonCameraOptions & {
+  /** The input map driving the control (InputMap.drive): its `look`,
+   * `move` and `rise` actions, or the ones `actions` names. Live: a new
+   * map reconnects. Without one the control moves only through `ref`. */
+  input?: InputMap<any>
+  /** Action names per axis when the map's differ (null skips an axis). */
+  actions?: Partial<Record<keyof FirstPersonAxes, string | null>>
+  /** The control's handle (pose()/set()/eye()/forward()/active(), the
+   * verbs, `axes` - also the debug command shape). */
+  ref?: (camera: FirstPersonCameraHandle) => void
+}
+
+/**
+ * createFirstPersonCamera as a Scene (or View3d) child: drives the
+ * enclosing camera - the scene's, or inside a `<View3d>` that view's -
+ * through context, and takes its input from the map in `input`, nothing
+ * else (ARCHITECTURE.md: the app binds keys, a pointer feed, a pad or
+ * anything else to the map, and spreads the map's key handlers where the
+ * keys should be caught). Pointer lock stays the app's: call
+ * `lockPointer(true)` from a click and `lockPointer(false)` from Escape;
+ * the pointer feed's `mouseDelta` source looks around while locked. The
+ * pose props (position, yaw, pitch) are initial values - change the pose
+ * at runtime through `ref`'s set() or the verbs; every other prop is
+ * live, forwarded to the control as a getter and read where it applies:
+ * `fly={flying()}` swaps walk and fly on the running control (pose
+ * carries over, no remount), `moveSpeed`, `lookSpeed` and
+ * `clampPosition` follow their props, and a pitch clamp change re-clamps
+ * at once. A frame loop runs only while `active()` - a rate driving - so
+ * a still scene stays demand-driven idle.
+ */
+export let FirstPersonCamera: VoidComponent<FirstPersonCameraProps> = props => {
+  let ctx = useContext(SceneContext)
+  // Getters, not a spread: see OrbitCamera.
+  let options: FirstPersonCameraOptions = merge(props, {})
+  let camera = untrack(() => createFirstPersonCamera(ctx.viewport, options))
+  createEffect(
+    () => props.input,
+    input => (input ? input.drive(camera.axes, untrack(() => props.actions)) : undefined),
+  )
+  createEffect(
+    () => camera.active(),
+    on => {
+      if (!on) return
+      let last: number | null = null
+      return onFrame(tick => {
+        let now = tick / 1000
+        let dt = last === null ? 0 : Math.min(now - last, MAX_WALK_DT)
+        last = now
+        camera.update(dt)
+      })
+    },
+  )
+  // A pitch clamp change re-clamps the pose at once; deferred and
+  // untracked as OrbitCamera's.
+  createEffect(
+    () => [options.minPitch, options.maxPitch],
+    () => untrack(() => camera.set({})),
+    { defer: true },
+  )
+  untrack(() => props.ref)?.(camera)
+  return null
+}

package/src/components/group.tsx

@@ -0,0 +1,18 @@
+import { onCleanup, untrack, useContext } from "@solidrt/core"
+import type { ParentComponent } from "@solidrt/core"
+import { SceneContext, provide } from "./context.tsx"
+import { syncNode } from "./node-props.ts"
+import type { TransformProps, PointerEventProps } from "./node-props.ts"
+import { add, createGroup, remove } from "../node.ts"
+import type { SceneNode } from "../node.ts"
+
+/** A transform node: children inherit its position/rotation/scale. */
+export let Group: ParentComponent<TransformProps & PointerEventProps & { ref?: (node: SceneNode) => void }> = props => {
+  let ctx = useContext(SceneContext)
+  let node = createGroup()
+  add(ctx.parent, node)
+  syncNode(node, props)
+  untrack(() => props.ref)?.(node)
+  onCleanup(() => remove(node))
+  return provide(ctx, node, props)
+}

package/src/components/hemisphere-light.tsx

@@ -0,0 +1,24 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { add, remove } from "../node.ts"
+import { createHemisphereLight, setLight } from "../light.ts"
+import type { HemisphereLight as HemisphereLightNode } from "../light.ts"
+import type { Vec3 } from "../math.ts"
+
+export type HemisphereLightProps = { sky?: Vec3; ground?: Vec3; intensity?: number; ref?: (light: HemisphereLightNode) => void }
+
+/** The scene's ambient term as a node (createHemisphereLight); one per
+ * scene, the last mounted wins. */
+export let HemisphereLight: VoidComponent<HemisphereLightProps> = props => {
+  let ctx = useContext(SceneContext)
+  let light = untrack(() => createHemisphereLight({ sky: props.sky, ground: props.ground, intensity: props.intensity }))
+  add(ctx.parent, light)
+  createEffect(
+    () => [props.sky, props.ground, props.intensity] as const,
+    ([sky, ground, intensity]) => setLight(light, { sky, ground, intensity }),
+  )
+  untrack(() => props.ref)?.(light)
+  onCleanup(() => remove(light))
+  return null
+}

package/src/components/index.ts

@@ -0,0 +1,46 @@
+// The Solid face: PascalCase components over context, syncing the retained
+// scene (node/mesh/light/scene.ts) - no new intrinsic elements, no
+// renderer changes. Props
+// follow the Solid 2.0 model (reactive values, no destructuring); effects
+// write into the retained nodes and the runtime's dirty flush renders.
+// Anything moving at frame rate can bypass the declarative layer: grab the
+// node with `ref` and call setTransform from onFrame - signals carry
+// structure and slow state, per-frame motion goes straight to the scene.
+//
+// One file per component (the lights, cameras and meshes each their own),
+// with the shared pieces beside them: context.tsx (the scene context and
+// useScene), node-props.ts (the transform and pointer
+// props every node component syncs) and mesh.tsx (the mesh-side props the
+// populated meshes share). This index is the package's face: index.ts at
+// the root re-exports it, nothing outside imports the files directly.
+
+export { useScene } from "./context.tsx"
+export type { CameraTarget } from "./context.tsx"
+export type { PointerEventProps, TransformProps } from "./node-props.ts"
+export { Scene } from "./scene.tsx"
+export type { ScenePointerProps, SceneProps } from "./scene.tsx"
+export { View3d } from "./view3d.tsx"
+export type { View3dProps } from "./view3d.tsx"
+export { Group } from "./group.tsx"
+export { Mesh } from "./mesh.tsx"
+export type { MeshProps } from "./mesh.tsx"
+export { Sprite } from "./sprite.tsx"
+export type { SpriteProps } from "./sprite.tsx"
+export { Instance, InstancedMesh } from "./instanced-mesh.tsx"
+export type { InstancedMeshProps, InstanceProps } from "./instanced-mesh.tsx"
+export { RecordMesh } from "./record-mesh.tsx"
+export type { RecordMeshProps } from "./record-mesh.tsx"
+export { PerspectiveCamera } from "./perspective-camera.tsx"
+export type { PerspectiveCameraProps } from "./perspective-camera.tsx"
+export { OrbitCamera } from "./orbit-camera.tsx"
+export type { OrbitCameraProps } from "./orbit-camera.tsx"
+export { FirstPersonCamera } from "./first-person-camera.tsx"
+export type { FirstPersonCameraProps } from "./first-person-camera.tsx"
+export { HemisphereLight } from "./hemisphere-light.tsx"
+export type { HemisphereLightProps } from "./hemisphere-light.tsx"
+export { DirectionalLight } from "./directional-light.tsx"
+export type { DirectionalLightProps } from "./directional-light.tsx"
+export { SpotLight } from "./spot-light.tsx"
+export type { SpotLightProps } from "./spot-light.tsx"
+export { PointLight } from "./point-light.tsx"
+export type { PointLightProps } from "./point-light.tsx"

package/src/components/instanced-mesh.tsx

@@ -0,0 +1,105 @@
+import { createContext, createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { ParentComponent } from "@solidrt/core"
+import { SceneContext, provide } from "./context.tsx"
+import { syncNode } from "./node-props.ts"
+import type { TransformProps, PointerEventProps } from "./node-props.ts"
+import { syncMesh } from "./mesh.tsx"
+import type { PopulatedMeshProps } from "./mesh.tsx"
+import { add } from "../node.ts"
+import { addInstance, createInstancedMesh, disposeInstances, removeInstance, setCastShadow, setGeometry, setInstanceStyle } from "../mesh.ts"
+import type { InstancedMesh as InstancedMeshNode, InstanceNode } from "../mesh.ts"
+import type { Geometry } from "../geometry.ts"
+import type { Material } from "../material.ts"
+
+export type InstancedMeshProps = PopulatedMeshProps & {
+  geometry: Geometry
+  /** An instanced material: a stock one with `instanced` (or
+   * `instanceColors`, for a per-instance tint), or a class declaring
+   * INSTANCE_MATRIX_ATTRIBUTES in slot 0 and any style layout in slot 1. */
+  material: Material
+  /** Instance slots reserved up front (default 64; fixed at creation).
+   * Past it the buffers double into replacements - amortized, but size it
+   * realistically to skip the copies. */
+  capacity?: number
+  /** LOCAL bounds covering the population ([minX..maxZ]), fixed at
+   * creation: the mesh node's own box for the frustum test and the
+   * transparent sort. Optional here - instances pick by themselves, and
+   * without it the mesh culls by the union of their boxes. */
+  bounds?: ArrayLike<number>
+  /** Debug label for the record buffers. */
+  label?: string
+  /** Draw into the scene's shadow map (setCastShadow as a prop); default
+   * false. The stock instanced materials cast; a custom class needs a
+   * `shadowVertex`. */
+  castShadow?: boolean
+  ref?: (mesh: InstancedMeshNode) => void
+}
+
+let InstancedMeshContext = createContext<InstancedMeshNode | null>(null)
+
+/**
+ * One draw entry covering N instance NODES (createInstancedMesh as a
+ * component): `<Instance>` children populate it - each a scene node the
+ * core places, so their `transition` props spring with zero per-frame
+ * JS, and picking, pointer events, overlap and sweep name the instance
+ * struck. `<Group>` children between the mesh and its instances are
+ * squads (the records stay mesh-relative through them). The record
+ * buffers are component-owned and freed on unmount.
+ */
+export let InstancedMesh: ParentComponent<InstancedMeshProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() =>
+    createInstancedMesh(props.geometry, props.material, { capacity: props.capacity, bounds: props.bounds, label: props.label }),
+  )
+  add(ctx.parent, mesh)
+  createEffect(
+    () => props.geometry,
+    g => setGeometry(mesh, g),
+    { defer: true },
+  )
+  createEffect(
+    () => props.castShadow,
+    c => setCastShadow(mesh, c === true),
+  )
+  syncMesh(mesh, props)
+  untrack(() => props.ref)?.(mesh)
+  onCleanup(() => disposeInstances(mesh))
+  return (
+    <SceneContext value={{ scene: ctx.scene, parent: mesh, viewport: ctx.viewport, pointer: ctx.pointer }}>
+      <InstancedMeshContext value={mesh}>{props.children}</InstancedMeshContext>
+    </SceneContext>
+  )
+}
+
+export type InstanceProps = TransformProps & PointerEventProps & {
+  /** The instance's style record (setInstanceStyle as a prop): the
+   * floats of the material's slot-1 instance attributes - `[r, g, b, a]`
+   * under a stock material's `instanceColors`. Reactive; absent, the
+   * instance keeps the material's instanceStyle (white for a tint). */
+  style?: ArrayLike<number>
+  ref?: (instance: InstanceNode) => void
+}
+
+/**
+ * One instance of the enclosing `<InstancedMesh>` (addInstance as a
+ * component): a node placed under the nearest `<Group>` or `<Instance>`
+ * inside the mesh, with the transform, transition and pointer props of
+ * a `<Group>` plus `style`. Children (a `<Mesh>` headlight under a car
+ * instance) mount under it. Throws outside an `<InstancedMesh>`.
+ */
+export let Instance: ParentComponent<InstanceProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = useContext(InstancedMeshContext)
+  if (mesh === null) throw new Error("<Instance> must be inside an <InstancedMesh>")
+  let instance = addInstance(mesh, undefined, ctx.parent)
+  syncNode(instance, props)
+  createEffect(
+    () => props.style,
+    s => {
+      if (s !== undefined) setInstanceStyle(instance, s)
+    },
+  )
+  untrack(() => props.ref)?.(instance)
+  onCleanup(() => removeInstance(instance))
+  return provide(ctx, instance, props)
+}

package/src/components/mesh.tsx

@@ -0,0 +1,92 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { syncNode } from "./node-props.ts"
+import type { TransformProps, PointerEventProps } from "./node-props.ts"
+import { add, remove } from "../node.ts"
+import { createMesh, setCastShadow, setCulling, setGeometry, setLayers, setMaterial, setMeshParams, setRenderOrder } from "../mesh.ts"
+import type { Mesh as MeshNode } from "../mesh.ts"
+import type { ShaderParams } from "@solidrt/core/gpu"
+import type { Geometry } from "../geometry.ts"
+import type { Material } from "../material.ts"
+
+export type MeshProps = TransformProps & PointerEventProps & {
+  geometry: Geometry
+  material: Material
+  /** Per-mesh uniforms for a custom material (setMeshParams as a prop).
+   * Keys merge - a key that disappears keeps its old value; there is no
+   * unset. Names must be declared by the material's shaders. For values
+   * changing every frame prefer `ref` + setMeshParams from onFrame, the
+   * same split as setTransform. */
+  params?: ShaderParams
+  /** Explicit draw-order key (setRenderOrder as a prop); default 0. */
+  renderOrder?: number
+  /** Draw into the scene's shadow map (setCastShadow as a prop); default
+   * false. Needs a `castShadow` light to show. */
+  castShadow?: boolean
+  /** Layer membership bitmask (setLayers as a prop; default 1): a target
+   * draws the mesh when its mask intersects this. Not inherited from
+   * ancestor Groups. */
+  layers?: number
+  /** Frustum culling switch (setCulling as a prop; default true). */
+  frustumCulled?: boolean
+  /** World units the culled box grows by (setCulling as a prop; default 0). */
+  cullMargin?: number
+  ref?: (mesh: MeshNode) => void
+}
+
+// The mesh-side props every mesh component shares (Sprite has no
+// geometry and casts no shadow, so those stay with the components that
+// take them); the
+// ref and the cleanup are each component's own (a populated mesh frees
+// its buffers, a plain one is removed).
+export function syncMesh(mesh: MeshNode, props: Omit<MeshProps, "geometry" | "castShadow" | "ref">): void {
+  createEffect(
+    () => props.material,
+    m => setMaterial(mesh, m),
+    { defer: true },
+  )
+  createEffect(
+    () => props.params,
+    p => {
+      if (p !== undefined) setMeshParams(mesh, p)
+    },
+  )
+  createEffect(
+    () => props.renderOrder,
+    o => setRenderOrder(mesh, o ?? 0),
+  )
+  createEffect(
+    () => props.layers,
+    l => setLayers(mesh, l ?? 1),
+  )
+  createEffect(
+    () => [props.frustumCulled, props.cullMargin] as const,
+    ([culled, margin]) => setCulling(mesh, { frustumCulled: culled !== false, cullMargin: margin ?? 0 }),
+  )
+  syncNode(mesh, props)
+}
+
+/** One draw entry: geometry drawn with a material at a transform. */
+export let Mesh: VoidComponent<MeshProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() => createMesh(props.geometry, props.material))
+  add(ctx.parent, mesh)
+  createEffect(
+    () => props.geometry,
+    g => setGeometry(mesh, g),
+    { defer: true },
+  )
+  createEffect(
+    () => props.castShadow,
+    c => setCastShadow(mesh, c === true),
+  )
+  syncMesh(mesh, props)
+  untrack(() => props.ref)?.(mesh)
+  onCleanup(() => remove(mesh))
+  return null
+}
+
+// The props both populated meshes share with Mesh: everything but the
+// geometry/material pair (documented per component) and the ref.
+export type PopulatedMeshProps = Omit<MeshProps, "geometry" | "material" | "ref">