@driftengine/core 3.61.0

package/dist/math/scalar.d.ts

@@ -0,0 +1,51 @@
+export declare const TAU: number;
+export declare const DEG_TO_RAD: number;
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function lerp(a: number, b: number, t: number): number;
+/** Hermite interpolation between two edges: 0 below `a`, 1 above `b`. */
+export declare function smoothstep(a: number, b: number, x: number): number;
+/**
+ * Framerate-independent exponential approach of `a` toward `b`.
+ * `lambda` is the convergence rate in 1/seconds (higher = snappier).
+ */
+export declare function damp(a: number, b: number, lambda: number, dt: number): number;
+/**
+ * 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 declare function dampTracking(a: number, b: number, velocity: number, lambda: number, dt: number): number;
+/** Signed shortest angular distance from `a` to `b`, in (-π, π]. */
+export declare function angleDelta(a: number, b: number): number;
+/**
+ * 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 declare function wrapAngle(a: number): number;
+/** `lerp` along the shortest arc — the angular counterpart for render interpolation. */
+export declare function lerpAngle(a: number, b: number, t: number): number;
+/** `damp` along the shortest arc between two angles. */
+export declare function dampAngle(a: number, b: number, lambda: number, dt: number): number;

package/dist/math/scalar.js

@@ -0,0 +1,99 @@
+export const TAU = Math.PI * 2;
+export const DEG_TO_RAD = Math.PI / 180;
+export function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+export function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+/** Hermite interpolation between two edges: 0 below `a`, 1 above `b`. */
+export function smoothstep(a, b, x) {
+    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, b, lambda, dt) {
+    /*
+     * **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, b, velocity, lambda, dt) {
+    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, b) {
+    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) {
+    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, b, t) {
+    return a + angleDelta(a, b) * t;
+}
+/** `damp` along the shortest arc between two angles. */
+export function dampAngle(a, b, lambda, dt) {
+    // determinism: build-time — presentation smoothing; see `damp`
+    return a + angleDelta(a, b) * (1 - Math.exp(-lambda * dt));
+}

package/dist/math/spring.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 declare class Spring {
+    value: number;
+    velocity: number;
+    /** Place the spring, with no motion unless one is given. Use on a cut. */
+    reset(value: number, velocity?: number): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/dist/math/spring.js

@@ -0,0 +1,88 @@
+import { angleDelta, wrapAngle } from './scalar.js';
+/**
+ * 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, velocity = 0) {
+        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, targetVelocity, rate, dt) {
+        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, targetVelocity, rate, dt) {
+        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.
+     */
+    advance(error, target, targetVelocity, rate, dt) {
+        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, targetVelocity, dt) {
+    return target - targetVelocity * dt;
+}

package/dist/nav/navGraph.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 declare function buildNavGraph(positions: Float32Array | readonly number[], edges: readonly NavEdge[]): NavGraph;
+/**
+ * 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 declare function nearestNavNode(graph: NavGraph, x: number, y: number, z: number, maxDistance?: number): number;

package/dist/nav/navGraph.js

@@ -0,0 +1,111 @@
+/**
+ * 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.
+ */
+/**
+ * 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, edges) {
+    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, x, y, z, maxDistance = Infinity) {
+    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, count, which) {
+    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, a, b) {
+    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, cursor, edgeTarget, edgeCost, from, to, cost) {
+    const at = (edgeStart[from] ?? 0) + (cursor[from] ?? 0);
+    cursor[from] = (cursor[from] ?? 0) + 1;
+    edgeTarget[at] = to;
+    edgeCost[at] = cost;
+}

package/dist/nav/navPath.d.ts

@@ -0,0 +1,93 @@
+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 declare function createNavSteer(): NavSteer;
+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 declare class NavPath {
+    private readonly graph;
+    private readonly lookaheadM;
+    private readonly arriveM;
+    /** Node indices of the route, and how many are live. */
+    private readonly nodes;
+    private length;
+    /** Cumulative distance to the start of each segment, so a lookahead is a lookup. */
+    private readonly distanceTo;
+    private total;
+    /** Which segment the agent was on last update: where the search for the nearest one starts. */
+    private segment;
+    constructor(graph: NavGraph, capacity: number, options?: NavPathOptions);
+    get nodeCount(): number;
+    get lengthM(): number;
+    /** Whether there is a route to follow at all. */
+    get active(): boolean;
+    /**
+     * 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;
+    clear(): void;
+    /**
+     * 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;
+    /** How far along segment `i` the point `(x, y, z)` projects, clamped to the segment. */
+    private project;
+    private distanceSquaredTo;
+    /** The world point a given distance along the route. */
+    private pointAt;
+    private span;
+    private px;
+    private py;
+    private pz;
+}