@jgengine/core 0.18.1 → 0.21.0

package/dist/physics/ballisticSweep.d.ts

@@ -11,8 +11,15 @@ export interface BallisticSweepOptions {
     radius?: number;
 }
 /**
- * Marches the closed-form arc (constant gravity, straight lateral) through `world` and reports the
- * first sample inside any live body's AABB — sleeping bodies included — refined by one bisection
- * between the last clear sample and the hit sample. Returns `null` when the whole arc is clear.
+ * Sweeps each short chord of the closed-form arc through live body AABBs, including sleeping bodies.
+ * Thin cover between samples blocks; `step` controls the approximation of the curved path.
  */
 export declare function createBallisticSweep(world: PhysicsWorld, options?: BallisticSweepOptions): BallisticSweep;
+/** Contact fraction for a point segment against a translating axis-aligned box; inflate extents for a projectile radius.
+ * @capability moving-box-sweep detect contact with boxes crossing a projectile segment between simulation poses
+ */
+export declare function sweepMovingBounds(from: readonly [number, number, number], to: readonly [number, number, number], targetFrom: readonly [number, number, number], targetTo: readonly [number, number, number], halfExtents: readonly [number, number, number]): number | null;
+/** Contact fraction for a point segment against a translating sphere; add the projectile radius to `radius`.
+ * @capability moving-sphere-sweep detect contact with spheres crossing a projectile segment between simulation poses
+ */
+export declare function sweepMovingSphere(from: readonly [number, number, number], to: readonly [number, number, number], targetFrom: readonly [number, number, number], targetTo: readonly [number, number, number], radius: number): number | null;

package/dist/physics/ballisticSweep.js

