@opsydyn/effect-three 0.3.0 → 0.6.4

package/src/kernel/lockstep.ts

@@ -0,0 +1,237 @@
+/**
+ * Lockstep, as data (roadmap, "Beyond parity" 2): peers that run the same `update` stay
+ * in the same state by applying the same inputs in the same order. Time is cut into
+ * turns; every member sends one packet for each turn (empty when it did nothing), and a
+ * turn applies only once every member's packet for it has arrived, its inputs in peer
+ * order. Any transport that delivers each packet to every peer will do: a
+ * `BroadcastChannel` between tabs, a socket relay between machines.
+ *
+ * Membership changes in step too. The leader (the member whose id sorts first) admits
+ * a newcomer with an entry in its own packet; when that turn applies, everywhere at
+ * once, the newcomer becomes a member `lead + 1` turns later, and the leader sends it
+ * the state as it is then (`welcomeDue`), from which it carries on. A member that leaves
+ * says which turn it sent last (`leave`); one that goes quiet is dropped by the leader
+ * from the turn everyone is waiting on, which no one can have applied.
+ *
+ * Pure functions over a value, like the rest of the kernel: an app keeps the `Lockstep`
+ * in its Model, sends what `send` gives it, passes what arrives to `receive`, and
+ * applies what `advance` returns. Use it as a namespace: `Lockstep.make(self)`.
+ *
+ * @module
+ */
+
+/** What a turn carries: an app's input, or the leader admitting a newcomer. */
+export type Entry<I> =
+  | { readonly _tag: 'Input'; readonly input: I }
+  | { readonly _tag: 'Admit'; readonly peer: string };
+
+/** One member's packet for one turn. */
+export type Packet<I> = {
+  readonly peer: string;
+  readonly turn: number;
+  readonly entries: ReadonlyArray<Entry<I>>;
+};
+
+/** A member: the first turn it sends for, and the turn it stopped before, once it has. */
+export type Member = {
+  readonly peer: string;
+  readonly from: number;
+  readonly until: number | null;
+};
+
+export type Lockstep<I> = {
+  readonly self: string;
+  readonly members: ReadonlyArray<Member>;
+  /** The next turn to apply. */
+  readonly turn: number;
+  /** The next turn this peer sends for. */
+  readonly sent: number;
+  /** How many turns ahead of the applied one a peer may send: inputs wait this long. */
+  readonly lead: number;
+  /** Entries waiting for this peer's next packet. */
+  readonly pending: ReadonlyArray<Entry<I>>;
+  /** Packets for turns not yet applied, this peer's own among them. */
+  readonly received: ReadonlyArray<Packet<I>>;
+};
+
+/** An input applied: the turn, and the peer it came from. */
+export type Applied<I> = { readonly turn: number; readonly peer: string; readonly input: I };
+
+const sortedPeers = (members: ReadonlyArray<Member>): ReadonlyArray<Member> =>
+  members.toSorted((a, b) => (a.peer < b.peer ? -1 : a.peer > b.peer ? 1 : 0));
+
+const memberAt = (member: Member, turn: number): boolean =>
+  member.from <= turn && (member.until === null || turn < member.until);
+
+/** The members a turn waits for, in the order their inputs apply. */
+export const membersAt = <I>(state: Lockstep<I>, turn: number): ReadonlyArray<string> =>
+  sortedPeers(state.members.filter((member) => memberAt(member, turn))).map(
+    (member) => member.peer,
+  );
+
+/** The member who admits and drops others at `turn`: the one whose id sorts first. */
+export const leaderAt = <I>(state: Lockstep<I>, turn: number): string | undefined =>
+  membersAt(state, turn)[0];
+
+/** A session of one: this peer alone, from turn 0. */
+export const make = <I>(self: string, lead = 2): Lockstep<I> => ({
+  self,
+  members: [{ peer: self, from: 0, until: null }],
+  turn: 0,
+  sent: 0,
+  lead,
+  pending: [],
+  received: [],
+});
+
+/**
+ * A newcomer's session, from the leader's welcome: the members and the turn it starts
+ * at, with whatever packets it heard while it waited.
+ */
+export const join = <I>(
+  self: string,
+  welcome: {
+    readonly turn: number;
+    readonly members: ReadonlyArray<Member>;
+    readonly lead: number;
+  },
+  heard: ReadonlyArray<Packet<I>> = [],
+): Lockstep<I> => ({
+  self,
+  members: welcome.members,
+  turn: welcome.turn,
+  sent: welcome.turn,
+  lead: welcome.lead,
+  pending: [],
+  received: heard.filter((packet) => packet.turn >= welcome.turn),
+});
+
+/** `input` waits for this peer's next packet. */
+export const submit = <I>(state: Lockstep<I>, input: I): Lockstep<I> => ({
+  ...state,
+  pending: [...state.pending, { _tag: 'Input', input }],
+});
+
+const known = <I>(state: Lockstep<I>, peer: string): boolean =>
+  state.members.some((member) => member.peer === peer && member.until === null) ||
+  state.pending.some((entry) => entry._tag === 'Admit' && entry.peer === peer);
+
+/** The leader asks for `peer` to be admitted; anyone else, or a known peer, changes nothing. */
+export const admit = <I>(state: Lockstep<I>, peer: string): Lockstep<I> =>
+  leaderAt(state, state.sent) !== state.self || known(state, peer)
+    ? state
+    : { ...state, pending: [...state.pending, { _tag: 'Admit', peer }] };
+
+const hasPacket = <I>(state: Lockstep<I>, peer: string, turn: number): boolean =>
+  state.received.some((packet) => packet.peer === peer && packet.turn === turn);
+
+/**
+ * A packet arriving: kept until its turn applies. Ones for turns already applied, from
+ * peers not members then, and second copies are dropped.
+ */
+export const receive = <I>(state: Lockstep<I>, packet: Packet<I>): Lockstep<I> => {
+  if (packet.turn < state.turn || hasPacket(state, packet.peer, packet.turn)) return state;
+  const member = state.members.find((each) => each.peer === packet.peer);
+  if (member !== undefined && !memberAt(member, packet.turn)) return state;
+  return { ...state, received: [...state.received, packet] };
+};
+
+/**
+ * This peer's packet for its next turn, with what is pending, when it is a member then
+ * and not more than `lead` turns ahead; it keeps its own copy.
+ */
+export const send = <I>(
+  state: Lockstep<I>,
+): { readonly state: Lockstep<I>; readonly packet: Packet<I> | undefined } => {
+  const member = state.members.find((each) => each.peer === state.self);
+  const ahead = state.sent >= state.turn + state.lead;
+  if (member === undefined || !memberAt(member, state.sent) || ahead) {
+    return { state, packet: undefined };
+  }
+  const packet: Packet<I> = { peer: state.self, turn: state.sent, entries: state.pending };
+  return {
+    state: { ...state, sent: state.sent + 1, pending: [], received: [...state.received, packet] },
+    packet,
+  };
+};
+
+/** Peers whose packet for the next turn has not arrived: what the session waits on. */
+export const waitingOn = <I>(state: Lockstep<I>): ReadonlyArray<string> =>
+  membersAt(state, state.turn).filter((peer) => !hasPacket(state, peer, state.turn));
+
+/** `peer`'s packet for `turn`, as a list of none or one. */
+const packetsOf = <I>(state: Lockstep<I>, peer: string, turn: number): ReadonlyArray<Packet<I>> =>
+  state.received.filter((packet) => packet.peer === peer && packet.turn === turn);
+
+/** One turn applied, its admissions made members `lead + 1` turns on. */
+const applyTurn = <I>(
+  state: Lockstep<I>,
+): { state: Lockstep<I>; applied: ReadonlyArray<Applied<I>> } => {
+  const turn = state.turn;
+  const packets = membersAt(state, turn).flatMap((peer) => packetsOf(state, peer, turn));
+  const entries = packets.flatMap((packet) =>
+    packet.entries.map((entry) => ({ peer: packet.peer, entry })),
+  );
+  const admitted = entries.flatMap(({ entry }) =>
+    entry._tag === 'Admit' && !state.members.some((member) => member.peer === entry.peer)
+      ? [{ peer: entry.peer, from: turn + state.lead + 1, until: null }]
+      : [],
+  );
+  const applied = entries.flatMap(({ peer, entry }) =>
+    entry._tag === 'Input' ? [{ turn, peer, input: entry.input }] : [],
+  );
+  return {
+    state: {
+      ...state,
+      turn: turn + 1,
+      members: [...state.members, ...admitted],
+      received: state.received.filter((packet) => packet.turn > turn),
+    },
+    applied,
+  };
+};
+
+/**
+ * Every turn whose packets have all arrived, applied in order: the new state, and the
+ * inputs to apply to the app, oldest first and in peer order within a turn.
+ */
+export const advance = <I>(
+  state: Lockstep<I>,
+): { readonly state: Lockstep<I>; readonly applied: ReadonlyArray<Applied<I>> } => {
+  let current = state;
+  const applied: Array<Applied<I>> = [];
+  // A turn with no members waits forever rather than passing unheard.
+  while (membersAt(current, current.turn).length > 0 && waitingOn(current).length === 0) {
+    const next = applyTurn(current);
+    current = next.state;
+    applied.push(...next.applied);
+  }
+  return { state: current, applied };
+};
+
+/**
+ * Newcomers this peer, as leader, should welcome now: those who become members at the
+ * turn about to apply, once every turn before it has (the state is then theirs to start
+ * from). Each is due once: at the moment `before` (the previous turn) is passed.
+ */
+export const welcomeDue = <I>(before: number, state: Lockstep<I>): ReadonlyArray<string> =>
+  state.members
+    .filter((member) => member.from > before && member.from <= state.turn)
+    // The leader of the turn before the newcomer counts: never the newcomer itself, whose
+    // id may sort first.
+    .filter((member) => leaderAt(state, member.from - 1) === state.self)
+    .map((member) => member.peer);
+
+/** This peer leaving: the turn it sent last, for the others to stop waiting after. */
+export const leave = <I>(state: Lockstep<I>): number => state.sent - 1;
+
+/** `peer` stops being a member from `until`; its packets from then are dropped. */
+export const remove = <I>(state: Lockstep<I>, peer: string, until: number): Lockstep<I> => ({
+  ...state,
+  members: state.members.map((member) =>
+    member.peer === peer && (member.until === null || until < member.until)
+      ? { ...member, until }
+      : member,
+  ),
+  received: state.received.filter((packet) => packet.peer !== peer || packet.turn < until),
+});

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) {
@@ -215,6 +217,11 @@ export const createSceneLoop = (options: SceneLoopOptions): SceneLoop => {
       const views = graph.views();
       if (views.length === 0) renderer.render(graph.scene, graph.camera);
       for (const view of views) renderer.render(graph.scene, view.camera, view.area);
+      const hud = graph.hud();
+      if (hud !== undefined && renderer.renderOver !== undefined) {
+        renderer.renderOver(hud.graph.scene, hud.graph.camera);
+        hud.graph.drawn();
+      }
       graph.drawn();
       measure();
       const overlays = graph.overlays();

package/src/kernel/materials.ts

@@ -108,6 +108,9 @@ const applyBasic = (
   textures: Textures,
 ): void => {
   material.color.setHex(description.color);
+  // Drawn over everything when not depth-tested, and leaving no depth behind.
+  material.depthTest = description.depthTest;
+  material.depthWrite = description.depthTest;
   const mapChanged = applyMap(material, description.map, textures);
   if (applySurface(material, description) || mapChanged) material.needsUpdate = true;
 };

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];