@opsydyn/effect-three 0.1.0 → 0.3.0

package/dist/webgpu/index.js.map

@@ -5,9 +5,9 @@
     "/**\n * The WebGPU kit's contact shadow materials, in TSL: the WebGL kit's shadow-from-depth\n * output (colour `color · depth · 2`, alpha `1 − depth`) and three's horizontal and\n * vertical blur shaders (nine taps, their weights). The passes themselves are the\n * kernel's.\n *\n * @module\n */\nimport { type Color, NoBlending, Texture } from 'three';\nimport { depth, float, texture, uniform, uv, vec2 } from 'three/tsl';\nimport { MeshBasicNodeMaterial } from 'three/webgpu';\n\nimport {\n  type BlurPass,\n  createContactShadowPasses,\n  type ShadowMaterials,\n} from '../kernel/contactShadowPasses.ts';\nimport type { SceneRenderer } from '../kernel/renderer.ts';\nimport type { ContactShadowPasses, ShadowedScene } from '../kernel/renderKit.ts';\n\n/** A material writing exactly what its nodes say: no blending, depth or tone mapping. */\nconst plainMaterial = (): MeshBasicNodeMaterial => {\n  const material = new MeshBasicNodeMaterial();\n  material.transparent = true;\n  material.blending = NoBlending;\n  material.depthTest = false;\n  material.depthWrite = false;\n  material.toneMapped = false;\n  return material;\n};\n\nconst depthMaterial = (color: Color): MeshBasicNodeMaterial => {\n  const material = plainMaterial();\n  // Darkest where an object touches the plane: `depth` is linear for the orthographic camera.\n  material.colorNode = uniform(color).mul(depth).mul(2);\n  material.opacityNode = float(1).sub(depth);\n  return material;\n};\n\n/** three's `HorizontalBlurShader` and `VerticalBlurShader` taps: offset and weight. */\nconst taps = [\n  [-4, 0.051],\n  [-3, 0.0918],\n  [-2, 0.12245],\n  [-1, 0.1531],\n  [0, 0.1633],\n  [1, 0.1531],\n  [2, 0.12245],\n  [3, 0.0918],\n  [4, 0.051],\n] as const;\n\nconst blur = (direction: 'horizontal' | 'vertical'): BlurPass => {\n  const source = texture(new Texture());\n  const step = uniform(0);\n  const along = direction === 'horizontal' ? vec2(step, 0) : vec2(0, step);\n  const [first, ...rest] = taps.map(([offset, weight]) =>\n    source.sample(uv().add(along.mul(offset))).mul(weight),\n  );\n  const sum = rest.reduce((total, tap) => total.add(tap), first ?? source);\n  const material = plainMaterial();\n  material.colorNode = sum.rgb;\n  material.opacityNode = sum.a;\n  return {\n    material,\n    set: (map, amount) => {\n      source.value = map;\n      step.value = amount;\n    },\n  };\n};\n\nconst webgpuShadowMaterials: ShadowMaterials = {\n  depth: depthMaterial,\n  blur,\n  flippedTargets: true,\n};\n\n/** Creates the contact shadow passes for one scene graph and renderer, in TSL. */\nexport const createContactShadows = (\n  graph: ShadowedScene,\n  renderer: SceneRenderer,\n): ContactShadowPasses => createContactShadowPasses(graph, renderer, webgpuShadowMaterials);\n",
     "/**\n * The WebGPU kit's shader grid: the WebGL kit's grid (Drei's `Grid`, `bf6f4ad`, MIT; after\n * Fyrestar's `THREE.InfiniteGridHelper` and threlte's `Grid`) written in TSL, so that\n * three's `WebGPURenderer` can draw it on either backend. Same lines, same fade, same\n * camera uniforms set in `onBeforeRender`.\n *\n * @module\n */\nimport {\n  BackSide,\n  Color,\n  DoubleSide,\n  FrontSide,\n  Mesh,\n  Plane,\n  PlaneGeometry,\n  type Side,\n  Vector3,\n} from 'three';\nimport {\n  abs,\n  distance,\n  float,\n  fract,\n  fwidth,\n  min,\n  mix,\n  modelWorldMatrix,\n  modelWorldMatrixInverse,\n  positionGeometry,\n  pow,\n  select,\n  uniform,\n  varying,\n  vec4,\n} from 'three/tsl';\nimport { MeshBasicNodeMaterial } from 'three/webgpu';\n\nimport type { MaterialSide, ShaderGridNode } from '../kernel/description.ts';\nimport type { HostedShaderGrid } from '../kernel/renderKit.ts';\n\nconst sides = { front: FrontSide, back: BackSide, double: DoubleSide } satisfies Record<\n  MaterialSide,\n  Side\n>;\n\n/** The grid's uniforms: one node each, written from the description. */\nconst createUniforms = () => ({\n  cellSize: uniform(0.5),\n  cellThickness: uniform(0.5),\n  cellColor: uniform(new Color()),\n  sectionSize: uniform(1),\n  sectionThickness: uniform(1),\n  sectionColor: uniform(new Color()),\n  fadeDistance: uniform(100),\n  fadeStrength: uniform(1),\n  fadeFrom: uniform(1),\n  infinite: uniform(0),\n  followCamera: uniform(0),\n  cameraOnPlane: uniform(new Vector3()),\n  planeOrigin: uniform(new Vector3()),\n});\n\ntype Uniforms = ReturnType<typeof createUniforms>;\n\n/** The grid's material: the WebGL kit's vertex and fragment shaders, as TSL nodes. */\nconst gridMaterial = (u: Uniforms): MeshBasicNodeMaterial => {\n  const material = new MeshBasicNodeMaterial({ transparent: true });\n  // The plane geometry lies in XY; the grid lies in XZ. Infinite grids reach the fade.\n  const lifted = positionGeometry.xzy.mul(\n    select(u.infinite.greaterThan(0.5), u.fadeDistance.add(1), 1),\n  );\n  // Following the camera slides the plane by its foot's offset, in the grid's own space.\n  const shift = modelWorldMatrixInverse.mul(vec4(u.cameraOnPlane.sub(u.planeOrigin), 0)).xyz;\n  const local = select(u.followCamera.greaterThan(0.5), lifted.add(shift), lifted);\n  material.positionNode = local;\n  const gridPosition = varying(local);\n  const worldPosition = varying(modelWorldMatrix.mul(vec4(local, 1)).xyz);\n  // 1 on a line of a grid with this spacing, 0 between, antialiased over a pixel.\n  const lines = (spacing: typeof u.cellSize, thickness: typeof u.cellThickness) => {\n    const at = gridPosition.xz.div(spacing);\n    const away = abs(fract(at.sub(0.5)).sub(0.5)).div(fwidth(at));\n    return float(1).sub(min(min(away.x, away.y).add(1).sub(thickness), 1));\n  };\n  const cell = lines(u.cellSize, u.cellThickness);\n  const section = lines(u.sectionSize, u.sectionThickness);\n  const away = distance(u.cameraOnPlane.mul(u.fadeFrom), worldPosition);\n  const fade = pow(float(1).sub(min(away.div(u.fadeDistance), 1)), u.fadeStrength);\n  const alpha = cell.add(section).mul(fade);\n  material.colorNode = mix(u.cellColor, u.sectionColor, min(1, u.sectionThickness.mul(section)));\n  material.opacityNode = mix(alpha.mul(0.75), alpha, section);\n  // Discard where there is no line, as the WebGL kit's shader does.\n  material.alphaTest = 1e-4;\n  return material;\n};\n\n/** Writes a node's settings into the uniforms and material. */\nconst writeUniforms = (\n  u: Uniforms,\n  material: MeshBasicNodeMaterial,\n  node: ShaderGridNode,\n): void => {\n  u.cellSize.value = node.cellSize;\n  u.cellThickness.value = node.cellThickness;\n  u.cellColor.value.setHex(node.cellColor);\n  u.sectionSize.value = node.sectionSize;\n  u.sectionThickness.value = node.sectionThickness;\n  u.sectionColor.value.setHex(node.sectionColor);\n  u.fadeDistance.value = node.fadeDistance;\n  u.fadeStrength.value = node.fadeStrength;\n  u.fadeFrom.value = node.fadeFrom;\n  u.infinite.value = node.infinite ? 1 : 0;\n  u.followCamera.value = node.followCamera ? 1 : 0;\n  material.side = sides[node.side];\n};\n\nconst up = new Vector3(0, 1, 0);\nconst origin = new Vector3();\nconst plane = new Plane();\nconst cameraPosition = new Vector3();\n\n/** The WebGPU kit's shader grid: a plane with the grid material, placed and updated. */\nexport const hostShaderGrid = (node: ShaderGridNode): HostedShaderGrid => {\n  const u = createUniforms();\n  const material = gridMaterial(u);\n  writeUniforms(u, material, node);\n  const mesh = new Mesh(new PlaneGeometry(...node.size), material);\n  // The shader moves vertices (infinite, following): the plane's own bounds mean nothing.\n  mesh.frustumCulled = false;\n  const place = (next: ShaderGridNode): void => {\n    mesh.position.fromArray(next.position);\n    mesh.rotation.fromArray([...next.rotation]);\n  };\n  place(node);\n  mesh.onBeforeRender = (_renderer, _scene, camera) => {\n    plane.setFromNormalAndCoplanarPoint(up, origin).applyMatrix4(mesh.matrixWorld);\n    plane.projectPoint(\n      cameraPosition.setFromMatrixPosition(camera.matrixWorld),\n      u.cameraOnPlane.value,\n    );\n    u.planeOrigin.value.set(0, 0, 0).applyMatrix4(mesh.matrixWorld);\n  };\n  return {\n    object: mesh,\n    update: (previous, next) => {\n      if (previous.size[0] !== next.size[0] || previous.size[1] !== next.size[1]) {\n        mesh.geometry.dispose();\n        mesh.geometry = new PlaneGeometry(...next.size);\n      }\n      writeUniforms(u, material, next);\n      place(next);\n    },\n    dispose: () => {\n      mesh.geometry.dispose();\n      material.dispose();\n    },\n  };\n};\n",
     "/**\n * The WebGPU kit's sky: three.js's `SkyMesh` (`addons/objects/SkyMesh.js` at 0.186.1), the\n * same Preetham sky as the WebGL kit's `Sky`, written in TSL. Never picked.\n *\n * @module\n */\nimport { SkyMesh } from 'three/addons/objects/SkyMesh.js';\n\nimport type { Sky } from '../kernel/description.ts';\nimport type { HostedSky } from '../kernel/renderKit.ts';\n\n/** Writes a sky's description into the mesh's uniforms and scale. */\nconst writeSky = (mesh: SkyMesh, description: Sky): void => {\n  mesh.turbidity.value = description.turbidity;\n  mesh.rayleigh.value = description.rayleigh;\n  mesh.mieCoefficient.value = description.mieCoefficient;\n  mesh.mieDirectionalG.value = description.mieDirectionalG;\n  mesh.cloudCoverage.value = description.clouds;\n  mesh.sunPosition.value.fromArray(description.sunPosition);\n  mesh.scale.setScalar(description.distance);\n};\n\n/** Creates the sky mesh; the scene graph adds it and writes its description. */\nexport const hostSky = (): HostedSky => {\n  const mesh = new SkyMesh();\n  mesh.raycast = () => undefined;\n  return {\n    object: mesh,\n    update: (description) => writeSky(mesh, description),\n    dispose: () => {\n      mesh.geometry.dispose();\n      mesh.material.dispose();\n    },\n  };\n};\n",