@@ -1,49 +1,73 @@
+import { intersectAabb } from "../scene/objectQuery.js";
 const DEFAULT_SWEEP_STEP = 1 / 60;
 /**
- * Marches the closed-form arc (constant gravity, straight lateral) through `world` and reports the
- * first sample inside any live body's AABB — sleeping bodies included — refined by one bisection
- * between the last clear sample and the hit sample. Returns `null` when the whole arc is clear.
+ * Sweeps each short chord of the closed-form arc through live body AABBs, including sleeping bodies.
+ * Thin cover between samples blocks; `step` controls the approximation of the curved path.
  */
 export function createBallisticSweep(world, options = {}) {
     const step = options.step ?? DEFAULT_SWEEP_STEP;
     const radius = options.radius ?? 0;
-    function overlapsAnyBody(x, y, z) {
-        for (let i = 0; i < world.highWater; i += 1) {
-            if (!world.isAlive(i))
-                continue;
-            if (Math.abs(x - world.posX[i]) > world.halfX[i] + radius)
-                continue;
-            if (Math.abs(y - world.posY[i]) > world.halfY[i] + radius)
-                continue;
-            if (Math.abs(z - world.posZ[i]) > world.halfZ[i] + radius)
-                continue;
-            return true;
-        }
-        return false;
-    }
+    if (!Number.isFinite(step) || step <= 0 || !Number.isFinite(radius) || radius < 0)
+        throw new RangeError("Ballistic sweep requires a finite positive step and nonnegative radius");
     return (origin, velocity, gravity, maxTime) => {
+        if (!origin.every(Number.isFinite) || !velocity.every(Number.isFinite) || !Number.isFinite(gravity) || !Number.isFinite(maxTime) || maxTime < 0 || Math.ceil(maxTime / step) > 100_000)
+            throw new RangeError("Ballistic sweep requires finite inputs within its 100000 segment budget");
         const pointAt = (t) => [
             origin[0] + velocity[0] * t,
             origin[1] + velocity[1] * t - 0.5 * gravity * t * t,
             origin[2] + velocity[2] * t,
         ];
-        let lastClear = 0;
         let t = 0;
         for (;;) {
-            const sample = pointAt(t);
-            if (overlapsAnyBody(sample[0], sample[1], sample[2])) {
-                if (t === 0)
-                    return { point: sample, time: 0 };
-                const mid = (lastClear + t) / 2;
-                const midSample = pointAt(mid);
-                return overlapsAnyBody(midSample[0], midSample[1], midSample[2])
-                    ? { point: midSample, time: mid }
-                    : { point: sample, time: t };
+            const nextTime = Math.min(t + step, maxTime);
+            const from = pointAt(t);
+            const to = pointAt(nextTime);
+            let fraction = null;
+            for (let i = 0; i < world.highWater; i += 1) {
+                if (!world.isAlive(i))
+                    continue;
+                const contact = sweepMovingBounds(from, to, [world.posX[i], world.posY[i], world.posZ[i]], [world.posX[i], world.posY[i], world.posZ[i]], [world.halfX[i] + radius, world.halfY[i] + radius, world.halfZ[i] + radius]);
+                if (contact !== null && (fraction === null || contact < fraction))
+                    fraction = contact;
+            }
+            if (fraction !== null) {
+                const time = t + (nextTime - t) * fraction;
+                return { point: pointAt(time), time };
             }
             if (t >= maxTime)
                 return null;
-            lastClear = t;
-            t = Math.min(t + step, maxTime);
+            t = nextTime;
         }
     };
 }
+/** Contact fraction for a point segment against a translating axis-aligned box; inflate extents for a projectile radius.
+ * @capability moving-box-sweep detect contact with boxes crossing a projectile segment between simulation poses
+ */
+export function sweepMovingBounds(from, to, targetFrom, targetTo, halfExtents) {
+    const origin = [from[0] - targetFrom[0], from[1] - targetFrom[1], from[2] - targetFrom[2]];
+    const motion = [to[0] - targetTo[0] - origin[0], to[1] - targetTo[1] - origin[1], to[2] - targetTo[2] - origin[2]];
+    return intersectAabb(origin, motion, [-halfExtents[0], -halfExtents[1], -halfExtents[2]], halfExtents, 1)?.distance ?? null;
+}
+/** Contact fraction for a point segment against a translating sphere; add the projectile radius to `radius`.
+ * @capability moving-sphere-sweep detect contact with spheres crossing a projectile segment between simulation poses
+ */
+export function sweepMovingSphere(from, to, targetFrom, targetTo, radius) {
+    const ox = from[0] - targetFrom[0];
+    const oy = from[1] - targetFrom[1];
+    const oz = from[2] - targetFrom[2];
+    const dx = to[0] - targetTo[0] - ox;
+    const dy = to[1] - targetTo[1] - oy;
+    const dz = to[2] - targetTo[2] - oz;
+    const c = ox * ox + oy * oy + oz * oz - radius * radius;
+    if (c <= 0)
+        return 0;
+    const a = dx * dx + dy * dy + dz * dz;
+    if (a <= 1e-18)
+        return null;
+    const b = ox * dx + oy * dy + oz * dz;
+    const discriminant = b * b - a * c;
+    if (discriminant < 0)
+        return null;
+    const fraction = (-b - Math.sqrt(discriminant)) / a;
+    return fraction >= 0 && fraction <= 1 ? fraction : null;
+}

package/dist/physics/boatDynamics.d.ts

@@ -0,0 +1,116 @@
+import type { AxisInput } from "../input/axisInput.js";
+/** How the boat turns: a rudder needs water flowing past it; an outboard swings its own thrust. */
+export type BoatSteering = {
+    kind: "rudder";
+    /** Rudder area, m². */
+    area: number;
+    /** Largest rudder angle, rad (default `0.6`). */
+    maxAngle?: number;
+    /** Share of prop thrust that washes over the rudder as flow, `0..1` (default `0.5`) — steering at low speed. */
+    propWash?: number;
+} | {
+    kind: "outboard";
+    /** Largest thrust angle, rad (default `0.5`). */
+    maxAngle?: number;
+};
+/**
+ * A powered hull in physical units. Drag rises toward hull speed (`√(g·L)·1.34`) and then falls away once the hull
+ * planes, the keel resists sliding sideways, and the prop's thrust fades as the boat approaches the prop's speed.
+ */
+export interface BoatTuning {
+    /** Displacement, kg. */
+    massKg: number;
+    /** Waterline length, m; sets hull speed and the rudder's lever arm. */
+    length: number;
+    /** Beam, m; sets the visual roll response. */
+    beam: number;
+    /** Peak prop thrust, N. */
+    maxThrust: number;
+    /** Speed at which prop thrust reaches zero, m/s. */
+    propSpeed: number;
+    /** Reverse thrust as a share of `maxThrust` (default `0.4`). */
+    reverseScale?: number;
+    /** Hull drag coefficient × wetted frontal area, m², before planing (default `0.3 · beam`). */
+    dragArea?: number;
+    /** Speed where the hull planes and drag drops, m/s; omit for a displacement hull that never planes. */
+    planingSpeed?: number;
+    /** Drag multiplier once fully planing, `0..1` (default `0.35`). */
+    planingDrag?: number;
+    /** Keel lateral resistance, N per (m/s)² of sideways speed (default `massKg · 6`). */
+    keel?: number;
+    /** Extra yaw damping, N·m per rad/s, on top of the keel resisting rotation along the hull (default `0`). */
+    yawDamping?: number;
+    steering: BoatSteering;
+    /** Rudder or outboard slew rate, rad/s (default `2`). */
+    steerRate?: number;
+    /** Largest bow-up pitch while climbing onto the plane, rad (default `0.12`). */
+    bowRise?: number;
+    /** Largest heel in a hard turn, rad (default `0.15`); planing hulls lean into the turn. */
+    maxHeel?: number;
+    /** Integration substep, s (default `1/240`). */
+    maxSubstep?: number;
+}
+/** World hooks for a boat instance. */
+export interface BoatOptions {
+    position?: readonly [number, number, number];
+    heading?: number;
+    /** Water surface height, m, under a point at a time (waves); default flat at the spawn height. */
+    waterHeight?: (x: number, z: number, time: number) => number;
+    /** Surface current, m/s, `[vx, vz]`; the hull drags toward it. */
+    current?: (x: number, z: number) => readonly [number, number];
+}
+/** Serializable boat state. */
+export interface BoatState {
+    x: number;
+    y: number;
+    z: number;
+    heading: number;
+    vx: number;
+    vz: number;
+    yawRate: number;
+    steerAngle: number;
+    time: number;
+    bodyPitch: number;
+    bodyRoll: number;
+}
+/** One boat tick: pose plus the telemetry wake, spray and engine sound read. */
+export interface BoatStep {
+    position: readonly [number, number, number];
+    heading: number;
+    forwardSpeed: number;
+    lateralSpeed: number;
+    yawRate: number;
+    /** Rudder or outboard angle, rad, positive steers like `steer > 0`. */
+    steerAngle: number;
+    /** `0` displacement … `1` fully planing. */
+    planing: number;
+    /** Thrust in use as a share of `maxThrust`, `0..1` — engine load. */
+    engineLoad: number;
+    bodyPitch: number;
+    bodyRoll: number;
+    /** Always `0`: the hull rides the water surface. Present so `tickDrivableVehicle` can drive it. */
+    airOffset: number;
+    airborne: boolean;
+}
+/** A force-based powered hull on the same tick/snapshot/retune contract as `VehicleDynamics`. */
+export interface BoatDynamics {
+    tick(dt: number, input: AxisInput): BoatStep;
+    pose(): {
+        position: readonly [number, number, number];
+        heading: number;
+    };
+    velocity(): readonly [number, number];
+    applyImpulse(dvx: number, dvz: number): void;
+    retune(next: BoatTuning): void;
+    tuning(): BoatTuning;
+    snapshot(): BoatState;
+    restore(state: BoatState): void;
+    resetTo(position: readonly [number, number, number], heading: number): void;
+}
+/**
+ * Creates a {@link BoatDynamics}: throttle drives the prop, brake reverses it, steer swings the rudder or outboard.
+ * A rudder boat barely turns at rest unless the prop is washing over it; an outboard turns at rest because it swings
+ * the thrust itself. Deterministic for a given `dt` sequence.
+ * @capability boat-dynamics force-based powered hull — hull-speed drag hump, planing, keel, rudder that needs flow or outboard thrust
+ */
+export declare function createBoatDynamics(initial: BoatTuning, options?: BoatOptions): BoatDynamics;

package/dist/physics/boatDynamics.js

@@ -0,0 +1,160 @@
+const GRAVITY = 9.81;
+const WATER_DENSITY = 1025;
+const DEFAULT_SUBSTEP = 1 / 240;
+function forwardOf(heading) {
+    return [Math.sin(heading), Math.cos(heading)];
+}
+/**
+ * Creates a {@link BoatDynamics}: throttle drives the prop, brake reverses it, steer swings the rudder or outboard.
+ * A rudder boat barely turns at rest unless the prop is washing over it; an outboard turns at rest because it swings
+ * the thrust itself. Deterministic for a given `dt` sequence.
+ * @capability boat-dynamics force-based powered hull — hull-speed drag hump, planing, keel, rudder that needs flow or outboard thrust
+ */
+export function createBoatDynamics(initial, options = {}) {
+    let tuning = initial;
+    const spawnY = options.position?.[1] ?? 0;
+    const water = options.waterHeight ?? (() => spawnY);
+    const current = options.current;
+    const state = fresh(options.position ?? [0, 0, 0], options.heading ?? 0);
+    state.y = water(state.x, state.z, 0);
+    const telemetry = { planing: 0, engineLoad: 0 };
+    function fresh(position, heading) {
+        return { x: position[0], y: position[1], z: position[2], heading, vx: 0, vz: 0, yawRate: 0, steerAngle: 0, time: 0, bodyPitch: 0, bodyRoll: 0 };
+    }
+    function substep(h, input) {
+        const t = tuning;
+        const m = t.massKg;
+        const [fx, fz] = forwardOf(state.heading);
+        let relX = state.vx;
+        let relZ = state.vz;
+        if (current !== undefined) {
+            const [cx, cz] = current(state.x, state.z);
+            relX -= cx;
+            relZ -= cz;
+        }
+        const u = relX * fx + relZ * fz;
+        const v = -relX * fz + relZ * fx;
+        const r = state.yawRate;
+        const throttle = Math.max(0, Math.min(1, input.throttle));
+        const reverse = Math.max(0, Math.min(1, input.brake));
+        const steerInput = Math.max(-1, Math.min(1, input.steer));
+        const steering = t.steering;
+        const maxAngle = steering.maxAngle ?? (steering.kind === "rudder" ? 0.6 : 0.5);
+        const targetAngle = -steerInput * maxAngle;
+        const slew = (t.steerRate ?? 2) * h;
+        state.steerAngle += Math.max(-slew, Math.min(slew, targetAngle - state.steerAngle));
+        const propFade = Math.max(0, 1 - Math.max(0, u) / Math.max(0.1, t.propSpeed));
+        const thrust = throttle * t.maxThrust * propFade - reverse * t.maxThrust * (t.reverseScale ?? 0.4);
+        telemetry.engineLoad = Math.max(throttle * propFade, reverse);
+        let forceLong = 0;
+        let forceLat = 0;
+        let yawMoment = 0;
+        const lever = t.length * 0.45;
+        if (steering.kind === "outboard") {
+            // The motor swings its own thrust, so the stern is pushed sideways even at rest.
+            forceLong += thrust * Math.cos(state.steerAngle);
+            const side = thrust * Math.sin(state.steerAngle);
+            forceLat += side;
+            yawMoment += lever * side;
+        }
+        else {
+            forceLong += thrust;
+            const flow = Math.max(0, u) + (steering.propWash ?? 0.5) * Math.sqrt(Math.max(0, thrust) / (WATER_DENSITY * Math.max(0.05, steering.area)));
+            // Rudder lift ≈ ½ρ·A·flow²·π·α (thin foil), stalled past ~0.6 rad. It pushes the stern away from the turn.
+            const angle = Math.max(-0.6, Math.min(0.6, state.steerAngle));
+            const lift = 0.5 * WATER_DENSITY * steering.area * flow * flow * Math.PI * angle;
+            forceLat += lift;
+            yawMoment += lever * lift;
+        }
+        const hullSpeed = 1.34 * Math.sqrt(GRAVITY * t.length);
+        const planeSpeed = t.planingSpeed;
+        const planing = planeSpeed === undefined ? 0 : Math.max(0, Math.min(1, (Math.abs(u) - planeSpeed * 0.8) / (planeSpeed * 0.4)));
+        telemetry.planing = planing;
+        // Wave-making drag climbs toward hull speed; a planing hull rides over it and sheds most of the hull drag.
+        // A displacement hull that never planes keeps climbing its own bow wave, so past hull speed the drag is a wall.
+        const over = Math.abs(u) / hullSpeed - 1;
+        const hump = planeSpeed === undefined && over > 0
+            ? 3.5 + 60 * over * over
+            : 1 + 2.5 * Math.exp(-((over / 0.35) ** 2));
+        const dragArea = (t.dragArea ?? 0.3 * t.beam) * (1 - planing * (1 - (t.planingDrag ?? 0.35))) * (planeSpeed === undefined ? hump : 1 + (hump - 1) * (1 - planing));
+        forceLong -= 0.5 * WATER_DENSITY * dragArea * u * Math.abs(u) * 0.01;
+        // A planing hull runs on a fraction of its bottom, so it grips the water less sideways and turns more freely.
+        const keel = (t.keel ?? m * 6) * (1 - 0.7 * planing);
+        forceLat -= keel * v * Math.abs(v) + m * 0.8 * v;
+        // A turning hull drags every station of the keel sideways at r·x; integrated over the length that resists yaw.
+        const length4 = t.length ** 4;
+        yawMoment -= keel * r * Math.abs(r) * (length4 / 80) + m * 0.8 * r * (t.length * t.length) / 12 + (t.yawDamping ?? 0) * r;
+        const iz = Math.max(1, m * t.length * t.length / 12);
+        let du = forceLong / m - r * v;
+        const dv = forceLat / m + r * u;
+        if (h > 0 && thrust === 0 && Math.sign(u + du * h) !== Math.sign(u) && u !== 0)
+            du = -u / h;
+        const nu = u + du * h;
+        const nv = v + dv * h;
+        const nr = r + (yawMoment / iz) * h;
+        state.heading += nr * h;
+        const [nfx, nfz] = forwardOf(state.heading);
+        let nvx = nfx * nu - nfz * nv;
+        let nvz = nfz * nu + nfx * nv;
+        if (current !== undefined) {
+            const [cx, cz] = current(state.x, state.z);
+            nvx += cx;
+            nvz += cz;
+        }
+        state.vx = nvx;
+        state.vz = nvz;
+        state.yawRate = nr;
+        state.x += nvx * h;
+        state.z += nvz * h;
+        state.time += h;
+        state.y = water(state.x, state.z, state.time);
+        const response = 1 - Math.exp(-4 * h);
+        const climb = planeSpeed === undefined ? 0 : Math.max(0, Math.min(1, Math.abs(u) / planeSpeed)) * (1 - planing);
+        const pitchTarget = -(t.bowRise ?? 0.12) * climb;
+        const heelTarget = Math.max(-(t.maxHeel ?? 0.15), Math.min(t.maxHeel ?? 0.15, (r * u) / GRAVITY * (planing > 0.5 ? -0.4 : 0.25)));
+        state.bodyPitch += (pitchTarget - state.bodyPitch) * response;
+        state.bodyRoll += (heelTarget - state.bodyRoll) * response;
+    }
+    return {
+        tick(dt, input) {
+            const maxSub = Math.max(1 / 2000, tuning.maxSubstep ?? DEFAULT_SUBSTEP);
+            const steps = dt > 0 ? Math.max(1, Math.ceil(dt / maxSub - 1e-9)) : 0;
+            const h = steps > 0 ? dt / steps : 0;
+            for (let i = 0; i < steps; i += 1)
+                substep(h, input);
+            const [fx, fz] = forwardOf(state.heading);
+            return {
+                position: [state.x, state.y, state.z],
+                heading: state.heading,
+                forwardSpeed: state.vx * fx + state.vz * fz,
+                lateralSpeed: -state.vx * fz + state.vz * fx,
+                yawRate: state.yawRate,
+                steerAngle: -state.steerAngle,
+                planing: telemetry.planing,
+                engineLoad: telemetry.engineLoad,
+                bodyPitch: state.bodyPitch,
+                bodyRoll: state.bodyRoll,
+                airOffset: 0,
+                airborne: false,
+            };
+        },
+        pose: () => ({ position: [state.x, state.y, state.z], heading: state.heading }),
+        velocity: () => [state.vx, state.vz],
+        applyImpulse(dvx, dvz) {
+            state.vx += dvx;
+            state.vz += dvz;
+        },
+        retune(next) {
+            tuning = next;
+        },
+        tuning: () => tuning,
+        snapshot: () => ({ ...state }),
+        restore(next) {
+            Object.assign(state, next);
+        },
+        resetTo(position, heading) {
+            Object.assign(state, fresh(position, heading));
+            state.y = water(state.x, state.z, 0);
+        },
+    };
+}

package/dist/physics/drivableVehicle.d.ts

@@ -1,12 +1,24 @@
 import type { AxisInput } from "../input/axisInput.js";
-import type { KinematicVehicle, KinematicVehicleModifiers, KinematicVehicleStep } from "./kinematicVehicle.js";
+import type { KinematicVehicleModifiers, KinematicVehicleStep } from "./kinematicVehicle.js";
 /** World-space `[x, y, z]` for a drivable vehicle's resolved pose. */
 export type DrivableVehiclePosition = readonly [number, number, number];
+/** The pose fields {@link tickDrivableVehicle} reads from a sim step; `KinematicVehicleStep` and `VehicleDynamicsStep` both carry them. */
+export interface DrivableSimStep {
+    position: readonly [number, number, number];
+    heading: number;
+    bodyPitch: number;
+    bodyRoll: number;
+    airOffset: number;
+}
+/** Any ground-vehicle sim {@link tickDrivableVehicle} can drive: `KinematicVehicle` or `VehicleDynamics`. */
+export interface DrivableSim<TModifiers, TStep extends DrivableSimStep> {
+    tick(dt: number, axis: AxisInput, modifiers?: TModifiers): TStep;
+}
 /** Options for {@link tickDrivableVehicle} — ground snapping and per-tick tuning modifiers. */
-export interface DrivableVehicleOptions {
+export interface DrivableVehicleOptions<TModifiers = KinematicVehicleModifiers> {
     /** Resamples world-space Y each tick (terrain height, a ramp, a bridge deck); omit to keep the sim's own flat `y`. */
     groundHeight?: (x: number, z: number) => number;
-    modifiers?: KinematicVehicleModifiers;
+    modifiers?: TModifiers;
 }
 /** A `setPose`-ready patch — spread straight into `entities.setPose(vehicleId, drive.pose)`. */
 export interface DrivableVehiclePose {
@@ -17,15 +29,17 @@ export interface DrivableVehiclePose {
     dt: number;
 }
 /** {@link tickDrivableVehicle}'s result — the ready-to-apply pose patch plus the raw sim step for HUD/telemetry reads. */
-export interface DrivableVehicleStep {
+export interface DrivableVehicleStep<TStep extends DrivableSimStep = KinematicVehicleStep> {
     pose: DrivableVehiclePose;
-    step: KinematicVehicleStep;
+    step: TStep;
 }
 /**
- * Connects an `AxisInput` sample straight through a {@link KinematicVehicle} to a scene entity's pose
- * for one tick (#533.1) — the throttle/steer/handbrake → sim → `setPose` loop every drivable-vehicle
+ * Connects an `AxisInput` sample straight through a ground-vehicle sim (`KinematicVehicle` or
+ * `VehicleDynamics`) to a scene entity's pose for one tick (#533.1) — the throttle/steer/handbrake → sim → `setPose` loop every drivable-vehicle
  * game hand-rolled. Ground-snaps the result when `groundHeight` is given (terrain-following cars, not
  * just flat racetracks). Pair with `scene/vehicleSeat` for who is allowed to drive and where the camera
  * points; this function only steps the sim and shapes the pose patch, nothing else.
+ *
+ * @capability drivable-vehicle drive a car from throttle/steer/handbrake input each tick: step the vehicle sim and pose its entity
  */
-export declare function tickDrivableVehicle(vehicle: KinematicVehicle, dt: number, axis: AxisInput, options?: DrivableVehicleOptions): DrivableVehicleStep;
+export declare function tickDrivableVehicle<TStep extends DrivableSimStep = KinematicVehicleStep, TModifiers = KinematicVehicleModifiers>(vehicle: DrivableSim<TModifiers, TStep>, dt: number, axis: AxisInput, options?: DrivableVehicleOptions<TModifiers>): DrivableVehicleStep<TStep>;

package/dist/physics/drivableVehicle.js

@@ -1,9 +1,11 @@
 /**
- * Connects an `AxisInput` sample straight through a {@link KinematicVehicle} to a scene entity's pose
- * for one tick (#533.1) — the throttle/steer/handbrake → sim → `setPose` loop every drivable-vehicle
+ * Connects an `AxisInput` sample straight through a ground-vehicle sim (`KinematicVehicle` or
+ * `VehicleDynamics`) to a scene entity's pose for one tick (#533.1) — the throttle/steer/handbrake → sim → `setPose` loop every drivable-vehicle
  * game hand-rolled. Ground-snaps the result when `groundHeight` is given (terrain-following cars, not
  * just flat racetracks). Pair with `scene/vehicleSeat` for who is allowed to drive and where the camera
  * points; this function only steps the sim and shapes the pose patch, nothing else.
+ *
+ * @capability drivable-vehicle drive a car from throttle/steer/handbrake input each tick: step the vehicle sim and pose its entity
  */
 export function tickDrivableVehicle(vehicle, dt, axis, options = {}) {
     const step = vehicle.tick(dt, axis, options.modifiers);

package/dist/physics/flightDynamics.d.ts

@@ -27,7 +27,10 @@ export interface FlightControlRates {
 }
 /** Axes an aircraft can bind — which actions drive each flight control. */
 export type AircraftAxis = "pitch" | "roll" | "yaw" | "throttle" | "collective" | "airbrake" | "afterburner" | "vectoring";
-/** Data-first physical tuning shared by all aircraft instances of one catalog type. */
+/**
+ * Data-first physical tuning shared by all aircraft instances of one catalog type.
+ * @deprecated Rotation is commanded from rates with pitch clamped to ±0.49π, so it can't loop, and mass and stall angle are fixed. Use `createRigidAircraft` (`physics/aircraftDynamics`), whose rotation comes from surface forces on an inertia tensor.
+ */
 export interface AircraftTuning {
     kind: AircraftKind;
     mass: number;
@@ -73,6 +76,15 @@ export interface AircraftStep {
     grounded: boolean;
     gForce: number;
 }
+/** Serializable integrator state of an {@link AircraftDynamics}: what `restore` needs to resume bit-for-bit. */
+export interface AircraftDynamicsState {
+    position: FlightVector;
+    velocity: FlightVector;
+    rotation: FlightVector;
+    angular: FlightVector;
+    rotor: number;
+    lastVerticalSpeed: number;
+}
 /** Stateful six-degree-of-freedom aircraft simulation. */
 export interface AircraftDynamics {
     tick(dt: number, input: FlightControlInput): AircraftStep;
@@ -83,8 +95,13 @@ export interface AircraftDynamics {
     velocity(): FlightVector;
     resetTo(position: FlightVector, rotation?: FlightVector): void;
     setVelocity(velocity: FlightVector): void;
+    /** Swap tuning in place (damage, upgrades, a live tuning panel) without losing pose or momentum. */
+    retune(next: AircraftTuning): void;
+    snapshot(): AircraftDynamicsState;
+    restore(state: AircraftDynamicsState): void;
 }
-/** Six-degree-of-freedom arcade flight model for fixed-wing, helicopter, and VTOL aircraft.
- * @capability flight-dynamics simulate fixed-wing, helicopter, and VTOL aircraft
+/**
+ * Six-degree-of-freedom arcade flight model for fixed-wing, helicopter, and VTOL aircraft.
+ * @deprecated Rotation is commanded from rates with pitch clamped to ±0.49π, so it can't loop, and mass and stall angle are fixed. Use `createRigidAircraft` (`physics/aircraftDynamics`), whose rotation comes from surface forces on an inertia tensor.
  */
-export declare function createAircraftDynamics(tuning: AircraftTuning, options?: AircraftOptions): AircraftDynamics;
+export declare function createAircraftDynamics(initialTuning: AircraftTuning, options?: AircraftOptions): AircraftDynamics;

package/dist/physics/flightDynamics.js

@@ -29,18 +29,20 @@ function wrapAngle(value) {
         angle += Math.PI * 2;
     return angle;
 }
-/** Six-degree-of-freedom arcade flight model for fixed-wing, helicopter, and VTOL aircraft.
- * @capability flight-dynamics simulate fixed-wing, helicopter, and VTOL aircraft
+/**
+ * Six-degree-of-freedom arcade flight model for fixed-wing, helicopter, and VTOL aircraft.
+ * @deprecated Rotation is commanded from rates with pitch clamped to ±0.49π, so it can't loop, and mass and stall angle are fixed. Use `createRigidAircraft` (`physics/aircraftDynamics`), whose rotation comes from surface forces on an inertia tensor.
  */
-export function createAircraftDynamics(tuning, options = {}) {
+export function createAircraftDynamics(initialTuning, options = {}) {
+    let tuning = initialTuning;
     let position = [...(options.position ?? [0, 0, 0])];
     let velocity = [...(options.velocity ?? [0, 0, 0])];
     let rotation = [...(options.rotation ?? [0, 0, 0])];
     let angular = [0, 0, 0];
     let rotor = 0;
     let lastVerticalSpeed = velocity[1];
-    const gravity = Math.abs(tuning.gravity ?? 9.81);
-    const gravityField = options.gravityField ?? uniformGravity([0, -gravity, 0]);
+    let gravity = Math.abs(tuning.gravity ?? 9.81);
+    let gravityField = options.gravityField ?? uniformGravity([0, -gravity, 0]);
     const windAt = options.wind ?? (() => [0, 0, 0]);
     const groundAt = options.groundHeight ?? (() => 0);
     return {
@@ -161,5 +163,26 @@ export function createAircraftDynamics(tuning, options = {}) {
             velocity = [...nextVelocity];
             lastVerticalSpeed = velocity[1];
         },
+        retune(next) {
+            tuning = next;
+            gravity = Math.abs(next.gravity ?? 9.81);
+            gravityField = options.gravityField ?? uniformGravity([0, -gravity, 0]);
+        },
+        snapshot: () => ({
+            position: [...position],
+            velocity: [...velocity],
+            rotation: [...rotation],
+            angular: [...angular],
+            rotor,
+            lastVerticalSpeed,
+        }),
+        restore(state) {
+            position = [...state.position];
+            velocity = [...state.velocity];
+            rotation = [...state.rotation];
+            angular = [...state.angular];
+            rotor = state.rotor;
+            lastVerticalSpeed = state.lastVerticalSpeed;
+        },
     };
 }

package/dist/physics/forceVolume.d.ts

@@ -1,5 +1,46 @@
 import type { PhysicsBounds, PhysicsWorld } from "./physicsWorld.js";
 export type ForceMode = "impulse" | "velocity" | "accelerate";
+/** World-space force position, axis or acceleration vector. */
+export type ForceVector = readonly [number, number, number];
+/** Renderer-free localized acceleration shared by physical actors and cosmetic particles. */
+export interface ForceFieldConfig {
+    center: ForceVector;
+    shape: {
+        kind: "sphere";
+        radius: number;
+    } | {
+        kind: "box";
+        halfExtents: ForceVector;
+    };
+    /** Positive attracts toward the center; negative repels. Units/s². */
+    strength: number;
+    /** Edge-to-center falloff exponent; zero is uniform. Default 1. */
+    attenuation?: number;
+    /** Blend radial attraction with `direction`, from 0 to 1. */
+    directionality?: number;
+    /** World-space direction; default [0, 0, -1]. */
+    direction?: ForceVector;
+    /** Signed tangential acceleration around a world-space axis. */
+    vortex?: {
+        axis: ForceVector;
+        strength: number;
+        /** Independent signed acceleration along the normalized axis, in units/s². */
+        lift?: number;
+    };
+    /** Affected target bits; omission affects every target. */
+    mask?: number;
+    /** Cap the combined acceleration magnitude. */
+    maxAcceleration?: number;
+}
+/** Validate force authoring once before sampling in a hot loop.
+ * Coordinates stay within the safe integer range; acceleration magnitudes stay within 1e12 units/s².
+ * @capability force-field-validation reject invalid localized force authoring before simulation
+ */
+export declare function validateForceField(config: ForceFieldConfig): void;
+/** Sample localized acceleration; `out` permits allocation-free integration.
+ * @capability localized-forces sample signed attraction, directional force, vortex spin and axial lift with target masks and caps
+ */
+export declare function sampleForceField(config: ForceFieldConfig, position: ForceVector, targetMask?: number, out?: [number, number, number]): [number, number, number];
 export interface ForceVolumeConfig {
     /** Region a body's center must be inside to be affected. */
     bounds: PhysicsBounds;