@jgengine/core 0.8.0 → 0.10.0

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

package/dist/nav/timetable.d.ts

@@ -0,0 +1,41 @@
+import type { Waypoint } from "./pathFollow.js";
+export interface TimetableStop {
+    at: Waypoint;
+    /** Seconds the mover holds at this waypoint before departing. */
+    dwellSeconds?: number;
+}
+export interface RouteTimetableConfig {
+    waypoints: readonly (Waypoint | TimetableStop)[];
+    /** World units per second between stops. */
+    speed: number;
+    /** Wrap from the last waypoint back to the first (a circular line). Default `false` — the mover holds at the terminus. */
+    loop?: boolean;
+    /** Default dwell applied at every waypoint without its own `dwellSeconds`; default `0`. */
+    dwellSeconds?: number;
+    /** Shifts the whole timetable so `t = 0` lands mid-route — staggers several movers on one route. */
+    offsetSeconds?: number;
+}
+export interface TimetablePose {
+    position: Waypoint;
+    /** Yaw (radians) of the travel direction, matching engine `rotationY`; holds through dwells. */
+    heading: number;
+    /** Index of the segment being travelled (or the stop being dwelt at). */
+    segment: number;
+    /** True while holding at a stop. */
+    dwelling: boolean;
+}
+/**
+ * A deterministic mover over an authored route: position is a pure function of absolute time, so a
+ * forecast preview (`poseAt(t + 30)`) and the live mover can never disagree — the seam `nav/pathFollow`'s
+ * dt-incremental state can't offer. Trains, ferries, patrol shuttles, crushers: anything on a timetable.
+ */
+export interface RouteTimetable {
+    /** Seconds for one full cycle (travel + dwells); non-loop routes hold at the terminus after this. */
+    readonly cycleSeconds: number;
+    readonly distance: number;
+    poseAt(t: number): TimetablePose;
+    positionAt(t: number): Waypoint;
+    /** Cycle progress in `[0, 1]` — clamps at `1` on a non-looping route's terminus. */
+    progressAt(t: number): number;
+}
+export declare function createRouteTimetable(config: RouteTimetableConfig): RouteTimetable;

package/dist/nav/timetable.js

@@ -0,0 +1,94 @@
+function stopOf(entry) {
+    return Array.isArray(entry) ? { at: entry } : entry;
+}
+export function createRouteTimetable(config) {
+    if (!(config.speed > 0))
+        throw new Error(`timetable speed must be positive, got ${config.speed}`);
+    const stops = config.waypoints.map(stopOf);
+    if (stops.length < 2)
+        throw new Error("timetable needs at least two waypoints");
+    const loop = config.loop ?? false;
+    const defaultDwell = Math.max(0, config.dwellSeconds ?? 0);
+    const offset = config.offsetSeconds ?? 0;
+    const legs = [];
+    let clock = 0;
+    let distance = 0;
+    const legCount = loop ? stops.length : stops.length - 1;
+    for (let i = 0; i < legCount; i += 1) {
+        const from = stops[i];
+        const to = stops[(i + 1) % stops.length];
+        const dwell = Math.max(0, from.dwellSeconds ?? defaultDwell);
+        const dx = to.at[0] - from.at[0];
+        const dy = to.at[1] - from.at[1];
+        const dz = to.at[2] - from.at[2];
+        const length = Math.hypot(dx, dy, dz);
+        const heading = length > 1e-9 ? Math.atan2(dx, dz) : 0;
+        legs.push({
+            from: from.at,
+            to: to.at,
+            heading,
+            startSeconds: clock,
+            travelSeconds: length / config.speed,
+            dwellSeconds: dwell,
+        });
+        clock += dwell + length / config.speed;
+        distance += length;
+    }
+    const cycleSeconds = clock;
+    const terminus = stops[stops.length - 1].at;
+    const lastHeading = legs[legs.length - 1].heading;
+    function poseAt(t) {
+        let local = t + offset;
+        if (loop) {
+            local = ((local % cycleSeconds) + cycleSeconds) % cycleSeconds;
+        }
+        else {
+            local = Math.max(0, local);
+            if (local >= cycleSeconds) {
+                return { position: terminus, heading: lastHeading, segment: legs.length - 1, dwelling: true };
+            }
+        }
+        let leg = legs[legs.length - 1];
+        let segment = legs.length - 1;
+        for (let i = 0; i < legs.length; i += 1) {
+            const candidate = legs[i];
+            if (local < candidate.startSeconds + candidate.dwellSeconds + candidate.travelSeconds) {
+                leg = candidate;
+                segment = i;
+                break;
+            }
+        }
+        const intoLeg = local - leg.startSeconds;
+        if (intoLeg < leg.dwellSeconds) {
+            const previous = legs[(segment - 1 + legs.length) % legs.length];
+            const heading = segment === 0 && !loop ? leg.heading : previous.heading;
+            return { position: leg.from, heading, segment, dwelling: true };
+        }
+        const travelled = intoLeg - leg.dwellSeconds;
+        const fraction = leg.travelSeconds <= 0 ? 1 : Math.min(1, travelled / leg.travelSeconds);
+        return {
+            position: [
+                leg.from[0] + (leg.to[0] - leg.from[0]) * fraction,
+                leg.from[1] + (leg.to[1] - leg.from[1]) * fraction,
+                leg.from[2] + (leg.to[2] - leg.from[2]) * fraction,
+            ],
+            heading: leg.heading,
+            segment,
+            dwelling: false,
+        };
+    }
+    return {
+        cycleSeconds,
+        distance,
+        poseAt,
+        positionAt: (t) => poseAt(t).position,
+        progressAt(t) {
+            if (cycleSeconds <= 0)
+                return 1;
+            const local = t + offset;
+            if (loop)
+                return (((local % cycleSeconds) + cycleSeconds) % cycleSeconds) / cycleSeconds;
+            return Math.max(0, Math.min(1, local / cycleSeconds));
+        },
+    };
+}

