@jgengine/core 0.8.0 → 0.9.0

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;

package/dist/physics/forceVolume.js

@@ -63,6 +63,44 @@ export class ForceVolume {
         this.members = next;
     }
 }
+/** One tick's force math for a body outside `PhysicsWorld` — apply the returned velocity in any custom integrator. */
+export function applyVolumeForce(velocity, force, mode, dt) {
+    if (mode === "velocity")
+        return force;
+    if (mode === "accelerate") {
+        return [velocity[0] + force[0] * dt, velocity[1] + force[1] * dt, velocity[2] + force[2] * dt];
+    }
+    return [velocity[0] + force[0], velocity[1] + force[1], velocity[2] + force[2]];
+}
+export function createVolumeTrigger(config) {
+    let members = new Set();
+    return {
+        bounds: config.bounds,
+        step(bodies) {
+            const entered = [];
+            const insideNow = [];
+            const next = new Set();
+            for (const body of bodies) {
+                if (!inside(config.bounds, body.position[0], body.position[1], body.position[2]))
+                    continue;
+                next.add(body.id);
+                insideNow.push(body.id);
+                if (!members.has(body.id))
+                    entered.push(body.id);
+            }
+            const exited = [];
+            for (const id of members) {
+                if (!next.has(id))
+                    exited.push(id);
+            }
+            members = next;
+            return { entered, inside: insideNow, exited };
+        },
+        reset() {
+            members = new Set();
+        },
+    };
+}
 /**
  * Carries bodies standing on a moving platform by composing their transform with the platform's
  * per-`step` delta — moving/rotating lifts and conveyor floors (Fall Guys, Gang Beasts). The

package/dist/physics/kinematicVehicle.d.ts

@@ -0,0 +1,52 @@
+import type { AxisInput } from "../input/axisInput.js";
+import { type GripCurve } from "./vehicleBody.js";
+export interface KinematicVehicleTuning {
+    engineAccel: number;
+    brakeAccel: number;
+    topSpeed: number;
+    reverseSpeed: number;
+    turnRate: number;
+    turnSpeedRef: number;
+    grip?: GripCurve;
+    gripStrength: number;
+    handbrakeGrip: number;
+    /** Forward-speed decay per second when coasting (sleds, boats); default `0`. */
+    rollingResistance?: number;
+}
+export interface KinematicVehicleOptions {
+    position?: readonly [number, number, number];
+    heading?: number;
+    /** Grip multiplier by world position — off-track gravel, ice patches; default `1` everywhere. */
+    surfaceFriction?: (x: number, z: number) => number;
+    /** Extra velocity damping per second by world position (rough ground drag); default `0`. */
+    dragAt?: (x: number, z: number) => number;
+}
+export interface KinematicVehicleStep {
+    position: readonly [number, number, number];
+    heading: number;
+    /** Signed speed along the heading, world units/s. */
+    forwardSpeed: number;
+    lateralSpeed: number;
+    /** Lateral/forward slip ratio driving the grip curve — drift indicators key off it. */
+    slip: number;
+    /** The `surfaceFriction` sample used this tick (`< 1` = off the ideal surface). */
+    surface: number;
+}
+/**
+ * The pure-kinematic arcade car every racing game hand-rolled (#282.1): steer-yaw scaled by speed,
+ * throttle/brake acceleration, and a grip-curve lateral-slip bleed — no `PhysicsWorld`, no wheels,
+ * just the drift-friendly integration the three shipped racers proved out. Games keep their flavor
+ * (drift meters, boost, off-track rules) via `surfaceFriction`/`dragAt` hooks and the returned slip.
+ */
+export interface KinematicVehicle {
+    tick(dt: number, axis: AxisInput): KinematicVehicleStep;
+    pose(): {
+        position: readonly [number, number, number];
+        heading: number;
+    };
+    velocity(): readonly [number, number];
+    /** Scale the current velocity (boost pads, hard collisions). */
+    scaleVelocity(factor: number): void;
+    resetTo(position: readonly [number, number, number], heading: number): void;
+}
+export declare function createKinematicVehicle(tuning: KinematicVehicleTuning, options?: KinematicVehicleOptions): KinematicVehicle;

package/dist/physics/kinematicVehicle.js

