lecodes-sdk 0.20.2 → 1.0.0

package/src/scene/defineScene.ts

@@ -46,13 +46,14 @@ import { CameraPlace } from "../gl/CameraPlace"
 import { Node } from "../gl/Node"
 import { Mesh } from "../gl/Mesh"
 import { Model } from "../gl/Model"
-import { Physics } from "../gl/Physics"
+import { Physics } from "../gl/physics/Physics"
+import { CharacterController } from "../gl/physics/CharacterController"
 import { Lightmap } from "../gl/Lightmap"
-import { NavMesh } from "../gl/NavMesh"
-import { Terrain, type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/Terrain"
+import { NavMesh } from "../gl/nav/NavMesh"
+import { Terrain, type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/terrain/Terrain"
 import { Light, type SunOptions } from "../gl/Light"
 import { assignMaterialDef, MaterialHandle, resolveMaterialDef, type MaterialDef } from "./material"
-import type { CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
+import type { CapsuleOptions, CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
 import { GizmoBuffer, Gizmos, withGizmoScope, type GizmoBatch } from "./gizmos"
 
 // ---- the literal grammar (what the visual editor reads and writes) -----------
@@ -61,6 +62,7 @@ export type MeshDef =
   | { kind: "box", size?: Vec3Like | number }
   | ({ kind: "sphere" } & SphereOptions)
   | ({ kind: "cylinder" } & CylinderOptions)
+  | ({ kind: "capsule" } & CapsuleOptions)
   | ({ kind: "plane" } & PlaneOptions)
 
 export type LightDef = { kind: "sun" } & SunOptions
@@ -230,6 +232,10 @@ export type SceneLightmapDef = {
    *  ambient cube (2026-08-31) movers shade like the statics and the default is right; it stays as a
    *  trim. See `LightmapLoadOptions.volumeBoost`. */
   volumeBoost?: number
+  /** Occluder-only statics (props without lightmap UVs): `"baked"` (default) = their shadow is in the
+   *  atlas, they stop casting in real time and the shadow pass draws only the movers; `"realtime"` =
+   *  they keep casting (their shadow on other non-receiver props). See `LightmapLoadOptions.occluderShadows`. */
+  occluderShadows?: "baked" | "realtime"
 }
 
 /** `env.navmesh` — the level's navigation mesh (see navmesh.md): the file `lecodes navmesh bake`
@@ -402,6 +408,7 @@ const createMesh = async (def: MeshDef, material?: MaterialDef): Promise<Mesh> =
     case "box": mesh = Mesh.box({ size: def.size, material: mat }); break
     case "sphere": { const { kind: _k, ...opts } = def; mesh = Mesh.sphere({ ...opts, material: mat }); break }
     case "cylinder": { const { kind: _k, ...opts } = def; mesh = Mesh.cylinder({ ...opts, material: mat }); break }
+    case "capsule": { const { kind: _k, ...opts } = def; mesh = Mesh.capsule({ ...opts, material: mat }); break }
     case "plane": { const { kind: _k, ...opts } = def; mesh = Mesh.plane({ ...opts, material: mat }); break }
   }
   if (material instanceof MaterialHandle) material._users.add({ node: mesh, slot: 0 })
@@ -417,11 +424,15 @@ const createMesh = async (def: MeshDef, material?: MaterialDef): Promise<Mesh> =
 
 type LightmapCtx = { prefix: string, volume: boolean, dynamicOnly?: boolean }
 
+// A CharacterController moves its node as surely as a dynamic body does (2026-09-11: the hero's
+// capsule was read as static, so its sword baked a shadow into the terrain at the spawn point).
 const movesByPhysics = (def: SceneNodeDef): boolean =>
   (def.aspects ?? []).some((e) =>
-    (e.ctor as unknown) === Physics && ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") !== "static")
+    ((e.ctor as unknown) === Physics && ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") !== "static")
+    || (e.ctor as unknown) === CharacterController)
 
-/** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule). */
+/** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule).
+ *  Children of a mover are movers too — buildNodes carries that down, this is the node's own verdict. */
 export const isLightmapStatic = (def: SceneNodeDef): boolean => def.lightmap ?? !movesByPhysics(def)
 
 // `lightmap` undefined = Model.load's own default ('dynamic' while a level with a light volume runs —
@@ -860,7 +871,9 @@ const buildNodes = async (
 ): Promise<void> => {
   const pending: { path: string, node: Node, def: SceneNodeDef }[] = []
 
-  const build = async (name: string, nd: SceneNodeDef, parentNode: Node | null, parentPath: string): Promise<void> => {
+  // `parentMoves`: a child of a mover moves with it (the body under the hero's capsule) — it never
+  // bakes, whatever its own def says short of an explicit `lightmap: true`
+  const build = async (name: string, nd: SceneNodeDef, parentNode: Node | null, parentPath: string, parentMoves = false): Promise<void> => {
     // names are path segments — '/' would fork the path, ':' would ambiguate editor card keys
     if (name === "" || name.includes("/") || name.includes(":")) {
       throw new Error(`Scene node name "${name}" is invalid — names are non-empty and contain no '/' or ':'`)
@@ -868,7 +881,7 @@ const buildNodes = async (
     // the path is derived from def keys BEFORE any await, so it is deterministic even though
     // Promise.all makes build completion (and record insertion) order nondeterministic
     const path = parentPath === "" ? name : `${parentPath}/${name}`
-    const lmStatic = lm !== null && !lm.dynamicOnly && isLightmapStatic(nd)
+    const lmStatic = lm !== null && !lm.dynamicOnly && (nd.lightmap ?? (!parentMoves && isLightmapStatic(nd)))
     // a mover in a level with a light volume reads the volume (models: the engine binds it; meshes: registered below)
     const lmDynamic = lm !== null && !lmStatic && lm.volume
     const node = await createSource(path, nd, lmStatic ? true : lmDynamic ? "dynamic" : undefined)
@@ -886,7 +899,7 @@ const buildNodes = async (
     if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack, lmStatic ? { prefix: `${lm!.prefix}${path}/`, volume: lm!.volume } : lm && lm.volume ? { prefix: `${lm.prefix}${path}/`, volume: true, dynamicOnly: true } : null)
     pending.push({ path, node, def: nd })
     nodes[path] = node
-    await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node, path)))
+    await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node, path, parentMoves || (lm !== null && !lmStatic))))
   }
 
   await Promise.all(Object.entries(defs).map(([ name, nd ]) => build(name, nd, parent, "")))
@@ -983,7 +996,7 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   if (lm && lightmap) {
     await Lightmap.load(scene, { data: lightmap.data, texture: lightmap.texture, light: lightmap.light, volume: lightmap.volume },
       { sunStrength: lightmap.sunStrength, ambientScale: lightmap.ambientScale, aoStrength: lightmap.aoStrength,
-        lightBoost: lightmap.lightBoost, volumeBoost: lightmap.volumeBoost })
+        lightBoost: lightmap.lightBoost, volumeBoost: lightmap.volumeBoost, occluderShadows: lightmap.occluderShadows })
   }
   // navigation: load the baked mesh — or, under `lecodes navmesh bake`, dump the level's collision
   // geometry for it (the static bodies exist by now; edit mode never loads it — v1)
