@opsydyn/effect-three 0.3.0 → 0.6.4

package/src/kernel/sceneGraph.ts

@@ -30,14 +30,21 @@ 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 BodyCollision,
+  type BodyContactForce,
+  createBodyHost,
+  type PhysicsReached,
+} 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,
@@ -45,6 +52,8 @@ import type {
   Instance,
   InstancesNode,
   LabelNode,
+  LineNode,
+  PointsNode,
   MaterialRef,
   ShaderGridNode,
   MeshNode,
@@ -68,9 +77,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,
@@ -80,7 +96,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,
@@ -89,6 +112,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. */
@@ -142,6 +166,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. */
@@ -154,12 +192,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. */
@@ -170,12 +222,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;
@@ -232,6 +289,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. */
@@ -244,6 +303,8 @@ export type SceneGraph = {
   readonly collisions: () => ReadonlyArray<BodyCollision>;
   /** Contact forces over their bodies' thresholds since the last call. */
   readonly contactForces: () => ReadonlyArray<BodyContactForce>;
+  /** Steps a world on `physics({ until })` has reached since the last call. */
+  readonly physicsReached: () => ReadonlyArray<PhysicsReached>;
   /** How the scene is presented immersively, for the host; `null` if it never is. */
   readonly xr: () => Xr | null;
   /** Keys of the nodes whose bounds the frame loop reports. */
@@ -448,6 +509,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;
@@ -557,8 +621,30 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
   const spinning = new Set<Entry>();
   // Billboards: turned towards the camera each frame, after everything else has moved.
   const facing = new Set<Entry>();
+  // Parents first, so a billboard inside a billboard reads this frame's parent turn.
+  const facingOrder: Array<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();
@@ -639,6 +725,99 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     if (lockZ) object.rotation.z = 0;
   };
 
+  const depthOf = (object: Object3D): number => {
+    let depth = 0;
+    for (let parent = object.parent; parent !== null; parent = parent.parent) depth += 1;
+    return depth;
+  };
+
+  /**
+   * Faces every billboard, shallowest first: a nested one is turned against its parent's
+   * world rotation, so the parent must have turned this frame. Drei gets this from React
+   * running a parent's frame callback before its child's.
+   */
+  const faceCameras = (): void => {
+    facingOrder.length = 0;
+    facing.forEach((entry) => facingOrder.push(entry));
+    facingOrder.sort((a, b) => depthOf(a.object) - depthOf(b.object));
+    facingOrder.forEach(faceCamera);
+  };
+
+  /** 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];
@@ -704,6 +883,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
         // 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': {
@@ -719,6 +899,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': {
@@ -799,6 +981,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);
@@ -973,6 +1177,17 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     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);
@@ -984,7 +1199,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) {
@@ -1114,6 +1332,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;
@@ -1150,6 +1374,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       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;
@@ -1186,6 +1411,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;
@@ -1317,6 +1562,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     gestures: 'page',
     views: [],
     renderTextures: [],
+    hud: null,
     overlays: [],
     environment: null,
     sky: null,
@@ -1324,11 +1570,84 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     physics: null,
     xr: null,
     measure: [],
+    assets: [],
     render: parent.render,
     resources: parent.resources,
     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);
@@ -1389,6 +1708,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);
@@ -1417,12 +1740,14 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     if ((physicsDescription?.debug ?? false) !== (next.physics?.debug ?? false)) invalidate();
     physicsDescription = next.physics;
     bodyHost.sync(next.physics, bodySources());
+    // A world on `until` that owes steps needs frames, though nothing else may be moving.
+    if (bodyHost.owesSteps()) invalidate();
     // Read by the host when it presents the scene immersively: no operation, no frame.
     xrDescription = next.xr;
     // 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 };
   };
@@ -1435,6 +1760,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);
@@ -1453,7 +1779,14 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     // After the camera and everything a billboard may sit on have moved.
     if (facing.size > 0) {
       camera.getWorldQuaternion(cameraTurn);
-      facing.forEach(faceCamera);
+      faceCameras();
+    }
+    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);
@@ -1468,6 +1801,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);
@@ -1482,6 +1816,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);
@@ -1512,12 +1848,14 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       return viewMotions.get(view)?.turned();
     },
     renderTextures: () => textureList,
+    hud: () => hudHosted,
     gestures: () => gestures,
     overlays: () => overlayList,
     environment: () => environmentDescription,
     contactShadows: () => contactDescription,
     collisions: bodyHost.drainCollisions,
     contactForces: bodyHost.drainContactForces,
+    physicsReached: bodyHost.drainReached,
     xr: () => xrDescription,
     measured: () => measured,
     labelLayout: (key) => {
@@ -1540,7 +1878,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 ||
@@ -1549,7 +1889,9 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
           cameraMotion.moving() ||
           viewsMoving() ||
           shaking() ||
-          bodyHost.needsFrame())),
+          sparkling.size > 0 ||
+          bodyHost.needsFrame())) ||
+      bodyHost.owesSteps(),
     drawn: () => {
       dirty = false;
     },
@@ -1576,6 +1918,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       viewport = { width, height };
       fitCamera(camera, viewport);
       hostViews(viewDescriptions);
+      refitHud();
       invalidate();
     },
     dispose,

package/src/kernel/sceneIndex.ts

@@ -32,6 +32,8 @@ export type DescriptionError =
   | { readonly _tag: 'UnknownOverlayNode'; readonly key: string; readonly node: string }
   | { readonly _tag: 'UnknownOverlayView'; readonly key: string; readonly view: string }
   | { readonly _tag: 'UnknownMeasuredNode'; readonly key: string }
+  /** Two assets the scene asks for share an id. */
+  | { readonly _tag: 'DuplicateAssetId'; readonly id: string }
   /** Two joints share a key. */
   | { readonly _tag: 'DuplicateJointKey'; readonly key: string }
   /** A joint names a node that is not in the scene. */
@@ -104,6 +106,12 @@ export const indexScene = (
   if (duplicateView !== undefined) {
     return { _tag: 'Invalid', error: { _tag: 'DuplicateViewKey', key: duplicateView } };
   }
+  const duplicateAsset = firstDuplicateInstance(
+    description.assets.map((asset) => ({ key: asset.id })),
+  );
+  if (duplicateAsset !== undefined) {
+    return { _tag: 'Invalid', error: { _tag: 'DuplicateAssetId', id: duplicateAsset } };
+  }
   const duplicateOverlay = firstDuplicateInstance(description.overlays);
   if (duplicateOverlay !== undefined) {
     return { _tag: 'Invalid', error: { _tag: 'DuplicateOverlayKey', key: duplicateOverlay } };

package/src/kernel/seeded.ts

@@ -0,0 +1,18 @@
+/**
+ * A small seeded random generator (mulberry32): the same numbers for the same seed on
+ * every page load, so randomly scattered scene parts are reproducible.
+ *
+ * @module
+ */
+
+/** A generator of numbers in [0, 1) from `seed`, as `Math.random` would give them. */
+export const seededRandom = (seed: number): (() => number) => {
+  let state = seed >>> 0;
+  return () => {
+    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;
+  };
+};