@driftengine/core 3.61.0

package/src/math/scalar.ts

@@ -0,0 +1,109 @@
+export const TAU = Math.PI * 2;
+export const DEG_TO_RAD = Math.PI / 180;
+
+export function clamp(value: number, min: number, max: number): number {
+  return value < min ? min : value > max ? max : value;
+}
+
+export function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}
+
+/** Hermite interpolation between two edges: 0 below `a`, 1 above `b`. */
+export function smoothstep(a: number, b: number, x: number): number {
+  const t = clamp((x - a) / (b - a), 0, 1);
+  return t * t * (3 - 2 * t);
+}
+
+/**
+ * Framerate-independent exponential approach of `a` toward `b`.
+ * `lambda` is the convergence rate in 1/seconds (higher = snappier).
+ */
+export function damp(a: number, b: number, lambda: number, dt: number): number {
+  /*
+   * **Presentation smoothing, which is why the marker is here and not a rewrite.** `damp`,
+   * `dampAngle` and `dampTracking` converge a *drawn* value toward a target over wall-clock
+   * seconds: a camera following a car, a dial settling. `scripts/determinism.mjs` refuses `Math.exp`
+   * inside the simulation set because ECMAScript does not specify it, and that refusal is right for
+   * anything a tick's state depends on — but none of these three is that.
+   *
+   * **What a simulation wants instead**, if it ever wants exponential approach inside the fixed
+   * step, is a per-tick factor computed once from `lambda` and the fixed `dt` and passed in as a
+   * number: at a constant step the factor is a constant, so nothing has to call `exp` on a tick at
+   * all. `exactExp` in `math/exact.ts` is the other answer, and is the one to reach for when the
+   * rate itself varies.
+   */
+  // determinism: build-time — presentation smoothing; see the note above for a simulation
+  return lerp(a, b, 1 - Math.exp(-lambda * dt));
+}
+
+/**
+ * Exponential approach of `a` toward a target that is itself **moving**, at `velocity`.
+ *
+ * `damp` above is `lerp(a, b, 1 - exp(-lambda dt))`, which is the exact solution of
+ * `a' = lambda (b - a)` for a `b` that holds still across the interval — a zero-order hold. For a
+ * target that is moving it is wrong in two ways that both show up as the frame rate changes,
+ * because the error is a function of `dt`:
+ *
+ * - the settled gap becomes `v dt (1-k)/k` for `k = 1 - exp(-lambda dt)`, which *shrinks as the
+ *   frame time grows*, so a machine that drops rate quietly re-frames the shot;
+ * - and under uneven frames the gap oscillates rather than settling at all.
+ *
+ * This solves the same equation for `b(t) = b - v (dt - t)`, a target arriving at `b` having
+ * travelled at `v`. Substituting `e = a - b` gives `e' = -lambda e - v`, whose solution is
+ * `e(t) = (e0 + v/lambda) exp(-lambda t) - v/lambda` — so the settled gap is `v/lambda` at every
+ * rate and there is nothing left for jitter to move. `b` is the target **now**, at the end of the
+ * interval, which is what a caller has.
+ *
+ * **What it costs is a velocity the caller has to supply**, and a caller that passes zero gets
+ * `damp` back exactly. A finite difference of the target over the frame is the usual source and is
+ * exact for a target that is moving smoothly; what it is not good for is a target that *steps*,
+ * where one frame of `delta/dt` is a spike and this will aim `v/lambda` ahead of it.
+ *
+ * Zero or negative `lambda` returns `a` rather than dividing by it. The limit as `lambda` goes to
+ * zero is `a` — no pull, no movement — so the guard agrees with the arithmetic rather than merely
+ * avoiding an infinity.
+ */
+export function dampTracking(
+  a: number,
+  b: number,
+  velocity: number,
+  lambda: number,
+  dt: number,
+): number {
+  if (lambda <= 0) return a;
+  const lag = velocity / lambda;
+  // determinism: build-time — presentation smoothing, like `damp`; see the note there
+  return b - lag + (a - b + lag + velocity * dt) * Math.exp(-lambda * dt);
+}
+
+/** Signed shortest angular distance from `a` to `b`, in (-π, π]. */
+export function angleDelta(a: number, b: number): number {
+  let d = (b - a) % TAU;
+  if (d > Math.PI) d -= TAU;
+  if (d < -Math.PI) d += TAU;
+  return d;
+}
+
+/**
+ * Fold an angle into (-π, π]. Simulation state uses this so a long session
+ * cannot accumulate an unbounded angle and lose float precision. Anything
+ * replaying a recorded session depends on staying bit-stable over its length.
+ */
+export function wrapAngle(a: number): number {
+  let w = a % TAU;
+  if (w > Math.PI) w -= TAU;
+  if (w <= -Math.PI) w += TAU;
+  return w;
+}
+
+/** `lerp` along the shortest arc — the angular counterpart for render interpolation. */
+export function lerpAngle(a: number, b: number, t: number): number {
+  return a + angleDelta(a, b) * t;
+}
+
+/** `damp` along the shortest arc between two angles. */
+export function dampAngle(a: number, b: number, lambda: number, dt: number): number {
+  // determinism: build-time — presentation smoothing; see `damp`
+  return a + angleDelta(a, b) * (1 - Math.exp(-lambda * dt));
+}

