lecodes-sdk 0.20.0 → 1.0.0

package/dist/types/gl/{CharacterController.d.ts → physics/CharacterController.d.ts}

@@ -1,8 +1,8 @@
-import { Aspect } from "../core/Aspect";
-import type { FieldMeta } from "../core/fields";
-import { Vec3, type Vec2Like, type Vec3Like } from "../math/vec";
-import type { CompWriter } from "../core/compWrite";
-import type { Node } from "./Node";
+import { Aspect } from "../../core/Aspect";
+import type { FieldMeta } from "../../core/fields";
+import { Vec3, type Vec2Like, type Vec3Like } from "../../math/vec";
+import type { CompWriter } from "../../core/compWrite";
+import type { Node } from "../Node";
 /** Where the character's feet are, as reported by the solver after the last step. */
 export type GroundState = "ground" | "slope" | "unsupported" | "air";
 export declare class CharacterController extends Aspect<"controller", Node> implements CompWriter {

package/dist/types/gl/{Physics.d.ts → physics/Physics.d.ts}

@@ -1,8 +1,8 @@
-import { Aspect } from "../core/Aspect";
-import type { FieldMeta } from "../core/fields";
-import type { CompAxis, CompWriter } from "../core/compWrite";
-import { Vec3, type Vec3Like } from "../math/vec";
-import { type Node } from "./Node";
+import { Aspect } from "../../core/Aspect";
+import type { FieldMeta } from "../../core/fields";
+import type { CompAxis, CompWriter } from "../../core/compWrite";
+import { Vec3, type Vec3Like } from "../../math/vec";
+import { type Node } from "../Node";
 export type MotionType = "static" | "dynamic" | "kinematic";
 export interface PhysicsConfig {
     /** Gravity in world units/s² (Y-up: down is negative). Default [0, -9.81, 0]. */
@@ -57,6 +57,7 @@ export declare class Physics extends Aspect<"physics", Node> implements CompWrit
     /** Scene-editor inspector: `motion` as a dropdown (a string default alone infers a text box). */
     static fields: FieldMeta<Physics>;
     private _bodyId;
+    private static _refusedWarned;
     onAttach(): void;
     onDetach(): void;
     /** Native Jolt body id. 0 until attached, or if the build has no physics support. */

package/dist/types/gl/{Ragdoll.d.ts → physics/Ragdoll.d.ts}

@@ -1,7 +1,7 @@
-import { Aspect } from "../core/Aspect";
-import type { FieldMeta } from "../core/fields";
-import { type Vec3Like } from "../math/vec";
-import { Node } from "./Node";
+import { Aspect } from "../../core/Aspect";
+import type { FieldMeta } from "../../core/fields";
+import { type Vec3Like } from "../../math/vec";
+import { Node } from "../Node";
 export interface RagdollHinge {
     /** The hinge axis in the MODEL's space (its rest pose: +Z forward, +Y up, +X the model's left in
      *  glTF). Perpendicular to the bone; the engine drops any component along it. */

package/dist/types/gl/{Shape.d.ts → physics/Shape.d.ts}

@@ -1,6 +1,6 @@
-import { Aspect } from "../core/Aspect";
-import { type Vec3Like } from "../math/vec";
-import type { Node } from "./Node";
+import { Aspect } from "../../core/Aspect";
+import { type Vec3Like } from "../../math/vec";
+import type { Node } from "../Node";
 /** Which geometry a Shape uses — the one-of the fields below encode (see `_build`'s order). */
 export type ShapeKind = "auto" | "box" | "sphere" | "cylinder" | "capsule" | "mesh" | "convex" | "heightfield";
 /** A node-local AABB, in the node's OWN frame (its own transform excluded), before world scale. */

package/dist/types/gl/{Trigger.d.ts → physics/Trigger.d.ts}

@@ -1,5 +1,5 @@
-import { Aspect } from "../core/Aspect";
-import type { Node } from "./Node";
+import { Aspect } from "../../core/Aspect";
+import type { Node } from "../Node";
 export declare class Trigger extends Aspect<"trigger", Node> {
     static readonly aspect = "trigger";
     private _bodyId;

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

@@ -1,5 +1,4 @@
 import type { Scene } from "./Scene";
 export declare const glState: {
     activeScene: Scene | null;
-    frame: number;
 };

package/dist/types/gl/{Terrain.d.ts → terrain/Terrain.d.ts}

@@ -1,9 +1,9 @@
-import { Node } from "./Node";
-import { Material } from "./Material";
-import { Texture } from "./Texture";
-import { Geometry } from "./Geometry";
-import { type ColorInput } from "../core/color";
-import { Vec3, type Vec3Like } from "../math/vec";
+import { Node } from "../Node";
+import { Material } from "../Material";
+import { Texture } from "../Texture";
+import { Geometry } from "../Geometry";
+import { type ColorInput } from "../../core/color";
+import { Vec3, type Vec3Like } from "../../math/vec";
 export type TerrainLayer = {
     /** Albedo texture (a URL / `asset()` handle, or a loaded Texture). Unset = white. */
     albedo?: string | Texture;

package/dist/types/gl/{terrainMesh.d.ts → terrain/terrainMesh.d.ts}

@@ -1,4 +1,4 @@
-import { Geometry } from "./Geometry";
+import { Geometry } from "../Geometry";
 export type TerrainGrid = {
     sizeX: number;
     sizeZ: number;

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

@@ -0,0 +1,300 @@
+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, type Point } from "./Wheel";
+/** Which axle the engine drives — the default for every wheel's own `driven` share. */
+export type DriveLayout = "rear" | "front" | "all" | "none";
+/**
+ * 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) — Jolt's own clamp; a rev limiter's stutter is the game's. */
+    maxRpm?: number;
+    /** Idle RPM (default 1000): the engine's floor. `0` = no floor — the engine can be dragged to a
+     *  standstill and stall, and holding idle (a governor), cranking it, are the game's to write. */
+    idleRpm?: number;
+    /**
+     * The engine's CHARACTER: points `{ x, y }` in NORMALISED units — x a fraction of the redline, y a
+     * fraction of `torque`, x ascending. Left out, Jolt's own broad curve is used.
+     *
+     * `[{ x: 0, y: 0.8 }, { x: 0.66, y: 1 }, { x: 1, y: 0.8 }]` is an ordinary petrol engine (peak two
+     * thirds up, falling to the redline); `[{ x: 0, y: 1 }, { x: 1, y: 1 }]` is flat, an electric motor.
+     */
+    curve?: Point[];
+    /** 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;
+}
+/**
+ * The steering wheel as a BODY the tires push back on, simulated by the engine every sub-step. With
+ * it, `steer` is where the driver's hands AIM the wheel and `steerForce` how firmly they hold it;
+ * where the road wheels end up is physics:
+ *
+ *     I·θ̈ = T_hand + T_align·(1 − powerSteering) + T_stop − (damping + endStop.damping·depth)·θ̇ − parkingFriction(v) − friction
+ *
+ * `T_align` is the tires' self-aligning torque (`steering.caster` / `trail` / `trailAtPeak` — the
+ * same torque `steerTorque` reports without a feedback body, for a force-feedback wheel). `T_hand`
+ * is the driver's arms, `steering.driver`. So: heavy at speed, light when the front lets go,
+ * self-centring on release, and in a slide a let-go wheel swings into opposite lock by itself.
+ * Without `feedback` there is no body: `steer` is the road wheels' angle as a fraction of `maxAngle`.
+ */
+export interface SteeringFeedback {
+    /** Moment of inertia of wheel + column + rack about the axis, kg·m² (default 1). Heavier = slower
+     *  off the mark under the hands, but a wheel whipping into counter-steer carries further. */
+    inertia?: number;
+    /** Viscous damping, N·m·s/rad (default 25): what keeps a let-go wheel from ringing about centre. */
+    damping?: number;
+    /** The column's own dry friction, N·m, at any speed (default 8) — rack and bearings: the floor a
+     *  free wheel's spin decays against, and what keeps a let-go wheel from creeping under a small torque. */
+    friction?: number;
+    /** The contact patch's dry friction while (nearly) parked, N·m (default 40), fading out by 1.5 m/s
+     *  — why a parked car is hard to steer, and why a wheel left turned stays turned. */
+    parkingFriction?: number;
+    /** Power steering, 0..1 (default 0.5): the share of the tires' aligning torque the wheel never
+     *  sees. It is NOT a gain on the angle: 0 is a kart (heavy, full of feel, a held key gives up its
+     *  lock early at speed), 1 is a dead rim that neither centres nor counter-steers. */
+    powerSteering?: number;
+    /** The END STOP before the lock — rubber, not a wall (default `{ band: 16, torque: 120, damping: 150 }`):
+     *  over the last `band` degrees the rack pushes back toward centre with the SQUARE of the depth,
+     *  `torque` N·m at the lock, and damps by `damping` N·m·s/rad × depth. A wheel let go on the stop
+     *  eases back off it a few degrees; `band: 0` = the hard clamp only. */
+    endStop?: {
+        band?: number;
+        torque?: number;
+        damping?: number;
+    };
+}
+/** The driver's ARMS on a `feedback` wheel — an actuator with numbers, because a stiff hand spring
+ *  has to be integrated with the column every sub-step. WHAT the hands do (aim, hold, let go) is
+ *  the game's, per frame, through `steer` and `steerForce`. */
+export interface SteeringDriver {
+    /** The most torque the hands can put on the wheel, N·m (default 130). The ceiling on how much lock
+     *  a held key keeps at speed against the tires' pull. */
+    maxTorque?: number;
+    /** How stiff the arms are, N·m/rad of the gap between where they aim and where the wheel is (default 500). */
+    stiffness?: number;
+    /** The fastest the hands turn the road wheels, deg/s (default 120): the hands cannot PUSH a wheel
+     *  that already outruns them, they can still hold and brake it; a let-go wheel is uncapped. */
+    maxRate?: number;
+    /** Seconds the hands' torque takes to build to `maxTorque` (default 0.1): muscles do not step. */
+    rampTime?: number;
+}
+export interface SteeringConfig {
+    /** Steering lock in degrees (default 35): what `steer = ±1` means. */
+    maxAngle?: number;
+    /** The front axle's GEOMETRY, the source of the tires' self-aligning torque (`steerTorque`, and
+     *  what a `feedback` wheel is pushed by): the mechanical caster's trail, metres (default 0.03)… */
+    caster?: number;
+    /** …and the pneumatic trail, metres (default 0.025) — the patch's own lever, which collapses as the
+     *  tire reaches its peak slip angle (the steering going light when the front lets go)… */
+    trail?: number;
+    /** …to this fraction of itself at the peak (default 0.5). */
+    trailAtPeak?: number;
+    /** Simulate the steering wheel as a body the tires push back on (`SteeringFeedback`). `true` = the
+     *  defaults. Without it `steer` sets the road wheels' angle directly. */
+    feedback?: boolean | SteeringFeedback;
+    /** The driver's arms on a `feedback` wheel (`SteeringDriver`); the defaults without it. */
+    driver?: SteeringDriver;
+}
+/**
+ * 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") — the default for every wheel's own `driven`
+     *  share: 1 on that axle, 0 elsewhere. `none` = no drive at all (a trailer, a pushed cart). */
+    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` × 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. `clutch` (the input) scales it 0..1. */
+    clutchStrength: number;
+    /** The clutch's torque CAPACITY, N·m (default 0 = none: Jolt's viscous clutch alone, torque =
+     *  `clutchStrength` × slip speed, no ceiling — rigid at any real slip). Set it and the clutch
+     *  SLIPS at this much torque × `clutch` — a dry clutch, emulated a physics step at a time: a
+     *  launch can be feathered, and a dumped clutch in too high a gear drags the engine down instead
+     *  of lurching. A road car's is ~1.5× the engine's peak torque. */
+    clutchCapacity: 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;
+    };
+    /** Driver systems tick at the default 0, so their inputs land in the SAME early pass, before this flush. */
+    protected updateOrder: number;
+    private _id;
+    private _bodyId;
+    private _builtMass;
+    private _wheels;
+    private _state;
+    private _stateFrame;
+    private _throttle;
+    private _steer;
+    private _steerForce;
+    private _ratio;
+    private _clutch;
+    private _input;
+    private _sent;
+    private _dirty;
+    private _retunePending;
+    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`,
+     * `clutchCapacity`, `antiRoll` (its stiffness, on axles that have a bar), and every `Wheel`'s
+     * `tire`. Everything else describes the car's STRUCTURE — `mass`, `centerOfMass`, which wheels
+     * exist and where, their suspension, the driven shares — 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 (for `physicsApplyImpulse`-style calls). */
+    get bodyId(): number;
+    /** The wheels, front axle first, in the order the engine knows them. */
+    get wheels(): readonly Wheel[];
+    /** Throttle 0..1 — the engine's pedal. No sign: the direction is `ratio`'s. */
+    get throttle(): number;
+    set throttle(v: number);
+    /** Steering −1..1. Without `steering.feedback`: the road wheels' angle as a fraction of `maxAngle`,
+     *  applied as is (a taper with speed, a rate limit, are the game's). With it: where the hands AIM
+     *  the wheel; the tires decide where the road wheels end up. */
+    get steer(): number;
+    set steer(v: number);
+    /** How firmly the hands hold a `feedback` wheel, 0..1 (default 1): the hands' torque is capped at
+     *  `driver.maxTorque × steerForce`. 0 = let go — the tires alone have the wheel: back to centre in
+     *  a grip corner, into opposite lock in a slide. Ignored without a feedback wheel. */
+    get steerForce(): number;
+    set steerForce(v: number);
+    /** The ONE gear ratio the engine runs (default 1): engine rpm = wheel rpm × ratio × the final
+     *  drive (3.42). The SIGN is the direction — negative is reverse — and 0 is neutral. */
+    get ratio(): number;
+    set ratio(v: number);
+    /** Clutch engagement 0..1 (default 1 = home). 0 = out: the engine is free of the wheels. */
+    get clutch(): number;
+    set clutch(v: number);
+    /**
+     * EARLY phase: hand this frame's inputs to the engine, before the step. The vector is sent when
+     * anything changed — and every frame while a throttle, steer or brake is non-zero, because that is
+     * what keeps a driven car awake (an idle car with zero input sleeps). The pending re-tune (a
+     * config or tire change) goes first, so the step runs on the new numbers.
+     */
+    protected updateBefore(): void;
+    /** Teleport upright and clear all motion (velocity, engine rpm, wheel spin). Defaults to the
+     *  chassis node's current pose — `reset()` alone un-flips a car where it lies. The inputs are
+     *  kept and re-sent on the next early pass. */
+    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 RPM. */
+    get rpm(): number;
+    /** How many wheels touch the ground this frame. */
+    get wheelsOnGround(): number;
+    /** At least one wheel on the ground. */
+    get grounded(): boolean;
+    /** Chassis velocity in world space, m/s. */
+    get velocity(): Vec3;
+    /** Chassis angular velocity in world space, rad/s. */
+    get angularVelocity(): Vec3;
+    /** How fast the car is turning about the vertical, in degrees per second — positive turning RIGHT
+     *  (the same sense as `steer`). The signal a counter-steer assist reads. */
+    get yawRate(): number;
+    /**
+     * The car's slip angle in degrees: the angle between where the nose points and where the car is
+     * actually travelling, positive when it is travelling to the RIGHT of the nose. 0 going straight,
+     * ±180 backing up, and past ~10° the rear has stepped out — a drift.
+     */
+    get slipAngle(): number;
+    /**
+     * The angle of the SLIDE, degrees, signed like `slipAngle` (positive = travelling to the right of
+     * the nose), −180..180: the angle between the car's axis and where its REAR AXLE travels — the
+     * mean of the non-steering wheels (every wheel if all of them steer), its velocity from the
+     * body's velocity and spin. Unlike `slipAngle` (the body's, at its centre) this is 0 on a clean
+     * corner at ANY speed: at walking pace and full lock the body already travels ~20° off its nose
+     * while the rear axle rolls straight along it. It is the rear stepping out — what a gyro comes in
+     * on, and what a drift meter should show — and unlike the tires' own `Wheel.slipAngle` it does
+     * not fold at 90°: a backward entry reads 110°, not 70°. The axis it is measured from is the one
+     * the DRIVETRAIN pushes along — the nose for a positive `ratio`, the tail for a negative one — so
+     * honest reversing reads 0, and a car spun round in a forward gear reads past 90°. 0 at a
+     * standstill: with no speed a direction is noise, so it fades in over walking pace,
+     * `DRIFT_SPEED_FROM`..`DRIFT_SPEED_FULL` of the axle's ground speed.
+     */
+    get driftAngle(): number;
+    /** Where the steered wheels actually are, in degrees, right-positive: the angle `steer` set, or
+     *  with `steering.feedback` where the column has come to. */
+    get steerAngle(): number;
+    /** The tires' self-aligning torque on the steering, N·m, positive = it pulls the wheel to the
+     *  RIGHT — what the driver feels: heavy at speed, light when the front lets go, and the
+     *  counter-steer in a slide. Reported with or without a `feedback` wheel: the signal a
+     *  force-feedback steering wheel is driven by. */
+    get steerTorque(): 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/vehicle/Wheel.d.ts

@@ -0,0 +1,147 @@
+import { Aspect } from "../../core/Aspect";
+import type { FieldMeta } from "../../core/fields";
+import { Vec3 } from "../../math/vec";
+import { Node } from "../Node";
+/** Floats `vehicleGetState` writes before the per-wheel block: speed, rpm, contacts, vx, vy, vz, wx, wy, wz,
+ *  steerDeg, steerTorque. */
+export declare const STATE_HEADER = 11;
+/** Floats per wheel: contact, slip, slipAngle, suspensionLength, steerDeg, spin, fLat, fLong, vLat, vSlip, load. */
+export declare const WHEEL_STATE = 11;
+/** Fully compressed = this fraction of `travel` (the engine's one suspension constant, mirrored here
+ *  so `compression` and the resting-height maths read the same number). */
+export declare const SUSPENSION_MIN_FRACTION = 0.4;
+/** A point on a curve — a tire's friction over slip, an engine's torque over rpm. */
+export type Point = {
+    x: number;
+    y: number;
+};
+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;
+}
+/**
+ * A tire, as the engine takes it: two friction curves and two numbers. `Tire.road()` and the other
+ * presets are starting points — copy one and edit, or `Tire.scale()` it.
+ */
+export interface Tire {
+    /** Lateral friction over slip ANGLE: `{ x: degrees, y: friction }`, x ascending. Friction is the
+     *  coefficient the tire's load is multiplied by; the last value holds to 90°. 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 — a road a car should really corner on wants `Physics { friction: 1 }`. */
+    side: Point[];
+    /** Longitudinal friction over slip RATIO: `{ x: ratio, y: friction }` (0 = rolling in sync, 1 =
+     *  locked or spinning freely). */
+    forward: Point[];
+    /** The longitudinal impulse clamp as a multiple of `friction × load` — for DRIVE only; a braking
+     *  wheel is always clamped at the physical limit (or a locked rear would stop the car at a full g
+     *  and kill every handbrake turn). `1` is the physical tire; `road`'s 10 is Jolt's own sample
+     *  value (it keeps a driven wheel from ever spinning up). Anything a friction circle should bite
+     *  on wants this near 1. */
+    traction?: number;
+    /** Friction circle, 0..1: how much of the lateral capacity the longitudinal impulse in use takes
+     *  away. `0` = the two axes independent (a spinning wheel corners as well as a rolling one);
+     *  `1` = the full circle — wheelspin or a locked wheel lets go sideways. */
+    circle?: number;
+}
+/**
+ * Tire presets — fresh point lists every call (editing one never touches another), and `scale`.
+ *
+ *  - `road` — Jolt's stock tire: lateral peak 1.2 at 3° falling to 1.0 by 20° and flat after, the
+ *    two axes independent, and the longitudinal clamp ×10 (Jolt's own sample runs this; it means a
+ *    driven wheel practically never spins up). Grippy, glued, hard to unsettle.
+ *  - `arcade` — the peak held all the way out on both axes: the car does not let go at all.
+ *  - `drift` — a tire that can be held sideways: lateral grip falls to 0.7 past 25°, the longitudinal
+ *    clamp is near the physical one (`traction: 2` — a launch at exactly 1 is a 0.4 g crawl; 2 keeps
+ *    it punchy) so the rear can be spun up, and a friction circle (`circle: 0.85` — most of it, so a
+ *    spinning rear loses most but not all of its lateral grip and the slide stays progressive):
+ *    power oversteer, and a slide the throttle keeps alive. A 600 N·m car lights its tires off the
+ *    line on it; that is the tire, and a traction control is the game's.
+ */
+export declare const Tire: {
+    road: () => Tire;
+    arcade: () => Tire;
+    drift: () => Tire;
+    /** Both curves multiplied by `k` — a grip slider, a cold tire, a wet road. A new tire; `t` is untouched. */
+    scale: (t: Tire, k: number) => Tire;
+};
+export declare function resolveTire(tire: Tire): ResolvedTire;
+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;
+    /** 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;
+    /** Does this wheel steer? Default: the wheels on the front axle. */
+    steer?: boolean;
+    /** This wheel's SHARE of the engine's torque, 0 = not driven. Default: from the vehicle's
+     *  `driveAxle` (1 on that axle). An axle's share is the sum of its two wheels', the left/right
+     *  split their ratio, so `0.6` / `0.4` front-to-rear is `driven: 0.3` on each front wheel and
+     *  `0.2` on each rear. Structural: baked at attach. */
+    driven?: number;
+    suspension: WheelSuspension;
+    /** The tire (default `Tire.road()`). Live: re-assign it or re-configure the aspect and the car
+     *  retunes in place — a grip slider, a tire that heats up. */
+    tire: Tire;
+    /** INPUT: brake torque on this wheel THIS frame, N·m (default 0). Sticky, like `Vehicle.throttle`:
+     *  write it every frame from a driver system's `updateBefore` — the foot brake's share, the
+     *  handbrake's 4500 on a rear wheel, an ABS's pulses — and the same physics step applies it. A
+     *  braking wheel is clamped at the physical tire limit (the `traction` boost is for drive only). */
+    brake: number;
+    /** Scene-editor inspector. `steer` / `driven` are deliberately absent: they are tri-state
+     *  (undefined = derive it from the axle), which a slider cannot express. */
+    static fields: FieldMeta<Wheel>;
+    static editor: {
+        rebuild: boolean;
+    };
+    onDetach(): void;
+    /** Re-configuring a wheel on a live car retunes the car: the tire is live; size, suspension, the
+     *  driven share and the axle are structural (re-attach the Vehicle). */
+    onReconfigure(): void;
+    private _state;
+    /** Touching the ground this step. */
+    get contact(): boolean;
+    /** Longitudinal slip RATIO, signed: 0 = rolling in sync with the ground, towards +1 = spinning up
+     *  (wheelspin), towards −1 = locking under braking — whichever way the car travels. Smoke, tire
+     *  marks, wheelspin sound and traction control key off this. */
+    get slip(): number;
+    /** Slip ANGLE in degrees, signed: how far the tire's travel direction is off from where it points,
+     *  positive when the contact patch slides to the tire's RIGHT. Past the curve's peak (~3°) the tire
+     *  is letting go sideways. */
+    get slipAngle(): number;
+    /** This wheel's steer angle in degrees, right-positive. */
+    get steerAngle(): number;
+    /** Wheel spin in rad/s (× radius ≈ the speed the tire is laying down). Forward-positive; a model
+     *  turns about the right-hand axle by MINUS the integrated angle. */
+    get spin(): number;
+    /** The tire's lateral force this step, N, positive toward the tire's right — the road pushing the
+     *  patch back against its slide. */
+    get sideForce(): number;
+    /** The tire's longitudinal force this step, N, positive pushing the car forward. */
+    get forwardForce(): number;
+    /** How fast the contact patch slides sideways, m/s, positive to the tire's right. */
+    get sideSlipSpeed(): number;
+    /** How fast the tread runs over the road, m/s, positive spinning up, negative locking. Force ×
+     *  sliding speed (`|sideForce × sideSlipSpeed| + |forwardForce × slipSpeed|`) is the friction's
+     *  heat into the tread, W — a tire-temperature model integrates it. */
+    get slipSpeed(): number;
+    /** The suspension's force on the wheel this step, N — the tire's LOAD (0 in the air). What a
+     *  friction budget divides by: `hypot(sideForce, forwardForce) / (load × μ)`. */
+    get load(): number;
+    /** Suspension compression, 0 = fully extended (drooping) … 1 = fully compressed. */
+    get compression(): number;
+    /** Where the wheel's centre is right now, in CHASSIS space: the suspension's attachment point,
+     *  down by however far it hangs this step. Put a wheel model here (see the file header). */
+    get position(): Vec3;
+    /** 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/dist/types/inject.d.ts

@@ -23,6 +23,10 @@ export { WebSocket } from "./runtime/net";
 export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform } from "./net";
 export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc";
 export { AudioPlayer, VideoPlayer } from "./runtime/media";
+export { Sound, type SoundOptions } from "./audio/Sound";
+export { Voice, type VoiceEvents } from "./audio/Voice";
+export { Bus, REVERB_PRESETS, type ReverbPreset, type ReverbParams, type EchoParams } from "./audio/Bus";
+export { audio, type PlaySoundOptions, type SpatialOptions, type Rolloff, type AudioStats } from "./audio/audio";
 export { openFilePicker, files, type FileData } from "./runtime/files";
 export { share } from "./runtime/share";
 export { ClickEvent, TouchStartEvent, LongPressEvent } from "./runtime/touch";
@@ -81,21 +85,24 @@ export { Scene, ARScene, VRScene } from "./gl/Scene";
 export { Node } from "./gl/Node";
 export { Mesh } from "./gl/Mesh";
 export { Model } from "./gl/Model";
-export { Shape } from "./gl/Shape";
-export { Physics } from "./gl/Physics";
-export { Trigger } from "./gl/Trigger";
-export { CharacterController } from "./gl/CharacterController";
-export { Vehicle } from "./gl/Vehicle";
-export type { DriveLayout, DifferentialMode, EngineConfig, SteeringConfig, AeroConfig } from "./gl/Vehicle";
-export { Wheel } from "./gl/Wheel";
-export { Ragdoll } from "./gl/Ragdoll";
-export type { RagdollPart, RagdollHinge } from "./gl/Ragdoll";
-export type { TireCurve, WheelSuspension, WheelTire, WheelVisual } from "./gl/Wheel";
-export { Gearbox } from "./gl/Gearbox";
+export { Shape } from "./gl/physics/Shape";
+export { Physics } from "./gl/physics/Physics";
+export { Trigger } from "./gl/physics/Trigger";
+export { AudioSource, type AudioCone } from "./gl/audio/AudioSource";
+export { AudioZone } from "./gl/audio/AudioZone";
+export { SceneAudio } from "./gl/audio/SceneAudio";
+export { CharacterController } from "./gl/physics/CharacterController";
+export { Vehicle } from "./gl/vehicle/Vehicle";
+export type { DriveLayout, DifferentialMode, EngineConfig, SteeringConfig, SteeringFeedback, SteeringDriver, AeroConfig } from "./gl/vehicle/Vehicle";
+export { Wheel, Tire, resolveTire } from "./gl/vehicle/Wheel";
+export { Ragdoll } from "./gl/physics/Ragdoll";
+export type { RagdollPart, RagdollHinge } from "./gl/physics/Ragdoll";
+export type { Point, WheelSuspension } from "./gl/vehicle/Wheel";
 export { AnimationClip } from "./gl/animation/AnimationClip";
 export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/animation/AnimationClip";
 export { Animator } from "./gl/animation/Animator";
 export type { LodMode } from "./gl/animation/Animator";
+export type { TrianglePick } from "./gl/Model";
 export { Feet } from "./gl/animation/Feet";
 export type { FeetOptions, FootState } from "./gl/animation/Feet";
 export { Warp } from "./gl/animation/Warp";
@@ -104,25 +111,30 @@ export { Playback } from "./gl/animation/Playback";
 export { Loop } from "./gl/animation/Loop";
 export { Layer } from "./gl/animation/Layer";
 export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition, BlendMember, ActiveClip, ClipInfo, ClipCycle, ClipAlign, KneeAxisReport, StepHandler, ClipEventHandler } from "./gl/animation/core";
-export { IK } from "./gl/IK";
-export type { IKTwoBone, IKLookAt } from "./gl/IK";
+export { IK } from "./gl/animation/IK";
+export { DynamicBone, DynamicBoneCollider } from "./gl/animation/DynamicBone";
+export type { DynamicBoneCurve, DynamicBoneFloor, DynamicBoneColliders } from "./gl/animation/DynamicBone";
+export type { IKTwoBone, IKLookAt } from "./gl/animation/IK";
 export { Light } from "./gl/Light";
 export { Lightmap } from "./gl/Lightmap";
-export { Terrain } from "./gl/Terrain";
-export type { TerrainOptions, TerrainLayer, TerrainRegion, ConformOptions, RibbonOptions, AutoPaintRules, SculptOptions, TerrainHit, TerrainSnapshot } from "./gl/Terrain";
-export { NavMesh, NavCrowd } from "./gl/NavMesh";
-export type { NavMeshLoadOptions, NavMeshInfo, NavPath, NavQueryOptions, NavRaycastHit, NavAgentSize } from "./gl/NavMesh";
-export { NavAgent } from "./gl/NavAgent";
-export type { NavAgentState, NavAgentAvoidance, NavAgentDrive, NavAgentEvents } from "./gl/NavAgent";
-export { Locomotion } from "./gl/Locomotion";
-export type { LocomotionSet, LocomotionClip, LocomotionTuning, LocomotionState, LocomotionEvents, Displacement, Gait } from "./gl/Locomotion";
+export { Terrain } from "./gl/terrain/Terrain";
+export type { TerrainOptions, TerrainLayer, TerrainRegion, ConformOptions, RibbonOptions, AutoPaintRules, SculptOptions, TerrainHit, TerrainSnapshot } from "./gl/terrain/Terrain";
+export { NavMesh, NavCrowd } from "./gl/nav/NavMesh";
+export type { NavMeshLoadOptions, NavMeshInfo, NavPath, NavQueryOptions, NavRaycastHit, NavAgentSize } from "./gl/nav/NavMesh";
+export { NavAgent } from "./gl/nav/NavAgent";
+export type { NavAgentState, NavAgentAvoidance, NavAgentDrive, NavAgentEvents } from "./gl/nav/NavAgent";
+export { Locomotion } from "./gl/animation/Locomotion";
+export type { LocomotionSet, LocomotionClip, LocomotionTuning, LocomotionState, LocomotionEvents, Displacement, Gait } from "./gl/animation/Locomotion";
 export { Material } from "./gl/Material";
 export { Geometry } from "./gl/Geometry";
 export { InstancedMesh } from "./gl/InstancedMesh";
 export type { InstanceTransform } from "./gl/InstancedMesh";
 export { Texture } from "./gl/Texture";
+export type { TextureLoadOptions } from "./gl/Texture";
 export { Camera } from "./gl/Camera";
 export { Ray } from "./gl/Ray";
 export { Plane } from "./gl/Plane";
 export { Noise } from "./gl/Noise";
 export { Particles, Trail, curve, colorCurve } from "./gl/Particles";
+export { DecalSet, DecalTrail } from "./gl/DecalSet";
+export type { DecalOptions, DecalSetOptions, DecalSpawnOptions, DecalPlacement, DecalTrailOptions } from "./gl/DecalSet";