-    "/**\n * The WebGPU render kit: the scene's shaded parts (the sky, the shader grid, contact\n * shadows) written in TSL, for three.js's `WebGPURenderer` on either of its backends.\n * The Foldkit adapter's `webgpuRendererFactory` carries it.\n *\n * @module\n */\nimport type { RenderKit } from '../kernel/renderKit.ts';\nimport { createContactShadows } from './contactShadows.ts';\nimport { hostShaderGrid } from './shaderGrid.ts';\nimport { hostSky } from './sky.ts';\n\nexport const webgpuKit: RenderKit = {\n  // troika's labels are WebGL materials; real WebGPU rejects their draw calls.\n  drawsLabels: false,\n  sky: hostSky,\n  shaderGrid: hostShaderGrid,\n  contactShadows: createContactShadows,\n};\n"
+    "/**\n * The WebGPU render kit: the scene's shaded parts (the sky, the shader grid, contact\n * shadows) written in TSL, for three.js's `WebGPURenderer` on either of its backends.\n * The Foldkit adapter's `webgpuRendererFactory` carries it.\n *\n * @module\n */\nimport type { RenderKit } from '../kernel/renderKit.ts';\nimport { createContactShadows } from './contactShadows.ts';\nimport { hostShaderGrid } from './shaderGrid.ts';\nimport { hostSky } from './sky.ts';\n\nexport const webgpuKit: RenderKit = {\n  // Node materials: label engines draw with their TSL implementation (`createTsl`).\n  shading: 'tsl',\n  sky: hostSky,\n  shaderGrid: hostShaderGrid,\n  contactShadows: createContactShadows,\n};\n"
   ],
