@opsydyn/effect-three 0.3.0 → 0.6.4

package/src/kernel/bodies.ts

@@ -15,7 +15,16 @@ import { Euler, Quaternion, type Scene } from 'three';
 import { bodyId, type BodySource } from './bodySources.ts';
 import type { Body, Joint, Physics, Vec3 } from './description.ts';
 import { bodyEquals, collidersEqual, jointEquals, physicsEquals } from './equality.ts';
-import type { BodyPose, PhysicsEngine, PhysicsJoint, PhysicsWorld, Quat } from './physics.ts';
+import {
+  type BodyPose,
+  type Collision,
+  type PhysicsEngine,
+  type PhysicsJoint,
+  type PhysicsWorld,
+  type Quat,
+  snapshotBytes,
+  snapshotText,
+} from './physics.ts';
 import { createPhysicsDebug } from './physicsDebug.ts';
 
 /** Two bodies began (`started`) or stopped touching: their nodes' keys, and instances'. */
@@ -48,6 +57,19 @@ export type BodyContactForce = {
   readonly maxForceMagnitude: number;
 };
 
+/**
+ * A world driven by `physics({ until })` has reached that step and waits: its run, what
+ * it has done (its step count since it was made), and a checksum of every body's pose
+ * there, so peers that should agree can check that they do.
+ */
+export type PhysicsReached = {
+  readonly run: number;
+  readonly step: number;
+  readonly checksum: string;
+  /** At `physics({ snapshotAt })`: the world there, for another to start `from`. */
+  readonly snapshot?: string;
+};
+
 type Hosted = {
   source: BodySource;
   /** What its colliders were made from; a change makes them again. */
@@ -69,6 +91,13 @@ export type BodyHost = {
   readonly drainCollisions: () => ReadonlyArray<BodyCollision>;
   /** Contact forces over their thresholds since the last call. */
   readonly drainContactForces: () => ReadonlyArray<BodyContactForce>;
+  /** Steps the Model has asked for and the world has reached since the last call. */
+  readonly drainReached: () => ReadonlyArray<PhysicsReached>;
+  /**
+   * Whether a world on `until` still owes steps, or a report: it needs frames even when
+   * nothing else moves, and even under reduced motion, as other peers wait on it.
+   */
+  readonly owesSteps: () => boolean;
   readonly dispose: () => void;
 };
 
@@ -108,6 +137,53 @@ const between = (a: BodyPose, b: BodyPose, alpha: number): BodyPose => {
   };
 };
 
+/**
+ * How far behind `until` (in seconds of simulation) a world may run at scene time's pace,
+ * following an `until` that moves on as time passes; further back (a newcomer replaying,
+ * a page that was busy), it goes straight there.
+ */
+const catchUpAfter = 0.25;
+
+/** The most simulation a world on `until` runs in one frame, in seconds. */
+const mostPerFrame = 1;
+
+const checksumBytes = new DataView(new ArrayBuffer(8));
+
+/** FNV-1a, a byte at a time. */
+const mixByte = (hash: number, byte: number): number => Math.imul(hash ^ byte, 0x0100_0193) >>> 0;
+
+const mixNumber = (hash: number, value: number): number => {
+  checksumBytes.setFloat64(0, value);
+  let mixed = hash;
+  for (let i = 0; i < 8; i++) mixed = mixByte(mixed, checksumBytes.getUint8(i));
+  return mixed;
+};
+
+const mixText = (hash: number, text: string): number => {
+  let mixed = hash;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    mixed = mixByte(mixByte(mixed, code & 0xff), code >>> 8);
+  }
+  return mixed;
+};
+
+/**
+ * A checksum of where every body is, by id: the bits of each pose's numbers, so peers
+ * agree only if their worlds are the same to the last bit.
+ */
+const checksumOf = (poses: ReadonlyArray<readonly [string, BodyPose]>): string => {
+  let hash = 0x811c_9dc5;
+  for (const [id, { position, quaternion }] of poses.toSorted(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0,
+  )) {
+    hash = mixText(hash, id);
+    for (const value of position) hash = mixNumber(hash, value);
+    for (const value of quaternion) hash = mixNumber(hash, value);
+  }
+  return hash.toString(16).padStart(8, '0');
+};
+
 /** A change that needs a new body: another holder or kind, or colliders made otherwise. */
 const remade = (hosted: Hosted, source: BodySource, signature: string): boolean =>
   hosted.source.holder !== source.holder ||
