@jgengine/core 0.18.0 → 0.19.0

package/dist/physics/vehicleDynamics.d.ts

@@ -0,0 +1,374 @@
+import type { AxisInput } from "../input/axisInput.js";
+import type { GripCurve } from "./vehicleBody.js";
+/**
+ * One axle's tire, in physical terms. Lateral force follows a simplified Pacejka curve
+ * `μ·Fz·sin(C·atan(B·α))` whose `B`/`C` are solved from `peakSlipAngle` and `slideGrip`, so the three
+ * numbers read the way a driver feels them: how much grip, how early it peaks, how much is left sliding.
+ */
+export interface VehicleTireTuning {
+    /** Peak friction coefficient μ on an ideal surface (0.7 worn street … 1.1 sport … 1.6 slick/arcade). */
+    peakGrip: number;
+    /** Slip angle in radians where lateral force peaks (0.07 stiff race tire … 0.2 soft, forgiving tire). */
+    peakSlipAngle: number;
+    /** Fraction of peak force left at a full 90° slide, `0..1` (0.6 snappy … 0.95 drift-friendly). */
+    slideGrip: number;
+}
+/** Engine and gearbox. Drive force at the wheels = torque · curve(rpm) · gear · finalDrive · efficiency / wheelRadius. */
+export interface VehicleGearboxTuning {
+    kind: "gearbox";
+    /** Peak engine torque, N·m. */
+    peakTorque: number;
+    /** Torque multiplier by normalized rpm (`0` = idle, `1` = redline); same shape as a grip curve. */
+    torqueCurve: GripCurve;
+    idleRpm: number;
+    redlineRpm: number;
+    shiftUpRpm: number;
+    shiftDownRpm: number;
+    /** Seconds of reduced drive during a shift. */
+    shiftSeconds: number;
+    gears: readonly number[];
+    reverseGear: number;
+    finalDrive: number;
+    /** Driven wheel radius, m. */
+    wheelRadius: number;
+    /** Driveline efficiency `0..1` (default `0.85`). */
+    efficiency?: number;
+    /** Engine-braking torque at the crank with the throttle closed, N·m (default `0.12 · peakTorque`). */
+    engineBrakeTorque?: number;
+    /** Clutch-slip rpm the engine holds while launching from rest (default halfway between idle and peak). */
+    launchRpm?: number;
+}
+/** Single-speed drive (electric, kart, arcade ball-car): force capped by power, so top speed comes out of drag. */
+export interface VehicleDirectDriveTuning {
+    kind: "direct";
+    /** Maximum tractive force at the wheels, N. */
+    maxForce: number;
+    /** Maximum power, W; force falls off as `power / speed` above the crossover. */
+    maxPower: number;
+    /** Reverse force as a fraction of `maxForce` (default `0.5`). */
+    reverseScale?: number;
+    /** Throttle-off drag force at the wheels, N (default `0.08 · maxForce`). */
+    coastForce?: number;
+}
+/** Steering rack: lock, speed-sensitive lock, rack speed, and caster self-alignment. */
+export interface VehicleSteeringTuning {
+    /** Front-wheel lock at parking speed, rad. */
+    maxAngle: number;
+    /** Lock at and above `highSpeedAt`, rad; lower = calmer at speed. */
+    highSpeedAngle: number;
+    /** Speed where lock reaches `highSpeedAngle`, m/s. */
+    highSpeedAt: number;
+    /** Rack speed toward the requested angle, rad/s — a keyboard tap and a stick flick both pass through this. */
+    rate: number;
+    /** Rack speed back to centre when the request is released or reversed, rad/s (default `rate`). */
+    returnRate?: number;
+    /**
+     * Caster self-alignment `0..1`: the fraction of the car's sideslip the front wheels steer into on their
+     * own. `0` leaves every catch to the driver (sim), `~0.3` is a real street car, `0.8+` catches slides for
+     * the player (arcade).
+     */
+    selfAlign?: number;
+}
+/** Electronic and arcade assists; each is a strength `0..1`, `0`/omitted = off. */
+export interface VehicleAssistTuning {
+    /** Anti-lock: caps brake force below the tire's remaining grip so the front keeps steering. */
+    abs?: number;
+    /** Traction control: caps drive force below the driven axle's remaining grip. */
+    tractionControl?: number;
+    /**
+     * Stability (yaw) control: a corrective yaw torque once sideslip exceeds `maxSideslip`. Real ESC is subtle
+     * (`~0.3`); arcade street cars that can't spin out sit near `1`.
+     */
+    stability?: number;
+    /** Sideslip in rad that `stability` allows before it intervenes (default `0.2`, ≈11°). */
+    maxSideslip?: number;
+    /** Anti-wheelie: caps drive below the acceleration that lifts the front (`g·b/h`); reports as `tractionLimited`. */
+    antiWheelie?: number;
+    /** Anti-stoppie: caps braking below the deceleration that lifts the rear (`g·a/h`); reports as `absActive`. */
+    antiStoppie?: number;
+}
+/** Aero and resistance. Uses air density 1.225 kg/m³. */
+export interface VehicleAeroTuning {
+    /** Drag coefficient × frontal area, m² (0.6 sports car … 1.0 SUV). */
+    dragArea?: number;
+    /** Lift coefficient × area producing downforce, m² (0 road car … 3 race car). */
+    downforceArea?: number;
+    /** Share of downforce on the front axle, `0..1` (default `0.45`). */
+    downforceFront?: number;
+    /** Rolling-resistance coefficient (default `0.015`). */
+    rollingResistance?: number;
+}
+/**
+ * Four sprung corners. With this block the chassis heaves, pitches and rolls on real springs, axle loads come
+ * from spring forces instead of a filtered estimate, slopes pull the car downhill, and the car can leave
+ * the ground and land. Omit it for the flat-ground model.
+ */
+export interface VehicleSuspensionTuning {
+    /** Spring rate per wheel, N/m (20 000 soft road car … 60 000 race car; monster trucks go lower with more travel). */
+    springRate: number;
+    /** Damper rate per wheel in compression, N·s/m (roughly 2·√(k·m/4)·0.3 for a comfortable car, higher for a racer). */
+    damperRate: number;
+    /** Damper rate per wheel in extension, N·s/m (default `1.5 · damperRate`); higher keeps a landing from bouncing. */
+    reboundRate?: number;
+    /** Compression available before the bump stop, m (0.08 race car … 0.6 monster truck). */
+    travel: number;
+    /** Centre-of-mass height above level ground at static rest, m. */
+    rideHeight: number;
+    /** Total anti-roll bar stiffness, N·m/rad, split between axles by `rollStiffnessFront` (default `0`). */
+    antiRoll?: number;
+    /** Pitch inertia as a multiple of `m·a·b` (default `0.9`). */
+    pitchInertiaIndex?: number;
+}
+/** Control of the body while airborne (needs `suspension`, the only way to leave the ground). */
+export interface VehicleAirTuning {
+    /** Angular acceleration at full input, rad/s², per axis. */
+    pitchAccel: number;
+    yawAccel: number;
+    rollAccel: number;
+    /** Angular damping while airborne, 1/s (default `1.5`); higher stops rotation when input is released. */
+    damping?: number;
+    /** Largest angular rate input can build, rad/s (default `5.5`). */
+    maxRate?: number;
+}
+/**
+ * Single-track lean for motorcycles, bicycles and scooters. Steer input asks for a lean angle; the front wheel
+ * then takes whatever angle a balanced turn at that lean needs (curvature = g·tan(lean) / v²), with a brief
+ * countersteer as the lean starts. Tire grip still limits the turn, so over-leaning on a low-grip surface slides.
+ */
+export interface VehicleLeanTuning {
+    /** Largest lean the rider asks for at full steer, rad (0.7 ≈ 40° road bike … 0.95 ≈ 55° race bike). */
+    maxLean: number;
+    /** How fast the bike can change lean, rad/s (2 heavy tourer … 5 light sport bike). */
+    leanRate: number;
+    /** Seconds of opposite bar per rad/s of lean change — the countersteer that starts a lean (default `0.012`, about 3° of bar on a quick sport bike). */
+    countersteer?: number;
+    /** Below this speed the bar steers directly, like walking a bike (default `3` m/s). */
+    directSteerBelow?: number;
+}
+/** Jumps from the ground and in the air. */
+export interface VehicleJumpTuning {
+    /** Upward velocity a jump adds, m/s. */
+    speed: number;
+    /** Jumps allowed per flight, counting the first from the ground (default `1`; `2` = double jump). */
+    count?: number;
+    /** Seconds after leaving the ground during which later jumps are allowed (default `Infinity`). */
+    window?: number;
+}
+/**
+ * Tuning for {@link createVehicleDynamics}. Every number is a physical quantity in SI units (kg, m, N,
+ * N·m, rad, s), so a feel target maps to a knob a person can reason about: more rear grip or a lower
+ * centre of mass for stability, softer tires for forgiveness, more drive to the rear for power oversteer.
+ */
+export interface VehicleDynamicsTuning {
+    /** Total mass, kg. */
+    massKg: number;
+    /** Axle-to-axle distance, m. */
+    wheelbase: number;
+    /** Share of static weight on the front axle, `0..1` (0.6 front-engined FWD … 0.45 mid-engine). */
+    frontWeight: number;
+    /** Centre-of-mass height, m; drives longitudinal and lateral load transfer and body attitude. */
+    comHeight: number;
+    /** Track width, m. */
+    trackWidth: number;
+    /** Yaw inertia as a dynamic index `Iz / (m·a·b)` (default `1`; `<1` rotates eagerly, `>1` lazily). */
+    yawInertiaIndex?: number;
+    /**
+     * Share of lateral load transfer taken by the front axle, `0..1` (default `0.5`). The classic balance knob:
+     * more front → the front saturates first (understeer), less → the rear does (oversteer).
+     */
+    rollStiffnessFront?: number;
+    /** Tire load sensitivity `0..0.5`: how much an axle's grip drops as load moves across it (default `0.2`). */
+    loadSensitivity?: number;
+    front: VehicleTireTuning;
+    /** Rear tire; defaults to `front`. */
+    rear?: VehicleTireTuning;
+    /** Share of drive force to the front axle, `0..1` (`0` RWD, `1` FWD, `0.35` rear-biased AWD). */
+    driveFront: number;
+    powertrain: VehicleGearboxTuning | VehicleDirectDriveTuning;
+    /** Peak service-brake force across all wheels, N. */
+    brakeForce: number;
+    /** Share of brake force on the front axle, `0..1` (default `0.65`). */
+    brakeFront?: number;
+    /** Rear lateral grip multiplier while the handbrake is fully on (default `0.35`). */
+    handbrakeGrip?: number;
+    steering: VehicleSteeringTuning;
+    assists?: VehicleAssistTuning;
+    aero?: VehicleAeroTuning;
+    /**
+     * Drive governor, m/s: drive force fades out over the last 0.5 m/s below it (arcade caps, electronic
+     * limiters). Thrust, slopes and impulses can still carry the car past it. Omit to let power and drag decide.
+     */
+    speedLimit?: number;
+    /** Reverse speed cap, m/s (default `8`). */
+    reverseSpeed?: number;
+    /** Body roll stiffness, N·m/rad, for the visual lean (default derived for ~3° at 1 g). */
+    rollStiffness?: number;
+    /** Body pitch stiffness, N·m/rad, for dive and squat (default derived for ~2° at 1 g). */
+    pitchStiffness?: number;
+    /** Suspension settle rate for load transfer and body attitude, 1/s (default `8`). */
+    suspensionResponse?: number;
+    /** Largest integration substep, s (default `1/240`); ticks are split so the result does not depend on frame rate. */
+    maxSubstep?: number;
+    /** Brake held near standstill drives in reverse (default `true`). Set `false` for a separate reverse action. */
+    reverseOnBrake?: boolean;
+    /** Sprung corners, slopes and air; omit for the flat-ground model. */
+    suspension?: VehicleSuspensionTuning;
+    /** Air control; needs `suspension`. Input comes from `modifiers.air`, else throttle−brake pitches and steer yaws. */
+    air?: VehicleAirTuning;
+    /** Enables {@link VehicleDynamics.jump}; needs `suspension`. */
+    jump?: VehicleJumpTuning;
+    /** Single-track lean (motorcycle); omit for a four-wheeled car. `trackWidth` then only sets the render width. */
+    lean?: VehicleLeanTuning;
+}
+/** Air-control input, each `-1..1`: `pitch > 0` noses down, `yaw > 0` turns like `steer > 0`, `roll > 0` drops the left side. */
+export interface VehicleAirInput {
+    pitch: number;
+    yaw: number;
+    roll: number;
+}
+/** Per-tick overrides layered over tuning: boost, grip zones, damage. Each scale defaults to `1`. */
+export interface VehicleDynamicsModifiers {
+    driveScale?: number;
+    brakeScale?: number;
+    gripScale?: number;
+    steerScale?: number;
+    /** Thrust along the heading that bypasses the tires, N — boost, a rocket, a tow. */
+    thrust?: number;
+    /** Air-control input this tick; omitted, throttle−brake pitches and steer yaws while airborne. */
+    air?: VehicleAirInput;
+}
+/** World hooks for one vehicle instance. */
+export interface VehicleDynamicsOptions {
+    position?: readonly [number, number, number];
+    heading?: number;
+    /** Grip multiplier by world position (gravel, ice, wet paint); default `1`. */
+    surfaceFriction?: (x: number, z: number) => number;
+    /** Clamp a planar move (walls, bounds); velocity is rederived from the allowed displacement. */
+    clampMove?: (from: readonly [number, number], to: readonly [number, number]) => readonly [number, number];
+    /** Terrain height under a point; read per wheel when `suspension` is set (ramps, hills, ledges). Default flat at the spawn height. */
+    groundHeight?: (x: number, z: number) => number;
+}
+/** Serializable integrator state: everything {@link VehicleDynamics.restore} needs to resume bit-for-bit. */
+export interface VehicleDynamicsState {
+    x: number;
+    y: number;
+    z: number;
+    heading: number;
+    vx: number;
+    vz: number;
+    yawRate: number;
+    steerAngle: number;
+    gearIndex: number;
+    reversing: boolean;
+    shiftRemaining: number;
+    rpm: number;
+    longitudinalAccel: number;
+    lateralAccel: number;
+    bodyPitch: number;
+    bodyRoll: number;
+    /** Vertical velocity of the chassis, m/s (suspension only). */
+    vy: number;
+    pitchRate: number;
+    rollRate: number;
+    /** Per-corner spring compression, m, in order front-left, front-right, rear-left, rear-right. */
+    compression: [number, number, number, number];
+    airborne: boolean;
+    /** The lean the rider is asking for, rad, positive right; it sets the turn the bar steers for. */
+    lean: number;
+    /** The rider's bar correction on top of the balanced-turn angle, rad. */
+    leanTrim: number;
+    /** Jumps used since last on the ground. */
+    jumpsUsed: number;
+    /** Seconds since leaving the ground (`0` while grounded). */
+    airTime: number;
+}
+/** Result of one {@link VehicleDynamics.tick}: pose plus the telemetry camera, audio, haptics and HUD read. */
+export interface VehicleDynamicsStep {
+    position: readonly [number, number, number];
+    heading: number;
+    /** Signed speed along the heading, m/s. */
+    forwardSpeed: number;
+    /** Lateral speed, m/s (same sign convention as `KinematicVehicleStep.lateralSpeed`). */
+    lateralSpeed: number;
+    yawRate: number;
+    /** Front-wheel angle, rad; positive steers the heading down, like `AxisInput.steer`. */
+    steerAngle: number;
+    /** Body sideslip β, rad: angle between heading and velocity. */
+    sideslip: number;
+    slipAngleFront: number;
+    slipAngleRear: number;
+    /** Share of each axle's friction budget in use, `0..1+`; `≥1` means that axle is sliding. Squeal, rumble and HUD key off it. */
+    frontSaturation: number;
+    rearSaturation: number;
+    /** Lateral acceleration, m/s²; positive toward the car's right, the way `steer > 0` turns. */
+    lateralAccel: number;
+    longitudinalAccel: number;
+    frontLoad: number;
+    rearLoad: number;
+    /** Surface multiplier sampled this tick. */
+    surface: number;
+    /** One-based forward gear; `-1` in reverse. */
+    gear: number;
+    rpm: number;
+    /** Throttle `0..1` actually applied after traction control and the rev limiter — engine audio load. */
+    engineLoad: number;
+    wheelspin: boolean;
+    wheelLock: boolean;
+    absActive: boolean;
+    tractionLimited: boolean;
+    stabilityActive: boolean;
+    bodyPitch: number;
+    bodyRoll: number;
+    /** Height of the car's base above the terrain under it, m; `0` on the ground and always `0` without `suspension`. */
+    airOffset: number;
+    /** No wheel touches the ground. */
+    airborne: boolean;
+    /** Vertical speed at the moment of touchdown this tick, m/s (`0` otherwise) — landing shake, thud, rumble. */
+    landingSpeed: number;
+    /** Per-corner spring load, N (front-left, front-right, rear-left, rear-right); all `0` without `suspension`. */
+    wheelLoads: readonly [number, number, number, number];
+    /** Balance lean the bike actually shows, `atan(lateral g)`, rad, positive leaning right; `0` without a `lean` block. */
+    lean: number;
+    /** Acceleration has taken all the load off the front axle. */
+    wheelie: boolean;
+    /** Braking has taken all the load off the rear axle. */
+    stoppie: boolean;
+}
+/**
+ * Force-based planar car: a two-axle ("bicycle") model where yaw comes from tire forces rather than being
+ * commanded, so understeer, oversteer, lift-off rotation, trail-braking, power slides and handbrake turns
+ * emerge from the numbers instead of from special cases. Deterministic for a given `dt` sequence; ticks are
+ * split into fixed substeps. Pairs with `tickDrivableVehicle` for the entity pose and `measureHandling`
+ * for asserting feel.
+ */
+export interface VehicleDynamics {
+    tick(dt: number, input: AxisInput, modifiers?: VehicleDynamicsModifiers): VehicleDynamicsStep;
+    pose(): {
+        position: readonly [number, number, number];
+        heading: number;
+    };
+    /** World velocity on the ground plane, `[vx, vz]`, m/s. */
+    velocity(): readonly [number, number];
+    /** Scale planar velocity and yaw rate (crash, boost pad). */
+    scaleVelocity(factor: number): void;
+    /** Add a world-space velocity change, m/s (impacts, knockback, a jump pad's `dvy` with `suspension`). */
+    applyImpulse(dvx: number, dvz: number, dvy?: number): void;
+    /**
+     * Jump if the tuning's `jump` block allows it now: from the ground, or in the air while jumps remain inside
+     * the window. Returns `false` and changes nothing otherwise, so a held key cannot stack jumps.
+     */
+    jump(): boolean;
+    /** Add angular velocity to the body, rad/s: `pitch > 0` noses down, `yaw` in heading sense, `roll > 0` drops the left side (dodges, flips, hits). */
+    applyAngularImpulse(pitch: number, yaw: number, roll: number): void;
+    /** Swap tuning in place (upgrades, damage, a live tuning panel) without losing momentum. */
+    retune(next: VehicleDynamicsTuning): void;
+    tuning(): VehicleDynamicsTuning;
+    snapshot(): VehicleDynamicsState;
+    restore(state: VehicleDynamicsState): void;
+    resetTo(position: readonly [number, number, number], heading: number): void;
+}
+/**
+ * Creates a {@link VehicleDynamics}.
+ * @capability vehicle-dynamics force-based car handling — tires, load transfer, drivetrain, assists — tuned with physical numbers
+ */
+export declare function createVehicleDynamics(initialTuning: VehicleDynamicsTuning, options?: VehicleDynamicsOptions): VehicleDynamics;