lecodes-sdk 0.19.0

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

@@ -0,0 +1,280 @@
+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;
+    /** Metres per texture repeat. Default 8. */
+    tiling?: number;
+    /** Perceptual roughness of the layer. Default 1. */
+    roughness?: number;
+    /** Normal-map strength (0 = the layer's slot of the pack is not read). Default 0 — set 1 when the
+     *  layer has a normal map in `normals`. */
+    normalScale?: number;
+    /** Sample this layer triplanar in world space (cliff rock): no stretching on steep slopes; its
+     *  normal map is then skipped. Default false. */
+    triplanar?: boolean;
+};
+export type TerrainOptions = {
+    /** Samples per side (square). 257 / 513 / 1025 are the usual sizes. Default 129. */
+    size?: number;
+    sizeX?: number;
+    sizeZ?: number;
+    /** Metres between samples. Default 1. */
+    cellSize?: number;
+    /** Cells per chunk side (≤ 255). Default 64. */
+    chunk?: number;
+    /** Heights in metres: an array of sizeX × sizeZ (row-major, z rows), or a function of the sample's
+     *  LOCAL position in metres. Default flat 0. */
+    heights?: Float32Array | ((x: number, z: number) => number);
+    /** A byte per sample, 1 = hole (a triangle needs its three samples valid). */
+    holes?: Uint8Array;
+    /** RGBA layer weights per sample (normalised in the shader). Default: all layer 0. */
+    control?: Uint8Array;
+    layers?: TerrainLayer[];
+    /** The two normal-map packs: `[layers 0+1, layers 2+3]` — XY of the even layer in RG, the odd in BA. */
+    normals?: [string | Texture | undefined, (string | Texture)?];
+    /** Multiplier on every layer's albedo. */
+    tint?: ColorInput;
+    name?: string;
+    /** A material to use instead of `Material.terrain()` (a custom terrain shader with the same uniforms). */
+    material?: Material;
+};
+/** A region of the terrain in LOCAL metres (XZ). `node` = the XZ footprint of a node's triangles. */
+export type TerrainRegion = {
+    circle: {
+        x: number;
+        z: number;
+        r: number;
+    };
+} | {
+    rect: {
+        x: number;
+        z: number;
+        w: number;
+        h: number;
+    };
+} | {
+    polygon: readonly (readonly [number, number])[];
+} | {
+    node: Node;
+};
+export type ConformOptions = {
+    /** How far below the target surface the ground sits (keeps bilinear terrain strictly under a
+     *  curved road between samples). Default 0.05. */
+    offset?: number;
+    /** Metres over which the surrounding ground blends back to its old height. Default 4; 0 = hard edge. */
+    falloff?: number;
+    /** `both` (default) cuts and fills; `lower` only cuts; `raise` only fills. */
+    mode?: "both" | "lower" | "raise";
+};
+export type RibbonOptions = {
+    /** Width in metres. */
+    width: number;
+    /** Metres of ribbon per texture repeat along its length. Default = width. */
+    uvScale?: number;
+};
+/** A brush dab for `sculpt` — LOCAL metres. */
+export type SculptOptions = {
+    x: number;
+    z: number;
+    /** Brush radius in metres. */
+    radius: number;
+    /** `raise` / `lower` by `amount` metres at full weight; `smooth` blends toward the 3×3 average
+     *  (`amount` 0…1 = how far); `flatten` pulls toward `target` (default: the height under the
+     *  centre) by `amount` 0…1. Default raise. */
+    mode?: "raise" | "lower" | "smooth" | "flatten";
+    amount?: number;
+    /** 0…1 — the share of the radius at full weight; the rest feathers out (default 0.5). */
+    hardness?: number;
+    target?: number;
+};
+/** `snapshot()` — the three sample arrays, copied; `restore()` puts them back (undo, a level reset). */
+export type TerrainSnapshot = {
+    heights: Float32Array;
+    holes: Uint8Array;
+    control: Uint8Array;
+};
+/** A ray hit on the terrain (`raycast` local, `raycastWorld` world). */
+export type TerrainHit = {
+    point: Vec3;
+    normal: Vec3;
+    distance: number;
+};
+export type AutoPaintRules = {
+    /** The layer everything starts as. Default 0. */
+    base?: number;
+    /** Slope rule: the layer takes over between `from` and `to` degrees of slope. */
+    slope?: {
+        layer: number;
+        from: number;
+        to: number;
+    };
+    /** Height rule: the layer takes over between `from` and `to` metres (snow line). */
+    height?: {
+        layer: number;
+        from: number;
+        to: number;
+    };
+    /** Low rule: the layer takes over BELOW `to` metres, fading in from `from` (valley floors). */
+    low?: {
+        layer: number;
+        from: number;
+        to: number;
+    };
+};
+/** What Shape { heightfield } reads off a terrain node (`node._terrain`). */
+export type TerrainData = {
+    sizeX: number;
+    sizeZ: number;
+    cellSize: number;
+    heights: Float32Array;
+    holes: Uint8Array | null;
+};
+export declare class Terrain {
+    /** The node the terrain hangs off: transform it to place the ground; add it to the scene. */
+    readonly node: Node;
+    readonly sizeX: number;
+    readonly sizeZ: number;
+    readonly cellSize: number;
+    readonly chunk: number;
+    /** sizeX × sizeZ heights in metres, row-major (z rows). Edit, then `commit()`. */
+    readonly heights: Float32Array;
+    /** A byte per sample, 1 = hole. */
+    readonly holes: Uint8Array;
+    /** RGBA layer weights per sample. */
+    readonly control: Uint8Array;
+    /** The splat material (`Material.terrain()` unless one was passed). */
+    readonly material: Material;
+    /** Resolves when every layer texture has loaded (the terrain renders white until then). */
+    readonly ready: Promise<void>;
+    layers: TerrainLayer[];
+    private _native;
+    private _chunkMeshes;
+    private _controlTex;
+    private _dirty;
+    private _holesTouched;
+    private _controlDirty;
+    private _anyHole;
+    private _cast;
+    private _receive;
+    private constructor();
+    /** Build a terrain from data / a generator (synchronous; `ready` resolves once its textures loaded). */
+    static create(opts?: TerrainOptions): Terrain;
+    /** The terrain a node carries (the node `Terrain.create` returned), or null. */
+    static of(node: Node | null | undefined): Terrain | null;
+    /** Load a `.terrain` file (`Terrain.serialize` / the editor / `lecodes terrain import`); layer textures
+     *  are not in the file — pass them in `opts` (they are asset handles the file cannot hold). */
+    static load(url: string, opts?: Omit<TerrainOptions, "size" | "sizeX" | "sizeZ" | "heights" | "holes" | "control">): Promise<Terrain>;
+    private get _grid();
+    /** Height at a local (x, z) on the drawn triangles; NaN in a hole or outside the grid. */
+    heightAt(x: number, z: number): number;
+    /** The drawn triangle's normal at a local (x, z) (unit Vec3, +Y up). */
+    normalAt(x: number, z: number): Vec3;
+    /** The smooth (vertex) normal at integer sample (ix, iz). */
+    sampleNormal(ix: number, iz: number): Vec3;
+    /** Extent in local metres: `[width, depth]`. */
+    get extent(): [number, number];
+    /** Min / max height over the grid. */
+    get heightRange(): [number, number];
+    /** A world-space point into the terrain's local frame. */
+    toLocal(p: Vec3Like): Vec3;
+    /** A local point into world space. */
+    toWorld(p: Vec3Like): Vec3;
+    /** The ground's WORLD height under a world (x, z): NaN off the grid / in a hole. */
+    worldHeightAt(x: number, z: number): number;
+    /** Nearest hit of a LOCAL ray on the drawn triangles (holes let it through), null on a miss.
+     *  Exact against what is rendered — the editor's brush and a host without physics pick with it. */
+    raycast(origin: Vec3Like, dir: Vec3Like, maxDistance?: number): TerrainHit | null;
+    /** `raycast` in WORLD space — through the node's transform (rotation + uniform scale). */
+    raycastWorld(origin: Vec3Like, dir: Vec3Like, maxDistance?: number): TerrainHit | null;
+    /** Write a rectangle of samples (`src` = w × h heights, row-major). */
+    setHeights(x0: number, z0: number, w: number, h: number, src: ArrayLike<number>): this;
+    /** Apply `fn(oldHeight, weight, x, z)` over a region; `weight` is 1 inside, fading to 0 over
+     *  `falloff` metres outside it. The building block of flatten / raise / hole. */
+    shape(region: TerrainRegion, fn: (h: number, w: number, x: number, z: number) => number, falloff?: number): this;
+    /** Flatten a region to `height` (a plateau / a building pad), blending over `falloff` metres. */
+    flatten(region: TerrainRegion, height: number, opts?: {
+        falloff?: number;
+    }): this;
+    /** Raise (or lower, negative) a region by `delta` metres, blending over `falloff` metres. */
+    raise(region: TerrainRegion, delta: number, opts?: {
+        falloff?: number;
+    }): this;
+    /** Copies of heights / holes / control — an undo point or a level reset. */
+    snapshot(): TerrainSnapshot;
+    /** Put a `snapshot()` back (same grid size) — everything marked dirty for the next `commit()`. */
+    restore(s: TerrainSnapshot): this;
+    /** One brush dab: raise / lower / smooth / flatten a disc of `radius` metres around (x, z), feathered
+     *  by `hardness` — the editor's sculpt tool and runtime deformation (craters, digging) share it. */
+    sculpt(opts: SculptOptions): this;
+    /** Cut a hole (no triangles, no collision, no navmesh) — or fill one back with `on = false`. */
+    hole(region: TerrainRegion, on?: boolean): this;
+    /**
+     * Conform the ground to a mesh — the terrain takes the target's TOP surface minus `offset` under
+     * its footprint (a road sits exactly on it, nothing pokes through), and blends back to the old
+     * ground over `falloff` metres around it. `target` = a node (a Mesh, a Model, or a node holding
+     * them — every triangle in the subtree counts), a Geometry in local coordinates, or a raw soup
+     * (9 floats per triangle, local). Call again after the target moves.
+     */
+    conform(target: Node | Geometry | Float32Array, opts?: ConformOptions): this;
+    /** `conform` to a ribbon along `points` (world/local metres, see `ribbon`) — the road stamp. */
+    conformPath(points: readonly Vec3Like[], opts: ConformOptions & RibbonOptions): this;
+    /**
+     * A flat ribbon Geometry along a polyline (the road mesh AND the conform target): `width` metres,
+     * vertices take the points' own Y, UV0 = (across 0…1, along / uvScale). Build it from heights you
+     * sampled with `heightAt` and smoothed, then `Mesh.from(geometry, { material })` + `conform`.
+     * It also carries a lightmap UV (uv1: along 0…1 × across 0…width/length — the strip's true aspect,
+     * so `lecodes lightmap bake` gives it uniform texels), which makes the road a bake receiver.
+     */
+    static ribbon(points: readonly Vec3Like[], opts: RibbonOptions): Geometry;
+    /** Write RGBA layer weights for a rectangle of samples (`rgba` = w × h × 4 bytes). */
+    paint(x0: number, z0: number, w: number, h: number, rgba: ArrayLike<number>): this;
+    /** Paint `layer` over a region with `strength` (0…1), feathered over `falloff` metres. */
+    paintLayer(region: TerrainRegion, layer: number, strength?: number, falloff?: number): this;
+    /** Paint the whole terrain from slope / height rules (grass on the flats, rock on cliffs, snow on
+     *  the peaks, dirt in the valleys) — the CPU pass a procedural level starts from. */
+    paintAuto(rules?: AutoPaintRules): this;
+    private _blendLayer;
+    /** Push every pending edit to the engine: chunk renderables + the height-field collider for the
+     *  dirty rectangle, the control texture. Call once after a batch of edits. */
+    commit(): this;
+    set castShadows(v: boolean);
+    get castShadows(): boolean;
+    set receiveShadows(v: boolean);
+    get receiveShadows(): boolean;
+    /** The whole terrain as a `.terrain` file (LTER: heights quantised to 16 bits, holes, control). */
+    serialize(): ArrayBuffer;
+    /** Decode a `.terrain` file into create() options (heights back in metres). */
+    static parse(buf: ArrayBuffer): {
+        sizeX: number;
+        sizeZ: number;
+        cellSize: number;
+        chunk: number;
+        heights: Float32Array;
+        holes: Uint8Array;
+        control: Uint8Array;
+        layers: TerrainLayer[];
+    };
+    private _build;
+    private _buildFallbackChunk;
+    private _rebuildFallbackChunks;
+    private _applyShadows;
+    private _uploadControl;
+    private _applyLayers;
+    /** Re-push layer scalars after editing `layers` (textures given as Texture apply too). */
+    applyLayers(): Promise<void>;
+    private _touch;
+    private _touchControl;
+    /** The sample rectangle a region (+ falloff) touches, or null when it misses the grid. */
+    private _regionRect;
+    /** Per-sample weights over `r`: 1 inside the region, smooth 1→0 across `falloff` metres outside. */
+    private _regionWeights;
+    /** World matrix of the node (column-major). */
+    private _world;
+    /** A target's triangles in the terrain's LOCAL frame, 9 floats per triangle. */
+    private _triangles;
+}

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