package/src/math/spring.ts

@@ -0,0 +1,106 @@
+import { angleDelta, wrapAngle } from './scalar.ts';
+
+/**
+ * A critically damped spring: a value that *accelerates* toward a target and
+ * settles on it.
+ *
+ * The counterpart to `damp`, and the difference is the whole reason this exists.
+ * `damp` is a first-order lag: its speed is proportional to the error it has
+ * already accumulated, so it is fastest on the first frame of a move and
+ * asymptotic for the rest of it. It cannot ease in, cannot settle, and — the
+ * part that bites — cannot follow a *moving* target without falling behind,
+ * because the only way it can travel at the target's speed is to build up an
+ * error of `speed / lambda` and hold it. A replay camera damping onto a character
+ * at 14 m/s was measured framing every shot 2.2 m further out than the shot
+ * asked for, and re-accumulating that error as a straight slide after every cut.
+ *
+ * This carries a velocity, so it has an acceleration profile — it leads into a
+ * move and comes to rest at the end of one — and it is stepped against the
+ * target's *own* velocity, so a target moving smoothly is ridden along with at
+ * zero steady-state error rather than trailed.
+ *
+ * Long-lived and stateful by nature, hence a class: one per axis, constructed
+ * once and mutated in place, so a per-frame caller allocates nothing.
+ */
+export class Spring {
+  value = 0;
+  velocity = 0;
+
+  /** Place the spring, with no motion unless one is given. Use on a cut. */
+  reset(value: number, velocity = 0): void {
+    this.value = value;
+    this.velocity = velocity;
+  }
+
+  /**
+   * Step toward `target`, which is itself travelling at `targetVelocity`.
+   *
+   * `rate` is the convergence rate in 1/seconds, as `damp`'s lambda is — higher
+   * is tighter — though the two are not numerically interchangeable: a spring at
+   * the same figure is gentler, because it spends the start of a move
+   * accelerating rather than covering ground.
+   */
+  step(target: number, targetVelocity: number, rate: number, dt: number): number {
+    this.advance(
+      this.value - startOf(target, targetVelocity, dt),
+      target,
+      targetVelocity,
+      rate,
+      dt,
+    );
+    return this.value;
+  }
+
+  /**
+   * The same, along the shortest arc, for angles. The value stays folded into
+   * (-π, π] so a long session cannot accumulate an unbounded angle.
+   */
+  stepAngle(target: number, targetVelocity: number, rate: number, dt: number): number {
+    const from = startOf(target, targetVelocity, dt);
+    this.advance(-angleDelta(this.value, from), target, targetVelocity, rate, dt);
+    this.value = wrapAngle(this.value);
+    return this.value;
+  }
+
+  /**
+   * The analytic solution of `e'' = -ω²e - 2ωe'` over one step, in the target's
+   * own frame of reference — which is what makes a moving target free of lag,
+   * and only if the error going in is measured in that same frame. See
+   * `startOf`: solving from an error taken against where the target has *got to*
+   * while integrating to where it is *going* leaves a step's worth of target
+   * motion unaccounted for every frame, which converges on twice the target's
+   * velocity and 2V/ω of standing error — 4.56 m of the 4.667 m predicted, in
+   * the first measurement taken of this.
+   *
+   * Solved rather than integrated because a spring stepped by Euler diverges
+   * once `ω·dt` approaches 1, and this runs on a frame that can be 250 ms long
+   * when a tab wakes up. `decay` stands in for `e^-x` with a rational
+   * approximation that stays inside (0, 1] for every non-negative x, so a long
+   * frame overshoots nothing — it just arrives.
+   */
+  private advance(
+    error: number,
+    target: number,
+    targetVelocity: number,
+    rate: number,
+    dt: number,
+  ): void {
+    const omega = rate > 0 ? rate : 0;
+    const relative = this.velocity - targetVelocity;
+    const x = omega * dt;
+    const decay = 1 / (1 + x + 0.48 * x * x + 0.235 * x * x * x);
+    const slope = relative + omega * error;
+    this.value = target + (error + slope * dt) * decay;
+    this.velocity = targetVelocity + (relative - omega * slope * dt) * decay;
+  }
+}
+
+/**
+ * Where a target travelling at `targetVelocity` was when this step began.
+ *
+ * `target` is where it has arrived, which is the natural thing for a caller to
+ * have and the wrong end of the step to measure an error against.
+ */
+function startOf(target: number, targetVelocity: number, dt: number): number {
+  return target - targetVelocity * dt;
+}

