lecodes-sdk 0.20.0 → 1.0.0

package/dist/types/gl/Vehicle.d.ts

@@ -1,191 +0,0 @@
-import { Aspect } from "../core/Aspect";
-import type { FieldMeta } from "../core/fields";
-import { Vec3, type Vec3Like } from "../math/vec";
-import { type QuatLike } from "../math/quat";
-import { Node } from "./Node";
-import { Wheel } from "./Wheel";
-/** Which axle the engine drives. A wheel's own `drive` overrides it. */
-export type DriveLayout = "rear" | "front" | "all";
-/**
- * How an axle's two wheels share torque.
- *  - `lsd` — limited slip (Jolt's 1.4 ratio), the sane default.
- *  - `open` — fully open: a lifted or spinning wheel takes ALL the torque.
- *  - `locked` — both wheels forced to the same speed. Breaks traction predictably: the drift diff.
- *  A number is the raw max/min wheel-speed ratio (> 1; smaller is more locked).
- */
-export type DifferentialMode = "lsd" | "open" | "locked";
-export interface EngineConfig {
-    /** Peak torque in N·m (default 500). The single biggest "how fast is it" knob. */
-    torque?: number;
-    /** Redline in RPM (default 6000). */
-    maxRpm?: number;
-    /** Idle RPM (default 1000) — the engine never falls below it. */
-    idleRpm?: number;
-    /**
-     * The engine's CHARACTER: a flat list `[rpm, torque, rpm, torque, …]` in NORMALISED units — x is
-     * a fraction of the redline, y a fraction of `torque`. Left out, Jolt's own broad curve is used.
-     *
-     * `[0, 0.8, 0.66, 1, 1, 0.8]` is an ordinary petrol engine (peak two thirds up, falling to the
-     * redline); `[0, 1, 1, 1]` is flat, which is what an electric motor feels like.
-     */
-    curve?: number[];
-    /** Moment of inertia in kg·m² (default 0.5) — how eagerly it revs when the clutch is out. */
-    inertia?: number;
-    /** Engine braking: angular damping of the engine itself (default 0.2). */
-    braking?: number;
-}
-export interface SteeringConfig {
-    /** Steering lock in degrees at a standstill (default 35). */
-    lock?: number;
-    /**
-     * The lock still available, in degrees, once the car reaches `speed` (default 10) — what stops a
-     * car over-driving its own front tires.
-     *
-     * A tire makes its peak grip at a few degrees of slip angle, and the steering angle a corner needs
-     * falls with the SQUARE of speed. Holding full lock at 100 km/h therefore asks the front for
-     * several times what it can give: the tires saturate, the car ploughs on, and the wheel stops
-     * answering. In between the lock eases on `(1 − v/speed)²`, which tracks the real curve closely.
-     * `0` turns the taper off — full lock at any speed.
-     */
-    atSpeed?: number;
-    /** The speed in m/s at which the lock has fallen to `atSpeed` (default 30 ≈ 108 km/h). */
-    speed?: number;
-    /** How fast the front wheels may turn, in degrees per second (default 220). A keyboard asks for
-     *  full lock in one frame, which no steering wheel can do, and that step alone snaps a tire past
-     *  its peak. `0` = instantly. */
-    rate?: number;
-}
-/**
- * Aerodynamics. Both numbers are quoted the same way — **a fraction of the car's own weight at
- * 30 m/s (108 km/h)** — and both grow with the SQUARE of speed from there, so `0.5` at 30 m/s is
- * `2.0` at 60 m/s. One mental model for both, and no drag coefficients or frontal areas to invent.
- */
-export interface AeroConfig {
-    /**
-     * Downforce (default 0 — a car with no wing). The knob that decides whether a car corners better
-     * or worse the faster it goes: tire grip is a constant, but the force a corner demands grows with
-     * v², so with no downforce every car runs out of road at speed. `0.6` roughly doubles a car's
-     * cornering at 150 km/h; a road car is nearer `0.1`, a race car well past `1`.
-     *
-     * It presses along the CHASSIS' own down axis (that is what keeps a car planted over a crest) and
-     * only while a wheel is on the ground — a car on its roof is never launched by its own wing.
-     */
-    downforce?: number;
-    /** Air resistance (default 0.03 — an ordinary car). What gives a car a top speed at all. */
-    drag?: number;
-}
-export declare class Vehicle extends Aspect<"vehicle", Node> {
-    static readonly aspect = "vehicle";
-    /** Chassis mass in kg (default 1200). Wheels are massless in this model. */
-    mass: number;
-    /** Centre of mass height in chassis space (metres, negative = lower). Left out, it drops to halfway
-     *  down the chassis shape — a car with its mass at the shape's centre tips over. */
-    centerOfMass?: number;
-    /** Which axle the engine drives (default "rear"). A wheel's own `drive` overrides it. */
-    driveAxle: DriveLayout;
-    /** Differential lock across each driven axle. `locked` is the drift setup — both wheels turn
-     *  together, so the pair lets go as a pair. Live: re-configure the aspect to switch it mid-drive. */
-    differential: DifferentialMode | number;
-    /**
-     * Anti-roll bars between each axle's wheels — what stops a car rolling onto its inside wheels in a
-     * fast corner. `true` (default) is a bar 0.01 as stiff as the wheel's own spring; a number is that
-     * ratio directly, and `0` / `false` removes the bars.
-     *
-     * **The numbers are far smaller than they look and the gain is steep** — Jolt's bar feeds
-     * `lengthDifference × stiffness × dt` as a bias into the suspension's own soft constraint, so 4%
-     * of the spring already flattens the body. Measured on a 1250 kg car: `0` → 1.3° of roll at 0.86 g,
-     * `0.01` → 0.6°, `0.15` → 0.2° (flat), `0.5` → the car HOPS.
-     *
-     * This is the knob for how much a car visibly LEANS, not for wheel lift: bars change how far the
-     * body tips, not how much load transfers. For lift, lower `centerOfMass`.
-     */
-    antiRoll: boolean | number;
-    /** Pitch/roll limit in degrees (default 60) before the constraint rights the car. 180 turns it off. */
-    maxTilt: number;
-    /** Friction of the CHASSIS body itself — how it slides when it lands on its roof or side. Nothing
-     *  to do with the tires; those are the `Wheel`'s `tire.grip` × the ground's friction. */
-    friction: number;
-    /** Strength of the clutch when fully engaged (default 10). Small values slip; large ones weld the
-     *  engine to the wheels. The `Gearbox` scales it 0..1 while shifting. */
-    clutchStrength: number;
-    engine: EngineConfig;
-    steering: SteeringConfig;
-    aero: AeroConfig;
-    /** Scene-editor inspector: the flat, tunable half. The grouped objects are edited in code. */
-    static fields: FieldMeta<Vehicle>;
-    static editor: {
-        rebuild: boolean;
-    };
-    private _id;
-    private _bodyId;
-    private _builtMass;
-    private _wheels;
-    private _state;
-    private _stateFrame;
-    private _throttle;
-    private _steer;
-    private _brake;
-    private _handbrake;
-    onAttach(): void;
-    onDetach(): void;
-    /**
-     * Re-configuring an attached vehicle retunes it in place — the way a drift button switches the
-     * differential without the car so much as blinking:
-     *
-     *   car.aspect(Vehicle, { differential: drift ? 'locked' : 'lsd' })
-     *
-     * Live: `differential`, `engine`, `steering`, `aero`, `maxTilt`, `friction`, `clutchStrength`, and
-     * every `Wheel`'s `tire.grip` and brake torques. Everything else describes the car's STRUCTURE —
-     * `mass`, `centerOfMass`, which wheels exist and where, their suspension, `driveAxle`, `antiRoll` — and
-     * is baked into the constraint at attach; to change one of those, re-attach the aspect.
-     */
-    onReconfigure(): void;
-    /** Native vehicle id (0 until attached / no physics support). */
-    get id(): number;
-    /** The chassis rigid-body id — the same handle the plain body calls take. */
-    get bodyId(): number;
-    /** The wheels, in blob order (front axle first). */
-    get wheels(): readonly Wheel[];
-    /**
-     * The driver's controls, all in [-1, 1] (brakes in [0, 1]). Sticky: the last values keep applying
-     * until the next call, so a held key does not need re-sending. `forward < 0` asks for reverse; the
-     * `Gearbox` engages it once the car has stopped.
-     */
-    drive(forward: number, steer?: number, brake?: number, handbrake?: number): this;
-    /** Teleport upright and clear all motion (velocity, engine, gearbox, wheel spin). Defaults to the
-     *  chassis node's current pose — `reset()` alone un-flips a car where it lies. */
-    reset(position?: Vec3Like, rotation?: QuatLike): this;
-    /** Push the chassis (a boost pad, an explosion) — an instantaneous impulse in kg·m/s. */
-    applyImpulse(v: Vec3Like): this;
-    private _read;
-    /** Speed along the car's forward axis in m/s — negative when reversing (× 3.6 for km/h). */
-    get speed(): number;
-    /** Engine revolutions per minute. */
-    get rpm(): number;
-    /** How many wheels are touching the ground. */
-    get wheelsOnGround(): number;
-    /** Any wheel on the ground — false while airborne. */
-    get grounded(): boolean;
-    /** Chassis velocity in world units/s (fresh Vec3). */
-    get velocity(): Vec3;
-    /** The last throttle handed to `drive()` — what the gearbox reads to know which way you want to go. */
-    get throttle(): number;
-    /** The last steer input handed to `drive()`, [-1, 1]. */
-    get steerInput(): number;
-    /** The last foot-brake input handed to `drive()`, [0, 1] — the pedal, not the resulting force. */
-    get brake(): number;
-    /** The last handbrake input handed to `drive()`, [0, 1]. */
-    get handbrake(): number;
-    /** Current gear from the attached `Gearbox`: −1 reverse, 0 neutral, 1… forward. */
-    get gear(): number;
-    /** The steering lock, in degrees, the car is allowed at its current speed — the full lock at rest,
-     *  falling to `steering.atSpeed`. The same curve the engine applies; useful on a HUD. */
-    get steerLock(): number;
-    /** Every Wheel under the chassis, ordered front axle first, with its axle group resolved. */
-    private _collectWheels;
-    /** Pack the whole configuration into the one blob the host ABI takes (see bridges.d.ts). */
-    private _buildSettings;
-    /** Edit mode: which way the chassis faces. Each wheel draws its own circle and travel range — see
-     *  `Wheel.rebuild()`. Play mode never calls this. */
-    rebuild(): void;
-}

