@jgengine/core 0.7.0 → 0.9.0

package/dist/multiplayer/voiceContract.d.ts

@@ -0,0 +1,44 @@
+export interface VoiceParticipant {
+    userId: string;
+    streamId?: string;
+}
+export interface VoiceRoute {
+    fromUserId: string;
+    channelId: string;
+    gain: number;
+}
+/**
+ * Signaling seam for voice: who is in a channel and which media stream
+ * descriptor they published. The media plane (WebRTC, SFU, or anything else
+ * that moves audio bytes) stays behind this seam, host-supplied — the engine
+ * never touches it. subscribers delivers the channel roster on every change,
+ * starting with the current roster.
+ */
+export interface VoiceTransport {
+    join(channelId: string, streamId?: string): Promise<void>;
+    leave(channelId: string): Promise<void>;
+    publish(channelId: string, streamId: string): Promise<void>;
+    subscribers(channelId: string, onChange: (participants: readonly VoiceParticipant[]) => void): () => void;
+}
+export declare function createLocalVoiceTransport(options?: {
+    userId?: string;
+}): {
+    transport: VoiceTransport;
+    participants(channelId: string): readonly VoiceParticipant[];
+};
+export type PushToTalkMode = "hold" | "toggle" | "openMic";
+export type PushToTalkStatus = "idle" | "keyed" | "open";
+export interface PushToTalk {
+    mode(): PushToTalkMode;
+    setMode(mode: PushToTalkMode): void;
+    keyDown(): void;
+    keyUp(): void;
+    muted(): boolean;
+    setMuted(muted: boolean): void;
+    status(): PushToTalkStatus;
+    transmitting(): boolean;
+}
+export declare function createPushToTalk(config?: {
+    mode?: PushToTalkMode;
+    onChange?: (transmitting: boolean) => void;
+}): PushToTalk;

package/dist/multiplayer/voiceContract.js

@@ -0,0 +1,108 @@
+export function createLocalVoiceTransport(options) {
+    const userId = options?.userId ?? "local";
+    const rosters = new Map();
+    const listeners = new Map();
+    function roster(channelId) {
+        let entries = rosters.get(channelId);
+        if (entries === undefined) {
+            entries = new Map();
+            rosters.set(channelId, entries);
+        }
+        return entries;
+    }
+    function snapshot(channelId) {
+        return [...roster(channelId).values()].map((participant) => ({ ...participant }));
+    }
+    function notify(channelId) {
+        const current = snapshot(channelId);
+        for (const listener of listeners.get(channelId) ?? [])
+            listener(current);
+    }
+    const transport = {
+        join(channelId, streamId) {
+            const participant = { userId };
+            if (streamId !== undefined)
+                participant.streamId = streamId;
+            roster(channelId).set(userId, participant);
+            notify(channelId);
+            return Promise.resolve();
+        },
+        leave(channelId) {
+            if (roster(channelId).delete(userId))
+                notify(channelId);
+            return Promise.resolve();
+        },
+        publish(channelId, streamId) {
+            const participant = roster(channelId).get(userId);
+            if (participant !== undefined) {
+                participant.streamId = streamId;
+                notify(channelId);
+            }
+            return Promise.resolve();
+        },
+        subscribers(channelId, onChange) {
+            let set = listeners.get(channelId);
+            if (set === undefined) {
+                set = new Set();
+                listeners.set(channelId, set);
+            }
+            set.add(onChange);
+            onChange(snapshot(channelId));
+            return () => {
+                set.delete(onChange);
+                if (set.size === 0)
+                    listeners.delete(channelId);
+            };
+        },
+    };
+    return { transport, participants: snapshot };
+}
+export function createPushToTalk(config) {
+    let mode = config?.mode ?? "hold";
+    let keyed = false;
+    let muted = false;
+    let lastTransmitting = false;
+    function transmitting() {
+        if (muted)
+            return false;
+        return mode === "openMic" ? true : keyed;
+    }
+    function emit() {
+        const current = transmitting();
+        if (current === lastTransmitting)
+            return;
+        lastTransmitting = current;
+        config?.onChange?.(current);
+    }
+    return {
+        mode: () => mode,
+        setMode(next) {
+            mode = next;
+            keyed = false;
+            emit();
+        },
+        keyDown() {
+            if (mode === "hold")
+                keyed = true;
+            else if (mode === "toggle")
+                keyed = !keyed;
+            emit();
+        },
+        keyUp() {
+            if (mode === "hold")
+                keyed = false;
+            emit();
+        },
+        muted: () => muted,
+        setMuted(next) {
+            muted = next;
+            emit();
+        },
+        status() {
+            if (mode === "openMic")
+                return "open";
+            return keyed ? "keyed" : "idle";
+        },
+        transmitting,
+    };
+}