package/src/nav/navGraph.ts

@@ -0,0 +1,168 @@
+/**
+ * A graph to path over: nodes somewhere in the world, edges between them, and a cost per edge.
+ *
+ * **A graph rather than a navigation mesh, and that is a decision rather than a first step.** A
+ * mesh is what you build when walkable space is an arbitrary region and an agent may cross it
+ * anywhere; a graph is what you build when the ways through a world are *already* a network —
+ * roads, corridors, rails, docking lanes, the connections between rooms. Consumers of this engine
+ * keep arriving with the second: one reported that they extract a road graph from their world
+ * already and that their agents still walk straight at the target and wedge against a wall on the
+ * way, about once every two minutes of play. A mesh would have asked them to throw that away and
+ * start from geometry.
+ *
+ * What it costs is honest and worth saying at the top: **an agent on a graph travels along edges,
+ * so it takes corners the graph has and none it does not.** Open ground crossed by two nodes is
+ * crossed in one straight line. If a world's walkable space genuinely is a region, this is the
+ * wrong structure and a mesh is the row that is still open.
+ *
+ * **Structure of arrays, CSR adjacency, everything typed.** The search below runs inside a frame
+ * budget against a graph a consumer may rebuild when the world changes, so nothing here holds an
+ * object per node and nothing allocates during a query.
+ */
+
+export interface NavGraph {
+  /** xyz per node, in world units. */
+  readonly positions: Float32Array;
+  readonly nodeCount: number;
+  /** CSR offsets: node `i`'s edges are `[edgeStart[i], edgeStart[i + 1])`. Length `nodeCount + 1`. */
+  readonly edgeStart: Uint32Array;
+  /** The node at the far end of each edge. */
+  readonly edgeTarget: Uint32Array;
+  /** What each edge costs to traverse. Distance unless the caller said otherwise. */
+  readonly edgeCost: Float32Array;
+}
+
+export interface NavEdge {
+  readonly from: number;
+  readonly to: number;
+  /**
+   * What crossing it costs. Defaults to the distance between its ends.
+   *
+   * **A cost is not a distance and the difference is the whole of route quality.** Mud, a hill, a
+   * toll, a road an agent should prefer, a corridor it should avoid unless there is nothing else:
+   * all of them are this number, and a consumer that never sets it gets shortest-path behaviour.
+   * The one rule the search depends on is that a cost is **never less than the straight-line
+   * distance between the two ends** — see `navSearch`, where the heuristic that makes A* exact
+   * assumes exactly that. Faster-than-flying edges are refused at build time rather than producing
+   * a route that is quietly not the best one.
+   */
+  readonly cost?: number;
+  /** Whether it may also be crossed the other way. Default true. */
+  readonly bidirectional?: boolean;
+}
+
+/**
+ * Build the graph, checking the two things that make a wrong route look like a working one.
+ *
+ * An edge naming a node that does not exist, and an edge cheaper than flying: both produce a graph
+ * that searches happily and answers wrongly, one by reading past the end of an array and one by
+ * breaking the admissibility A* needs. Refused here, at build time, which is where this engine
+ * refuses things.
+ */
+export function buildNavGraph(
+  positions: Float32Array | readonly number[],
+  edges: readonly NavEdge[],
+): NavGraph {
+  const points = positions instanceof Float32Array ? positions : new Float32Array(positions);
+  if (points.length % 3 !== 0) {
+    throw new Error(`buildNavGraph: positions must be xyz-packed, got ${points.length} floats`);
+  }
+  const nodeCount = points.length / 3;
+  if (nodeCount === 0)
+    throw new Error('buildNavGraph: a graph with no nodes has nothing to path over');
+
+  const degree = new Uint32Array(nodeCount);
+  for (const edge of edges) {
+    check(edge.from, nodeCount, 'from');
+    check(edge.to, nodeCount, 'to');
+    degree[edge.from] = (degree[edge.from] ?? 0) + 1;
+    if (edge.bidirectional !== false) degree[edge.to] = (degree[edge.to] ?? 0) + 1;
+  }
+
+  const edgeStart = new Uint32Array(nodeCount + 1);
+  for (let i = 0; i < nodeCount; i++) edgeStart[i + 1] = (edgeStart[i] ?? 0) + (degree[i] ?? 0);
+  const total = edgeStart[nodeCount] ?? 0;
+  const edgeTarget = new Uint32Array(total);
+  const edgeCost = new Float32Array(total);
+
+  const cursor = new Uint32Array(nodeCount);
+  for (const edge of edges) {
+    const span = distance(points, edge.from, edge.to);
+    const cost = edge.cost ?? span;
+    if (!(cost >= span)) {
+      throw new Error(
+        `buildNavGraph: edge ${edge.from}->${edge.to} costs ${cost} over a span of ${span}. ` +
+          'A cost below the straight-line distance breaks the search heuristic and returns routes ' +
+          'that are not the cheapest, silently.',
+      );
+    }
+    write(edgeStart, cursor, edgeTarget, edgeCost, edge.from, edge.to, cost);
+    if (edge.bidirectional !== false) {
+      write(edgeStart, cursor, edgeTarget, edgeCost, edge.to, edge.from, cost);
+    }
+  }
+
+  return { positions: points, nodeCount, edgeStart, edgeTarget, edgeCost };
+}
+
+/**
+ * The node nearest a world position, or −1 for a graph with none in reach.
+ *
+ * **A linear scan, and the ceiling is stated rather than discovered.** A road network is hundreds
+ * of nodes and a scan over it is microseconds; a graph of tens of thousands wants a spatial index,
+ * and a consumer with one should keep their own and pass the answer to `navSearch` directly, which
+ * is why that function takes node indices and not positions.
+ *
+ * `maxDistance` is what stops an agent that has walked off the network being snapped onto the far
+ * side of the map. Absent means the nearest node however far away it is.
+ */
+export function nearestNavNode(
+  graph: NavGraph,
+  x: number,
+  y: number,
+  z: number,
+  maxDistance = Infinity,
+): number {
+  let best = -1;
+  let bestSquared = maxDistance === Infinity ? Infinity : maxDistance * maxDistance;
+  for (let i = 0; i < graph.nodeCount; i++) {
+    const dx = (graph.positions[i * 3] ?? 0) - x;
+    const dy = (graph.positions[i * 3 + 1] ?? 0) - y;
+    const dz = (graph.positions[i * 3 + 2] ?? 0) - z;
+    const squared = dx * dx + dy * dy + dz * dz;
+    /* Strictly nearer, so an exact tie keeps the lower index and two runs agree. */
+    if (squared < bestSquared) {
+      bestSquared = squared;
+      best = i;
+    }
+  }
+  return best;
+}
+
+function check(node: number, count: number, which: string): void {
+  if (!Number.isInteger(node) || node < 0 || node >= count) {
+    throw new Error(`buildNavGraph: edge ${which} is ${node}, which is not a node of ${count}`);
+  }
+}
+
+function distance(points: Float32Array, a: number, b: number): number {
+  const dx = (points[a * 3] ?? 0) - (points[b * 3] ?? 0);
+  const dy = (points[a * 3 + 1] ?? 0) - (points[b * 3 + 1] ?? 0);
+  const dz = (points[a * 3 + 2] ?? 0) - (points[b * 3 + 2] ?? 0);
+  return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+
+function write(
+  edgeStart: Uint32Array,
+  cursor: Uint32Array,
+  edgeTarget: Uint32Array,
+  edgeCost: Float32Array,
+  from: number,
+  to: number,
+  cost: number,
+): void {
+  const at = (edgeStart[from] ?? 0) + (cursor[from] ?? 0);
+  cursor[from] = (cursor[from] ?? 0) + 1;
+  edgeTarget[at] = to;
+  edgeCost[at] = cost;
+}

package/src/nav/navPath.ts

@@ -0,0 +1,217 @@
+import type { NavGraph } from './navGraph.ts';
+
+/**
+ * Following a route, which is the half of navigation that is not the search.
+ *
+ * **A path is a list of nodes and an agent is not.** Between the two sits a set of decisions every
+ * consumer makes and none of them enjoys: when has a waypoint been reached, what happens when the
+ * agent is pushed off the line, what does the last waypoint mean, and — the one that is always got
+ * wrong first — what do you steer *at*. Steering at the next node makes an agent visibly zigzag
+ * between waypoints on a curved road; steering at a point a fixed distance ahead *along* the path
+ * makes it cut the corner smoothly, and that is what this returns.
+ *
+ * **It does not move anything.** It answers where to aim, in world units, and the caller applies
+ * their own speed, acceleration, turn rate and physics — which is the same boundary
+ * `CharacterController` and `groundMotor` draw, and for the same reason: how a thing moves is the
+ * game's, where it should go is the engine's.
+ *
+ * Nothing here allocates and nothing reads a clock.
+ */
+export interface NavSteer {
+  /** Where to aim, in world units. */
+  x: number;
+  y: number;
+  z: number;
+  /** How far along the path is left, following the line rather than as the crow flies. */
+  remainingM: number;
+  /** True once the agent is within `arriveM` of the final node. */
+  arrived: boolean;
+}
+
+export function createNavSteer(): NavSteer {
+  return { x: 0, y: 0, z: 0, remainingM: 0, arrived: false };
+}
+
+export interface NavPathOptions {
+  /**
+   * How far ahead along the path to aim, metres.
+   *
+   * **The one number that decides whether following looks like driving or like a wind-up toy.**
+   * Short and the agent snaps at each waypoint in turn; long and it cuts corners so hard it leaves
+   * the road. A useful value is a little more than the agent's turning radius, and the default of
+   * two metres suits somebody walking.
+   */
+  readonly lookaheadM?: number;
+  /** Within this of the last node, the agent has arrived. Default half a metre. */
+  readonly arriveM?: number;
+}
+
+/**
+ * A route being walked: the nodes, and how far along them the agent is.
+ *
+ * **Progress is a distance along the path, not an index into it**, and that is what makes this
+ * survive an agent being shoved. An index only ever counts up when a waypoint is reached, so an
+ * agent knocked backwards past one keeps aiming at the waypoint behind it; a distance is recovered
+ * from the agent's own position every update, against the segment it is nearest to, so being pushed
+ * about costs progress and never correctness.
+ */
+export class NavPath {
+  private readonly graph: NavGraph;
+  private readonly lookaheadM: number;
+  private readonly arriveM: number;
+  /** Node indices of the route, and how many are live. */
+  private readonly nodes: Uint32Array;
+  private length = 0;
+  /** Cumulative distance to the start of each segment, so a lookahead is a lookup. */
+  private readonly distanceTo: Float64Array;
+  private total = 0;
+  /** Which segment the agent was on last update: where the search for the nearest one starts. */
+  private segment = 0;
+
+  constructor(graph: NavGraph, capacity: number, options: NavPathOptions = {}) {
+    if (!(capacity > 1)) throw new Error(`NavPath: capacity must be at least 2, got ${capacity}`);
+    this.graph = graph;
+    this.nodes = new Uint32Array(capacity);
+    this.distanceTo = new Float64Array(capacity);
+    this.lookaheadM = options.lookaheadM ?? 2;
+    this.arriveM = options.arriveM ?? 0.5;
+  }
+
+  get nodeCount(): number {
+    return this.length;
+  }
+
+  get lengthM(): number {
+    return this.total;
+  }
+
+  /** Whether there is a route to follow at all. */
+  get active(): boolean {
+    return this.length > 1;
+  }
+
+  /**
+   * Take a route, as `NavSearch.find` filled it.
+   *
+   * A route of one node is a route to where the agent already is, and is stored as no route: it
+   * has no direction to steer along and every caller would otherwise have to special-case it.
+   */
+  set(path: Uint32Array, count: number): void {
+    this.length = 0;
+    this.total = 0;
+    this.segment = 0;
+    if (count < 2) return;
+    const usable = Math.min(count, this.nodes.length);
+    this.nodes.set(path.subarray(0, usable));
+    this.length = usable;
+    this.distanceTo[0] = 0;
+    for (let i = 1; i < usable; i++) {
+      this.total += this.span(i - 1, i);
+      this.distanceTo[i] = this.total;
+    }
+  }
+
+  clear(): void {
+    this.length = 0;
+    this.total = 0;
+    this.segment = 0;
+  }
+
+  /**
+   * Where an agent at `(x, y, z)` should aim next.
+   *
+   * With no route, the agent is told to aim where it stands and that it has arrived, so a caller
+   * driving off `arrived` needs no separate check for having no path at all.
+   */
+  steer(x: number, y: number, z: number, out: NavSteer): void {
+    if (this.length < 2) {
+      out.x = x;
+      out.y = y;
+      out.z = z;
+      out.remainingM = 0;
+      out.arrived = true;
+      return;
+    }
+
+    /*
+     * Where the agent is, as a distance along the route. Searched over the whole path rather than
+     * forward from the last segment: an agent carried backwards — a lift, a shove, a vehicle it
+     * was standing on — is exactly the case a forward-only scan gets wrong, and a route is tens of
+     * nodes rather than thousands.
+     */
+    let bestSquared = Infinity;
+    let travelled = 0;
+    for (let i = 0; i + 1 < this.length; i++) {
+      const along = this.project(i, x, y, z);
+      const squared = this.distanceSquaredTo(i, along, x, y, z);
+      if (squared < bestSquared) {
+        bestSquared = squared;
+        travelled = (this.distanceTo[i] ?? 0) + along;
+        this.segment = i;
+      }
+    }
+
+    const remaining = this.total - travelled;
+    out.remainingM = remaining > 0 ? remaining : 0;
+    out.arrived = remaining <= this.arriveM;
+    /* Aim ahead along the line, clamped to the end: near the goal the target is the goal, which is
+       what stops an agent overshooting it to satisfy a lookahead. */
+    this.pointAt(Math.min(travelled + this.lookaheadM, this.total), out);
+  }
+
+  /** How far along segment `i` the point `(x, y, z)` projects, clamped to the segment. */
+  private project(i: number, x: number, y: number, z: number): number {
+    const ax = this.px(i);
+    const ay = this.py(i);
+    const az = this.pz(i);
+    const dx = this.px(i + 1) - ax;
+    const dy = this.py(i + 1) - ay;
+    const dz = this.pz(i + 1) - az;
+    const lengthSquared = dx * dx + dy * dy + dz * dz;
+    if (lengthSquared === 0) return 0;
+    let t = ((x - ax) * dx + (y - ay) * dy + (z - az) * dz) / lengthSquared;
+    if (t < 0) t = 0;
+    else if (t > 1) t = 1;
+    return t * Math.sqrt(lengthSquared);
+  }
+
+  private distanceSquaredTo(i: number, along: number, x: number, y: number, z: number): number {
+    const span = this.span(i, i + 1);
+    const t = span === 0 ? 0 : along / span;
+    const dx = this.px(i) + (this.px(i + 1) - this.px(i)) * t - x;
+    const dy = this.py(i) + (this.py(i + 1) - this.py(i)) * t - y;
+    const dz = this.pz(i) + (this.pz(i + 1) - this.pz(i)) * t - z;
+    return dx * dx + dy * dy + dz * dz;
+  }
+
+  /** The world point a given distance along the route. */
+  private pointAt(distance: number, out: NavSteer): void {
+    let i = this.segment;
+    while (i + 2 < this.length && (this.distanceTo[i + 1] ?? 0) < distance) i++;
+    const base = this.distanceTo[i] ?? 0;
+    const span = this.span(i, i + 1);
+    const t = span === 0 ? 0 : Math.min(1, Math.max(0, (distance - base) / span));
+    out.x = this.px(i) + (this.px(i + 1) - this.px(i)) * t;
+    out.y = this.py(i) + (this.py(i + 1) - this.py(i)) * t;
+    out.z = this.pz(i) + (this.pz(i + 1) - this.pz(i)) * t;
+  }
+
+  private span(a: number, b: number): number {
+    const dx = this.px(b) - this.px(a);
+    const dy = this.py(b) - this.py(a);
+    const dz = this.pz(b) - this.pz(a);
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+  }
+
+  private px(i: number): number {
+    return this.graph.positions[(this.nodes[i] ?? 0) * 3] ?? 0;
+  }
+
+  private py(i: number): number {
+    return this.graph.positions[(this.nodes[i] ?? 0) * 3 + 1] ?? 0;
+  }
+
+  private pz(i: number): number {
+    return this.graph.positions[(this.nodes[i] ?? 0) * 3 + 2] ?? 0;
+  }
+}