package/dist/physics/buoyancy.d.ts

@@ -15,6 +15,10 @@ export interface BuoyantBodyConfig {
     topSpeed?: number;
     turnRate?: number;
     turnSpeedRef?: number;
+    /** Water-current acceleration (units/s²) sampled at the hull each tick and applied while submerged — feed a `windZones`/`flowTube` sample or a fixed vector. */
+    current?: (x: number, z: number, time: number) => readonly [number, number];
+    /** How much more current a broadside hull catches than a bow-on one (`1` = uniform, default; `2` = side-on drifts twice as hard). */
+    currentBroadside?: number;
 }
 /**
  * Floats a {@link PhysicsWorld} body on a CPU {@link WaterSurface}: each hull sample point pushes the
@@ -38,6 +42,8 @@ export declare class BuoyantBody {
     private readonly topSpeed;
     private readonly turnRate;
     private readonly turnSpeedRef;
+    private readonly current;
+    private readonly currentBroadside;
     private submergedFlag;
     constructor(world: PhysicsWorld, config: BuoyantBodyConfig);
     get position(): [number, number, number];

package/dist/physics/buoyancy.js

@@ -26,6 +26,8 @@ export class BuoyantBody {
     topSpeed;
     turnRate;
     turnSpeedRef;
+    current;
+    currentBroadside;
     submergedFlag = false;
     constructor(world, config) {
         this.world = world;
@@ -42,6 +44,8 @@ export class BuoyantBody {
         this.topSpeed = config.topSpeed ?? 14;
         this.turnRate = config.turnRate ?? 1.2;
         this.turnSpeedRef = config.turnSpeedRef ?? 4;
+        this.current = config.current ?? null;
+        this.currentBroadside = config.currentBroadside ?? 1;
     }
     get position() {
         return [this.world.posX[this.body], this.world.posY[this.body], this.world.posZ[this.body]];
@@ -81,6 +85,16 @@ export class BuoyantBody {
             const drag = Math.max(0, 1 - this.linearDrag * dt);
             w.velX[b] *= drag;
             w.velZ[b] *= drag;
+            if (this.current !== null) {
+                const [cx, cz] = this.current(w.posX[b], w.posZ[b], time);
+                const magnitude = Math.hypot(cx, cz);
+                if (magnitude > 0) {
+                    const alignment = Math.abs((cx * sin + cz * cos) / magnitude);
+                    const scale = this.currentBroadside + (1 - this.currentBroadside) * alignment;
+                    w.velX[b] += cx * scale * dt;
+                    w.velZ[b] += cz * scale * dt;
+                }
+            }
             this.submergedFlag = true;
             w.wake(b);
         }

package/dist/physics/flowTube.d.ts

@@ -0,0 +1,32 @@
+export type FlowVec3 = readonly [number, number, number];
+export interface FlowTubeConfig {
+    from: FlowVec3;
+    to: FlowVec3;
+    /** Tube radius; flow strength fades from the axis to zero here. */
+    radius: number;
+    /** Axial flow speed on the core at full spool. */
+    strength: number;
+    /** Radial falloff exponent — `1` linear, `2` (default) keeps a fat core with soft edges. */
+    falloff?: number;
+    /** Extra reach past each end where the axial envelope fades to zero; default `0` (hard caps). */
+    capFalloff?: number;
+}
+/**
+ * An axial corridor of directional flow with radial core falloff and a spool scalar — fan tunnels,
+ * updraft shafts, river narrows, thruster wash. Pure math: sample `velocityAt(point, spool)` and add
+ * it to whatever integrator moves the body (walk controller drift, `BuoyantBody`, a custom sim).
+ */
+export interface FlowTube {
+    readonly axis: FlowVec3;
+    readonly length: number;
+    /** Flow velocity at a world point, scaled by `spool` in `[0, 1]` (default `1`); zero outside the tube. */
+    velocityAt(point: FlowVec3, spool?: number): FlowVec3;
+    /** The radial × axial envelope in `[0, 1]` at a world point — feed particle density, audio gain, rumble. */
+    intensityAt(point: FlowVec3): number;
+}
+export declare function createFlowTube(config: FlowTubeConfig): FlowTube;
+/** Sum several tubes' flow at one point — each entry carries its own spool. */
+export declare function combineFlowVelocity(tubes: readonly (FlowTube | {
+    tube: FlowTube;
+    spool: number;
+})[], point: FlowVec3): FlowVec3;