@@ -156,6 +232,19 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
   const debug = createPhysicsDebug(scene);
   let last: number | undefined;
   let accumulator = 0;
+  /** Steps taken since the world was made. */
+  let steps = 0;
+  /** The last `until` reported as reached. */
+  let reported: number | undefined;
+  /** The last `snapshotAt` reported, snapshot and all. */
+  let snapped: number | undefined;
+  let reached: Array<PhysicsReached> = [];
+  /** Snapshots of the latest stops, by step, oldest first, while `keep` asks for them. */
+  const kept = new Map<number, Uint8Array>();
+  /** A run just started from a snapshot: it goes straight to `until`, as one far behind. */
+  let rushing = false;
+  /** What a world made from a snapshot holds already, until this sync takes it on. */
+  let restored: { readonly bodies: Set<string>; readonly joints: Set<string> } | undefined;
 
   /** Draws the world's lines while the description asks for them. */
   const drawDebug = (): void => {
@@ -172,10 +261,51 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
     joined.clear();
     accumulator = 0;
     last = undefined;
+    steps = 0;
+    reported = undefined;
+    snapped = undefined;
+    reached = [];
+  };
+
+  /**
+   * The world for a run: made from the snapshot it starts `from`, counting on from its
+   * step, when the engine can; otherwise from the description, at step 0.
+   */
+  const make = (active: PhysicsEngine, physics: Physics): PhysicsWorld => {
+    const { from } = physics;
+    const bytes =
+      from === null
+        ? undefined
+        : from.snapshot === null
+          ? kept.get(from.step)
+          : snapshotBytes(from.snapshot);
+    if (from === null || bytes === undefined || active.restoreWorld === undefined) {
+      kept.clear();
+      return active.createWorld(physics);
+    }
+    // What was kept after the step it goes back to was of a world that went another way.
+    for (const step of kept.keys())
+      if (step > from.step || from.snapshot !== null) kept.delete(step);
+    const made = active.restoreWorld(physics, bytes);
+    steps = from.step;
+    rushing = true;
+    restored = { bodies: new Set(made.bodies), joints: new Set(made.joints) };
+    return made.world;
   };
 