@@ -0,0 +1,27 @@
+import { type FetchResponse, type File } from "../runtime/fetch";
+export declare class Texture {
+    readonly width: number;
+    readonly height: number;
+    /** Horizontal wrap mode (U). */
+    wrapS: number;
+    /** Vertical wrap mode (V). */
+    wrapT: number;
+    constructor(width: number, height: number, id: number);
+    static fromCanvas(canvas: {
+        _bakeSurface(): number;
+        width: number;
+        height: number;
+        pixelRatio: number;
+        _tex3dId: number;
+    }): Texture;
+    /** A texture from raw pixels: `channels` (1–4, default 4) UBYTE per pixel, row-major, `width ×
+     *  height × channels` bytes; `srgb` (default true for colour) picks the sRGB internal format —
+     *  pass false for data (a heightmap, a mask). No mips. Throws on a host without the call. */
+    static fromPixels(width: number, height: number, data: Uint8Array, opts?: {
+        channels?: 1 | 2 | 3 | 4;
+        srgb?: boolean;
+    }): Texture;
+    /** Re-upload a rectangle of a `fromPixels` texture (same channel count). */
+    update(x: number, y: number, width: number, height: number, data: Uint8Array): void;
+    static load(source: string | FetchResponse | File): Promise<Texture>;
+}

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