package/dist/physics/flowTube.js

@@ -0,0 +1,64 @@
+export function createFlowTube(config) {
+    if (!(config.radius > 0))
+        throw new Error(`flow tube radius must be positive, got ${config.radius}`);
+    const [fx, fy, fz] = config.from;
+    const dx = config.to[0] - fx;
+    const dy = config.to[1] - fy;
+    const dz = config.to[2] - fz;
+    const length = Math.hypot(dx, dy, dz);
+    if (length <= 1e-9)
+        throw new Error("flow tube needs distinct from/to points");
+    const axis = [dx / length, dy / length, dz / length];
+    const falloff = config.falloff ?? 2;
+    const capFalloff = Math.max(0, config.capFalloff ?? 0);
+    function envelopeAt(point) {
+        const px = point[0] - fx;
+        const py = point[1] - fy;
+        const pz = point[2] - fz;
+        const along = px * axis[0] + py * axis[1] + pz * axis[2];
+        if (along < -capFalloff || along > length + capFalloff)
+            return 0;
+        const axial = capFalloff <= 0
+            ? along >= 0 && along <= length
+                ? 1
+                : 0
+            : along < 0
+                ? 1 + along / capFalloff
+                : along > length
+                    ? 1 - (along - length) / capFalloff
+                    : 1;
+        if (axial <= 0)
+            return 0;
+        const rx = px - axis[0] * along;
+        const ry = py - axis[1] * along;
+        const rz = pz - axis[2] * along;
+        const radial = Math.hypot(rx, ry, rz);
+        if (radial >= config.radius)
+            return 0;
+        return axial * Math.pow(1 - radial / config.radius, falloff);
+    }
+    return {
+        axis,
+        length,
+        velocityAt(point, spool = 1) {
+            const scale = envelopeAt(point) * config.strength * Math.max(0, Math.min(1, spool));
+            return scale <= 0 ? [0, 0, 0] : [axis[0] * scale, axis[1] * scale, axis[2] * scale];
+        },
+        intensityAt: envelopeAt,
+    };
+}
+/** Sum several tubes' flow at one point — each entry carries its own spool. */
+export function combineFlowVelocity(tubes, point) {
+    let x = 0;
+    let y = 0;
+    let z = 0;
+    for (const entry of tubes) {
+        const tube = "velocityAt" in entry ? entry : entry.tube;
+        const spool = "velocityAt" in entry ? 1 : entry.spool;
+        const [vx, vy, vz] = tube.velocityAt(point, spool);
+        x += vx;
+        y += vy;
+        z += vz;
+    }
+    return [x, y, z];
+}

package/dist/physics/forceVolume.d.ts

@@ -27,6 +27,33 @@ export declare class ForceVolume {
     constructor(config: ForceVolumeConfig);
     apply(world: PhysicsWorld, dt: number): void;
 }
+/** One tick's force math for a body outside `PhysicsWorld` — apply the returned velocity in any custom integrator. */
+export declare function applyVolumeForce(velocity: readonly [number, number, number], force: readonly [number, number, number], mode: ForceMode, dt: number): readonly [number, number, number];
+export interface VolumeTriggerConfig {
+    bounds: PhysicsBounds;
+}
+export interface VolumeTriggerStep<TId> {
+    /** Ids inside this tick that were outside last tick — the boost-pad edge. */
+    entered: readonly TId[];
+    /** Every id inside this tick. */
+    inside: readonly TId[];
+    /** Ids inside last tick that left. */
+    exited: readonly TId[];
+}
+/**
+ * The enter-once membership tracking from `ForceVolume`, freed from `PhysicsWorld`'s body indices
+ * (#286.8): feed any integrator's `{ id, position }` list each tick and act on the edges — apply
+ * `applyVolumeForce` on `entered` for a boost pad, on `inside` for a fan.
+ */
+export interface VolumeTrigger<TId> {
+    readonly bounds: PhysicsBounds;
+    step(bodies: Iterable<{
+        id: TId;
+        position: readonly [number, number, number];
+    }>): VolumeTriggerStep<TId>;
+    reset(): void;
+}
+export declare function createVolumeTrigger<TId = string>(config: VolumeTriggerConfig): VolumeTrigger<TId>;
 export interface PlatformCarryConfig {
     /** Vertical gap between a rider's base and the platform top counted as "standing on". Default 0.12. */
     contactTolerance?: number;