@opsydyn/effect-three 0.4.0 → 0.6.4

package/src/kernel/index.ts

@@ -48,6 +48,10 @@ export {
   xrMesh,
   xrMeshGeometryId,
   physics,
+  modelAsset,
+  textureAsset,
+  environmentAsset,
+  fontAsset,
   cuboidCollider,
   ballCollider,
   capsuleCollider,
@@ -149,6 +153,7 @@ export {
   overlaysEqual,
   xrEquals,
   physicsEquals,
+  assetsEqual,
   skyEquals,
   viewsEqual,
   vec3Equals,
@@ -207,8 +212,12 @@ export {
   type PhysicsJoint,
   type PhysicsWorld,
   type Quat,
+  type Received,
+  type RestoredWorld,
+  snapshotBytes,
+  snapshotText,
 } from './physics.ts';
-export type { BodyCollision, BodyContactForce } from './bodies.ts';
+export type { BodyCollision, BodyContactForce, PhysicsReached } from './bodies.ts';
 export type {
   ContactShadowPasses,
   HostedLine,
@@ -255,6 +264,7 @@ export {
   type Picker,
   type PlaneEquation,
   pointOnPlane,
+  type PointerDevice,
   type PointerInput,
   type PointerTracker,
   type Ray,
@@ -282,6 +292,7 @@ export {
   type SceneGraph,
   type SceneGraphOptions,
 } from './sceneGraph.ts';
+export { type PreviewOptions, type PreviewResult, previewSvg } from './preview.ts';
 export {
   type DescriptionError,
   emptyIndex,
@@ -310,6 +321,7 @@ export {
 export { type BoxCorner, boxSelect, type CanvasSize, type Selectable } from './boxSelect.ts';
 export * as History from './history.ts';
 export * as Lockstep from './lockstep.ts';
+export * as Timeline from './timeline.ts';
 export {
   describeScene,
   formatSummary,

package/src/kernel/loop.ts

@@ -203,6 +203,8 @@ export const createSceneLoop = (options: SceneLoopOptions): SceneLoop => {
       for (const event of tracker.frame()) emit(event);
       for (const collision of graph.collisions()) emit({ _tag: 'Collision', ...collision });
       for (const force of graph.contactForces()) emit({ _tag: 'ContactForce', ...force });
+      // After the collisions of the steps that led there, so a Model has them all first.
+      for (const reached of graph.physicsReached()) emit({ _tag: 'PhysicsReached', ...reached });
       // Settings change only through reconcile, which replaces the value: compare by reference.
       const settings = graph.renderSettings();
       if (settings !== configured) {

package/src/kernel/paintOrder.ts

@@ -0,0 +1,274 @@
+/**
+ * The order to paint a still in, far to near from one eye, exactly: a binary space
+ * partition (Fuchs, Kedem and Naylor, 1980) of what is drawn, where sorting by depth
+ * would paint a floor over what stands on it. It partitions objects rather than faces: an
+ * object none of whose faces can hide another (any convex solid, its back faces culled)
+ * is painted as it is, and is told which side of a plane it lies by its bounding sphere
+ * before its faces are looked at, so a scene of many objects stays quick. Splitting
+ * planes are chosen to cut few objects and to share them out evenly.
+ *
+ * @module
+ */
+import { Sphere, Vector3 } from 'three';
+
+/** A flat convex polygon in the world, and what it is painted as. */
+export type Facet<T> = {
+  readonly _tag: 'Facet';
+  readonly points: ReadonlyArray<Vector3>;
+  readonly item: T;
+};
+
+/** Something without area (a line, a point) at a place in the world. */
+export type Mark<T> = { readonly _tag: 'Mark'; readonly at: Vector3; readonly item: T };
+
+/** What one object draws, and whether its facets may be painted in any order. */
+export type Unit<T> = {
+  readonly facets: ReadonlyArray<Facet<T>>;
+  readonly marks: ReadonlyArray<Mark<T>>;
+  readonly bounds: Sphere;
+  readonly selfOrdered: boolean;
+};
+
+/** A plane, `normal · p = constant`. */
+export type Plane = { readonly normal: Vector3; readonly constant: number };
+
+/** How far from a plane, in world units a unit from the origin, a point counts as on it. */
+const onPlane = 1e-6;
+
+/** How many facets are weighed as each partition's plane. */
+const candidates = 8;
+
+/** How much worse a cut object is than an object on the fuller side. */
+const splitCost = 8;
+
+const planeOf = (points: ReadonlyArray<Vector3>): Plane | undefined => {
+  const [a, b, c] = points;
+  if (a === undefined || b === undefined || c === undefined) return undefined;
+  const normal = new Vector3().subVectors(b, a).cross(new Vector3().subVectors(c, a));
+  if (normal.lengthSq() === 0) return undefined;
+  normal.normalize();
+  return { normal, constant: normal.dot(a) };
+};
+
+const side = (plane: Plane, point: Vector3): number => plane.normal.dot(point) - plane.constant;
+
+const toleranceAt = (points: ReadonlyArray<Vector3>): number =>
+  onPlane * Math.max(1, ...points.map((point) => point.length()));
+
+type Parts<T> = {
+  readonly front?: Facet<T>;
+  readonly back?: Facet<T>;
+  readonly on?: Facet<T>;
+};
+
+/** A facet split by a plane: what lies in front of it, behind it, and in it. */
+export const split = <T>(plane: Plane, facet: Facet<T>): Parts<T> => {
+  const sides = facet.points.map((point) => side(plane, point));
+  const tolerance = toleranceAt(facet.points);
+  if (sides.every((s) => Math.abs(s) <= tolerance)) return { on: facet };
+  if (sides.every((s) => s >= -tolerance)) return { front: facet };
+  if (sides.every((s) => s <= tolerance)) return { back: facet };
+  const front: Array<Vector3> = [];
+  const back: Array<Vector3> = [];
+  facet.points.forEach((point, i) => {
+    const next = facet.points[(i + 1) % facet.points.length] ?? point;
+    const here = sides[i] ?? 0;
+    const there = sides[(i + 1) % sides.length] ?? 0;
+    if (here >= -tolerance) front.push(point);
+    if (here <= tolerance) back.push(point);
+    if ((here > tolerance && there < -tolerance) || (here < -tolerance && there > tolerance)) {
+      const crossing = point.clone().lerp(next, here / (here - there));
+      front.push(crossing);
+      back.push(crossing.clone());
+    }
+  });
+  return {
+    ...(front.length >= 3 ? { front: { ...facet, points: front } } : {}),
+    ...(back.length >= 3 ? { back: { ...facet, points: back } } : {}),
+  };
+};
+
+/** Whether the eye is in front of `facet` and all of `facets` lie on or behind its plane. */
+function hidesNone<T>(facet: Facet<T>, facets: ReadonlyArray<Facet<T>>, eye: Vector3): boolean {
+  const plane = planeOf(facet.points);
+  if (plane === undefined) return true;
+  const tolerance = toleranceAt(facet.points);
+  return (
+    side(plane, eye) > tolerance &&
+    facets.every(
+      (other) => other === facet || other.points.every((point) => side(plane, point) <= tolerance),
+    )
+  );
+}
+
+/**
+ * Gathers what one object draws. Its facets may be painted in any order when the eye is
+ * in front of each and every other lies on or behind each one's plane: then none comes
+ * between the eye and another.
+ */
+export const unitOf = <T>(
+  facets: ReadonlyArray<Facet<T>>,
+  marks: ReadonlyArray<Mark<T>>,
+  eye: Vector3,
+): Unit<T> => {
+  const points = [...facets.flatMap((facet) => facet.points), ...marks.map((mark) => mark.at)];
+  const bounds = new Sphere().setFromPoints(points);
+  const selfOrdered = facets.every((facet) => hidesNone(facet, facets, eye));
+  return { facets, marks, bounds, selfOrdered };
+};
+
+type Partition<T> = {
+  readonly front: ReadonlyArray<Unit<T>>;
+  readonly back: ReadonlyArray<Unit<T>>;
+  readonly on: ReadonlyArray<Facet<T>>;
+};
+
+const sizeOf = <T>(unit: Unit<T>): number => unit.facets.length + unit.marks.length;
+
+/** Which side of `plane` a unit lies, by its bounds: `0` when they cross it. */
+const sideOf = <T>(plane: Plane, unit: Unit<T>): number => {
+  const distance = side(plane, unit.bounds.center);
+  const reach = unit.bounds.radius * (1 + onPlane) + onPlane;
+  return distance > reach ? 1 : distance < -reach ? -1 : 0;
+};
+
+/** Units cut in two by `plane`, and how many facets and marks fall either side. */
+const weigh = <T>(plane: Plane, units: ReadonlyArray<Unit<T>>): number => {
+  let cut = 0;
+  let front = 0;
+  let back = 0;
+  for (const unit of units) {
+    const whole = sideOf(plane, unit);
+    if (whole > 0) front += sizeOf(unit);
+    else if (whole < 0) back += sizeOf(unit);
+    else {
+      const parts = unit.facets.map((facet) => split(plane, facet));
+      const ahead = parts.filter((part) => part.front !== undefined).length;
+      const behind = parts.filter((part) => part.back !== undefined).length;
+      if (ahead > 0 && behind > 0) cut++;
+      front += ahead;
+      back += behind;
+    }
+  }
+  return splitCost * cut + Math.abs(front - back);
+};
+
+const partition = <T>(plane: Plane, units: ReadonlyArray<Unit<T>>): Partition<T> => {
+  const front: Array<Unit<T>> = [];
+  const back: Array<Unit<T>> = [];
+  const on: Array<Facet<T>> = [];
+  for (const unit of units) {
+    const whole = sideOf(plane, unit);
+    if (whole > 0) front.push(unit);
+    else if (whole < 0) back.push(unit);
+    else {
+      const ahead: Array<Facet<T>> = [];
+      const behind: Array<Facet<T>> = [];
+      for (const facet of unit.facets) {
+        const parts = split(plane, facet);
+        if (parts.front !== undefined) ahead.push(parts.front);
+        if (parts.back !== undefined) behind.push(parts.back);
+        if (parts.on !== undefined) on.push(parts.on);
+      }
+      const marksAhead = unit.marks.filter((mark) => side(plane, mark.at) >= 0);
+      const marksBehind = unit.marks.filter((mark) => side(plane, mark.at) < 0);
+      // A part of an object is bounded by the whole, and keeps its order.
+      if (ahead.length + marksAhead.length > 0)
+        front.push({ ...unit, facets: ahead, marks: marksAhead });
+      if (behind.length + marksBehind.length > 0)
+        back.push({ ...unit, facets: behind, marks: marksBehind });
+    }
+  }
+  return { front, back, on };
+};
+
+/** The plane of one of a few facets spread over the units: the one that weighs least. */
+const planeFor = <T>(units: ReadonlyArray<Unit<T>>): Plane | undefined => {
+  const withFacets = units.filter((unit) => unit.facets.length > 0);
+  const count = Math.min(candidates, withFacets.length);
+  let best: Plane | undefined;
+  let lightest = Number.POSITIVE_INFINITY;
+  for (let i = 0; i < count; i++) {
+    const unit = withFacets[Math.floor((i * withFacets.length) / count)];
+    const facet = unit?.facets[Math.floor((i * (unit?.facets.length ?? 0)) / count)];
+    const plane = facet === undefined ? undefined : planeOf(facet.points);
+    if (plane === undefined) continue;
+    const weight = weigh(plane, units);
+    if (weight < lightest) {
+      lightest = weight;
+      best = plane;
+    }
+  }
+  if (best !== undefined) return best;
+  // Every one weighed has no area: any facet that has one.
+  for (const unit of withFacets) {
+    for (const facet of unit.facets) {
+      const plane = planeOf(facet.points);
+      if (plane !== undefined) return plane;
+    }
+  }
+  return undefined;
+};
+
+const distanceFrom =
+  (eye: Vector3) =>
+  <T>(mark: Mark<T>): number =>
+    mark.at.distanceToSquared(eye);
+
+/** Each facet of a unit as a unit of its own, and each mark: for a unit that is not self-ordered. */
+const apart = <T>(unit: Unit<T>): ReadonlyArray<Unit<T>> => [
+  ...unit.facets.map((facet) => ({
+    facets: [facet],
+    marks: [],
+    bounds: new Sphere().setFromPoints([...facet.points]),
+    selfOrdered: true,
+  })),
+  ...unit.marks.map((mark) => ({
+    facets: [],
+    marks: [mark],
+    bounds: new Sphere(mark.at.clone(), 0),
+    selfOrdered: true,
+  })),
+];
+
+/** Appends what `units` draw to `into`, farthest from `eye` first. */
+const paint = <T>(
+  units: ReadonlyArray<Unit<T>>,
+  eye: Vector3,
+  into: Array<Facet<T> | Mark<T>>,
+): void => {
+  const [only] = units;
+  if (only !== undefined && units.length === 1) {
+    if (only.selfOrdered && only.marks.length === 0) {
+      into.push(...only.facets);
+      return;
+    }
+    if (only.facets.length === 0) {
+      into.push(...only.marks.toSorted((a, b) => distanceFrom(eye)(b) - distanceFrom(eye)(a)));
+      return;
+    }
+    paint(apart(only), eye, into);
+    return;
+  }
+  const plane = planeFor(units);
+  if (plane === undefined) {
+    const marks = units.flatMap((unit) => unit.marks);
+    into.push(...marks.toSorted((a, b) => distanceFrom(eye)(b) - distanceFrom(eye)(a)));
+    return;
+  }
+  const { front, back, on } = partition(plane, units);
+  const facing = side(plane, eye) >= 0;
+  paint(facing ? back : front, eye, into);
+  into.push(...on);
+  paint(facing ? front : back, eye, into);
+};
+
+/** What `units` draw, in the order to paint it seen from `eye`: farthest first. */
+export const paintOrder = <T>(
+  units: ReadonlyArray<Unit<T>>,
+  eye: Vector3,
+): ReadonlyArray<Facet<T> | Mark<T>> => {
+  const into: Array<Facet<T> | Mark<T>> = [];
+  paint(units, eye, into);
+  return into;
+};

package/src/kernel/physics.ts

@@ -145,10 +145,95 @@ export type PhysicsWorld = {
   /** Whether any dynamic body is still moving (not asleep). */
   readonly awake: () => boolean;
   readonly dispose: () => void;
+  /**
+   * For a world that does what it is asked elsewhere (in a worker, ADR-017): the
+   * collisions that have come back since the last call, and whether anything it was asked
+   * is still to come back. Until it has, `pose`, `contactForces` and `debugLines` are as
+   * of what has, and `step` returns no collisions. The scene graph takes it every frame,
+   * and reports a world on `until` as there only once nothing is pending, so its checksum
+   * is of the engine's own poses. Absent for a world that does what it is asked at once.
+   */
+  readonly received?: () => Received;
+  /**
+   * The world as it is between steps, for `PhysicsEngine.restoreWorld` to make again:
+   * every body, collider and joint, and whatever the engine carries from step to step.
+   * A world working elsewhere gives `undefined` until it has the snapshot it asked for
+   * (`received` is pending meanwhile). Absent for an engine that cannot.
+   */
+  readonly snapshot?: () => Uint8Array | undefined;
+};
+
+/** What a world stepping elsewhere has sent back (`PhysicsWorld.received`). */
+export type Received = {
+  readonly collisions: ReadonlyArray<Collision>;
+  readonly pending: boolean;
+};
+
+/**
+ * A world made from a snapshot, and what it holds already: the ids of its bodies and of
+ * its joints, which the scene graph takes on rather than adding again.
+ */
+export type RestoredWorld = {
+  readonly world: PhysicsWorld;
+  readonly bodies: ReadonlyArray<string>;
+  readonly joints: ReadonlyArray<string>;
 };
 
 /** Makes physics worlds. Provide one to the scene graph (in Foldkit, the environment). */
-export type PhysicsEngine = { readonly createWorld: (physics: Physics) => PhysicsWorld };
+export type PhysicsEngine = {
+  readonly createWorld: (physics: Physics) => PhysicsWorld;
+  /**
+   * Makes a world from a snapshot one of this engine's worlds took (`snapshot`), as it
+   * was then, for `physics({ from })`. Absent for an engine that cannot.
+   */
+  readonly restoreWorld?: (physics: Physics, snapshot: Uint8Array) => RestoredWorld;
+};
+
+/** `count` characters from `first` on. */
+const run = (first: string, count: number): ReadonlyArray<string> =>
+  Array.from({ length: count }, (_, i) => String.fromCharCode(first.charCodeAt(0) + i));
+
+/** Base64's digits, in order. */
+const digits: ReadonlyArray<string> = [...run('A', 26), ...run('a', 26), ...run('0', 10), '+', '/'];
+const digitValues = new Map(digits.map((char, i) => [char, i]));
+const digit = (value: number): string => digits[value] ?? '';
+
+/** A snapshot as text (base64), as `PhysicsReached` carries it and a message can. */
+export const snapshotText = (bytes: Uint8Array): string => {
+  const out: Array<string> = [];
+  for (let at = 0; at < bytes.length; at += 3) {
+    const a = bytes[at] ?? 0;
+    const b = bytes[at + 1] ?? 0;
+    const c = bytes[at + 2] ?? 0;
+    const left = bytes.length - at;
+    out.push(
+      digit(a >> 2),
+      digit(((a & 3) << 4) | (b >> 4)),
+      left > 1 ? digit(((b & 15) << 2) | (c >> 6)) : '=',
+      left > 2 ? digit(c & 63) : '=',
+    );
+  }
+  return out.join('');
+};
+
+/** The bytes of a snapshot written by `snapshotText`. */
+export const snapshotBytes = (text: string): Uint8Array => {
+  const digits = text.replace(/=+$/, '');
+  const bytes = new Uint8Array(Math.floor((digits.length * 3) / 4));
+  let bits = 0;
+  let held = 0;
+  let at = 0;
+  for (const char of digits) {
+    bits = (bits << 6) | (digitValues.get(char) ?? 0);
+    held += 6;
+    if (held >= 8) {
+      held -= 8;
+      bytes[at] = (bits >> held) & 255;
+      at += 1;
+    }
+  }
+  return bytes;
+};
 
 const toVec3 = (vector: Vector3): Vec3 => [vector.x, vector.y, vector.z];
 

package/src/kernel/pointer.ts

@@ -26,10 +26,15 @@ export type Modifiers = {
   readonly alt: boolean;
 };
 
+/** What pressed: `PointerEvent.pointerType`. A finger is less steady than a mouse or pen. */
+export type PointerDevice = 'mouse' | 'pen' | 'touch';
+
 /**
  * Pointer input in normalised device coordinates. `button` follows `MouseEvent.button`.
  * `pointer` is the input's `PointerEvent.pointerId` (0 when absent): with two pointers
- * pressed (two fingers), the second only takes part in pinches.
+ * pressed (two fingers), the second only takes part in pinches. A press's `device` is
+ * what pressed (a mouse when absent); it decides how far a press may travel and still be
+ * a click on nothing.
  */
 export type PointerInput =
   | {
@@ -45,6 +50,7 @@ export type PointerInput =
       readonly button: number;
       readonly pointer?: number;
       readonly modifiers?: Modifiers;
+      readonly device?: PointerDevice;
     }
   | {
       readonly _tag: 'PointerUp';
@@ -285,6 +291,19 @@ export type SceneEvent =
       readonly maxForceDirection: Vec3;
       readonly maxForceMagnitude: number;
     }
+  /**
+   * A world on `physics({ until })` reached that step and waits there: its run, its
+   * step count, and a checksum of every body's pose, which peers running the same inputs
+   * share (ADR-014). It comes after the collisions of the steps that led there. At
+   * `physics({ snapshotAt })` it carries a snapshot of the world, to start another `from`.
+   */
+  | {
+      readonly _tag: 'PhysicsReached';
+      readonly run: number;
+      readonly step: number;
+      readonly checksum: string;
+      readonly snapshot?: string;
+    }
   /**
    * A measured label's laid-out size changed (`scene({ measure })`, after its glyphs are
    * laid out): in its own units, before its scale, for sizing what goes behind it, as
@@ -530,14 +549,24 @@ export type PointerTracker = {
 
 const none: ReadonlyArray<SceneEvent> = [];
 
-/** A click moving further than this, in CSS pixels, is a drag and never a miss. */
-const missTolerance = 2;
+/**
+ * How far, in CSS pixels, a press on nothing may travel and still be a miss rather than a
+ * drag. React Three Fiber allows 2 (`events.ts`, `delta <= 2`, at pinned `d74622e`), but
+ * measures it on the browser's `click`, which a browser only synthesises from a tap that
+ * kept within its own, larger touch slop. This kernel works from pointer down and up, so
+ * it gives a finger its own allowance: a steady tap wanders a few pixels, a drag far more.
+ */
+const missTolerances = { mouse: 2, pen: 2, touch: 10 } as const satisfies Record<
+  PointerDevice,
+  number
+>;
 
 type Press = {
   readonly key: string | undefined;
   readonly button: number;
   readonly x: number;
   readonly y: number;
+  readonly device: PointerDevice;
 };
 
 /** The press a gesture began with: its button, modifiers, mesh and region. */
@@ -599,7 +628,10 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
       }
       return;
     }
-    if (from?.button === event.button && travel(from, event.x, event.y) <= missTolerance) {
+    if (
+      from?.button === event.button &&
+      travel(from, event.x, event.y) <= missTolerances[from.device]
+    ) {
       events.push({ _tag: 'PointerMissed', button: event.button });
     }
   };
@@ -781,7 +813,13 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
         moveGesture(id, event, events);
         break;
       case 'PointerDown':
-        press = { key: hit?.key, button: event.button, x: event.x, y: event.y };
+        press = {
+          key: hit?.key,
+          button: event.button,
+          x: event.x,
+          y: event.y,
+          device: event.device ?? 'mouse',
+        };
         pressing = true;
         dragged = false;
         if (hit !== undefined) events.push({ _tag: 'PointerDown', button: event.button, ...hit });