package/dist/nav/corridors.d.ts

@@ -0,0 +1,30 @@
+export type CorridorPoint = readonly [number, number];
+export interface CorridorEdge {
+    /** Centerline polyline in XZ; at least two points. */
+    points: readonly CorridorPoint[];
+    /** Full corridor width around the centerline. */
+    width: number;
+}
+export interface CorridorSample {
+    /** Distance from the query point to the nearest centerline. */
+    distance: number;
+    /** Nearest point on that centerline. */
+    closest: CorridorPoint;
+    /** Index of the edge owning the nearest centerline point. */
+    edgeIndex: number;
+}
+/**
+ * Organic corridor/path collision (#284.9): a distance-to-polyline width clamp over an edge graph —
+ * cave tunnels, river channels, winding roads. Grid/navmesh/voxel collision can't express a smooth
+ * ribbon; this can. Pure math over authored centerlines.
+ */
+export interface CorridorField {
+    contains(x: number, z: number): boolean;
+    /** Nearest-centerline sample, or `null` for an empty field. */
+    nearest(x: number, z: number): CorridorSample | null;
+    /** The input point when inside; otherwise the nearest point on the corridor boundary — the movement clamp. */
+    clamp(x: number, z: number): CorridorPoint;
+    /** Signed distance to the corridor edge: negative inside, positive outside. */
+    distanceToBoundary(x: number, z: number): number;
+}
+export declare function createCorridorField(edges: readonly CorridorEdge[]): CorridorField;

package/dist/nav/corridors.js