@@ -0,0 +1,10 @@
+import { Aspect } from "../core/Aspect";
+import type { Node } from "./Node";
+export declare class Trigger extends Aspect<"trigger", Node> {
+    static readonly aspect = "trigger";
+    private _bodyId;
+    /** Native body id (0 if no physics support). */
+    get id(): number;
+    onAttach(): void;
+    onDetach(): void;
+}

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

@@ -0,0 +1,191 @@
+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

@@ -0,0 +1,95 @@
+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/dist/types/gl/animation/AnimationClip.d.ts

@@ -0,0 +1,60 @@
+import { type FetchResponse } from "../../runtime/fetch";
+import type { Vec3Like } from "../../math/vec";
+import type { QuatLike } from "../../math/quat";
+/** A keyframe: `[time (s), value]`. */
+export type ClipKey<V> = [number, V];
+export type ClipInterpolation = "linear" | "step";
+/** Curves for one target node (bone name), any subset of the three channels. */
+export type ClipTrackDef = {
+    position?: ClipKey<Vec3Like | [number, number, number]>[];
+    rotation?: ClipKey<QuatLike | [number, number, number, number]>[];
+    scale?: ClipKey<Vec3Like | [number, number, number]>[];
+    interpolation?: ClipInterpolation;
+};
+export type ClipDef = {
+    /** Clip length in seconds — defaults to the last key time across all tracks. */
+    duration?: number;
+    /** Target node name → its curves. Names bind to bones (or any child node) at Animator attach. */
+    tracks: Record<string, ClipTrackDef>;
+};
+export type ClipInfo = {
+    name: string;
+    duration: number;
+    trackCount: number;
+};
+export declare class AnimationClip {
+    /** Source name (the clip's name inside its file; `"clip"` for procedural clips). Informational —
+     *  an Animator addresses clips by the key YOU give it. */
+    readonly name: string;
+    /** Length in seconds. */
+    readonly duration: number;
+    /** Number of animated (node, channel) tracks. */
+    readonly trackCount: number;
+    private constructor();
+    /** Mark a moment of the clip (SECONDS from its start) with an event name: `kick.addEvent(0.4, 'hit')`
+     *  → `anim.on('hit', (clip, layer) => …)` fires when the playhead crosses it, loops included.
+     *  Events are part of the clip: every model playing it gets them; `slice()` keeps the ones inside
+     *  the range, re-timed. Chainable. */
+    addEvent(time: number, name: string): this;
+    private _pushEvents;
+    /** Load ONE clip from a GLB: the file's only/first clip, or the one named / at the given index. */
+    static load(source: string | FetchResponse, clip?: string | number): Promise<AnimationClip>;
+    /** Load EVERY clip of a GLB (library files), keyed by clip name. */
+    static loadAll(source: string | FetchResponse): Promise<Record<string, AnimationClip>>;
+    /** Build a clip from curves in code — no DCC needed. Keys are `[time, value]`; a track binds to the
+     *  node of that name when the clip is used by an Animator (bones, or any child node). */
+    static from(def: ClipDef): AnimationClip;
+    /** A sub-range of this clip as a NEW clip — `[start, end]` seconds of the source, re-timed to 0
+     *  (`end` defaults to the clip's end; array-slice semantics). Cut a too-long take down to the
+     *  action, or carve several sub-clips out of one packed timeline:
+     *
+     *    clips: { Kick: kick.slice(0.2, 1.1) }
+     *
+     *  Keys outside the range are dropped and exact boundary values are interpolated in, so the
+     *  sliced clip starts and ends precisely on the source's pose at the cut points. Everything
+     *  downstream (blend spaces, events' 0–1 times, root motion, phase sync) sees a normal clip of
+     *  the new duration. */
+    slice(start: number, end?: number): AnimationClip;
+    private static _label;
+    private static _loadSet;
+}