@jgengine/core 0.8.0 → 0.9.0

package/dist/movement/grappleSwing.js

@@ -0,0 +1,56 @@
+export function createGrappleSwing(config = {}) {
+    const reelSpeed = config.reelSpeed ?? 0;
+    const minLength = config.minLength ?? 1;
+    const stiffness = config.stiffness ?? 0;
+    const damping = config.damping ?? 0.1;
+    let anchor = null;
+    let ropeLength = 0;
+    return {
+        fire(nextAnchor, from) {
+            anchor = nextAnchor;
+            ropeLength = Math.max(minLength, Math.hypot(from[0] - nextAnchor[0], from[1] - nextAnchor[1], from[2] - nextAnchor[2]));
+        },
+        release() {
+            anchor = null;
+        },
+        state: () => ({ attached: anchor !== null, anchor, ropeLength }),
+        step(position, velocity, dt, reeling = false) {
+            if (anchor === null || dt <= 0)
+                return { position, velocity };
+            if (reeling && reelSpeed > 0)
+                ropeLength = Math.max(minLength, ropeLength - reelSpeed * dt);
+            let px = position[0];
+            let py = position[1];
+            let pz = position[2];
+            let vx = velocity[0];
+            let vy = velocity[1];
+            let vz = velocity[2];
+            const dx = px - anchor[0];
+            const dy = py - anchor[1];
+            const dz = pz - anchor[2];
+            const distance = Math.hypot(dx, dy, dz);
+            if (distance > ropeLength && distance > 1e-9) {
+                const nx = dx / distance;
+                const ny = dy / distance;
+                const nz = dz / distance;
+                px = anchor[0] + nx * ropeLength;
+                py = anchor[1] + ny * ropeLength;
+                pz = anchor[2] + nz * ropeLength;
+                const radial = vx * nx + vy * ny + vz * nz;
+                if (radial > 0) {
+                    vx -= nx * radial;
+                    vy -= ny * radial;
+                    vz -= nz * radial;
+                }
+                if (stiffness > 0) {
+                    const pull = (distance - ropeLength) * stiffness * dt;
+                    vx -= nx * pull;
+                    vy -= ny * pull;
+                    vz -= nz * pull;
+                }
+            }
+            const damp = Math.max(0, 1 - damping * dt);
+            return { position: [px, py, pz], velocity: [vx * damp, vy * damp, vz * damp] };
+        },
+    };
+}

package/dist/movement/leaderTrail.d.ts

@@ -0,0 +1,29 @@
+export type TrailPoint = readonly [number, number, number];
+export interface LeaderTrailConfig {
+    /** Arc-length gap between consecutive followers. */
+    spacing: number;
+    /** Followers the trail must be able to serve; history is capped to cover them. Default `16`. */
+    maxFollowers?: number;
+    /** Minimum leader movement before a new trail sample is recorded; default `spacing / 8`. */
+    sampleDistance?: number;
+}
+export interface TrailPose {
+    position: TrailPoint;
+    /** Yaw (radians) of the trail direction at this point, matching engine `rotationY`. */
+    heading: number;
+}
+/**
+ * A live breadcrumb trail recorded from a moving leader, with followers placed by arc-length
+ * behind the head — conga lines, convoys, duckling chains, snake bodies. Call `record` with the
+ * leader's position every tick; read `followerAt(i)` for the pose `spacing * (i + 1)` behind.
+ */
+export interface LeaderTrail {
+    record(position: TrailPoint): void;
+    /** Pose for follower `index` (0 = closest behind the leader); `null` until enough trail exists. */
+    followerAt(index: number): TrailPose | null;
+    /** Recorded arc length available behind the leader. */
+    length(): number;
+    /** Drop all history (teleport, respawn) and optionally restart from a position. */
+    reset(position?: TrailPoint): void;
+}
+export declare function createLeaderTrail(config: LeaderTrailConfig): LeaderTrail;

package/dist/movement/leaderTrail.js

@@ -0,0 +1,67 @@
+export function createLeaderTrail(config) {
+    if (!(config.spacing > 0))
+        throw new Error(`leader trail spacing must be positive, got ${config.spacing}`);
+    const spacing = config.spacing;
+    const maxFollowers = Math.max(1, config.maxFollowers ?? 16);
+    const sampleDistance = config.sampleDistance ?? spacing / 8;
+    const capacity = spacing * (maxFollowers + 1);
+    let points = [];
+    let lengths = [];
+    let total = 0;
+    function trim() {
+        while (total > capacity && lengths.length > 0) {
+            const tailSegment = lengths[0];
+            if (total - tailSegment < capacity)
+                break;
+            lengths.shift();
+            points.shift();
+            total -= tailSegment;
+        }
+    }
+    return {
+        record(position) {
+            const head = points[points.length - 1];
+            if (head === undefined) {
+                points.push(position);
+                return;
+            }
+            const step = Math.hypot(position[0] - head[0], position[1] - head[1], position[2] - head[2]);
+            if (step < sampleDistance)
+                return;
+            points.push(position);
+            lengths.push(step);
+            total += step;
+            trim();
+        },
+        followerAt(index) {
+            const behind = spacing * (index + 1);
+            if (behind > total)
+                return null;
+            let remaining = behind;
+            for (let i = lengths.length - 1; i >= 0; i -= 1) {
+                const segment = lengths[i];
+                const to = points[i + 1];
+                const from = points[i];
+                if (remaining <= segment) {
+                    const fraction = segment <= 1e-9 ? 0 : remaining / segment;
+                    return {
+                        position: [
+                            to[0] + (from[0] - to[0]) * fraction,
+                            to[1] + (from[1] - to[1]) * fraction,
+                            to[2] + (from[2] - to[2]) * fraction,
+                        ],
+                        heading: Math.atan2(to[0] - from[0], to[2] - from[2]),
+                    };
+                }
+                remaining -= segment;
+            }
+            return null;
+        },
+        length: () => total,
+        reset(position) {
+            points = position === undefined ? [] : [position];
+            lengths = [];
+            total = 0;
+        },
+    };
+}

