@jgengine/core 0.18.1 → 0.19.0

package/dist/physics/aircraftDynamics.d.ts

@@ -0,0 +1,390 @@
+import { type GravityField } from "./gravityField.js";
+/** Body-frame or world-frame vector, m or N. The body frame is `[left, up, forward]` about the centre of mass. */
+export type AircraftVector = readonly [number, number, number];
+/** Unit quaternion `[x, y, z, w]` taking body-frame vectors to world space. */
+export type AircraftQuaternion = readonly [number, number, number, number];
+/**
+ * One lifting surface: a wing panel, a tailplane, a fin, a canard. Its lift acts at `at`, so the moments that pitch,
+ * roll and yaw the body come from where the surfaces sit, not from commanded rates.
+ */
+export interface AircraftSurface {
+    /** Mount point relative to the centre of mass, body frame `[left, up, forward]`, m. */
+    at: AircraftVector;
+    /** Direction positive lift pushes, body frame (default `[0, 1, 0]`, a horizontal surface; `[1, 0, 0]` is a fin). Kept perpendicular to the chord, which runs along body forward. */
+    normal?: AircraftVector;
+    /** Planform area, m². */
+    area: number;
+    /** Lift curve slope, per rad (default `5`; thin-airfoil theory gives `2π`, lower for short spans). */
+    liftSlope?: number;
+    /** Angle of attack where the surface stalls, rad (default `0.28`). */
+    stallAngle?: number;
+    /** Lift kept past the stall as a share of peak lift, `0..1` (default `0.6`). */
+    postStallLift?: number;
+    /** Fixed mounting angle added to the local angle of attack, rad (default `0`); trims the cruise attitude. */
+    incidence?: number;
+    /** Zero-lift drag coefficient `CD0` of the drag polar `CD = CD0 + k·CL²` (default `0.02`). */
+    cd0?: number;
+    /** Induced drag factor `k` of the drag polar (default `0.06`). */
+    inducedDrag?: number;
+    /**
+     * Control authority: angle-of-attack change, rad, per rad of each channel's deflection. The sim signs it from the
+     * surface's lever arm, so positive input always gives nose-up pitch, right roll and nose-right yaw. A surface on the
+     * centreline has no roll arm, so its `roll` does nothing.
+     */
+    control?: {
+        pitch?: number;
+        roll?: number;
+        yaw?: number;
+    };
+}
+/** One control channel's actuator: how far the surfaces move and how fast. */
+export interface AircraftControlChannel {
+    /** Largest deflection, rad (default `0.35`). */
+    maxDeflection?: number;
+    /** Actuator slew rate, rad/s (default `2`). */
+    rate?: number;
+}
+/** A thrust source fixed to the body. */
+export interface AircraftEngineTuning {
+    /** Thrust at full throttle, N. */
+    maxThrust: number;
+    /** Engine spool response, 1/s: thrust follows the throttle with this first-order rate (default `1.5`; ~1.5 s to 90%). */
+    spoolRate?: number;
+    /** Thrust line offset from the centre of mass, body frame m (default on the centre of mass). */
+    at?: AircraftVector;
+    /** Thrust direction, body frame (default `[0, 0, 1]`, forward). */
+    direction?: AircraftVector;
+}
+/** Wheels or skids: what the body rests on when it touches the ground. */
+export interface AircraftGearTuning {
+    /** Height of the centre of mass above the ground when resting on the gear, m. */
+    height: number;
+    /** Rolling resistance coefficient (default `0.02`). */
+    rollingResistance?: number;
+    /** Deceleration at full `brake`, m/s² (default `4`). */
+    brakeDecel?: number;
+    /** Sideways friction coefficient of the tyres or skids (default `0.8`). */
+    sideGrip?: number;
+    /** Largest nose-up attitude the gear allows before the tail strikes, rad (default `0.25`). */
+    maxPitch?: number;
+}
+/**
+ * A rocket motor: thrust follows a curve over burn time, propellant leaves at a mass flow so the body gets lighter and
+ * easier to turn, and the nozzle gimbals on the pitch and yaw channels. Stage by `retune`-ing to the next stage's
+ * mass and motor.
+ */
+export interface AircraftMotorTuning {
+    /** Thrust over burn time, `[seconds since ignition, N]` points, linear between; zero past the last point. */
+    thrustCurve: readonly (readonly [number, number])[];
+    /** Propellant at ignition, kg, on top of `massKg`. */
+    propellantKg: number;
+    /** Propellant mass flow at the curve's peak thrust, kg/s; it scales with thrust (constant exhaust velocity). */
+    massFlow: number;
+    /** Nozzle position relative to the centre of mass, body frame m (default `[0, 0, -1]`, behind it). */
+    at?: AircraftVector;
+    /** Largest nozzle gimbal angle, rad (default `0`, fixed). Pitch and yaw inputs swing it through their actuators. */
+    gimbal?: number;
+}
+/**
+ * A main rotor. Collective sets blade pitch, throttle sets rotor speed, and cyclic (the pitch and roll channels) tilts
+ * the disc. Its drag torque yaws the body the other way unless a tail rotor, a second rotor or a pedal input cancels it.
+ */
+export interface AircraftRotorTuning {
+    /** Thrust at full collective and full rotor speed, out of ground effect and in a hover, N. */
+    maxThrust: number;
+    /** Blade radius, m. Sets the disc area, so the induced velocity behind translational lift, and the ground-effect height. */
+    radius: number;
+    /** Hub position relative to the centre of mass, body frame m (default `[0, 1.5, 0]`). A hub above the centre of mass turns disc tilt into pitch and roll moments. */
+    at?: AircraftVector;
+    /** Rotor speed response to throttle, 1/s (default `0.5`): rotors spin up slowly. */
+    spoolRate?: number;
+    /**
+     * Drag torque on the body at full collective and full rotor speed, N·m, scaling with collective and rotor speed².
+     * Positive yaws the nose left (a rotor turning counter-clockwise seen from above); negative yaws it right.
+     */
+    torque: number;
+    /** Disc tilt at full cyclic, rad (default `0.15`); the pitch and roll actuators set how fast it gets there. */
+    cyclic?: number;
+    /** Extra thrust once the rotor moves into clean air, as a share of thrust (default `0.2`): translational lift. */
+    translationalLift?: number;
+    /** Pitch and roll damping from the disc, N·m per rad/s (default `0`). */
+    damping?: number;
+    /**
+     * Tail rotor: sideways thrust at full yaw input and full rotor speed, N, acting at `at` (body frame m). Neutral pedal
+     * gives no thrust, so holding heading takes a yaw input that matches the main rotor torque. `sideDamping`, N per m/s
+     * of sideways air through it (default `maxThrust / 10`), is the yaw damping a spinning tail rotor adds.
+     */
+    tail?: {
+        maxThrust: number;
+        at: AircraftVector;
+        sideDamping?: number;
+    };
+}
+/** What an assist sees each substep, derived from the integrator state so it replays deterministically. */
+export interface AircraftAssistContext {
+    /** Substep, s. */
+    dt: number;
+    airspeed: number;
+    angleOfAttack: number;
+    heading: number;
+    pitch: number;
+    bank: number;
+    /** Body rates, rad/s: positive nose up, nose right, right roll. */
+    pitchRate: number;
+    yawRate: number;
+    rollRate: number;
+    /** World velocity, m/s. */
+    velocity: AircraftVector;
+    /** Horizontal velocity in the heading frame, m/s: `forward` along the nose, `right` to the right. */
+    forward: number;
+    right: number;
+    /** Load factor estimate from pitch rate and attitude, g. */
+    gLoad: number;
+    heightAboveGround: number;
+    /** The pilot's input this tick. */
+    pilot: RigidAircraftInput;
+}
+/** Control commands, `-1..1`, that drive the actuators after the assists. */
+export interface AircraftAssistCommand {
+    pitch: number;
+    roll: number;
+    yaw: number;
+}
+/**
+ * Flight assists. Each one moves the same actuators the pilot does, so a stronger assist still flies within the
+ * airframe's authority. Strengths are `0..1`; an axis the pilot is deflecting gets less help the further the stick is
+ * pushed, so full stick is always the pilot's.
+ */
+export interface AircraftAssistTuning {
+    /**
+     * Stability augmentation per axis, `0..1`: opposes body rate and, while that axis is hands-off, holds the attitude
+     * or heading it had when the pilot let go, learning the trim it needs. On a helicopter, `yaw` holds heading against
+     * rotor torque. Where `autoLevel` or `hoverHold` flies pitch and roll, SAS only damps their rates.
+     */
+    sas?: {
+        pitch?: number;
+        roll?: number;
+        yaw?: number;
+    };
+    /** Body rate at which SAS asks for full control, rad/s (default `0.5`); lower is firmer. */
+    sasRate?: number;
+    /** Hands-off, flies the wings level and the nose to the horizon, `0..1`. */
+    autoLevel?: number;
+    /** Largest angle of attack the pitch command may ask for, rad. */
+    maxAngleOfAttack?: number;
+    /** Largest load factor the pitch command may ask for, g. */
+    maxG?: number;
+    /** Hands-off cyclic flies the helicopter to a stop over the ground, `0..1`: velocity to attitude to rate. */
+    hoverHold?: number;
+    /** Runs after the built-in assists and returns the command the actuators get; replace or blend any policy here. */
+    policy?: (context: AircraftAssistContext, command: AircraftAssistCommand) => AircraftAssistCommand;
+}
+/**
+ * A rigid aircraft in physical units. There is no aircraft type: a jet, a glider and a paper plane differ only in these
+ * numbers. Rotation comes from surface forces acting on the inertia tensor, so loops, rolls, stalls and weathervaning
+ * are outcomes, not special cases.
+ */
+export interface RigidAircraftTuning {
+    /** Mass, kg; with a `motor`, the mass without propellant. */
+    massKg: number;
+    /** Principal moments of inertia about the body axes at `massKg`, kg·m²: `pitch` about left, `yaw` about up, `roll` about forward. Propellant scales them by total mass over `massKg`. */
+    inertia: {
+        pitch: number;
+        yaw: number;
+        roll: number;
+    };
+    surfaces: readonly AircraftSurface[];
+    engine?: AircraftEngineTuning;
+    rotor?: AircraftRotorTuning;
+    motor?: AircraftMotorTuning;
+    assists?: AircraftAssistTuning;
+    /** Actuators per channel; each channel defaults to `{ maxDeflection: 0.35, rate: 2 }`. */
+    controls?: {
+        pitch?: AircraftControlChannel;
+        roll?: AircraftControlChannel;
+        yaw?: AircraftControlChannel;
+    };
+    /** Fuselage drag coefficient × frontal area, m² (default `0`). */
+    dragArea?: number;
+    /** Omit for a body that never touches the ground (it falls through). */
+    gear?: AircraftGearTuning;
+    /** Integration substep, s (default `1/240`). */
+    maxSubstep?: number;
+}
+/** Pilot input for one tick. */
+export interface RigidAircraftInput {
+    /** `0..1`. */
+    throttle: number;
+    /** `-1..1`, positive pulls the nose up. */
+    pitch: number;
+    /** `-1..1`, positive rolls right (right wing down). */
+    roll: number;
+    /** `-1..1`, positive yaws the nose right. */
+    yaw: number;
+    /** Wheel brake, `0..1`. */
+    brake?: number;
+    /** Rotor collective, `0..1` (default `0`). */
+    collective?: number;
+}
+/** Per-tick overrides layered over tuning: damage, icing, boost, gusts. Each scale defaults to `1`. */
+export interface RigidAircraftModifiers {
+    thrustScale?: number;
+    liftScale?: number;
+    dragScale?: number;
+    /** Extra world-space force this tick, N — a tow, a gust, a tractor beam. */
+    force?: AircraftVector;
+    /** Extra body-frame torque this tick, N·m `[about left, about up, about forward]`. */
+    torque?: AircraftVector;
+}
+/** World hooks for one aircraft instance. */
+export interface RigidAircraftOptions {
+    position?: AircraftVector;
+    velocity?: AircraftVector;
+    /** Spawn heading, rad, with forward `[sin h, 0, cos h]`; ignored when `orientation` is set. */
+    heading?: number;
+    orientation?: AircraftQuaternion;
+    /** Wind velocity at a point, m/s. */
+    wind?: (position: AircraftVector) => AircraftVector;
+    /** Terrain height under a point; the gear rests on it. Default `0`. */
+    groundHeight?: (x: number, z: number) => number;
+    /** Default uniform `9.81` m/s² down. */
+    gravityField?: GravityField;
+    /** Air density at an altitude, kg/m³ (default sea level, `1.225`). */
+    airDensity?: (altitude: number) => number;
+}
+/** Serializable integrator state: everything `restore` needs to resume bit-for-bit. */
+export interface RigidAircraftState {
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    qx: number;
+    qy: number;
+    qz: number;
+    qw: number;
+    /** Angular velocity, body frame rad/s. */
+    wx: number;
+    wy: number;
+    wz: number;
+    pitchDeflection: number;
+    rollDeflection: number;
+    yawDeflection: number;
+    /** Engine output as a share of `maxThrust`, `0..1`. */
+    spool: number;
+    /** Rotor speed as a share of its rated speed, `0..1`. */
+    rotorSpeed: number;
+    /** Seconds the motor has burned. */
+    burnTime: number;
+    /** Propellant left, kg. */
+    propellantKg: number;
+    /** SAS hold per axis: body-angle change since that axis went hands-off, rad. */
+    holdPitch: number;
+    holdRoll: number;
+    holdYaw: number;
+    /** SAS trim per axis: the steady command it learned to hold against (rotor torque, an out-of-trim wing), rad/s. */
+    trimPitch: number;
+    trimRoll: number;
+    trimYaw: number;
+    /** Hover hold: world drift since the cyclic went hands-off, m. */
+    driftX: number;
+    driftZ: number;
+    time: number;
+}
+/** One aircraft tick: pose plus the telemetry HUDs, camera, sound and probes read. */
+export interface RigidAircraftStep {
+    position: AircraftVector;
+    velocity: AircraftVector;
+    orientation: AircraftQuaternion;
+    /** Heading, rad, forward `[sin h, 0, cos h]`; equals three.js `rotation.y` in `YXZ` order. */
+    heading: number;
+    /** Nose-up attitude, rad; three.js `rotation.x = -pitch` in `YXZ` order. */
+    pitch: number;
+    /** Bank, rad, positive right wing down; three.js `rotation.z` in `YXZ` order. */
+    bank: number;
+    /** Body rates, rad/s: positive nose up, nose right, right roll. */
+    pitchRate: number;
+    yawRate: number;
+    rollRate: number;
+    /** Speed relative to the air, m/s. */
+    airspeed: number;
+    /** Angle of attack at the centre of mass, rad. */
+    angleOfAttack: number;
+    /** Sideslip, rad, positive when the body moves to its right. */
+    sideslip: number;
+    /** Load factor along the body's up axis, g; `1` in level flight, `0` in free fall. */
+    gLoad: number;
+    /** The largest surface is past its stall angle. */
+    stalled: boolean;
+    /** Share of surface area past its stall angle, `0..1`. */
+    stallFraction: number;
+    /** Engine thrust this tick, N. */
+    thrust: number;
+    /** Current actuator deflection per channel, rad. */
+    deflection: {
+        pitch: number;
+        roll: number;
+        yaw: number;
+    };
+    grounded: boolean;
+    /** Total mass including propellant, kg. */
+    massKg: number;
+    /** The command the actuators got after assists, `-1..1`; equals the pilot's input without assists. */
+    command: AircraftAssistCommand;
+    /** The AoA or g limiter cut the pitch command this tick. */
+    limited: boolean;
+    /** Motor telemetry; absent without a `motor` block. */
+    motor?: {
+        /** Motor thrust this tick, N. */
+        thrust: number;
+        burnTime: number;
+        propellantKg: number;
+        /** Out of propellant or past the end of the thrust curve. */
+        burnedOut: boolean;
+    };
+    /** Rotor telemetry; absent without a `rotor` block. */
+    rotor?: {
+        /** Rotor speed, share of rated, `0..1`. */
+        speed: number;
+        /** Main rotor thrust, N. */
+        thrust: number;
+        /** Drag torque on the body, N·m, positive nose left. */
+        torque: number;
+        /** Thrust multiplier from ground effect, `≥ 1`. */
+        groundEffect: number;
+        /** Thrust multiplier from translational lift, `≥ 1`. */
+        translationalLift: number;
+    };
+}
+/** A force-and-torque aircraft on the same tick/snapshot/retune contract as `VehicleDynamics`. */
+export interface RigidAircraft {
+    tick(dt: number, input: RigidAircraftInput, modifiers?: RigidAircraftModifiers): RigidAircraftStep;
+    pose(): {
+        position: AircraftVector;
+        orientation: AircraftQuaternion;
+    };
+    velocity(): AircraftVector;
+    /** Adds a world-space velocity change, m/s — a hit, a catapult, an explosion. */
+    applyImpulse(dv: AircraftVector): void;
+    retune(next: RigidAircraftTuning): void;
+    tuning(): RigidAircraftTuning;
+    snapshot(): RigidAircraftState;
+    restore(state: RigidAircraftState): void;
+    resetTo(position: AircraftVector, orientation?: AircraftQuaternion): void;
+}
+/** Quaternion for a heading about world up, forward `[sin h, 0, cos h]`. */
+export declare function aircraftHeadingQuaternion(heading: number): AircraftQuaternion;
+/**
+ * Quaternion from heading, nose-up pitch and right bank, rad — the inverse of a step's `heading`/`pitch`/`bank`.
+ * Matches three.js `Euler(-pitch, heading, bank, "YXZ")`.
+ */
+export declare function aircraftAttitudeQuaternion(heading: number, pitch: number, bank: number): AircraftQuaternion;
+/**
+ * Creates a {@link RigidAircraft}: a quaternion rigid body with a diagonal inertia tensor, pushed by lifting surfaces,
+ * fuselage drag, an engine and gravity. Controls deflect surfaces through rate-limited actuators; nothing commands a
+ * rotation rate, so a jet loops when its tail can push the nose around and a glider stalls when it runs out of speed.
+ * Fixed internal substeps make it deterministic for a given `dt` sequence.
+ * @capability rigid-aircraft force-and-torque aircraft — lifting surfaces with stall and drag polar, control surfaces, inertia, loops and rolls
+ */
+export declare function createRigidAircraft(initial: RigidAircraftTuning, options?: RigidAircraftOptions): RigidAircraft;