@@ -1117,6 +1130,9 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
       scene.add(node)
       applyNode(node, p.slice(p.lastIndexOf("/") + 1), d)
       if (isEditMode()) addEditorMarker(node, d)
+      // a prefab wrapper instantiates its file's nodes (same path as buildNodes; no lightmap
+      // context — a patched node is an edit-mode rebuild, baked lighting is the level's business)
+      if (d.prefab !== undefined) await attachPrefab(node, p, d, scene, new Set([ this.def ]), null)
       attachAspects(node, p, d, nodes, scene, this._editorRuns)
       nodes[p] = node
       await Promise.all(Object.entries(d.children ?? {}).map(([ cn, cd ]) => build(`${p}/${cn}`, cd, node)))

package/src/scene/level.ts

@@ -14,8 +14,8 @@
 
 import { Node } from "../gl/Node"
 import { Model } from "../gl/Model"
-import { Shape } from "../gl/Shape"
-import { Physics } from "../gl/Physics"
+import { Shape } from "../gl/physics/Shape"
+import { Physics } from "../gl/physics/Physics"
 import { cx, cy, cz, type Vec3Like } from "../math/vec"
 
 /** One placement handed to a `build` function (all coordinates local to the group). */

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

@@ -1,86 +0,0 @@
-import { Aspect } from "../core/Aspect";
-import type { FieldMeta } from "../core/fields";
-import type { Node } from "./Node";
-import type { Vehicle } from "./Vehicle";
-export declare 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[];
-    /** Reverse ratio — negative, because a ratio's SIGN is what reverse means to the engine. */
-    reverse: number;
-    /** Shift up when the engine passes this fraction of its redline. */
-    shiftUp: number;
-    /** Shift down when it falls below this fraction. */
-    shiftDown: number;
-    /** How long a shift takes, in seconds — the clutch is out for this long. */
-    shiftTime: number;
-    /** How long the clutch takes to re-engage afterwards. */
-    clutchTime: number;
-    /** How long to wait after a shift before another is allowed — without it a car sitting on a
-     *  threshold hunts between two gears. */
-    latency: number;
-    /** 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: number;
-    static fields: FieldMeta<Gearbox>;
-    /** Current gear: −1 reverse, 0 neutral, 1… forward. Read it for a HUD. */
-    gear: number;
-    /** True while a shift is in progress — the clutch is out and the engine is not driving the wheels. */
-    get shifting(): boolean;
-    private _shiftLeft;
-    private _engageLeft;
-    private _waitLeft;
-    private _take;
-    /** EARLY phase: the pair has to be latched before this frame's step consumes it. */
-    updateBefore(dt: number): void;
-    /**
-     * 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;
-    /**
-     * 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;
-    /** 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;
-    /** The ratio the engine should be running: 0 in neutral, negative in reverse. */
-    get ratio(): number;
-    /**
-     * 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;
-}

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;
-}