@@ -0,0 +1,81 @@
+import { steerYaw } from "../movement/steering.js";
+import { DEFAULT_GRIP_CURVE, sampleGripCurve } from "./vehicleBody.js";
+export function createKinematicVehicle(tuning, options = {}) {
+    const grip = tuning.grip ?? DEFAULT_GRIP_CURVE;
+    const rollingResistance = tuning.rollingResistance ?? 0;
+    const surfaceFriction = options.surfaceFriction ?? (() => 1);
+    const dragAt = options.dragAt ?? (() => 0);
+    let x = options.position?.[0] ?? 0;
+    let y = options.position?.[1] ?? 0;
+    let z = options.position?.[2] ?? 0;
+    let heading = options.heading ?? 0;
+    let vx = 0;
+    let vz = 0;
+    function forward() {
+        return [Math.sin(heading), Math.cos(heading)];
+    }
+    return {
+        tick(dt, axis) {
+            const [fx0, fz0] = forward();
+            const speed = vx * fx0 + vz * fz0;
+            const steerScale = Math.min(1, Math.abs(speed) / tuning.turnSpeedRef);
+            const direction = speed >= 0 ? 1 : -1;
+            heading = steerYaw(heading, axis.steer * steerScale * direction, tuning.turnRate, dt);
+            const [fx, fz] = forward();
+            let accel = 0;
+            if (axis.throttle > 0 && speed < tuning.topSpeed)
+                accel += axis.throttle * tuning.engineAccel;
+            if (axis.brake > 0) {
+                if (speed > 0.2)
+                    accel -= axis.brake * tuning.brakeAccel;
+                else if (speed > -tuning.reverseSpeed)
+                    accel -= axis.brake * tuning.engineAccel;
+            }
+            vx += fx * accel * dt;
+            vz += fz * accel * dt;
+            let forwardSpeed = vx * fx + vz * fz;
+            const lateralSpeed = -vx * fz + vz * fx;
+            const surface = surfaceFriction(x, z);
+            const slip = Math.abs(lateralSpeed) / (Math.abs(forwardSpeed) + 1);
+            const handbrakeFactor = 1 - axis.handbrake * (1 - tuning.handbrakeGrip);
+            const gripValue = sampleGripCurve(grip, slip) * surface * handbrakeFactor;
+            const keep = Math.max(0, 1 - gripValue * tuning.gripStrength * dt);
+            const keptLateral = lateralSpeed * keep;
+            if (rollingResistance > 0)
+                forwardSpeed *= Math.max(0, 1 - rollingResistance * dt);
+            vx = fx * forwardSpeed - fz * keptLateral;
+            vz = fz * forwardSpeed + fx * keptLateral;
+            const drag = dragAt(x, z);
+            let dragDamp = 1;
+            if (drag > 0) {
+                dragDamp = Math.max(0, 1 - drag * dt);
+                vx *= dragDamp;
+                vz *= dragDamp;
+            }
+            x += vx * dt;
+            z += vz * dt;
+            return {
+                position: [x, y, z],
+                heading,
+                forwardSpeed: vx * fx + vz * fz,
+                lateralSpeed: keptLateral * dragDamp,
+                slip,
+                surface,
+            };
+        },
+        pose: () => ({ position: [x, y, z], heading }),
+        velocity: () => [vx, vz],
+        scaleVelocity(factor) {
+            vx *= factor;
+            vz *= factor;
+        },
+        resetTo(position, nextHeading) {
+            x = position[0];
+            y = position[1];
+            z = position[2];
+            heading = nextHeading;
+            vx = 0;
+            vz = 0;
+        },
+    };
+}

package/dist/physics/physicsWorld.d.ts

@@ -72,11 +72,15 @@ export type AddBodyOptions = BoxBodyOptions | SphereBodyOptions;
 export declare const SHAPE_BOX = 0;
 export declare const SHAPE_SPHERE = 1;
 /**
- * `hinge`/`fixed`/`distance` are hard bilateral constraints; `spring` is a soft PD constraint.
- * No angular state → `hinge`/`fixed` both pin the shared anchor (`axis` is metadata), `distance`
- * holds a fixed separation, `spring` drives toward `restLength` (suspension, follow-point carry).
+ * Hard bilateral: `fixed` pins the shared anchor (3-DOF), `hinge` pins only the plane
+ * perpendicular to `axis` (free along the axis — translational cylindrical), `distance`
+ * holds a fixed separation. `spring` is a soft PD drive toward `restLength`.
  */
 export type JointKind = "hinge" | "distance" | "spring" | "fixed";
+export declare const JOINT_FIXED = 0;
+export declare const JOINT_HINGE = 1;
+export declare const JOINT_DISTANCE = 2;
+export declare const JOINT_SPRING = 3;
 export interface JointOptions {
     /** First body index. */
     bodyA: number;
@@ -94,7 +98,7 @@ export interface JointOptions {
     damping?: number;
     /** Clamp on the per-substep spring impulse (a follow-point that never yanks). Default unbounded. */
     maxImpulse?: number;
-    /** Hinge axis, retained as metadata (this sim has no angular DOF). */
+    /** Unit hinge axis (world). Required semantics for `hingeJoint`; free motion along this axis. Default [0,1,0]. */
     axis?: readonly [number, number, number];
 }
 /** A contact reported to `onCollision`. The object is reused each call — read/copy, never retain. */
@@ -157,12 +161,12 @@ export declare class PhysicsWorld {
     private readonly numCells;
     private readonly cellStart;
     private readonly cursor;
-    private readonly sorted;
+    private sorted;
     private readonly bodyCell;
     private readonly awakeList;
     private readonly awakeSlot;
     private awakeCount;
-    private readonly jSpring;
+    private readonly jKind;
     private readonly jActive;
     private readonly jBodyA;
     private readonly jBodyB;
@@ -172,6 +176,9 @@ export declare class PhysicsWorld {
     private readonly jAnchorBX;
     private readonly jAnchorBY;
     private readonly jAnchorBZ;
+    private readonly jAxisX;
+    private readonly jAxisY;
+    private readonly jAxisZ;
     private readonly jRest;
     private readonly jStiffness;
     private readonly jDamping;