package/dist/movement/steering.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Yaw-frame steering math. The engine's heading convention is
+ * `forward = (sin yaw, cos yaw)` on the XZ plane with +Y up, which makes a
+ * positive yaw increment rotate counterclockwise seen from above — a turn to
+ * the entity's LEFT on screen. Every hand-written `heading += steer * rate * dt`
+ * therefore turns the wrong way; integrate steering through `steerYaw` instead.
+ */
+export type YawVectorXZ = readonly [number, number];
+/** XZ forward direction of a yaw (`rotationY`): `(sin yaw, cos yaw)`. */
+export declare function yawForward(yaw: number): YawVectorXZ;
+/** XZ screen-right of a yaw — `forward × up` with up = +Y: `(-cos yaw, sin yaw)`. */
+export declare function yawRight(yaw: number): YawVectorXZ;
+/**
+ * Integrate one steering step. `steerRight` is the signed steer input
+ * (+1 = turn right, matching `DRIVE_AXIS_BINDINGS`' KeyD/ArrowRight),
+ * `turnRatePerSecond` is radians per second at full lock. Steering right
+ * decreases yaw in the engine frame; this helper owns that sign so game
+ * code never re-derives it.
+ */
+export declare function steerYaw(yaw: number, steerRight: number, turnRatePerSecond: number, dt: number): number;
+/**
+ * Signed steer-right input that closes on `desiredYaw` when integrated
+ * through `steerYaw` — the seek half every AI driver and homing script
+ * needs. Magnitude is the wrapped radian error in (−π, π]; scale and clamp
+ * it into [-1, 1] at the call site.
+ */
+export declare function steerToward(yaw: number, desiredYaw: number): number;

package/dist/movement/steering.js

@@ -0,0 +1,40 @@
+/**
+ * Yaw-frame steering math. The engine's heading convention is
+ * `forward = (sin yaw, cos yaw)` on the XZ plane with +Y up, which makes a
+ * positive yaw increment rotate counterclockwise seen from above — a turn to
+ * the entity's LEFT on screen. Every hand-written `heading += steer * rate * dt`
+ * therefore turns the wrong way; integrate steering through `steerYaw` instead.
+ */
+/** XZ forward direction of a yaw (`rotationY`): `(sin yaw, cos yaw)`. */
+export function yawForward(yaw) {
+    return [Math.sin(yaw), Math.cos(yaw)];
+}
+/** XZ screen-right of a yaw — `forward × up` with up = +Y: `(-cos yaw, sin yaw)`. */
+export function yawRight(yaw) {
+    return [-Math.cos(yaw), Math.sin(yaw)];
+}
+/**
+ * Integrate one steering step. `steerRight` is the signed steer input
+ * (+1 = turn right, matching `DRIVE_AXIS_BINDINGS`' KeyD/ArrowRight),
+ * `turnRatePerSecond` is radians per second at full lock. Steering right
+ * decreases yaw in the engine frame; this helper owns that sign so game
+ * code never re-derives it.
+ */
+export function steerYaw(yaw, steerRight, turnRatePerSecond, dt) {
+    return yaw - steerRight * turnRatePerSecond * dt;
+}
+/**
+ * Signed steer-right input that closes on `desiredYaw` when integrated
+ * through `steerYaw` — the seek half every AI driver and homing script
+ * needs. Magnitude is the wrapped radian error in (−π, π]; scale and clamp
+ * it into [-1, 1] at the call site.
+ */
+export function steerToward(yaw, desiredYaw) {
+    let delta = (desiredYaw - yaw) % TWO_PI;
+    if (delta > Math.PI)
+        delta -= TWO_PI;
+    if (delta <= -Math.PI)
+        delta += TWO_PI;
+    return -delta;
+}
+const TWO_PI = Math.PI * 2;

package/dist/multiplayer/feedWriteGate.d.ts