@@ -0,0 +1,69 @@
+function closestOnSegment(px, pz, a, b) {
+    const abx = b[0] - a[0];
+    const abz = b[1] - a[1];
+    const lengthSq = abx * abx + abz * abz;
+    if (lengthSq <= 1e-12)
+        return a;
+    const t = Math.max(0, Math.min(1, ((px - a[0]) * abx + (pz - a[1]) * abz) / lengthSq));
+    return [a[0] + abx * t, a[1] + abz * t];
+}
+export function createCorridorField(edges) {
+    for (const edge of edges) {
+        if (edge.points.length < 2)
+            throw new Error("corridor edge needs at least two centerline points");
+        if (!(edge.width > 0))
+            throw new Error(`corridor width must be positive, got ${edge.width}`);
+    }
+    function nearest(x, z) {
+        let best = null;
+        for (let edgeIndex = 0; edgeIndex < edges.length; edgeIndex += 1) {
+            const edge = edges[edgeIndex];
+            for (let i = 0; i < edge.points.length - 1; i += 1) {
+                const closest = closestOnSegment(x, z, edge.points[i], edge.points[i + 1]);
+                const distance = Math.hypot(x - closest[0], z - closest[1]);
+                if (best === null || distance < best.distance)
+                    best = { distance, closest, edgeIndex };
+            }
+        }
+        return best;
+    }
+    function distanceToBoundary(x, z) {
+        let signed = Number.POSITIVE_INFINITY;
+        for (let edgeIndex = 0; edgeIndex < edges.length; edgeIndex += 1) {
+            const edge = edges[edgeIndex];
+            for (let i = 0; i < edge.points.length - 1; i += 1) {
+                const closest = closestOnSegment(x, z, edge.points[i], edge.points[i + 1]);
+                const toBoundary = Math.hypot(x - closest[0], z - closest[1]) - edge.width / 2;
+                if (toBoundary < signed)
+                    signed = toBoundary;
+            }
+        }
+        return signed;
+    }
+    return {
+        contains: (x, z) => distanceToBoundary(x, z) <= 0,
+        nearest,
+        clamp(x, z) {
+            let best = null;
+            for (const edge of edges) {
+                for (let i = 0; i < edge.points.length - 1; i += 1) {
+                    const closest = closestOnSegment(x, z, edge.points[i], edge.points[i + 1]);
+                    const distance = Math.hypot(x - closest[0], z - closest[1]);
+                    const half = edge.width / 2;
+                    if (distance <= half)
+                        return [x, z];
+                    const overshoot = distance - half;
+                    if (best === null || overshoot < best.overshoot) {
+                        const scale = half / distance;
+                        best = {
+                            point: [closest[0] + (x - closest[0]) * scale, closest[1] + (z - closest[1]) * scale],
+                            overshoot,
+                        };
+                    }
+                }
+            }
+            return best === null ? [x, z] : best.point;
+        },
+        distanceToBoundary,
+    };
+}

package/dist/nav/navConstrain.d.ts

@@ -0,0 +1,14 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+import type { NavGrid, NavPoint } from "./navGrid.js";
+export interface NavConstrainProposed {
+    position: EntityPosition;
+    rotationY: number;
+    grounded: boolean;
+}
+export interface NavConstrainEntity {
+    position: EntityPosition;
+}
+export interface NavConstrainOptions {
+    y?: (point: NavPoint) => number;
+}
+export declare function constrainToNavGrid(grid: NavGrid, options?: NavConstrainOptions): (proposed: NavConstrainProposed, entity: NavConstrainEntity) => NavConstrainProposed | null;

package/dist/nav/navConstrain.js

@@ -0,0 +1,26 @@
+function withYRemap(proposed, options) {
+    if (options?.y === undefined)
+        return proposed;
+    const y = options.y([proposed.position[0], proposed.position[2]]);
+    return { ...proposed, position: [proposed.position[0], y, proposed.position[2]] };
+}
+function walkable(grid, point) {
+    const cell = grid.cellAt(point);
+    return grid.isWalkable(cell.col, cell.row);
+}
+export function constrainToNavGrid(grid, options) {
+    return (proposed, entity) => {
+        const target = [proposed.position[0], proposed.position[2]];
+        if (walkable(grid, target))
+            return withYRemap(proposed, options);
+        const slideX = [entity.position[0], proposed.position[2]];
+        if (walkable(grid, slideX)) {
+            return withYRemap({ ...proposed, position: [entity.position[0], proposed.position[1], proposed.position[2]] }, options);
+        }
+        const slideZ = [proposed.position[0], entity.position[2]];
+        if (walkable(grid, slideZ)) {
+            return withYRemap({ ...proposed, position: [proposed.position[0], proposed.position[1], entity.position[2]] }, options);
+        }
+        return null;
+    };
+}

package/dist/nav/navFromEnvironment.d.ts

@@ -0,0 +1,11 @@
+import type { EnvironmentWorldFeature } from "../world/features.js";
+import type { Aabb } from "../world/geometry.js";
+export interface NavObstacleGrid {
+    blockAabb(aabb: Aabb): void;
+}
+/**
+ * Expands every structure descriptor on an environment world feature into its
+ * generated buildings and blocks their footprints on `grid`. Returns the
+ * number of buildings blocked.
+ */
+export declare function populateNavGridFromEnvironment(grid: NavObstacleGrid, world: EnvironmentWorldFeature): number;