+  /** Takes on a body the restored world holds: shown where the world has it. */
+  const adopt = (active: PhysicsWorld, source: BodySource, signature: string): void => {
+    const pose = active.pose(source.id) ?? source.described();
+    source.place(pose);
+    hosted.set(source.id, { source, signature, previous: pose, current: pose, shown: pose });
+  };
+
+  /** Whether this sync begins a new run: bodies start where the description puts them. */
+  let restarting = false;
+
   const add = (active: PhysicsWorld, source: BodySource, signature: string): void => {
-    const pose = source.pose();
+    const pose = restarting ? source.described() : source.pose();
+    if (restarting) source.place(pose);
     active.add(source.id, source.body, source.colliders(), pose);
     if (source.body.impulse !== null) active.applyImpulse(source.id, source.body.impulse.impulse);
     hosted.set(source.id, { source, signature, previous: pose, current: pose, shown: pose });
@@ -185,6 +315,10 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
   const syncBody = (active: PhysicsWorld, source: BodySource): void => {
     const existing = hosted.get(source.id);
     const signature = source.signature();
+    if (existing === undefined && restored?.bodies.has(source.id) === true) {
+      adopt(active, source, signature);
+      return;
+    }
     if (existing === undefined || remade(existing, source, signature)) {
       if (existing !== undefined) active.remove(source.id);
       add(active, source, signature);
@@ -247,11 +381,27 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
   const sync: BodyHost['sync'] = (physics, sources) => {
     if (physics === null || engine === undefined) {
       dispose();
+      kept.clear();
       return;
     }
-    if (world === undefined) world = engine.createWorld(physics);
-    // Joints are made below, not configured.
-    else if (!physicsEquals(settings && { ...settings, joints: physics.joints }, physics)) {
+    // Another run: the world goes, and a new one counts from step 0.
+    restarting = settings !== null && settings.run !== physics.run;
+    if (restarting) dispose();
+    if (world === undefined) world = make(engine, physics);
+    // Joints are made below, and the clock and snapshots are the host's: none is configured.
+    else if (
+      !physicsEquals(
+        settings && {
+          ...settings,
+          joints: physics.joints,
+          until: physics.until,
+          snapshotAt: physics.snapshotAt,
+          from: physics.from,
+          keep: physics.keep,
+        },
+        physics,
+      )
+    ) {
       world.configure(physics);
     }
     settings = physics;
@@ -267,7 +417,20 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
       world.remove(id);
       hosted.delete(id);
     }
+    if (restored !== undefined) {
+      // What the snapshot held and the description does not, goes; its joints that the
+      // description still has are kept as they were.
+      for (const id of restored.bodies) if (!seen.has(id)) world.remove(id);
+      for (const joint of physics.joints) {
+        if (restored.joints.has(joint.key)) joined.set(joint.key, joint);
+      }
+      for (const id of restored.joints) {
+        if (!joined.has(id)) world.removeJoint(id);
+      }
+      restored = undefined;
+    }
     syncJoints(world, physics.joints);
+    restarting = false;
     drawDebug();
   };
 
@@ -277,10 +440,8 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
     }
   };
 
-  const step = (active: PhysicsWorld, seconds: number): void => {
-    for (const body of hosted.values()) body.previous = body.current;
-    kinematicTargets(active);
-    for (const collision of active.step(seconds)) {
+  const heard = (arrived: ReadonlyArray<Collision>, active: PhysicsWorld): void => {
+    for (const collision of arrived) {
       collisions.push({
         ...named(hosted.get(collision.a)?.source, hosted.get(collision.b)?.source, collision),
         started: collision.started,
@@ -293,21 +454,128 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
         ...payload,
       });
     }
+  };
+
+  const step = (active: PhysicsWorld, seconds: number): void => {
+    for (const body of hosted.values()) body.previous = body.current;
+    kinematicTargets(active);
+    heard(active.step(seconds), active);
     for (const [id, body] of hosted) body.current = active.pose(id) ?? body.current;
+    steps += 1;
   };
 
-  const tick: BodyHost['tick'] = (elapsed, animating) => {
-    const delta = last === undefined ? 0 : Math.min(0.5, Math.max(0, elapsed - last));
-    last = elapsed;
-    if (world === undefined || settings === null || settings.paused || !animating) return;
-    const timeStep = settings.timeStep;
+  /**
+   * What a world working elsewhere has sent back since the last frame: its collisions and
+   * forces, and where its bodies are now. Whether anything is still to come back; never,
+   * for a world that does what it is asked at once.
+   */
+  const collect = (active: PhysicsWorld): boolean => {
+    if (active.received === undefined) return false;
+    const { collisions: arrived, pending } = active.received();
+    heard(arrived, active);
+    for (const [id, body] of hosted) body.current = active.pose(id) ?? body.current;
+    return pending;
+  };
+
+  /** On scene time: every whole step the time since the last frame holds. */
+  const free = (active: PhysicsWorld, timeStep: number, delta: number): number => {
     accumulator += delta;
-    scene.updateMatrixWorld();
     while (accumulator >= timeStep) {
-      step(world, timeStep);
+      step(active, timeStep);
       accumulator -= timeStep;
     }
-    const alpha = settings.interpolate ? accumulator / timeStep : 1;
+    collect(active);
+    return accumulator / timeStep;
+  };
+
+  /** Whether the world is to stop at `snapshotAt` on its way to `until` and report a snapshot there. */
+  const snapshotOwed = (physics: Physics, until: number): boolean =>
+    physics.snapshotAt !== null &&
+    snapped !== physics.snapshotAt &&
+    steps <= physics.snapshotAt &&
+    physics.snapshotAt <= until;
+
+  /**
+   * Reports where the world is: its checksum, and a snapshot of it when `snapshot` asks;
+   * one is kept too, while the description asks to `keep` some. False, reporting nothing,
+   * while a world working elsewhere has yet to send the snapshot (asking it for one).
+   */
+  const report = (active: PhysicsWorld, physics: Physics, snapshot: boolean): boolean => {
+    const wanted = snapshot || physics.keep > 0;
+    const bytes = wanted ? active.snapshot?.() : undefined;
+    if (wanted && active.snapshot !== undefined && bytes === undefined) return false;
+    if (physics.keep > 0 && bytes !== undefined) {
+      kept.delete(steps);
+      kept.set(steps, bytes);
+      for (const step of kept.keys()) if (kept.size > physics.keep) kept.delete(step);
+    }
+    const { run } = physics;
+    reached.push({
+      run,
+      step: steps,
+      checksum: checksumOf([...hosted.keys()].flatMap((id) => posed(active, id))),
+      ...(snapshot && bytes !== undefined ? { snapshot: snapshotText(bytes) } : {}),
+    });
+    return true;
+  };
+
+  /**
+   * Toward `until`: at scene time's pace while close behind it, straight there (a step
+   * budget a frame) when further back, never past it. A world that has reached it waits
+   * there and reports it once, with the bodies' checksum. A `snapshotAt` on the way is a
+   * stop too: the world reports there with a snapshot, and goes on.
+   */
+  const driven = (active: PhysicsWorld, physics: Physics, until: number, delta: number) => {
+    const { timeStep } = physics;
+    const snapping = snapshotOwed(physics, until);
+    const stop = snapping && physics.snapshotAt !== null ? physics.snapshotAt : until;
+    accumulator += delta;
+    const owed = Math.max(0, stop - steps);
+    const paced = Math.floor(accumulator / timeStep);
+    const behind = rushing || owed > Math.ceil(catchUpAfter / timeStep);
+    rushing = false;
+    const count = Math.min(owed, behind ? owed : paced, Math.ceil(mostPerFrame / timeStep));
+    for (let i = 0; i < count; i++) step(active, timeStep);
+    accumulator = Math.max(0, accumulator - count * timeStep);
+    const pending = collect(active);
+    if (steps < stop) return Math.min(1, accumulator / timeStep);
+    // A world working elsewhere is there once all it was asked has come back, poses and all.
+    if (stop < until) {
+      if (!pending && report(active, physics, true)) snapped = stop;
+      return Math.min(1, accumulator / timeStep);
+    }
+    // Waiting: time spent here is not owed once `until` moves on.
+    accumulator = 0;
+    // Reported there already, it reports again for a snapshot asked for afterwards.
+    if (
+      steps === until &&
+      (reported !== until || snapping) &&
+      !pending &&
+      report(active, physics, snapping)
+    ) {
+      reported = until;
+      if (snapping) snapped = until;
+    }
+    return 1;
+  };
+
+  const posed = (active: PhysicsWorld, id: string): ReadonlyArray<[string, BodyPose]> => {
+    const pose = active.pose(id);
+    return pose === undefined ? [] : [[id, pose]];
+  };
+
+  const tick: BodyHost['tick'] = (elapsed, animating) => {
+    const delta = last === undefined ? 0 : Math.min(0.5, Math.max(0, elapsed - last));
+    last = elapsed;
+    if (world === undefined || settings === null || settings.paused) return;
+    // A world on `until` steps under reduced motion too: other peers wait on it.
+    if (settings.until === null && !animating) return;
+    scene.updateMatrixWorld();
+    const progress =
+      settings.until === null
+        ? free(world, settings.timeStep, delta)
+        : driven(world, settings, settings.until, delta);
+    const alpha = settings.interpolate ? progress : 1;
     for (const body of hosted.values()) {
       if (body.source.body.type === 'dynamic') {
         body.shown = between(body.previous, body.current, alpha);
@@ -333,6 +601,20 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
       contactForces = [];
       return drained;
     },
+    drainReached: () => {
+      if (reached.length === 0) return reached;
+      const drained = reached;
+      reached = [];
+      return drained;
+    },
+    owesSteps: () =>
+      world !== undefined &&
+      settings !== null &&
+      !settings.paused &&
+      settings.until !== null &&
+      (steps < settings.until ||
+        reported !== settings.until ||
+        snapshotOwed(settings, settings.until)),
     dispose,
   };
 };

package/src/kernel/boxSelect.ts

@@ -0,0 +1,73 @@
+/**
+ * Box selection as data, after three.js's `SelectionBox` (0.186.1,
+ * `examples/jsm/interactive/SelectionBox.js`), which Drei's `Select` wraps. three's box
+ * walks the scene for meshes whose centres fall inside the frustum a rectangle on screen
+ * cuts from the camera; here the Model names the candidates and their centres, and
+ * `boxSelect` returns the keys inside, so a selection is a value the Model keeps.
+ *
+ * A point is inside when it projects into the rectangle, as three's side planes have it,
+ * and lies between the camera's near and far planes: what the camera can show. (three's
+ * perspective box reaches past far, and its orthographic box neither stops at far nor
+ * starts at near, `0.186.1`; a box here never selects what cannot be seen.)
+ *
+ * @module
+ */
+import { OrthographicCamera, PerspectiveCamera, Vector3 } from 'three';
+
+import type { Camera, Vec3 } from './description.ts';
+
+/** A corner of the box, in the canvas's normalised coordinates: −1 to 1, y up. */
+export type BoxCorner = { readonly x: number; readonly y: number };
+
+/** Something that can be selected: its key, and the point that must fall in the box. */
+export type Selectable = { readonly key: string; readonly at: Vec3 };
+
+/** The canvas's size in CSS pixels, which sets the camera's aspect (or ortho frustum). */
+export type CanvasSize = { readonly width: number; readonly height: number };
+
+/** The three.js camera the description renders through, fitted to `size`. */
+const hostCamera = (camera: Camera, size: CanvasSize): PerspectiveCamera | OrthographicCamera => {
+  const host =
+    camera._tag === 'Perspective'
+      ? new PerspectiveCamera(camera.fov, size.width / size.height, camera.near, camera.far)
+      : new OrthographicCamera(
+          size.width / -2,
+          size.width / 2,
+          size.height / 2,
+          size.height / -2,
+          camera.near,
+          camera.far,
+        );
+  if (host instanceof OrthographicCamera && camera._tag === 'Orthographic') {
+    host.zoom = camera.zoom;
+  }
+  host.position.set(...camera.position);
+  host.lookAt(...camera.lookAt);
+  host.updateMatrixWorld();
+  host.updateProjectionMatrix();
+  return host;
+};
+
+const between = (value: number, a: number, b: number): boolean =>
+  value >= Math.min(a, b) && value <= Math.max(a, b);
+
+/**
+ * The keys of `candidates` whose points fall inside the box from corner `from` to corner
+ * `to`, seen through `camera` on a canvas of `size`, in the order given.
+ */
+export const boxSelect = (
+  camera: Camera,
+  size: CanvasSize,
+  from: BoxCorner,
+  to: BoxCorner,
+  candidates: ReadonlyArray<Selectable>,
+): ReadonlyArray<string> => {
+  const host = hostCamera(camera, size);
+  // Projected, a point between near and far has a depth from −1 to 1; one behind the
+  // camera, above 1.
+  const inside = (candidate: Selectable): boolean => {
+    const seen = new Vector3(...candidate.at).project(host);
+    return between(seen.x, from.x, to.x) && between(seen.y, from.y, to.y) && between(seen.z, -1, 1);
+  };
+  return candidates.filter(inside).map((candidate) => candidate.key);
+};