@opsydyn/effect-three 0.2.0 → 0.4.0

package/src/kernel/sceneGraph.ts

@@ -21,20 +21,25 @@ import {
   OrthographicCamera,
   PerspectiveCamera,
   PointLight,
+  Quaternion,
   Scene,
   SpotLight,
   Vector3,
 } from 'three';
+import { clone as cloneSkinned } from 'three/addons/utils/SkeletonUtils.js';
 
 import { clipRunning, clipTime } from './animation.ts';
 import { writeRotation } from './behaviours.ts';
 import { type BodyCollision, type BodyContactForce, createBodyHost } from './bodies.ts';
 import { type BodySource, instanceSources, nodeSource, placeObject } from './bodySources.ts';
-import { renderSettings, scene as describeScene } from './build.ts';
+import { orthographicCamera, renderSettings, scene as describeScene } from './build.ts';
 import { type CameraMotion, createCameraMotion } from './cameraMotion.ts';
+import { type CameraShaker, createCameraShaker } from './cameraShake.ts';
 import type {
+  Hud,
   AmbientLightNode,
   BorrowedNode,
+  Edges,
   DirectionalLightNode,
   GridNode,
   HemisphereLightNode,
@@ -42,6 +47,8 @@ import type {
   Instance,
   InstancesNode,
   LabelNode,
+  LineNode,
+  PointsNode,
   MaterialRef,
   ShaderGridNode,
   MeshNode,
@@ -65,9 +72,16 @@ import type {
   ViewRect,
 } from './description.ts';
 import { diff, type Field, type Op } from './diff.ts';
-import { contactShadowsEquals, environmentEquals, overlaysEqual, skyEquals } from './equality.ts';
+import {
+  contactShadowsEquals,
+  edgesEquals,
+  environmentEquals,
+  overlaysEqual,
+  skyEquals,
+} from './equality.ts';
 import { createInstances, fits, type HostInstances, writeInstances } from './instances.ts';
 import type { HostedLabel, LabelEngine, LabelLayout } from './labels.ts';
+import { edgeLine, edgePoints } from './lineGeometry.ts';
 import type { HostMaterial } from './materials.ts';
 import {
   type Behaviour,
@@ -77,7 +91,14 @@ import {
   resetPose,
 } from './motion.ts';
 import type { BodyPose, PhysicsEngine } from './physics.ts';
-import type { HostedShaderGrid, HostedSky, RenderKit } from './renderKit.ts';
+import { animatedLook } from './pointBuffers.ts';
+import type {
+  HostedLine,
+  HostedPoints,
+  HostedShaderGrid,
+  HostedSky,
+  RenderKit,
+} from './renderKit.ts';
 import { createResourceStore, type ResourceStore } from './resources.ts';
 import {
   type DescriptionError,
@@ -86,6 +107,7 @@ import {
   type ParentKey,
   type SceneIndex,
 } from './sceneIndex.ts';
+import { createTrailRibbon, type TrailRibbon } from './trail.ts';
 import { applyTween, startTween, type Tween } from './tween.ts';
 
 /** The mesh type the kernel hosts. */
@@ -139,6 +161,20 @@ type Entry =
       readonly _tag: 'HemisphereLight';
       node: HemisphereLightNode;
       readonly object: HemisphereLight;
+    }
+  // `hosted` is the points the render kit drew, inside the wrapper; none without a kit.
+  | {
+      readonly _tag: 'Points';
+      node: PointsNode;
+      readonly object: Group;
+      readonly hosted: HostedPoints | undefined;
+    }
+  // `hosted` is the line the render kit drew, inside the wrapper; none without a kit.
+  | {
+      readonly _tag: 'Line';
+      node: LineNode;
+      readonly object: Group;
+      readonly hosted: HostedLine | undefined;
     };
 
 /** Entries with a transform: position, rotation, scale and transitions. */
@@ -151,12 +187,26 @@ type Player = {
   readonly startedAt: number;
 };
 
+/** A mesh's edge lines: the kit's line, and the geometry and look it was built from. */
+type EdgeLines = {
+  readonly hosted: HostedLine;
+  geometry: BufferGeometry | undefined;
+  edges: Edges | undefined;
+};
+
 /** Descriptions with a transform. */
-type PlacedNode = GroupNode | MeshNode | InstancesNode | BorrowedNode | LabelNode;
+type PlacedNode =
+  | GroupNode
+  | MeshNode
+  | InstancesNode
+  | BorrowedNode
+  | LabelNode
+  | LineNode
+  | PointsNode;
 
 type Placed = Extract<
   Entry,
-  { readonly _tag: 'Group' | 'Mesh' | 'Instances' | 'Borrowed' | 'Label' }
+  { readonly _tag: 'Group' | 'Mesh' | 'Instances' | 'Borrowed' | 'Label' | 'Line' | 'Points' }
 >;
 
 /** Entries drawing a geometry with a material. */
@@ -167,12 +217,17 @@ const isPlaced = (entry: Entry): entry is Placed =>
   entry._tag === 'Mesh' ||
   entry._tag === 'Instances' ||
   entry._tag === 'Borrowed' ||
-  entry._tag === 'Label';
+  entry._tag === 'Label' ||
+  entry._tag === 'Line' ||
+  entry._tag === 'Points';
 
 const isSurfaced = (entry: Entry): entry is Surfaced =>
   entry._tag === 'Mesh' || entry._tag === 'Instances';
 
 /** A render texture as hosted: its id, size and the nested graph that draws it. */
+/** The HUD as hosted: its nested graph, drawn over the scene by the frame loop. */
+export type HostedHud = { readonly graph: SceneGraph };
+
 export type HostedTexture = {
   readonly id: string;
   readonly graph: SceneGraph;
@@ -229,6 +284,8 @@ export type SceneGraph = {
   readonly turned: (view: string | undefined) => Vec3 | undefined;
   /** Render textures, each a nested graph to draw into its texture (by the frame loop). */
   readonly renderTextures: () => ReadonlyArray<HostedTexture>;
+  /** The HUD, a nested graph drawn over the scene (by the frame loop), if there is one. */
+  readonly hud: () => HostedHud | undefined;
   /** Whether the scene claims the pointer's gestures from the page. */
   readonly gestures: () => Gestures;
   /** Points to show HTML at; the frame loop places them after drawing. */
@@ -426,6 +483,14 @@ const noInstances: ReadonlyArray<Instance> = [];
 const emptyScene = describeScene({});
 
 /** Creates an empty scene graph. */
+/**
+ * A copy of a lent object for a second place to show it, sharing its geometry and
+ * materials, as Drei's `Clone` (`bf6f4ad`, `src/core/Clone.tsx`): a skinned model through
+ * three's `SkeletonUtils.clone`, so that the copy has bones of its own to animate.
+ */
+const cloneLoan = (lent: Object3D): Object3D =>
+  lent.getObjectByProperty('isSkinnedMesh', true) === undefined ? lent.clone() : cloneSkinned(lent);
+
 export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph => {
   const store = options.store ?? createResourceStore();
   const ownsStore = options.store === undefined;
@@ -437,6 +502,9 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     { readonly graph: SceneGraph; description: RenderTexture }
   >();
   let textureList: ReadonlyArray<HostedTexture> = [];
+  let hudHosted:
+    | { readonly graph: SceneGraph; description: Hud; parent: SceneDescription }
+    | undefined;
   let viewDescriptions: ReadonlyArray<View> = [];
   let gestures: Gestures = emptyScene.gestures;
   let overlayList: ReadonlyArray<Overlay> = emptyScene.overlays;
@@ -470,8 +538,22 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     hostedSky = undefined;
   }
   const cameraMotion = createCameraMotion();
+  const cameraShaker = createCameraShaker();
   /** Each view's camera motion, by the view's key. */
   const viewMotions = new Map<string, CameraMotion>();
+  /** Each view's camera shake, by the view's key. */
+  const viewShakers = new Map<string, CameraShaker>();
+  const shaking = (): boolean => {
+    if (cameraShaker.shaking(elapsed)) return true;
+    for (const shaker of viewShakers.values()) if (shaker.shaking(elapsed)) return true;
+    return false;
+  };
+  /** Shakes a view's camera on top of where its motion aims it. */
+  const shakeView = (view: HostedView): void => {
+    const motion = viewMotions.get(view.key);
+    if (motion === undefined) return;
+    viewShakers.get(view.key)?.apply(view.camera, motion.target(), elapsed, animating);
+  };
   const viewsMoving = (): boolean => {
     for (const motion of viewMotions.values()) if (motion.moving()) return true;
     return false;
@@ -505,6 +587,9 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     applyLens(hostedCamera, description.camera);
     const motion = viewMotions.get(description.key) ?? createCameraMotion();
     viewMotions.set(description.key, motion);
+    const shaker = viewShakers.get(description.key) ?? createCameraShaker();
+    viewShakers.set(description.key, shaker);
+    shaker.describe(description.camera.shake, elapsed);
     // As the scene's camera: a new kind of camera has nothing on screen to travel from.
     motion.aim(hostedCamera, description.camera, elapsed, hostedCamera !== previous || !animating);
     const area = areaOf(description.rect);
@@ -520,10 +605,41 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     for (const key of viewMotions.keys()) {
       if (!described.some((description) => description.key === key)) viewMotions.delete(key);
     }
+    for (const key of viewShakers.keys()) {
+      if (!described.some((description) => description.key === key)) viewShakers.delete(key);
+    }
   };
   const entries = new Map<string, Entry>();
   const keys = new WeakMap<Object3D, string>();
   const spinning = new Set<Entry>();
+  // Billboards: turned towards the camera each frame, after everything else has moved.
+  const facing = new Set<Entry>();
+  const cameraTurn = new Quaternion();
+  const parentTurn = new Quaternion();
+  // Points that move by themselves (sparkles, stars), ticked in scene time while animating.
+  const sparkling = new Set<Entry>();
+  const trackSparkle = (entry: Entry, node: PointsNode): void => {
+    if (animatedLook(node.look)) sparkling.add(entry);
+    else sparkling.delete(entry);
+    if (entry._tag === 'Points') entry.hosted?.tick(animating ? elapsed : 0);
+  };
+  const sparkle = (entry: Entry): void => {
+    if (entry._tag === 'Points') entry.hosted?.tick(elapsed);
+  };
+  // Groups and meshes with trails: each ribbon, in the scene's space.
+  const trailing = new Map<Entry, TrailRibbon>();
+  const trailPlace = new Vector3();
+  const eye = new Vector3();
+  const trailsMoving = (): boolean => {
+    for (const ribbon of trailing.values()) if (!ribbon.settled()) return true;
+    return false;
+  };
+  // Meshes with edge lines: rebuilt when the mesh's geometry or the edges' look changes.
+  const edged = new Map<Entry, EdgeLines>();
+  // Groups with levels of detail: one child shown at a time, by the camera's distance.
+  const detailing = new Set<Entry>();
+  const cameraPlace = new Vector3();
+  const groupPlace = new Vector3();
   const playing = new Set<Borrowing>();
   const registry: Readonly<Record<string, Behaviour>> = {
     ...builtinBehaviours,
@@ -580,6 +696,152 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     writeRotation(entry.object.rotation, node.rotation, elapsed);
     if (node.rotation._tag === 'Spin') spinning.add(entry);
     else spinning.delete(entry);
+    if (node.rotation._tag === 'Billboard') facing.add(entry);
+    else facing.delete(entry);
+  };
+
+  /**
+   * Drei's `Billboard`: the node's rotation is its parent's world rotation undone, then the
+   * camera's, so its world rotation is the camera's; locked axes go back to 0.
+   */
+  const faceCamera = (entry: Entry): void => {
+    if (!isPlaced(entry) || entry.node.rotation._tag !== 'Billboard') return;
+    const { lockX, lockY, lockZ } = entry.node.rotation;
+    const object = entry.object;
+    parentTurn.identity();
+    object.parent?.getWorldQuaternion(parentTurn);
+    object.quaternion.copy(cameraTurn).premultiply(parentTurn.invert());
+    if (lockX) object.rotation.x = 0;
+    if (lockY) object.rotation.y = 0;
+    if (lockZ) object.rotation.z = 0;
+  };
+
+  /** Where a trail follows its node: the world position, or with `local` its own. */
+  const trailTarget = (object: Object3D, local: boolean): Vector3 =>
+    local ? trailPlace.copy(object.position) : object.getWorldPosition(trailPlace);
+
+  /** Adds, restyles or removes a node's trail as its description says. */
+  const trackTrail = (entry: Entry, node: GroupNode | MeshNode): void => {
+    const current = trailing.get(entry);
+    if (node.trail === null) {
+      if (current === undefined) return;
+      current.object.removeFromParent();
+      current.dispose();
+      trailing.delete(entry);
+      return;
+    }
+    const start = trailTarget(entry.object, node.trail.local);
+    if (current !== undefined) {
+      current.restyle(node.trail, start, elapsed);
+      return;
+    }
+    const ribbon = createTrailRibbon(node.trail, start, elapsed);
+    scene.add(ribbon.object);
+    trailing.set(entry, ribbon);
+  };
+
+  /** Records where a trailing node is now, and turns its ribbon to the camera. */
+  const followTrail = (ribbon: TrailRibbon, entry: Entry): void => {
+    if (entry._tag !== 'Group' && entry._tag !== 'Mesh') return;
+    if (entry.node.trail === null) return;
+    ribbon.record(trailTarget(entry.object, entry.node.trail.local), elapsed);
+    ribbon.face(eye);
+  };
+
+  /** Drei's `Edges` turns off picking on its line: hits belong to the mesh. */
+  const unpickable = (part: Object3D): void => {
+    part.raycast = () => undefined;
+  };
+
+  /** Adds, keeps or removes a mesh's edge lines as its description says. */
+  const trackEdges = (entry: Entry, node: MeshNode): void => {
+    const current = edged.get(entry);
+    const draw = options.kit?.line;
+    if (node.edges === null || draw === undefined) {
+      if (current === undefined) return;
+      current.hosted.object.removeFromParent();
+      current.hosted.dispose();
+      edged.delete(entry);
+      return;
+    }
+    if (current !== undefined) return;
+    const hosted = draw(edgeLine(node.key, node.edges, []));
+    entry.object.add(hosted.object);
+    edged.set(entry, { hosted, geometry: undefined, edges: undefined });
+  };
+
+  /**
+   * Builds the edge lines again when the mesh shows another geometry (its own changed, a
+   * shared one was replaced, a lent one arrived) or the edges' look changed.
+   */
+  const refreshEdges = (lines: EdgeLines, entry: Entry): void => {
+    if (entry._tag !== 'Mesh' || entry.node.edges === null) return;
+    const { geometry } = entry.object;
+    const look = entry.node.edges;
+    if (
+      geometry === lines.geometry &&
+      lines.edges !== undefined &&
+      edgesEquals(look, lines.edges)
+    ) {
+      return;
+    }
+    lines.hosted.update(edgeLine(entry.node.key, look, edgePoints(geometry, look.threshold)));
+    lines.hosted.object.traverse(unpickable);
+    lines.geometry = geometry;
+    lines.edges = look;
+  };
+
+  /** The object of a group's `index`th child, as described. */
+  const childObject = (node: GroupNode, index: number): Object3D | undefined => {
+    const child = node.children[index];
+    return child === undefined ? undefined : entries.get(child.key)?.object;
+  };
+
+  /**
+   * three's `LOD.update`, as Drei's `Detailed` runs it each frame, over the group's children
+   * in order: the first level shows, each later one takes over once the camera is at least
+   * its distance away (less its hysteresis while it shows), and the rest hide.
+   */
+  const showLevel = (entry: Entry): void => {
+    if (entry._tag !== 'Group') return;
+    const { node } = entry;
+    const { detail } = node;
+    if (detail === null) return;
+    const { distances, hysteresis } = detail;
+    const count = node.children.length;
+    if (count < 2) return;
+    entry.object.getWorldPosition(groupPlace);
+    const distance = cameraPlace.distanceTo(groupPlace) / camera.zoom;
+    const first = childObject(node, 0);
+    if (first !== undefined) first.visible = true;
+    let level = 1;
+    for (; level < count; level++) {
+      const object = childObject(node, level);
+      const from = distances[level] ?? Number.NaN;
+      const reach = object?.visible === true ? from - from * hysteresis : from;
+      if (!(distance >= reach)) break;
+      const previous = childObject(node, level - 1);
+      if (previous !== undefined) previous.visible = false;
+      if (object !== undefined) object.visible = true;
+    }
+    for (; level < count; level++) {
+      const object = childObject(node, level);
+      if (object !== undefined) object.visible = false;
+    }
+  };
+
+  const trackDetail = (entry: Entry, node: GroupNode): void => {
+    if (node.detail !== null) {
+      detailing.add(entry);
+      return;
+    }
+    // No longer levels: every child shows again.
+    if (detailing.delete(entry)) {
+      for (let index = 0; index < node.children.length; index++) {
+        const object = childObject(node, index);
+        if (object !== undefined) object.visible = true;
+      }
+    }
   };
 
   const build = (node: SceneNode): Entry => {
@@ -593,6 +855,8 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
         trackInteractive(entry.object, node.interactive);
         // A group following a tracked space shows only once the space is found.
         if (node.follow !== null) entry.object.visible = false;
+        trackDetail(entry, node);
+        trackTrail(entry, node);
         return entry;
       }
       case 'Mesh': {
@@ -608,6 +872,8 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
         trackInteractive(object, node.interactive);
         object.castShadow = node.castShadow;
         object.receiveShadow = node.receiveShadow;
+        trackEdges(entry, node);
+        trackTrail(entry, node);
         return entry;
       }
       case 'Instances': {
@@ -688,6 +954,28 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
         const hosted = options.kit?.shaderGrid(node);
         return { _tag: 'ShaderGrid', node, object: hosted?.object ?? new Group(), hosted };
       }
+      case 'Points': {
+        const hosted = options.kit?.points?.(node);
+        const entry: Entry = { _tag: 'Points', node, object: new Group(), hosted };
+        if (hosted !== undefined) entry.object.add(hosted.object);
+        writeVec3(entry.object.position, node.position);
+        writeVec3(entry.object.scale, node.scale);
+        trackRotation(entry, node);
+        trackBehaviour(entry, node);
+        trackSparkle(entry, node);
+        return entry;
+      }
+      case 'Line': {
+        const hosted = options.kit?.line?.(node);
+        const entry: Entry = { _tag: 'Line', node, object: new Group(), hosted };
+        if (hosted !== undefined) entry.object.add(hosted.object);
+        writeVec3(entry.object.position, node.position);
+        writeVec3(entry.object.scale, node.scale);
+        trackRotation(entry, node);
+        trackBehaviour(entry, node);
+        trackInteractive(entry.object, node.interactive);
+        return entry;
+      }
       case 'HemisphereLight': {
         const object = new HemisphereLight();
         writeHemisphereLight(object, node);
@@ -706,12 +994,22 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     entry.shown = undefined;
     const lent = store.lent(entry.node.id);
     if (lent === undefined) return;
-    const shown = lent.parent === null ? lent : lent.clone();
+    const shown = lent.parent === null ? lent : cloneLoan(lent);
     entry.object.add(shown);
     entry.shown = shown;
+    castShadows(shown, entry.node);
     startPlayer(entry);
   };
 
+  /** Drei's `Clone` shadow shorthands: each mesh casts or receives where asked. */
+  const castShadows = (shown: Object3D, node: BorrowedNode): void => {
+    if (!node.castShadow && !node.receiveShadow) return;
+    shown.traverse((part) => {
+      if (part instanceof Mesh && node.castShadow) part.castShadow = true;
+      if (part instanceof Mesh && node.receiveShadow) part.receiveShadow = true;
+    });
+  };
+
   const stopPlayer = (entry: Borrowing): void => {
     if (entry.player === undefined) return;
     entry.player.mixer.stopAllAction();
@@ -850,6 +1148,19 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
   const release = (entry: Entry): void => {
     if (isPlaced(entry)) behaving.delete(entry);
     spinning.delete(entry);
+    facing.delete(entry);
+    detailing.delete(entry);
+    const lines = edged.get(entry);
+    if (lines !== undefined) {
+      lines.hosted.dispose();
+      edged.delete(entry);
+    }
+    const ribbon = trailing.get(entry);
+    if (ribbon !== undefined) {
+      ribbon.object.removeFromParent();
+      ribbon.dispose();
+      trailing.delete(entry);
+    }
     moving.delete(entry);
     reparented.delete(entry);
     trackInteractive(entry.object, false);
@@ -861,7 +1172,10 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     if (entry._tag === 'Instances') entry.object.dispose();
     // A grid's lines are its own.
     if (entry._tag === 'Grid') disposeGridLines(entry.helper);
-    if (entry._tag === 'ShaderGrid') entry.hosted?.dispose();
+    if (entry._tag === 'ShaderGrid' || entry._tag === 'Line' || entry._tag === 'Points') {
+      entry.hosted?.dispose();
+    }
+    sparkling.delete(entry);
     if (entry._tag === 'Label') {
       entry.hosted?.dispose();
       if (entry.node.material !== null && entry.material !== undefined) {
@@ -991,6 +1305,12 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       entry.node = next;
       if (movesTransform(entry, fields)) retarget(entry, next);
       if (fields.includes('rotation')) trackRotation(entry, next);
+      if (entry._tag === 'Mesh' && next._tag === 'Mesh' && fields.includes('edges')) {
+        trackEdges(entry, next);
+      }
+      if (entry._tag === 'Mesh' && next._tag === 'Mesh' && fields.includes('trail')) {
+        trackTrail(entry, next);
+      }
       if (fields.includes('behaviour')) trackBehaviour(entry, next);
       if (fields.includes('interactive')) trackInteractive(mesh, next.interactive);
       mesh.castShadow = next.castShadow;
@@ -1005,6 +1325,9 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       if (fields.includes('interactive')) trackInteractive(entry.object, next.interactive);
       if (fields.includes('id')) showLoan(entry);
       else if (fields.includes('animation')) startPlayer(entry);
+      if (fields.includes('castShadow') || fields.includes('receiveShadow')) {
+        if (entry.shown !== undefined) castShadows(entry.shown, next);
+      }
       return;
     }
     if (entry._tag === 'Label' && next._tag === 'Label') {
@@ -1023,6 +1346,8 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       if (fields.includes('rotation')) trackRotation(entry, next);
       if (fields.includes('behaviour')) trackBehaviour(entry, next);
       if (fields.includes('interactive')) trackInteractive(entry.object, next.interactive);
+      if (fields.includes('detail')) trackDetail(entry, next);
+      if (fields.includes('trail')) trackTrail(entry, next);
       if (fields.includes('follow')) {
         // Back to its own transform, or hidden until the new space is found.
         entry.object.visible = next.follow === null;
@@ -1059,6 +1384,26 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       entry.node = next;
       return;
     }
+    if (entry._tag === 'Points' && next._tag === 'Points') {
+      entry.node = next;
+      if (movesTransform(entry, fields)) retarget(entry, next);
+      if (fields.includes('rotation')) trackRotation(entry, next);
+      if (fields.includes('behaviour')) trackBehaviour(entry, next);
+      if (fields.includes('look')) {
+        entry.hosted?.update(next);
+        trackSparkle(entry, next);
+      }
+      return;
+    }
+    if (entry._tag === 'Line' && next._tag === 'Line') {
+      entry.node = next;
+      if (movesTransform(entry, fields)) retarget(entry, next);
+      if (fields.includes('rotation')) trackRotation(entry, next);
+      if (fields.includes('behaviour')) trackBehaviour(entry, next);
+      if (fields.includes('interactive')) trackInteractive(entry.object, next.interactive);
+      if (fields.includes('line')) entry.hosted?.update(next);
+      return;
+    }
     if (entry._tag === 'ShaderGrid' && next._tag === 'ShaderGrid') {
       entry.hosted?.update(entry.node, next);
       entry.node = next;
@@ -1098,6 +1443,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
         applyLens(camera, op.camera);
         // A new kind of camera has nothing on screen to travel from.
         cameraMotion.aim(camera, op.camera, elapsed, camera !== previous || !animating);
+        cameraShaker.describe(op.camera.shake, elapsed);
         fitCamera(camera, viewport);
         return;
       }
@@ -1189,6 +1535,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     gestures: 'page',
     views: [],
     renderTextures: [],
+    hud: null,
     overlays: [],
     environment: null,
     sky: null,
@@ -1201,6 +1548,78 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     children: texture.children,
   });
 
+  /**
+   * The HUD's camera: orthographic in CSS pixels, from in front, aimed so that the HUD's
+   * origin falls `margin` in from the aligned edges (as Drei's `GizmoHelper` places its
+   * group). The camera moves rather than the nodes, so their positions stay the Model's.
+   */
+  const hudCamera = (hud: Hud): CameraDescription => {
+    const [marginX, marginY] = hud.margin;
+    const [vertical, horizontal] = hud.alignment.split('-');
+    const across = { left: -viewport.width / 2 + marginX, right: viewport.width / 2 - marginX };
+    const up = { top: viewport.height / 2 - marginY, bottom: -viewport.height / 2 + marginY };
+    const x = across[horizontal as keyof typeof across] ?? 0;
+    const y = up[vertical as keyof typeof up] ?? 0;
+    return orthographicCamera({
+      zoom: 1,
+      near: 0.1,
+      far: 2000,
+      position: [-x, -y, 200],
+      lookAt: [-x, -y, 0],
+    });
+  };
+
+  /** The HUD as a scene of its own, sharing the parent's resources. */
+  const hudScene = (hud: Hud, parent: SceneDescription): SceneDescription =>
+    textureScene(
+      {
+        id: 'hud',
+        width: viewport.width,
+        height: viewport.height,
+        camera: hudCamera(hud),
+        background: null,
+        children: hud.children,
+      },
+      parent,
+    );
+
+  /**
+   * Brings the HUD in line with the description, `parent` the scene it is over: a nested
+   * graph on the same store, created, reconciled, re-aimed or disposed.
+   */
+  const syncHud = (next: SceneDescription): ReadonlyArray<Op> => {
+    if (next.hud === null) {
+      if (hudHosted === undefined) return [];
+      hudHosted.graph.dispose();
+      hudHosted = undefined;
+      return [{ _tag: 'RemoveHud' }];
+    }
+    const created = hudHosted === undefined;
+    const hosted = hudHosted ?? {
+      graph: createSceneGraph({
+        store,
+        ...(options.behaviours === undefined ? {} : { behaviours: options.behaviours }),
+        ...(options.kit === undefined ? {} : { kit: options.kit }),
+      }),
+      description: next.hud,
+      parent: next,
+    };
+    if (created) hosted.graph.resize(viewport.width, viewport.height);
+    const result = hosted.graph.reconcile(hudScene(next.hud, next));
+    hosted.description = next.hud;
+    hosted.parent = next;
+    hudHosted = hosted;
+    const ops = result._tag === 'Applied' ? result.ops : [];
+    return created || ops.length > 0 ? [{ _tag: 'UpdateHud', ops }] : [];
+  };
+
+  /** The HUD fitted to a resized canvas: its camera re-aimed at the aligned point. */
+  const refitHud = (): void => {
+    if (hudHosted === undefined) return;
+    hudHosted.graph.resize(viewport.width, viewport.height);
+    hudHosted.graph.reconcile(hudScene(hudHosted.description, hudHosted.parent));
+  };
+
   /** A hosted render texture as the loop sees it; none if it is not hosted. */
   function hostedTexture(texture: RenderTexture): ReadonlyArray<HostedTexture> {
     const hosted = textureGraphs.get(texture.id);
@@ -1261,6 +1680,10 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       const checked = indexScene(textureScene(texture, next), knownBehaviours);
       if (checked._tag === 'Invalid') return checked;
     }
+    if (next.hud !== null) {
+      const checked = indexScene(hudScene(next.hud, next), knownBehaviours);
+      if (checked._tag === 'Invalid') return checked;
+    }
     const result = diff(index, next, knownBehaviours);
     if (result._tag === 'Invalid') return result;
     for (const op of result.ops) apply(op);
@@ -1294,7 +1717,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     // Measured after the next drawn frame; a new list needs one.
     if (next.measure.join('\u0000') !== measured.join('\u0000')) invalidate();
     measured = next.measure;
-    const ops = [...result.ops, ...syncTextures(next)];
+    const ops = [...result.ops, ...syncTextures(next), ...syncHud(next)];
     if (ops.length > 0) invalidate();
     return { _tag: 'Applied', ops };
   };
@@ -1307,6 +1730,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
   const tick = (elapsedSeconds: number): void => {
     elapsed = elapsedSeconds;
     for (const texture of textureList) texture.graph.tick(elapsedSeconds);
+    hudHosted?.graph.tick(elapsedSeconds);
     for (const entry of spinning) {
       if (isPlaced(entry)) {
         writeRotation(entry.object.rotation, entry.node.rotation, elapsed);
@@ -1317,8 +1741,27 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     behaving.forEach(applyBehaviour);
     cameraMotion.step(camera, elapsed);
     for (const view of views) viewMotions.get(view.key)?.step(view.camera, elapsed);
+    // Shake on top of wherever the cameras are aimed now.
+    cameraShaker.apply(camera, cameraMotion.target(), elapsed, animating);
+    views.forEach(shakeView);
     // Last: a dynamic body's pose is the simulation's, whatever else moved the mesh.
     bodyHost.tick(elapsed, animating);
+    // After the camera and everything a billboard may sit on have moved.
+    if (facing.size > 0) {
+      camera.getWorldQuaternion(cameraTurn);
+      facing.forEach(faceCamera);
+    }
+    edged.forEach(refreshEdges);
+    // Reduced motion holds sparkles and stars where they are.
+    if (animating) sparkling.forEach(sparkle);
+    if (trailing.size > 0) {
+      camera.getWorldPosition(eye);
+      trailing.forEach(followTrail);
+    }
+    if (detailing.size > 0) {
+      camera.getWorldPosition(cameraPlace);
+      detailing.forEach(showLevel);
+    }
   };
 
   const finishTween = (tween: Tween, entry: Entry): void => {
@@ -1328,6 +1771,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
   const setAnimating = (next: boolean): void => {
     if (next !== animating) invalidate();
     for (const texture of textureList) texture.graph.setAnimating(next);
+    hudHosted?.graph.setAnimating(next);
     animating = next;
     if (next) return;
     moving.forEach(finishTween);
@@ -1342,6 +1786,8 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     for (const texture of textureList) texture.graph.dispose();
     textureGraphs.clear();
     textureList = [];
+    hudHosted?.graph.dispose();
+    hudHosted = undefined;
     for (const entry of entries.values()) {
       entry.object.removeFromParent();
       release(entry);
@@ -1372,6 +1818,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       return viewMotions.get(view)?.turned();
     },
     renderTextures: () => textureList,
+    hud: () => hudHosted,
     gestures: () => gestures,
     overlays: () => overlayList,
     environment: () => environmentDescription,
@@ -1400,7 +1847,9 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     renderSettings: () => settings,
     needsFrame: () =>
       dirty ||
+      trailsMoving() ||
       textureList.some((texture) => texture.graph.needsFrame()) ||
+      (hudHosted?.graph.needsFrame() ?? false) ||
       (animating &&
         (spinning.size > 0 ||
           moving.size > 0 ||
@@ -1408,6 +1857,8 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
           clipsRunning() ||
           cameraMotion.moving() ||
           viewsMoving() ||
+          shaking() ||
+          sparkling.size > 0 ||
           bodyHost.needsFrame())),
     drawn: () => {
       dirty = false;
@@ -1435,6 +1886,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       viewport = { width, height };
       fitCamera(camera, viewport);
       hostViews(viewDescriptions);
+      refitHud();
       invalidate();
     },
     dispose,