package/dist/nav/navFromEnvironment.js

@@ -0,0 +1,16 @@
+import { resolveStructureBuildings } from "../world/environmentSummary.js";
+/**
+ * Expands every structure descriptor on an environment world feature into its
+ * generated buildings and blocks their footprints on `grid`. Returns the
+ * number of buildings blocked.
+ */
+export function populateNavGridFromEnvironment(grid, world) {
+    let blocked = 0;
+    for (const descriptor of world.structures ?? []) {
+        for (const building of resolveStructureBuildings(descriptor)) {
+            grid.blockAabb(building.bounds);
+            blocked += 1;
+        }
+    }
+    return blocked;
+}

package/dist/nav/navGrid.d.ts

@@ -15,6 +15,8 @@ export interface FindPathOptions {
     smooth?: boolean;
     /** Diameter of the mover in world units — blocks cells within this margin of an obstacle. Default 0. */
     clearance?: number;
+    /** Multiplier (>=1) applied to the base cost of stepping from one cell center to a neighbour's. Use to penalize slopes, terrain, etc. */
+    stepCost?: (from: NavPoint, to: NavPoint) => number;
 }
 export interface NavGrid {
     readonly cols: number;
@@ -42,5 +44,13 @@ export declare function createNavGrid(config: NavGridConfig): NavGrid;
  * the nearest walkable cell so a click on an obstacle still routes to its edge.
  */
 export declare function findPath(grid: NavGrid, from: NavPoint, to: NavPoint, options?: FindPathOptions): NavPoint[] | null;
+/**
+ * `FindPathOptions.stepCost` factory that penalizes steep terrain: cost is
+ * `1 + weight * |Δheight| / horizontalDistance`, so with the default weight a
+ * 45° slope roughly doubles the step cost.
+ */
+export declare function slopeStepCost(field: {
+    sampleHeight(x: number, z: number): number;
+}, weight?: number): (from: NavPoint, to: NavPoint) => number;
 /** Remove waypoints the mover can skip because it has clear line-of-sight past them. */
 export declare function smoothPath(grid: NavGrid, points: readonly NavPoint[]): NavPoint[];

package/dist/nav/navGrid.js

@@ -82,11 +82,19 @@ export function createNavGrid(config) {
                 if (x === b.col && y === b.row)
                     return true;
                 const e2 = 2 * err;
-                if (e2 > -dy) {
+                const stepX = e2 > -dy;
+                const stepY = e2 < dx;
+                if (stepX && stepY) {
+                    if (walkable[index(x + sx, y)] === 0)
+                        return false;
+                    if (walkable[index(x, y + sy)] === 0)
+                        return false;
+                }
+                if (stepX) {
                     err -= dy;
                     x += sx;
                 }
-                if (e2 < dx) {
+                if (stepY) {
                     err += dx;
                     y += sy;
                 }
@@ -142,6 +150,24 @@ function withClearance(grid, clearance) {
         return true;
     };
 }
+function nearestPassable(grid, point, passable) {
+    const start = grid.cellAt(point);
+    if (passable(start.col, start.row))
+        return start;
+    const maxRadius = Math.max(grid.cols, grid.rows);
+    for (let radius = 1; radius <= maxRadius; radius += 1) {
+        for (let row = start.row - radius; row <= start.row + radius; row += 1) {
+            for (let col = start.col - radius; col <= start.col + radius; col += 1) {
+                const onRing = Math.abs(col - start.col) === radius || Math.abs(row - start.row) === radius;
+                if (!onRing || !grid.inBounds(col, row))
+                    continue;
+                if (passable(col, row))
+                    return { col, row };
+            }
+        }
+    }
+    return null;
+}
 /**
  * A* over the walkable grid. Returns a polyline of world-space `[x, z]` waypoints
  * from `from` to `to`, or `null` when no route exists. Blocked start/goal snap to
@@ -149,10 +175,11 @@ function withClearance(grid, clearance) {
  */
 export function findPath(grid, from, to, options = {}) {
     const passable = withClearance(grid, options.clearance ?? 0);
+    const stepCost = options.stepCost;
     const startCell = grid.cellAt(from);
     const goalCell = grid.cellAt(to);
-    const start = passable(startCell.col, startCell.row) ? startCell : grid.nearestWalkable(from);
-    const goal = passable(goalCell.col, goalCell.row) ? goalCell : grid.nearestWalkable(to);
+    const start = passable(startCell.col, startCell.row) ? startCell : nearestPassable(grid, from, passable);
+    const goal = passable(goalCell.col, goalCell.row) ? goalCell : nearestPassable(grid, to, passable);
     if (start === null || goal === null)
         return null;
     const cols = grid.cols;
@@ -209,7 +236,8 @@ export function findPath(grid, from, to, options = {}) {
             const nKey = keyOf(nc, nr);
             if (closed.has(nKey))
                 continue;
-            const tentative = g + step;
+            const multiplier = stepCost === undefined ? 1 : Math.max(1, stepCost(grid.center(col, row), grid.center(nc, nr)));
+            const tentative = g + step * multiplier;
             if (tentative < (gScore.get(nKey) ?? Number.POSITIVE_INFINITY)) {
                 gScore.set(nKey, tentative);
                 cameFrom.set(nKey, current.key);
@@ -231,6 +259,21 @@ export function findPath(grid, from, to, options = {}) {
         raw[raw.length - 1] = [to[0], to[1]];
     return options.smooth === false ? raw : smoothPath(grid, raw);
 }
+const DEFAULT_SLOPE_STEP_WEIGHT = 1;
+/**
+ * `FindPathOptions.stepCost` factory that penalizes steep terrain: cost is
+ * `1 + weight * |Δheight| / horizontalDistance`, so with the default weight a
+ * 45° slope roughly doubles the step cost.
+ */
+export function slopeStepCost(field, weight = DEFAULT_SLOPE_STEP_WEIGHT) {
+    return (from, to) => {
+        const horizontal = Math.hypot(to[0] - from[0], to[1] - from[1]);
+        if (horizontal < 1e-6)
+            return 1;
+        const rise = field.sampleHeight(to[0], to[1]) - field.sampleHeight(from[0], from[1]);
+        return 1 + (weight * Math.abs(rise)) / horizontal;
+    };
+}
 /** Remove waypoints the mover can skip because it has clear line-of-sight past them. */
 export function smoothPath(grid, points) {
     if (points.length <= 2)

package/dist/nav/pathFollow.d.ts

@@ -17,8 +17,10 @@ export interface PathFollowState {
     /** Total world-distance covered so far — drives progress/leak logic in tower defense. */
     distanceTravelled: number;
 }
-/** Lift an A* / navmesh `[x, z]` polyline onto a `y` plane for a path-follower. */
-export declare function pathFromNav(points: readonly NavPoint[], y?: number): Waypoint[];
+export interface HeightSampler {
+    sampleHeight(x: number, z: number): number;
+}
+export declare function pathFromNav(points: readonly NavPoint[], elevation?: number | HeightSampler, offset?: number): Waypoint[];
 export declare function createPathFollow(config: PathFollowConfig): PathFollowState;
 /**
  * Advance a path-follower by `speed * dt` along its authored polyline. Pure — returns

package/dist/nav/pathFollow.js

@@ -1,6 +1,8 @@
-/** Lift an A* / navmesh `[x, z]` polyline onto a `y` plane for a path-follower. */
-export function pathFromNav(points, y = 0) {
-    return points.map((point) => [point[0], y, point[1]]);
+export function pathFromNav(points, elevation = 0, offset = 0) {
+    if (typeof elevation === "number") {
+        return points.map((point) => [point[0], elevation + offset, point[1]]);
+    }
+    return points.map((point) => [point[0], elevation.sampleHeight(point[0], point[1]) + offset, point[1]]);
 }
 export function createPathFollow(config) {
     const first = config.waypoints[0];

package/dist/nav/railGraph.d.ts

@@ -0,0 +1,66 @@
+import type { Waypoint } from "./pathFollow.js";
+export interface RailNode {
+    id: string;
+    at: Waypoint;
+}
+export interface RailEdge {
+    id: string;
+    from: string;
+    to: string;
+    /** Intermediate shape points between the two node positions (curves, sidings). */
+    via?: readonly Waypoint[];
+}
+export interface RailGraphConfig {
+    nodes: readonly RailNode[];
+    edges: readonly RailEdge[];
+}
+export interface ResolvedRailEdge {
+    id: string;
+    from: string;
+    to: string;
+    points: readonly Waypoint[];
+    length: number;
+}
+/**
+ * A directed graph of track segments with junction switch-throw semantics — the topological seam
+ * `nav/navGrid`'s walkable cells can't express. Each node with several out-edges is a switch whose
+ * thrown edge decides where traffic exits; riders (`createRailRider`) run along edge polylines and
+ * take the thrown edge at every junction.
+ */
+export interface RailGraph {
+    node(id: string): RailNode | null;
+    edge(id: string): ResolvedRailEdge | null;
+    edges(): readonly string[];
+    /** Out-edge ids leaving a node, in declaration order. */
+    outEdges(nodeId: string): readonly string[];
+    /** The edge a rider leaves this node on — the thrown switch, defaulting to the first declared out-edge; `null` at a dead end. */
+    thrownEdge(nodeId: string): string | null;
+    /** Throw the switch at `nodeId` to `edgeId`; `false` unless `edgeId` leaves that node. */
+    throwSwitch(nodeId: string, edgeId: string): boolean;
+}
+export interface RailRiderConfig {
+    edgeId: string;
+    /** Arc-length position along the starting edge; default `0`. */
+    s?: number;
+    /** World units per second; mutate via `setSpeed`. */
+    speed: number;
+}
+export interface RailRiderPose {
+    position: Waypoint;
+    /** Yaw (radians) of the travel direction, matching engine `rotationY`. */
+    heading: number;
+    edgeId: string;
+    /** Arc-length along the current edge. */
+    s: number;
+    /** True once the rider stops at a node with no thrown out-edge. */
+    atDeadEnd: boolean;
+}
+export interface RailRider {
+    advance(dt: number): RailRiderPose;
+    pose(): RailRiderPose;
+    setSpeed(speed: number): void;
+    /** Teleport onto an edge (a respawn or re-rail); throws on an unknown edge. */
+    place(edgeId: string, s?: number): void;
+}
+export declare function createRailGraph(config: RailGraphConfig): RailGraph;
+export declare function createRailRider(graph: RailGraph, config: RailRiderConfig): RailRider;

package/dist/nav/railGraph.js

@@ -0,0 +1,129 @@
+function segmentLengths(points) {
+    const lengths = [];
+    let total = 0;
+    for (let i = 0; i < points.length - 1; i += 1) {
+        const a = points[i];
+        const b = points[i + 1];
+        const length = Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+        lengths.push(length);
+        total += length;
+    }
+    return { lengths, total };
+}
+export function createRailGraph(config) {
+    const nodes = new Map();
+    for (const node of config.nodes) {
+        if (nodes.has(node.id))
+            throw new Error(`duplicate rail node: ${node.id}`);
+        nodes.set(node.id, node);
+    }
+    const edges = new Map();
+    const outByNode = new Map();
+    const switches = new Map();
+    const edgeOrder = [];
+    for (const edge of config.edges) {
+        if (edges.has(edge.id))
+            throw new Error(`duplicate rail edge: ${edge.id}`);
+        const from = nodes.get(edge.from);
+        const to = nodes.get(edge.to);
+        if (from === undefined || to === undefined) {
+            throw new Error(`rail edge "${edge.id}" references unknown node "${from === undefined ? edge.from : edge.to}"`);
+        }
+        const points = [from.at, ...(edge.via ?? []), to.at];
+        const { total } = segmentLengths(points);
+        edges.set(edge.id, { id: edge.id, from: edge.from, to: edge.to, points, length: total });
+        edgeOrder.push(edge.id);
+        const out = outByNode.get(edge.from) ?? [];
+        out.push(edge.id);
+        outByNode.set(edge.from, out);
+        if (!switches.has(edge.from))
+            switches.set(edge.from, edge.id);
+    }
+    return {
+        node: (id) => nodes.get(id) ?? null,
+        edge: (id) => edges.get(id) ?? null,
+        edges: () => edgeOrder.slice(),
+        outEdges: (nodeId) => outByNode.get(nodeId) ?? [],
+        thrownEdge: (nodeId) => switches.get(nodeId) ?? null,
+        throwSwitch(nodeId, edgeId) {
+            const out = outByNode.get(nodeId);
+            if (out === undefined || !out.includes(edgeId))
+                return false;
+            switches.set(nodeId, edgeId);
+            return true;
+        },
+    };
+}
+export function createRailRider(graph, config) {
+    let edge = graph.edge(config.edgeId);
+    if (edge === null)
+        throw new Error(`unknown rail edge: ${config.edgeId}`);
+    let s = Math.max(0, Math.min(config.s ?? 0, edge.length));
+    let speed = config.speed;
+    let deadEnd = false;
+    function poseOn(current, arc) {
+        const { lengths } = segmentLengths(current.points);
+        let remaining = arc;
+        for (let i = 0; i < lengths.length; i += 1) {
+            const length = lengths[i];
+            if (remaining <= length || i === lengths.length - 1) {
+                const a = current.points[i];
+                const b = current.points[i + 1];
+                const fraction = length <= 1e-9 ? 0 : Math.min(1, remaining / length);
+                return {
+                    position: [
+                        a[0] + (b[0] - a[0]) * fraction,
+                        a[1] + (b[1] - a[1]) * fraction,
+                        a[2] + (b[2] - a[2]) * fraction,
+                    ],
+                    heading: Math.atan2(b[0] - a[0], b[2] - a[2]),
+                    edgeId: current.id,
+                    s: arc,
+                    atDeadEnd: deadEnd,
+                };
+            }
+            remaining -= length;
+        }
+        const last = current.points[current.points.length - 1];
+        return { position: last, heading: 0, edgeId: current.id, s: arc, atDeadEnd: deadEnd };
+    }
+    return {
+        advance(dt) {
+            if (deadEnd || dt <= 0 || speed <= 0)
+                return poseOn(edge, s);
+            let budget = speed * dt;
+            let guard = 64;
+            while (budget > 1e-9 && guard > 0) {
+                guard -= 1;
+                const room = edge.length - s;
+                if (budget < room) {
+                    s += budget;
+                    budget = 0;
+                    break;
+                }
+                budget -= room;
+                const nextId = graph.thrownEdge(edge.to);
+                if (nextId === null) {
+                    s = edge.length;
+                    deadEnd = true;
+                    break;
+                }
+                edge = graph.edge(nextId);
+                s = 0;
+            }
+            return poseOn(edge, s);
+        },
+        pose: () => poseOn(edge, s),
+        setSpeed(next) {
+            speed = next;
+        },
+        place(edgeId, arc = 0) {
+            const next = graph.edge(edgeId);
+            if (next === null)
+                throw new Error(`unknown rail edge: ${edgeId}`);
+            edge = next;
+            s = Math.max(0, Math.min(arc, next.length));
+            deadEnd = false;
+        },
+    };
+}