@@ -0,0 +1,10 @@
+export type FeedWriteGate = {
+    allowedActions: readonly string[];
+};
+export declare function createFeedWriteGate(allowedActions?: readonly string[]): FeedWriteGate;
+export declare function validateFeedWrite(gate: FeedWriteGate | undefined, action: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/multiplayer/feedWriteGate.js

@@ -0,0 +1,12 @@
+export function createFeedWriteGate(allowedActions = []) {
+    return { allowedActions: [...allowedActions] };
+}
+export function validateFeedWrite(gate, action) {
+    if (gate === undefined || gate.allowedActions.length === 0) {
+        return { ok: false, reason: "client feed writes are disabled" };
+    }
+    if (!gate.allowedActions.includes(action)) {
+        return { ok: false, reason: `feed action not allowed: ${action}` };
+    }
+    return { ok: true };
+}

package/dist/multiplayer/presenceModel.d.ts

@@ -22,8 +22,10 @@ export interface IncomingPose {
 export interface PoseSyncRules {
     /** Speed cap (units/sec) for client-authoritative movement. */
     maxSpeed: number;
-    /** Vertical offset clamp (e.g. peak jump height). */
+    /** Vertical offset clamp above floorY (e.g. peak jump height). */
     maxVerticalOffset: number;
+    /** World-floor Y used as the base of the jump band. Defaults to 0. */
+    floorY?: number;
     /** Elapsed-time clamp so stale or bursty clients cannot teleport. */
     minElapsedSec: number;
     maxElapsedSec: number;
@@ -44,7 +46,17 @@ export interface PoseSyncDecision {
     /** True when only the keep-alive stamp should be written. */
     refreshKeepAlive: boolean;
 }
-export declare function decidePoseSync(current: PresencePoseState, incoming: IncomingPose, rules: PoseSyncRules, nowMs: number): PoseSyncDecision;
+export declare const DEFAULT_SPAWN_ORIGIN: {
+    readonly x: 0;
+    readonly y: 0;
+    readonly z: 0;
+};
+export declare function spawnPresenceState(origin: {
+    x: number;
+    y: number;
+    z: number;
+} | undefined, nowMs: number, rules: Pick<PoseSyncRules, "maxElapsedSec">): PresencePoseState;
+export declare function decidePoseSync(current: PresencePoseState, incoming: IncomingPose, rules: PoseSyncRules, nowMs: number, floorY?: number): PoseSyncDecision;
 export declare function shouldRefreshKeepAlive(lastSeenAtMs: number | undefined, nowMs: number, rules: Pick<PoseSyncRules, "keepAliveRefreshMs">): boolean;
 export declare function shouldPersistWorldSnapshot(lastSavedAtMs: number | undefined, nowMs: number, intervalMs: number): boolean;
 export interface ActivePresenceResolution<T> {

package/dist/multiplayer/presenceModel.js

@@ -9,8 +9,18 @@ function appearanceEqual(a, b) {
         return false;
     return aKeys.every((key) => a[key] === b[key]);
 }
-export function decidePoseSync(current, incoming, rules, nowMs) {
-    const elapsedSec = Math.max(rules.minElapsedSec, Math.min(rules.maxElapsedSec, (nowMs - (current.lastSeenAtMs ?? nowMs)) / 1000));
+export const DEFAULT_SPAWN_ORIGIN = { x: 0, y: 0, z: 0 };
+export function spawnPresenceState(origin = DEFAULT_SPAWN_ORIGIN, nowMs, rules) {
+    return {
+        position: { x: origin.x, y: origin.y, z: origin.z },
+        rotationY: 0,
+        rotationPitch: 0,
+        lastSeenAtMs: nowMs - rules.maxElapsedSec * 1000,
+    };
+}
+export function decidePoseSync(current, incoming, rules, nowMs, floorY) {
+    const rawElapsedSec = Math.max(0, (nowMs - (current.lastSeenAtMs ?? nowMs)) / 1000);
+    const elapsedSec = Math.min(rules.maxElapsedSec, rawElapsedSec);
     const maxDist = rules.maxSpeed * elapsedSec;
     const maxDistSq = maxDist * maxDist;
     let targetX = incoming.position.x;
@@ -23,9 +33,11 @@ export function decidePoseSync(current, incoming, rules, nowMs) {
         targetX = current.position.x + dx * scale;
         targetZ = current.position.z + dz * scale;
     }
+    const floor = floorY ?? rules.floorY ?? 0;
+    const ceiling = floor + rules.maxVerticalOffset;
     const nextY = incoming.position.y === undefined
         ? current.position.y
-        : Math.max(0, Math.min(rules.maxVerticalOffset, incoming.position.y));
+        : Math.max(floor, Math.min(ceiling, incoming.position.y));
     const nextRotationY = incoming.rotationY ?? current.rotationY;
     const nextRotationPitch = incoming.rotationPitch ?? current.rotationPitch ?? 0;
     const nextAppearance = incoming.appearance ?? current.appearance;

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/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
@@ -152,8 +178,8 @@ export function findPath(grid, from, to, options = {}) {
     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;

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;
+        },
+    };
+}