package/dist/types/gl/Wheel.d.ts

@@ -1,95 +0,0 @@
-import { Aspect } from "../core/Aspect";
-import type { FieldMeta } from "../core/fields";
-import { type Vec3Like } from "../math/vec";
-import { Node } from "./Node";
-/** Floats `vehicleGetState` writes before the per-wheel block: speed, rpm, contacts, vx, vy, vz. */
-export declare const STATE_HEADER = 6;
-/** Floats per wheel: contact, slip, slipAngle, suspensionLength, steerDeg, spin. */
-export declare const WHEEL_STATE = 6;
-/** How a tire behaves past its grip peak. `road` is Jolt's own curve — grip falls off after the peak,
- *  so the car can be made to let go. `arcade` holds the peak all the way out: much harder to spin. */
-export type TireCurve = "road" | "arcade";
-export interface WheelSuspension {
-    /** Total travel in metres, full droop to fully compressed (default 0.4). */
-    travel?: number;
-    /** Spring frequency in Hz — bigger is stiffer (default 1.4; a race car ~2.5, a truck ~1). It also
-     *  sets the ride-height sag, and the sag is how far the wheel can still extend DOWN. */
-    stiffness?: number;
-    /** Damping ratio 0..1 (default 0.5). Low values pogo. */
-    damping?: number;
-}
-export interface WheelTire {
-    /** Grip multiplier on the friction curves (default 1). The grip a wheel actually gets is combined
-     *  with the ground it stands on as `sqrt(tire × groundFriction)`, and a body's friction defaults to
-     *  0.6 — so a road a car should really corner on wants `Physics { friction: 1 }`. */
-    grip?: number;
-    /** Which friction curve (default `road`). */
-    curve?: TireCurve;
-}
-export interface WheelVisual {
-    /** The MODEL's axle direction in its own space (default `[1, 0, 0]`). Set it instead of parenting
-     *  the mesh under a corrective node when the art points another way. */
-    axis?: Vec3Like;
-    /** Drawn radius, if the art is not exactly the physical `radius` — sinks a wheel into its arch or
-     *  lets a fat tire overhang, with no effect on the simulation. Default: the physical radius. */
-    radius?: number;
-    /** Let the model spin (default true). `false` keeps the steer angle and suspension travel but not
-     *  the rotation — a brake caliper. */
-    spin?: boolean;
-}
-export declare class Wheel extends Aspect<"wheel", Node> {
-    static readonly aspect = "wheel";
-    /** Wheel radius in metres. Default: measured from the node's rendered bounds, else 0.35. Too small
-     *  and the car scrapes, too large and it floats. */
-    radius?: number;
-    /** Wheel width in metres. Default: measured, else 0.25. */
-    width?: number;
-    /** Does this wheel steer? Default: the wheels on the front axle. */
-    steer?: boolean;
-    /** Does the engine drive it? Default: from the vehicle's `drive` layout. */
-    drive?: boolean;
-    /** Foot brake on this wheel. */
-    brake: boolean;
-    /** Handbrake on this wheel. Default: every non-steering wheel (locking the front wheels of a moving
-     *  car is not a handbrake turn, it is a crash). */
-    handbrake?: boolean;
-    /** Axle group, front to back. Default: derived from Z. Set it for a car whose wheels are not in neat
-     *  left/right pairs — an axle's wheels are paired for the differential and the anti-roll bar. */
-    axle?: number;
-    /** Foot-brake torque in N·m (default 1500); the handbrake pulls 3× on the wheels that have it. */
-    brakeTorque: number;
-    suspension: WheelSuspension;
-    tire: WheelTire;
-    visual: WheelVisual;
-    /** Scene-editor inspector. `steer` / `drive` / `handbrake` are deliberately absent: they are
-     *  tri-state (undefined = derive it from the axle), which a switch cannot express. */
-    static fields: FieldMeta<Wheel>;
-    static editor: {
-        rebuild: boolean;
-    };
-    private _angle;
-    private _scale;
-    private _local;
-    onAttach(): void;
-    onDetach(): void;
-    private _state;
-    /** Touching the ground this step. */
-    get contact(): boolean;
-    /** Longitudinal slip RATIO: 0 = rolling in sync with the ground, ~1 = spinning up or locked.
-     *  Unsigned — smoke, tire marks and wheelspin sound key off this. */
-    get slip(): number;
-    /** Slip ANGLE in degrees: how far the tire's travel direction is off from where it points.
-     *  Unsigned, 0..90 — past the curve's peak (~3°) the tire is sliding sideways. Drift particles. */
-    get slipAngle(): number;
-    /** Steer angle in degrees, positive to the right. */
-    get steerAngle(): number;
-    /** Wheel spin in rad/s (× radius ≈ the speed the tire is laying down). */
-    get spin(): number;
-    /** Suspension compression, 0 = fully extended (drooping) … 1 = fully compressed. */
-    get compression(): number;
-    /** LATE phase: after the step and the transform sync, right before the frame draws. */
-    update(dt: number): void;
-    /** Edit mode: this wheel's own circle at its resting height, its travel range, and a mark when the
-     *  engine drives it — enough to place a wheel without running the game. */
-    rebuild(): void;
-}