-  "mappings": "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",
-  "debugId": "A69C3B6B3C01FA2F64756E2164756E21",
+  "mappings": "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",
+  "debugId": "3D261B4594F0512A64756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsydyn/effect-three",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Effect-native declarative Three.js scenes: scoped resources, keyed reconciliation, testable frame loop.",
   "license": "MIT",
   "repository": {

package/src/kernel/behaviours.ts

@@ -21,6 +21,11 @@ export const writeRotation = (target: Euler, rotation: Rotation, elapsedSeconds:
     target.set(rotation.euler[0], rotation.euler[1], rotation.euler[2]);
     return;
   }
+  // The scene graph turns a billboard towards the camera each frame; until then, none.
+  if (rotation._tag === 'Billboard') {
+    target.set(0, 0, 0);
+    return;
+  }
   const angle = spinAngle(rotation, elapsedSeconds);
   switch (rotation.axis) {
     case 'x':

package/src/kernel/bodySources.ts

@@ -87,7 +87,7 @@ const scaleText = (from: Matrix4): string =>
     .join(',');
 
 const rotationText = (rotation: Rotation): string =>
-  rotation._tag === 'Fixed' ? rotation.euler.join(',') : 'spin';
+  rotation._tag === 'Fixed' ? rotation.euler.join(',') : rotation._tag;
 
 /** A world pose written to an object in its parent's space, keeping its scale. */
 export const placeObject = (object: Object3D, pose: BodyPose): void => {

package/src/kernel/build.ts

@@ -6,6 +6,8 @@
 import type {
   AmbientLightNode,
   Animation,
+  CameraShake,
+  Detail,
   BasicMaterial,
   Body,
   Behave,
@@ -40,6 +42,8 @@ import type {
   ColliderDescription,
   ColliderShapeDescription,
   CapsuleGeometry,
+  RoundedBoxGeometry,
+  BackdropGeometry,
   CircleGeometry,
   ConeGeometry,
   CylinderGeometry,
@@ -106,6 +110,21 @@ export const spin = (options: {
   phase: options.phase ?? 0,
 });
 
+/**
+ * Faces the camera every frame, as Drei's `Billboard` (`bf6f4ad`, `src/core/Billboard.tsx`):
+ * for labels, markers and sprites that should always read face on. Lock an axis to keep
+ * it still, `lockX` and `lockZ` together for something that stays upright and only turns
+ * round. To rotate it as well, put it in a rotated group.
+ */
+export const billboard = (
+  options: { readonly lockX?: boolean; readonly lockY?: boolean; readonly lockZ?: boolean } = {},
+): Rotation => ({
+  _tag: 'Billboard',
+  lockX: options.lockX ?? false,
+  lockY: options.lockY ?? false,
+  lockZ: options.lockZ ?? false,
+});
+
 /** Box geometry. Each dimension defaults to 1. */
 export const box = (
   size: { readonly width?: number; readonly height?: number; readonly depth?: number } = {},
@@ -197,6 +216,47 @@ export const capsule = (
   radialSegments: options.radialSegments ?? 8,
 });
 
+/**
+ * A box with rounded edges and corners, as Drei's `RoundedBox` (`bf6f4ad`,
+ * `src/core/RoundedBox.tsx`), with its defaults: 1 × 1 × 1, radius 0.05, smoothness 4,
+ * 4 bevel segments, 1 step, crease angle 0.4.
+ */
+export const roundedBox = (
+  options: {
+    readonly width?: number;
+    readonly height?: number;
+    readonly depth?: number;
+    readonly radius?: number;
+    readonly smoothness?: number;
+    readonly bevelSegments?: number;
+    readonly steps?: number;
+    readonly creaseAngle?: number;
+  } = {},
+): RoundedBoxGeometry => ({
+  _tag: 'RoundedBox',
+  width: options.width ?? 1,
+  height: options.height ?? 1,
+  depth: options.depth ?? 1,
+  radius: options.radius ?? 0.05,
+  smoothness: options.smoothness ?? 4,
+  bevelSegments: options.bevelSegments ?? 4,
+  steps: options.steps ?? 1,
+  creaseAngle: options.creaseAngle ?? 0.4,
+});
+
+/**
+ * A curved photo backdrop, as Drei's `Backdrop` (`bf6f4ad`, `src/core/Backdrop.tsx`), with
+ * its defaults: floor 0.25, 20 segments. One unit each way: scale the mesh to size, and
+ * give it `receiveShadow` to catch shadows as Drei's prop does.
+ */
+export const backdrop = (
+  options: { readonly floor?: number; readonly segments?: number } = {},
+): BackdropGeometry => ({
+  _tag: 'Backdrop',
+  floor: options.floor ?? 0.25,
+  segments: options.segments ?? 20,
+});
+
 /** Ring geometry facing +Z. Defaults (as three.js): radii 0.5 and 1, 32 segments. */
 export const ring = (
   options: {
@@ -478,6 +538,7 @@ export const group = (
     readonly children?: ReadonlyArray<SceneNode>;
     readonly body?: Body | null;
     readonly follow?: XrSpace | null;
+    readonly detail?: Detail | null;
   },
 ): GroupNode => ({
   _tag: 'Group',
@@ -491,8 +552,20 @@ export const group = (
   children: options.children ?? [],
   body: options.body ?? null,
   follow: options.follow ?? null,
+  detail: options.detail ?? null,
 });
 
+/**
+ * Levels of detail for a group, as Drei's `Detailed` (`bf6f4ad`, `src/core/Detailed.tsx`):
+ * `group({ detail: detailed({ distances: [0, 10, 20] }), children: [near, middle, far] })`
+ * shows `near` until the camera is 10 away, then `middle`, then `far` from 20. Hysteresis
+ * defaults to 0, as Drei's.
+ */
+export const detailed = (options: {
+  readonly distances: ReadonlyArray<number>;
+  readonly hysteresis?: number;
+}): Detail => ({ distances: options.distances, hysteresis: options.hysteresis ?? 0 });
+
 /** The head (the viewer), for content that stays in view. */
 export const headSpace = (): XrSpace => ({ _tag: 'Head' });
 
@@ -859,6 +932,8 @@ export const borrowed = (
     readonly interactive?: boolean;
     readonly animation?: Animation | null;
     readonly body?: Body | null;
+    readonly castShadow?: boolean;
+    readonly receiveShadow?: boolean;
   },
 ): BorrowedNode => ({
   _tag: 'Borrowed',
@@ -872,6 +947,8 @@ export const borrowed = (
   behaviour: options.behaviour ?? null,
   interactive: options.interactive ?? false,
   body: options.body ?? null,
+  castShadow: options.castShadow ?? false,
+  receiveShadow: options.receiveShadow ?? false,
 });
 
 /**
@@ -1060,6 +1137,7 @@ export const perspectiveCamera = (
   lookAt: options.lookAt ?? origin,
   damping: options.damping ?? 0,
   autoRotate: options.autoRotate ?? 0,
+  shake: options.shake ?? null,
 });
 
 /**
@@ -1077,6 +1155,26 @@ export const orthographicCamera = (
   lookAt: options.lookAt ?? origin,
   damping: options.damping ?? 0,
   autoRotate: options.autoRotate ?? 0,
+  shake: options.shake ?? null,
+});
+
+/**
+ * Camera shake, as Drei's `CameraShake` (`bf6f4ad`, `src/core/CameraShake.tsx`), with its
+ * defaults: intensity 1, no decay (rate 0.65 a second when on), and 0.1 radians at 0.1 for
+ * each of yaw, pitch and roll. `perspectiveCamera({ shake: cameraShake({ decay: true }) })`
+ * shakes once and settles; bump `trigger` to shake again.
+ */
+export const cameraShake = (options: Partial<CameraShake> = {}): CameraShake => ({
+  intensity: options.intensity ?? 1,
+  decay: options.decay ?? false,
+  decayRate: options.decayRate ?? 0.65,
+  maxYaw: options.maxYaw ?? 0.1,
+  maxPitch: options.maxPitch ?? 0.1,
+  maxRoll: options.maxRoll ?? 0.1,
+  yawFrequency: options.yawFrequency ?? 0.1,
+  pitchFrequency: options.pitchFrequency ?? 0.1,
+  rollFrequency: options.rollFrequency ?? 0.1,
+  trigger: options.trigger ?? 0,
 });
 
 const noEffects: ReadonlyArray<PostEffect> = [];

package/src/kernel/cameraMotion.ts

@@ -94,6 +94,8 @@ export type CameraMotion = {
   readonly hold: (held: boolean) => void;
   /** Where turning has taken the camera, when it has turned since its description. */
   readonly turned: () => Vec3 | undefined;
+  /** The point the camera looks at now, on its way to the aim. Not to be changed. */
+  readonly target: () => Vector3;
 };
 
 /** Radians a turning camera turns per second per unit of `autoRotate` (three's `2π / 60`). */
@@ -198,5 +200,6 @@ export const createCameraMotion = (): CameraMotion => {
       position.setFromSpherical(goal.spherical).add(goal.target);
       return [position.x, position.y, position.z];
     },
+    target: () => current.target,
   };
 };

package/src/kernel/cameraShake.ts

@@ -0,0 +1,97 @@
+/**
+ * Camera shake, as Drei's `CameraShake` (`bf6f4ad`, `src/core/CameraShake.tsx`): yaw, pitch
+ * and roll added to the camera's rotation from simplex noise, scaled by the square of the
+ * intensity. Here it is a pure function of scene time: the noise is seeded (Drei seeds
+ * from `Math.random`), and decay counts down from when the shake began, so the same scene
+ * time always shakes the same way, at any frame rate. Reduced motion holds it still.
+ *
+ * The camera always looks at its target here, so each frame it is aimed there again and
+ * the shake added on top: whatever moved the camera in between, nothing accumulates.
+ *
+ * @module
+ */
+import type { OrthographicCamera, PerspectiveCamera, Vector3 } from 'three';
+import { SimplexNoise } from 'three/addons/math/SimplexNoise.js';
+
+import type { CameraShake } from './description.ts';
+import { cameraShakeEquals } from './equality.ts';
+
+/** A small seeded generator (mulberry32), so the noise is the same on every page load. */
+const seeded = (seed: number): { readonly random: () => number } => {
+  let state = seed >>> 0;
+  return {
+    random: () => {
+      state = (state + 0x6d2b79f5) >>> 0;
+      let t = state;
+      t = Math.imul(t ^ (t >>> 15), t | 1);
+      t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    },
+  };
+};
+
+const yawNoise = new SimplexNoise(seeded(1));
+const pitchNoise = new SimplexNoise(seeded(2));
+const rollNoise = new SimplexNoise(seeded(3));
+
+/** The intensity at `seconds` after the shake began: Drei's, clamped to [0, 1], decaying. */
+export const shakeIntensity = (shake: CameraShake, seconds: number): number => {
+  const decayed = shake.decay ? shake.intensity - shake.decayRate * seconds : shake.intensity;
+  return Math.min(1, Math.max(0, decayed));
+};
+
+export type CameraShaker = {
+  /**
+   * The camera's shake as described at scene time `now`: one that first appears, changes
+   * or is triggered again begins then.
+   */
+  readonly describe: (shake: CameraShake | null, now: number) => void;
+  /**
+   * Aims the camera at `target` and adds the shake at scene time `now`, or only aims it
+   * when the shake has ended or motion is reduced. Does nothing when nothing was added.
+   */
+  readonly apply: (
+    camera: PerspectiveCamera | OrthographicCamera,
+    target: Vector3,
+    now: number,
+    animating: boolean,
+  ) => void;
+  /** Whether the camera is shaking at scene time `now`, and so needs frames. */
+  readonly shaking: (now: number) => boolean;
+};
+
+/** One camera's shake. Allocation-free once created. */
+export const createCameraShaker = (): CameraShaker => {
+  let current: CameraShake | null = null;
+  let since = 0;
+  // Whether the camera wears an offset that a still frame must take off again.
+  let offset = false;
+
+  return {
+    describe: (shake, now) => {
+      if (shake !== null && (current === null || !cameraShakeEquals(current, shake))) since = now;
+      current = shake;
+    },
+    apply: (camera, target, now, animating) => {
+      const shake = current;
+      const strength =
+        shake === null || !animating ? 0 : shakeIntensity(shake, Math.max(0, now - since)) ** 2;
+      if (shake === null || strength === 0) {
+        if (offset) camera.lookAt(target);
+        offset = false;
+        return;
+      }
+      camera.lookAt(target);
+      camera.rotation.set(
+        camera.rotation.x +
+          shake.maxPitch * strength * pitchNoise.noise(now * shake.pitchFrequency, 1),
+        camera.rotation.y + shake.maxYaw * strength * yawNoise.noise(now * shake.yawFrequency, 1),
+        camera.rotation.z +
+          shake.maxRoll * strength * rollNoise.noise(now * shake.rollFrequency, 1),
+      );
+      offset = true;
+    },
+    shaking: (now) =>
+      offset || (current !== null && shakeIntensity(current, Math.max(0, now - since)) > 0),
+  };
+};

package/src/kernel/description.ts

@@ -30,6 +30,17 @@ export type Rotation =
       readonly axis: Axis;
       readonly radiansPerSecond: number;
       readonly phase: number;
+    }
+  /**
+   * Faces the scene's camera every frame, as Drei's `Billboard`: the node turns so its
+   * world rotation is the camera's. A locked axis stays at 0 in the node's own Euler
+   * angles (Drei keeps its previous value, which starts at 0).
+   */
+  | {
+      readonly _tag: 'Billboard';
+      readonly lockX: boolean;
+      readonly lockY: boolean;
+      readonly lockZ: boolean;
     };
 
 /** Box geometry parameters. */
@@ -90,6 +101,36 @@ export type CapsuleGeometry = {
   readonly radialSegments: number;
 };
 
+/**
+ * A box with rounded edges and corners, centred, as Drei's `RoundedBox`: a rounded
+ * rectangle extruded and bevelled, with normals creased at `creaseAngle`.
+ */
+export type RoundedBoxGeometry = {
+  readonly _tag: 'RoundedBox';
+  readonly width: number;
+  readonly height: number;
+  readonly depth: number;
+  readonly radius: number;
+  /** Segments in each rounded corner of the outline. */
+  readonly smoothness: number;
+  /** Segments across the bevel, which Drei doubles. */
+  readonly bevelSegments: number;
+  readonly steps: number;
+  /** Faces meeting at more than this angle (radians) keep a hard edge. */
+  readonly creaseAngle: number;
+};
+
+/**
+ * A photo backdrop, as Drei's `Backdrop`: a floor that sweeps up into a wall behind it,
+ * one unit each way (scale it to size). The floor lies along +Z towards the viewer, the
+ * wall rises at its back, and `floor` extends the flat front.
+ */
+export type BackdropGeometry = {
+  readonly _tag: 'Backdrop';
+  readonly floor: number;
+  readonly segments: number;
+};
+
 /** A flat ring (annulus) in the XY plane, facing +Z. */
 export type RingGeometry = {
   readonly _tag: 'Ring';
@@ -150,7 +191,9 @@ export type ShapeGeometry =
   | ConeGeometry
   | CapsuleGeometry
   | RingGeometry
-  | CircleGeometry;
+  | CircleGeometry
+  | RoundedBoxGeometry
+  | BackdropGeometry;
 
 /** Which faces a material draws. */
 export type MaterialSide = 'front' | 'back' | 'double';
@@ -342,6 +385,22 @@ export type GroupNode = {
    * not tracked (or no session presents). `null` for the group's own transform.
    */
   readonly follow: XrSpace | null;
+  /**
+   * Levels of detail: the group shows one child at a time, chosen by the camera's
+   * distance (Drei's `Detailed`, three's `LOD`), or `null` to show them all.
+   */
+  readonly detail: Detail | null;
+};
+
+/**
+ * Levels of detail for a group's children, in order: child `i` shows from
+ * `distances[i]` (scene units from the camera, divided by its zoom) until the next level's
+ * distance. `hysteresis` (a fraction) keeps a shown level until the camera is that much
+ * nearer than its distance, so the switch does not flicker at the boundary.
+ */
+export type Detail = {
+  readonly distances: ReadonlyArray<number>;
+  readonly hysteresis: number;
 };
 
 /** The joints of a tracked hand, as WebXR names them (`XRHandJoint`). */
@@ -656,6 +715,13 @@ export type BorrowedNode = {
   readonly animation: Animation | null;
   /** A rigid body whose colliders are the model's meshes, once it is lent; or `null`. */
   readonly body: Body | null;
+  /**
+   * Every mesh in what it shows casts (receives) shadows, as Drei's `Clone` shorthands;
+   * `false` leaves each mesh's own setting. Set on the lent object itself where it is
+   * shown as lent rather than cloned.
+   */
+  readonly castShadow: boolean;
+  readonly receiveShadow: boolean;
 };
 
 /** Where a label's origin is along its width: an edge, the middle, or a fraction of it. */
@@ -902,6 +968,8 @@ export type PerspectiveCamera = {
    * (`autoRotated(camera, detail)`). A new position or `lookAt` turns on from there.
    */
   readonly autoRotate: number;
+  /** Shakes the rendered camera (Drei's `CameraShake`), or `null` for none. */
+  readonly shake: CameraShake | null;
 };
 
 /**
@@ -919,6 +987,28 @@ export type OrthographicCamera = {
   readonly damping: number;
   /** As on `PerspectiveCamera`. */
   readonly autoRotate: number;
+  /** As on `PerspectiveCamera`. */
+  readonly shake: CameraShake | null;
+};
+
+/**
+ * Camera shake, as Drei's `CameraShake`: yaw, pitch and roll of up to `max*` radians,
+ * from noise at `*Frequency`, scaled by `intensity` squared (0 to 1). With `decay` the
+ * intensity falls by `decayRate` a second from when the shake began, so a decaying shake
+ * is a one-off: it begins when it first appears or changes, and `trigger` (a count the
+ * Model bumps) begins the same shake again. Reduced motion holds the camera still.
+ */
+export type CameraShake = {
+  readonly intensity: number;
+  readonly decay: boolean;
+  readonly decayRate: number;
+  readonly maxYaw: number;
+  readonly maxPitch: number;
+  readonly maxRoll: number;
+  readonly yawFrequency: number;
+  readonly pitchFrequency: number;
+  readonly rollFrequency: number;
+  readonly trigger: number;
 };
 
 /** The single active camera. */

package/src/kernel/diff.ts

@@ -31,6 +31,7 @@ import {
   labelMaterialEquals,
   labelTypeEquals,
   xrSpaceEquals,
+  detailEquals,
   shaderGridLookEquals,
   instancesEqual,
   materialRefEquals,
@@ -82,7 +83,9 @@ export type Field =
   /** A shader grid's look: anything but where it is. */
   | 'grid'
   /** The tracked space a group follows. */
-  | 'follow';
+  | 'follow'
+  /** A group's levels of detail. */
+  | 'detail';
 
 /** A single change to apply to the hosted scene graph. */
 export type Op =
@@ -131,6 +134,7 @@ export const changedFields = (
       if (prev.interactive !== next.interactive) fields.push('interactive');
       if (!bodyEquals(prev.body, next.body)) fields.push('body');
       if (!xrSpaceEquals(prev.follow, next.follow)) fields.push('follow');
+      if (!detailEquals(prev.detail, next.detail)) fields.push('detail');
       return fields;
     }
     case 'Mesh': {
@@ -175,6 +179,8 @@ export const changedFields = (
       if (!animationEquals(prev.animation, next.animation)) fields.push('animation');
       if (prev.interactive !== next.interactive) fields.push('interactive');
       if (!bodyEquals(prev.body, next.body)) fields.push('body');
+      if (prev.castShadow !== next.castShadow) fields.push('castShadow');
+      if (prev.receiveShadow !== next.receiveShadow) fields.push('receiveShadow');
       return fields;
     }
     case 'Label': {

package/src/kernel/equality.ts

@@ -7,6 +7,8 @@
 import type {
   Animation,
   Behave,
+  CameraShake,
+  Detail,
   Body,
   BodyRef,
   GeometryRef,
@@ -46,6 +48,17 @@ import type {
 export const vec3Equals = (a: Vec3, b: Vec3): boolean =>
   a === b || (Object.is(a[0], b[0]) && Object.is(a[1], b[1]) && Object.is(a[2], b[2]));
 
+/** Levels-of-detail equality: the same distances and hysteresis. */
+export const detailEquals = (a: Detail | null, b: Detail | null): boolean => {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  return (
+    Object.is(a.hysteresis, b.hysteresis) &&
+    a.distances.length === b.distances.length &&
+    a.distances.every((distance, index) => Object.is(distance, b.distances[index]))
+  );
+};
+
 /** Rotation equality, including behaviour parameters. */
 export const rotationEquals = (a: Rotation, b: Rotation): boolean => {
   if (a === b) return true;
@@ -57,6 +70,9 @@ export const rotationEquals = (a: Rotation, b: Rotation): boolean => {
       Object.is(a.phase, b.phase)
     );
   }
+  if (a._tag === 'Billboard' && b._tag === 'Billboard') {
+    return a.lockX === b.lockX && a.lockY === b.lockY && a.lockZ === b.lockZ;
+  }
   return false;
 };
 
@@ -120,6 +136,20 @@ export const shapeEquals = (a: ShapeGeometry, b: ShapeGeometry): boolean => {
       );
     case 'Circle':
       return b._tag === 'Circle' && Object.is(a.radius, b.radius) && a.segments === b.segments;
+    case 'RoundedBox':
+      return (
+        b._tag === 'RoundedBox' &&
+        Object.is(a.width, b.width) &&
+        Object.is(a.height, b.height) &&
+        Object.is(a.depth, b.depth) &&
+        Object.is(a.radius, b.radius) &&
+        a.smoothness === b.smoothness &&
+        a.bevelSegments === b.bevelSegments &&
+        a.steps === b.steps &&
+        Object.is(a.creaseAngle, b.creaseAngle)
+      );
+    case 'Backdrop':
+      return b._tag === 'Backdrop' && Object.is(a.floor, b.floor) && a.segments === b.segments;
     case 'Text':
       return (
         b._tag === 'Text' &&
@@ -223,6 +253,22 @@ export const materialRefEquals = (a: MaterialRef, b: MaterialRef): boolean => {
 };
 
 /** Camera equality: same kind, same lens and same placement. */
+/** Camera shake equality: every setting, and the trigger count. */
+export const cameraShakeEquals = (a: CameraShake | null, b: CameraShake | null): boolean =>
+  a === b ||
+  (a !== null &&
+    b !== null &&
+    Object.is(a.intensity, b.intensity) &&
+    a.decay === b.decay &&
+    Object.is(a.decayRate, b.decayRate) &&
+    Object.is(a.maxYaw, b.maxYaw) &&
+    Object.is(a.maxPitch, b.maxPitch) &&
+    Object.is(a.maxRoll, b.maxRoll) &&
+    Object.is(a.yawFrequency, b.yawFrequency) &&
+    Object.is(a.pitchFrequency, b.pitchFrequency) &&
+    Object.is(a.rollFrequency, b.rollFrequency) &&
+    Object.is(a.trigger, b.trigger));
+
 export const cameraEquals = (a: Camera, b: Camera): boolean => {
   if (a === b) return true;
   const sameLens =
@@ -234,6 +280,7 @@ export const cameraEquals = (a: Camera, b: Camera): boolean => {
     Object.is(a.far, b.far) &&
     Object.is(a.damping, b.damping) &&
     Object.is(a.autoRotate, b.autoRotate) &&
+    cameraShakeEquals(a.shake, b.shake) &&
     vec3Equals(a.position, b.position) &&
     vec3Equals(a.lookAt, b.lookAt)
   );

package/src/kernel/index.ts

@@ -96,12 +96,17 @@ export {
   pointLight,
   renderSettings,
   ring,
+  roundedBox,
+  backdrop,
   scene,
   sharedGeometry,
   lentGeometry,
   sharedMaterial,
   sphere,
   spin,
+  cameraShake,
+  detailed,
+  billboard,
   spotLight,
   standard,
   overlay,

package/src/kernel/labels.ts

@@ -44,5 +44,11 @@ export type HostedLabel = {
  * and glyphs build in the background), so the scene can draw again.
  */
 export type LabelEngine = {
+  /** A label drawn with WebGL's own materials, for a `'webgl'` render kit. */
   readonly create: (label: LabelNode, ready: () => void) => HostedLabel;
+  /**
+   * A label drawn with three's node materials (TSL), for a `'tsl'` render kit such as
+   * `WebGPURenderer`'s. Without it, those renderers draw no labels.
+   */
+  readonly createTsl?: (label: LabelNode, ready: () => void) => HostedLabel;
 };