package/src/gl/Gearbox.ts

@@ -1,212 +0,0 @@
-// The gearbox of a `Vehicle`, as an aspect on the same node. It is deliberately NOT in the engine:
-// picking a gear is policy, not physics — two RPM thresholds and a latency timer — and every game
-// wants its own. The engine keeps only the physical half (the clutch's stiffness and the coupled
-// engine/wheel solve), and is told one ratio and one clutch scalar per frame.
-//
-//   car.aspect(Gearbox, { ratios: [2.66, 1.78, 1.3, 1.0, 0.74], reverse: -2.9 })
-//
-// A `Vehicle` with no `Gearbox` attaches this one with its defaults, so a car that never mentions
-// gears still drives.
-//
-// Custom behaviour is a subclass overriding ONE method:
-//
-//   class SportBox extends Gearbox {
-//     select(v: Vehicle): number { return v.rpm > 6200 ? this.gear + 1 : this.gear }
-//   }
-//
-// The clutch is two things multiplied. The SHIFT envelope (`shiftTime`/`clutchTime`) stays with the
-// base class on purpose: a forgotten ramp breaks a car silently — no drive at all, or a slammed
-// clutch. The TAKE-UP (`takeUp`) is the left-foot half, and is overridable for a car that launches
-// unusually — a torque converter, a rally launch control.
-
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import type { Node } from "./Node"
-import type { Vehicle } from "./Vehicle"
-
-// How far above idle counts as "revs to spare". A simulated engine cannot fall below its idle — the
-// physics clamps it — so being AT idle is the observable form of "the wheels are dragging me under".
-// This is the tolerance for reading that clamp, not a tuning knob.
-const IDLE_MARGIN = 1.05
-
-// The car this gearbox belongs to. Read through the aspect accessor rather than node.get(Vehicle),
-// so this file needs Vehicle only as a TYPE and the two do not import each other at runtime.
-const carOf = (n: Node): Vehicle | null => (n as unknown as { vehicle?: Vehicle }).vehicle ?? null
-
-export class Gearbox extends Aspect<"gearbox", Node> {
-  static readonly aspect = "gearbox"
-
-  /** Forward gear ratios, first gear first. Engine RPM = wheel speed × ratio × the differential. */
-  ratios: number[] = [ 2.66, 1.78, 1.3, 1.0, 0.74 ]
-  /** Reverse ratio — negative, because a ratio's SIGN is what reverse means to the engine. */
-  reverse = -2.9
-  /** Shift up when the engine passes this fraction of its redline. */
-  shiftUp = 0.67
-  /** Shift down when it falls below this fraction. */
-  shiftDown = 0.33
-  /** How long a shift takes, in seconds — the clutch is out for this long. */
-  shiftTime = 0.2
-  /** How long the clutch takes to re-engage afterwards. */
-  clutchTime = 0.3
-  /** How long to wait after a shift before another is allowed — without it a car sitting on a
-   *  threshold hunts between two gears. */
-  latency = 0.5
-
-  /** How far the clutch bites the instant drive is asked for from rest, 0..1. It only has to COUPLE
-   *  the shafts — how much torque that passes is the engine's business, so a feathered throttle
-   *  still pulls away gently at the same bite point. */
-  bite = 0.4
-
-  static fields: FieldMeta<Gearbox> = {
-    reverse: { max: -0.1, step: 0.1 },
-    shiftUp: { min: 0.1, max: 1, step: 0.01 },
-    shiftDown: { min: 0, max: 0.9, step: 0.01 },
-    shiftTime: { min: 0, max: 3, step: 0.05 },
-    clutchTime: { min: 0, max: 3, step: 0.05 },
-    latency: { min: 0, max: 3, step: 0.05 },
-    bite: { min: 0, max: 1, step: 0.05 },
-    ratios: { hidden: true },
-  }
-
-  /** Current gear: −1 reverse, 0 neutral, 1… forward. Read it for a HUD. */
-  gear = 0
-  /** True while a shift is in progress — the clutch is out and the engine is not driving the wheels. */
-  get shifting(): boolean { return this._shiftLeft > 0 }
-
-  private _shiftLeft = 0      // seconds of clutch-out left
-  private _engageLeft = 0     // seconds of clutch re-engagement left
-  private _waitLeft = 0       // anti-hunting
-  private _take = 0           // how far the CAR's own state wants the clutch in, latched per frame
-
-  /** EARLY phase: the pair has to be latched before this frame's step consumes it. */
-  updateBefore(dt: number): void {
-    const v = carOf(this.node)
-    if (!v || !v.id) return
-
-    this._waitLeft = Math.max(0, this._waitLeft - dt)
-
-    if (this._shiftLeft > 0) {
-      // Mid-shift: clutch fully out, and the moment it ends the re-engagement ramp starts.
-      this._shiftLeft = Math.max(0, this._shiftLeft - dt)
-      if (this._shiftLeft === 0) this._engageLeft = this.clutchTime
-    } else {
-      const want = this.select(v)
-      if (want !== this.gear) this.shift(want)
-      else this._engageLeft = Math.max(0, this._engageLeft - dt)
-    }
-
-    // The pedal only moves while no shift is in flight. During one the revs say nothing about
-    // whether the wheels can sustain them: an engine still spinning down from the last gear reads as
-    // "revs to spare" and would drop the clutch straight back in — enough to shove a stopped car
-    // several km/h with no throttle at all. Freezing it is what a driver does anyway; the foot is
-    // already down, and the envelope owns the clutch until the gear is in.
-    if (this._shiftLeft === 0 && this._engageLeft === 0) {
-      this._take = Math.max(0, Math.min(1, this.takeUp(v, dt)))
-    }
-
-    v._setTransmission(this.ratio, this.clutch)
-  }
-
-  /**
-   * The driver's left foot: where the clutch pedal is, ignoring shifts. Returns the new engagement.
-   *
-   * A driver does not compute anything. They watch the tacho: **revs sinking to idle means the
-   * wheels are about to drag the engine under, and that is when you push the clutch in.** That
-   * single test replaces every ratio and threshold — the crossover it finds is the exact speed where
-   * engine braking stops and the engine would start PUSHING instead, and it finds it per gear
-   * without being told the gear.
-   *
-   * The pedal comes back UP only for the throttle. Healthy revs are not on their own a reason to
-   * engage: a car standing still shows healthy revs too — the wheels simply are not turning to say
-   * otherwise — and a clutch dropped on that evidence lurches the car off with no throttle at all.
-   *
-   * Three things fall out of it for free:
-   *
-   * - **A braked car stops.** The engine cannot stall, so a clutch left in at 0 km/h feeds idle
-   *   torque to the wheels forever and the car creeps against its own brakes. Here the revs pin at
-   *   idle, so the pedal goes down and the brakes have nothing to fight.
-   * - **Reverse is not a special case.** No ratio takes part, so it needs no separate number — which
-   *   is exactly why a fixed road-speed threshold got reverse wrong.
-   * - **Hill starts judder instead of stalling.** Let the pedal out, the load pulls the revs down,
-   *   the rule pushes it straight back in, and the clutch sits slipping at the bite point until the
-   *   car moves. So the test deliberately ignores the throttle — gating it on "no throttle" would
-   *   stall the car under load. Throttle only holds the floor at `bite`.
-   *
-   * The cost is honest and small: once the pedal is down the revs sit at idle and cannot rise on
-   * their own, so **coasting downhill gives no engine braking until you touch the throttle** — which
-   * is precisely what a car with the clutch in does. Slipping it permanently to keep listening would
-   * bring the creep straight back.
-   */
-  protected takeUp(v: Vehicle, dt: number): number {
-    if (this.gear === 0) return 0
-    const idle = v.engine.idleRpm ?? 1000
-    const step = dt / Math.max(this.clutchTime, dt)
-    const asked = v.throttle !== 0
-    let take = this._take
-    if (v.rpm <= idle * IDLE_MARGIN) take -= step   // being dragged under: pedal goes down
-    else if (asked) take += step                    // revs to spare AND somewhere to go: let it up
-    // Asking for drive also holds the pedal at the bite point however far down the rule wants it;
-    // that is what makes a launch — and a hill start — slip instead of collapsing to nothing.
-    return asked ? Math.max(take, this.bite) : take
-  }
-
-  /**
-   * Which gear the car should be in. The default is an ordinary automatic: pull away from neutral in
-   * the direction of the throttle, shift up past `shiftUp` of the redline and down below `shiftDown`,
-   * and refuse to shift again for `latency` seconds. Override this and nothing else.
-   */
-  select(v: Vehicle): number {
-    const throttle = v.throttle
-    // Neutral, or asked to go the other way: engage once the car has (nearly) stopped.
-    if (this.gear === 0 || throttle * this.gear < 0) {
-      if (Math.abs(v.speed) > 1 && this.gear !== 0) return this.gear
-      return throttle > 0 ? 1 : throttle < 0 ? -1 : this.gear
-    }
-    if (this.gear < 0 || this._waitLeft > 0 || this.shifting) return this.gear
-    const rpm = v.rpm
-    const max = v.engine.maxRpm ?? 6000
-    // Upshifting needs COUPLED revs. With the clutch out the engine is free, so a blip at a
-    // standstill reads as 6000 rpm and the box would climb to top gear without the car moving —
-    // then launch in it. Downshifting stays open either way: it can only take you to a lower gear,
-    // which is where a car with dying revs belongs.
-    if (rpm > max * this.shiftUp && this.clutch >= 1 && this.gear < this.ratios.length) return this.gear + 1
-    if (rpm < max * this.shiftDown && this.gear > 1) return this.gear - 1
-    return this.gear
-  }
-
-  /** Change gear now, with the clutch envelope. Safe to call from `select()` or from game code
-   *  (a sequential manual is `if (Input.key('KeyE')) car.gearbox.shift(car.gearbox.gear + 1)`). */
-  shift(gear: number): void {
-    const clamped = Math.max(-1, Math.min(this.ratios.length, Math.round(gear)))
-    if (clamped === this.gear) return
-    // The envelope is for swapping one ENGAGED gear for another. If nothing is coupled there is
-    // nothing to disengage, so it is skipped: neutral at either end, and equally a car sitting still
-    // with the pedal already down — picking reverse there should pull away the moment it is asked
-    // to, not sit out a shift it never had to make.
-    const swapping = this.gear !== 0 && clamped !== 0 && this._take > 0
-    this.gear = clamped
-    this._shiftLeft = swapping ? this.shiftTime : 0
-    this._engageLeft = swapping ? this.clutchTime : 0
-    this._waitLeft = this.latency + this._shiftLeft
-  }
-
-  /** The ratio the engine should be running: 0 in neutral, negative in reverse. */
-  get ratio(): number {
-    if (this.gear === 0) return 0
-    if (this.gear < 0) return this.reverse
-    return this.ratios[this.gear - 1] ?? 1
-  }
-
-  /**
-   * The clutch scalar 0..1 the engine is given: the SHIFT envelope (out during a shift, ramping back
-   * over `clutchTime`) times the driver's pedal (`takeUp`). Two independent reasons for the clutch
-   * to be out, so they multiply: mid-shift is out however healthy the revs are, and an engine being
-   * dragged to idle is out whatever gear it just picked.
-   */
-  get clutch(): number {
-    if (this._shiftLeft > 0) return 0
-    const envelope =
-      this._engageLeft > 0 && this.clutchTime > 0 ? 1 - this._engageLeft / this.clutchTime : 1
-    return envelope * this._take
-  }
-}