lecodes-sdk 0.20.0 → 1.0.0

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

@@ -1,6 +1,34 @@
 import { type FetchResponse } from "../runtime/fetch";
 import { Node } from "./Node";
 import { Animator, type LodMode } from "./animation/Animator";
+/** One polygon under a screen point — what `Model.pickTriangle` returns. `bones` are the vertex's raw
+ *  JOINTS_0 / WEIGHTS_0 pairs (weight > 0; empty = unweighted), `bind` its position in mesh space,
+ *  `world` its skinned position this frame. */
+export interface TrianglePick {
+    /** the Model's root entity, and the mesh node's own entity (0 when the host has no entity for it) */
+    entity: number;
+    node: number;
+    nodeName: string;
+    mesh: string;
+    primitive: number;
+    material: string;
+    /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
+    triangle: number;
+    backface: boolean;
+    distance: number;
+    point: [number, number, number];
+    bary: [number, number, number];
+    skin: string;
+    vertices: {
+        index: number;
+        bind: [number, number, number];
+        world: [number, number, number];
+        bones: {
+            name: string;
+            weight: number;
+        }[];
+    }[];
+}
 export declare class Model extends Node {
     /** The model's Animator — always present, its clip table = the GLB's embedded clips. Configure
      *  more (external clips, blend spaces, layers) with `model.aspect(Animator, {...})`. */
@@ -31,6 +59,12 @@ export declare class Model extends Node {
     get lod(): LodMode;
     set lod(v: LodMode);
     private static _cullDefault;
+    /** DEBUG: the closest polygon of this model under a screen point (logical px — `Input.mouse.position`,
+     *  a touch event's clientX/Y), tested against the CPU-skinned CURRENT pose, both faces. Names the
+     *  triangle, its three vertices (bind + skinned positions) and their raw bone weights, so a stretched
+     *  or misbound polygon can be traced to its binding. One full CPU skin of the model per call: click-rate
+     *  only. null = miss, or a host without the pick (desktop today). */
+    pickTriangle(screenX: number, screenY: number): TrianglePick | null;
     /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
      *  the same parent and scene and sharing this model's current transform. The clone has its own
      *  independent animation state (reach it via clone.anim). Mirrors this model's culling flag. */

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

@@ -116,6 +116,12 @@ type Noise = {
     strength?: number;
     frequency?: number;
     speed?: number;
+    /** How much of the displacement a particle earns with AGE (default 0 = all of it from birth).
+     *  The field is sampled by position, so at 0 every particle born at the same spot is pushed the
+     *  same way and a plume's root wanders off its emitter by up to `strength` metres; at 1 a particle
+     *  is born exactly where the emitter put it and drifts into the field over its life — what you
+     *  want whenever the source is visible (an exhaust pipe, a contact patch, a muzzle). */
+    ramp?: number;
 };
 /** Ground plane for bouncing particles (all render modes). `height` is in the simulation space:
  *  world y with `space: 'world'`, emitter-local y otherwise. */
@@ -169,6 +175,11 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
      *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
      *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
     order?: number;
+    /** Coarse draw order among ALL blended draws, 0 (first) … 7 (last) — see `Mesh.renderPriority`.
+     *  Default 5: meshes sit at 4 and decals at 3, so smoke covers a car's glass and its skid marks
+     *  whatever the camera does (the engine's depth sort compares object centres, and an emitter's
+     *  centre says nothing about where its cloud is). `order` breaks ties inside one priority. */
+    renderPriority?: number;
     shape?: Shape;
     /** Extra velocity over life (radial burst that decays, axis drift) — see `VelocityOverLife`. */
     velocityOverLife?: VelocityOverLife;
@@ -212,6 +223,8 @@ export declare class Particles extends Node {
     set inheritVelocity(val: number);
     set rateOverDistance(val: number);
     set order(val: number);
+    /** Coarse draw order, 0 … 7 — see `Mesh.renderPriority`. Write-only. */
+    set renderPriority(v: number);
     set velocityOverLife(v: VelocityOverLife);
     set shape(shape: Shape);
     /** (mesh mode) Replace the particle mesh; live particles keep flying as the new shape. */

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

@@ -4,6 +4,7 @@ import { Presentable, type PresentOptions } from "../ui/presentable";
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
 import type { FetchResponse } from "../runtime/fetch";
 import { Camera } from "./Camera";
+import { SceneAudio } from "./audio/SceneAudio";
 import { type ControlsHandle, type ControlsOptions } from "./controls";
 import { Material } from "./Material";
 import { Node } from "./Node";
@@ -95,6 +96,9 @@ export type SceneOptions = {
      *  takes over). Unset keeps the host default (desktop 4×, mobile/web off). The biggest single
      *  fill-rate cost after resolution — turn it down on big screens before anything else. */
     antialias?: boolean | 2 | 4;
+    /** Keep a stencil buffer for this scene (off by default: it costs memory and a clear per frame).
+     *  Needed before any material's `stencil` test or write does anything. */
+    stencil?: boolean;
     /** Render the 3D at this fraction of the viewport (0.25–1) and upscale; the UI stays at native
      *  resolution. A fixed, predictable cut of per-pixel GPU work — `0.75` is ~45 % cheaper and
      *  barely visible in motion, `0.5` quarters it. Headless renders ignore it. */
@@ -118,6 +122,10 @@ export type SceneOptions = {
      *  scene file — `env` is applied before the nodes build) and leaves already-loaded ones alone.
      *  On the desktop host `CREATOR_TEXTURE_ANISOTROPY` overrides it, for tuning without a rebuild. */
     anisotropy?: number;
+    /** Engine-wide cap on texture size, 0 / unset = none (see `Texture.maxSize`): a KTX2 above it
+     *  loses its top mip levels on load, a glTF image is downsampled. Applied before this scene's
+     *  assets load; like `anisotropy` it does not touch textures already loaded. */
+    maxTextureSize?: number;
     /** The look on an HDR display (a screen with headroom above SDR white — Apple XDR panels, the
      *  macOS host today); ignored on SDR. `strength` 0..1 is how much of the picture reaches for the
      *  display's headroom (0 only what SDR clipped, 1 nearly everything; default 0.35). `paperWhite`
@@ -132,6 +140,8 @@ export type SceneOptions = {
 };
 export declare class Scene implements Presentable {
     readonly camera: Camera;
+    /** The listener + global 3D audio knobs (docs/audio-plan.md). */
+    readonly audio: SceneAudio;
     readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node | null>) => void>;
     private _material?;
     private static _active;
@@ -153,6 +163,19 @@ export declare class Scene implements Presentable {
     setFog(options: FogOptions | false): void;
     setMaterialGlobalParameter(i: number, x: number, y: number, z: number, w: number): void;
     setAntialias(enabled: boolean, scale?: number): void;
+    /** Depth-reading effects on / off (a graphics-settings menu): soft particles and projected decals
+     *  read the scene depth, which costs a depth pre-pass of every opaque draw (~12 % of a fill-bound
+     *  frame). Off = hard-edged particles, no decals, no pre-pass. Engine-wide, live. */
+    setDepthEffects(enabled: boolean): void;
+    /** LOD distance (a graphics-settings menu): the engine's LOD thresholds × `bias`. 2 = every level
+     *  switches at half the distance (a model must look twice as big on screen to keep its detail),
+     *  0.5 = full detail twice as far, 1 = the defaults. Engine-wide, live. Only GLBs that carry
+     *  `_LOD<n>` meshes (`lecodes assets doctor --lod`) have levels to switch. */
+    setLodBias(bias: number): void;
+    /** Runtime form of `bloom` / `bloomIntensity` (a graphics-settings menu). */
+    setBloom(enabled: boolean, intensity?: number): void;
+    /** The scene's stencil buffer on / off (see `SceneOptions.stencil`). */
+    setStencil(enabled: boolean): void;
     add(...nodes: Node[]): this;
     remove(...nodes: Node[]): this;
     /** Attach (and configure) a system, or reconfigure it if already present. Returns the scene typed

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

@@ -1,5 +1,28 @@
 import { type FetchResponse, type File } from "../runtime/fetch";
+/** `Texture.load` options. */
+export type TextureLoadOptions = {
+    /** `true` (default): colour, stored sRGB. `false`: data (normal map, mask, heightmap) — kept linear. */
+    srgb?: boolean;
+    /** Ignore `Texture.maxSize` for this texture (a lightmap page, a lookup table). */
+    fullSize?: boolean;
+};
 export declare class Texture {
+    static _maxSize: number;
+    /** Engine-wide cap on texture size (a "texture quality" setting), 0 = none. A KTX2 wider or
+     *  taller than this loses its top mip levels on load (nothing resampled, less memory and
+     *  bandwidth), a glTF PNG/JPEG is downsampled. Reaches textures loaded AFTER it is set — a loaded
+     *  level keeps its textures — so set it up front (`SceneOptions.maxTextureSize`, or before the
+     *  level loads) and apply a menu change on the next level load. Lightmap pages are exempt
+     *  (`TextureLoadOptions.fullSize`). A host may pin it (desktop `CREATOR_TEXTURE_MAX_SIZE`). */
+    static _anisotropy: number;
+    /** Engine-wide anisotropic filtering, 1 (off) … 16 (default 2; `SceneOptions.anisotropy` sets it up
+     *  front). A sampler is baked when its texture is bound, so like `maxSize` this reaches textures
+     *  loaded AFTER it — set it before the level loads. Measured on a lightmapped interior at 720p:
+     *  4× costs ~20 % of the frame over 1× on an integrated GPU. A host may pin it. */
+    static get anisotropy(): number;
+    static set anisotropy(level: number);
+    static get maxSize(): number;
+    static set maxSize(size: number);
     readonly width: number;
     readonly height: number;
     /** Horizontal wrap mode (U). */
@@ -23,5 +46,10 @@ export declare class Texture {
     }): 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>;
+    /** Decode an image (PNG / JPG, or a KTX2 the core transcodes) into a texture. `srgb` (default
+     *  true) says the bytes are COLOUR, stored sRGB so the GPU linearises them on sample; pass
+     *  `false` for DATA — a normal map, a mask, a heightmap — which must come back as stored (a
+     *  flat normal read through sRGB bends by ~35°). A KTX2 decides by its own header. Image
+     *  textures get a mip chain (trilinear) on hosts that build one. */
+    static load(source: string | FetchResponse | File, options?: TextureLoadOptions): Promise<Texture>;
 }

package/dist/types/gl/animation/AnimationClip.d.ts

@@ -22,6 +22,19 @@ export type ClipInfo = {
     duration: number;
     trackCount: number;
 };
+/** What `AnimationClip.from(clip, …)` derives from a clip. */
+export type DeriveOptions = {
+    /** The clip MIRRORED — left ↔ right, the motion on the other side of the body (a stop that brakes on the
+     *  left foot brakes on the right). Derived on the rig of the clip's own file (joints pair by name, the
+     *  sagittal plane comes from the rest pose), so the result is the same on every model: its contacts,
+     *  phase, root motion and heading are the mirrored ones, its name is `<name>_M`. Only clips from a GLB
+     *  carry a rig; a curve-built clip cannot be mirrored. */
+    mirror?: boolean;
+    /** Start of the window, seconds of the source (default 0). */
+    from?: number;
+    /** End of the window, seconds of the source (default the clip's end). */
+    to?: 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. */
@@ -33,8 +46,8 @@ export declare class AnimationClip {
     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. */
+     *  Events are part of the clip: every model playing it gets them; `AnimationClip.from(clip, { from, to })`
+     *  keeps the ones inside the window, 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. */
@@ -43,18 +56,18 @@ export declare class AnimationClip {
     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:
+    static fromCurves(def: ClipDef): AnimationClip;
+    /** A NEW clip derived from `clip`: its mirror (`{ mirror: true }` — the other side of the body), a window
+     *  of it (`{ from, to }` seconds of the source, re-timed to 0; array-slice semantics), or both. Cut a
+     *  too-long take down to the action, carve several sub-clips out of one packed timeline, get the
+     *  left-footed stop from the right-footed one:
      *
-     *    clips: { Kick: kick.slice(0.2, 1.1) }
+     *    clips: { Kick: AnimationClip.from(kick, { from: 0.2, to: 1.1 }), StopM: AnimationClip.from(stop, { mirror: true }) }
      *
-     *  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;
+     *  A window drops the keys outside it and interpolates exact boundary values in, so the clip starts and
+     *  ends precisely on the source's pose at the cut points. Everything downstream (blend spaces, events'
+     *  times, root motion, foot contacts, phase sync) sees a normal clip. */
+    static from(clip: AnimationClip, options: DeriveOptions): AnimationClip;
     private static _label;
     private static _loadSet;
 }

package/dist/types/gl/animation/DynamicBone.d.ts

@@ -0,0 +1,173 @@
+import { Aspect } from "../../core/Aspect";
+import type { FieldMeta } from "../../core/fields";
+import { Vec3, type Vec3Like } from "../../math/vec";
+import { Node } from "../Node";
+/** One value for the chain, or `[root, tip]` interpolated down it by depth. */
+export type DynamicBoneCurve = number | readonly [root: number, tip: number];
+/** `'none'`, `'probe'` (a ray from the chain root down against the physics world, every frame), a
+ *  height (a horizontal plane at that world y) or a world point (a plane through it, `floorNormal` up). */
+export type DynamicBoneFloor = "none" | "probe" | number | Vec3Like;
+/** `'auto'` = every DynamicBoneCollider under the model; `'humanoid'` = those plus capsules generated
+ *  on the standard humanoid bones (hips, spine, head, limbs — the Ragdoll's layout); `'none'`; or the
+ *  nodes carrying the colliders to use. */
+export type DynamicBoneColliders = "auto" | "humanoid" | "none" | Node[];
+/** The cloth's OUTSIDE, which makes every collider one-sided: `'none'` = a collider pushes a bone to its
+ *  nearest surface (tails, ropes); `'auto'` = away from the root bone's own axis (a cloak's strips round a
+ *  spine face out from it); a vector = a fixed direction in the root bone's frame (a cape on the back:
+ *  `[0, 0, -1]`). With a side the body is under the cloth by definition: an arm that swung through the
+ *  cape pushes it away, and a bone that ended up inside a capsule leaves it on the outside — never
+ *  through it to be held against the chest from the wrong side. */
+export type DynamicBoneSide = "none" | "auto" | Vec3Like;
+/** A capsule (or a sphere) riding a bone — what dynamic bones stay out of. Attach to a body bone:
+ *  `hips.aspect(DynamicBoneCollider, { radius: 0.12, to: 'Spine' })`. The capsule runs from
+ *  `offset` (the bone's origin by default) to the `to` bone's origin, or to `end` (both in the bone's
+ *  local space); neither = a sphere at `offset`. Picked up by every DynamicBone on the same model
+ *  with `colliders: 'auto'` / `'humanoid'`, or listed explicitly. */
+export declare class DynamicBoneCollider extends Aspect<"dynamicBoneCollider", Node> {
+    static readonly aspect = "dynamicBoneCollider";
+    /** Radius in metres, in the world: the bone's scale does not touch it (`offset` / `end` are in the bone's own units). */
+    radius: number;
+    /** Start of the capsule in the bone's local space (default: the bone's origin). */
+    offset: Vec3Like;
+    /** End of the capsule in the bone's local space (a sphere when neither `end` nor `to` is set). */
+    end?: Vec3Like;
+    /** The bone the capsule reaches (its origin), instead of `end`. */
+    to?: string;
+    static fields: FieldMeta<DynamicBoneCollider>;
+    private _id;
+    private _segment;
+    onAttach(): void;
+    onReconfigure(): void;
+    onDetach(): void;
+}
+export declare class DynamicBone extends Aspect<"dynamicBone", Node> {
+    static readonly aspect = "dynamicBone";
+    /** Only these bones (by name) join the chain — the root always does, a bone left out takes its
+     *  subtree with it. Default: the root's whole subtree. */
+    bones?: string[];
+    /** Depth limit under the root (0 = no limit). */
+    depth: number;
+    /** Particle radius for the collisions, metres. */
+    radius: DynamicBoneCurve;
+    /** 0..1 — how fast a bone returns to the animated shape (per 1/60 s). 0 = a rope, 1 = rigid. */
+    stiffness: DynamicBoneCurve;
+    /** 0..1 — velocity lost per 1/60 s. 0.02 swings like a rope, 0.1 settles like a tail, 0.3 is honey. */
+    damping: DynamicBoneCurve;
+    /** m/s² downward. A hanging rest pose feels none of it (the bone length cancels it); a pose that
+     *  sticks out droops by as much as `stiffness` lets it. */
+    gravity: DynamicBoneCurve;
+    /** Max deviation from the animated direction, degrees per bone (0 = free). */
+    angleLimit: DynamicBoneCurve;
+    /** Relative mass per bone. A bone-length constraint moves its two ends in inverse proportion to
+     *  their masses (the root is kinematic): `[3, 1]` makes a tail's base carry its tip, `1` shares
+     *  evenly like a rope. */
+    mass: DynamicBoneCurve;
+    /** Bones (by name) that ride the animation exactly while their subtrees still simulate: a sheet's
+     *  several roots under one anchor (a cloak's seven strips under the spine), so ONE chain owns them all
+     *  and `link` ties neighbouring strips. */
+    pinned?: string[];
+    /** Metres a PINNED bone may be pushed off its animated place by a collider — a soft pin. Its particle
+     *  collides and takes the edge pushes like a free bone (the strip below hangs from where it IS) and is
+     *  drawn back to the animation when the collider leaves; the bone's local translation follows. A hard
+     *  pin (0) at a capsule's edge made the first free bone below it jitter: the edge push on a segment
+     *  with an immovable end is a lever, and a touch near the root threw the child out. 2–3 cm for a
+     *  cloak's roots under a shoulder capsule. */
+    pinGive: number;
+    /** 0..1 of the character's travel the chain takes rigidly (0 = the full whip on a dash, 1 = it
+     *  moves with the body and only the pose's own motion swings it). */
+    follow: number;
+    /** World wind, m/s². */
+    wind: Vec3Like;
+    /** The BODY'S TURN, ≥ 0. Above 0 the chain lives in the parent bone's ROTATING frame: `damping` acts
+     *  against the body's rigid motion (its travel plus its spin), so a heavily damped cloak RIDES a turn —
+     *  sweeps round with the back — instead of standing in the world while the character spins under it and
+     *  being dragged round after. The turn's inertia comes back as the frame's forces, scaled by this value:
+     *  a centrifugal push `ω² · r` along each bone's animated direction from the axis (the hem, farthest
+     *  from the spine, flies out and, on the chain's length, up). The frame's own physics is built in: the
+     *  whip back when the turn starts and forward when it stops, Coriolis. 1 = the physical push; more = a
+     *  bigger fling. With low damping the frame reproduces a free particle (nothing is counted twice);
+     *  an animation's spine sway is ~1 % of a 900°/s turn. A rotation over 90° in one frame (a respawn
+     *  facing) counts as a snap, not a spin. 0 = the plain translational frame, no turn forces. */
+    spin: number;
+    /** With `spin`: the cloth's INERTIA against the body's turn, seconds — the cloth's own rotation follows the
+     *  body's with this time constant. It falls behind when a turn starts (by about ω·τ: 45° at 900°/s and 0.05),
+     *  rides once caught up, and keeps turning past the back when the body stops (the same angle, eased out over
+     *  τ). Smooth by construction. 0 = glued to the turn; large = the cloth stays in the world while the body spins. */
+    spinInertia: number;
+    /** 0..1 strength of the ties between neighbouring columns at the same depth (a cloak). */
+    link: number;
+    /** 0..1 blend from the animation (0) to the simulation (1). At 0 nothing is simulated and the
+     *  chain re-arms on the animated pose when it comes back. */
+    weight: number;
+    /** Substep rate, Hz (≤ 4 substeps per frame). */
+    rate: number;
+    /** A root jump longer than this in one frame (metres) resets the chain instead of whipping it. */
+    teleport: number;
+    /** What the particles stay above: `'none'`, `'probe'`, a height, or a world point. */
+    floor: DynamicBoneFloor;
+    /** The floor plane's normal when `floor` is a point. */
+    floorNormal: Vec3Like;
+    /** Friction against the floor, a Coulomb coefficient: a resting bone's slide loses up to
+     *  `floorFriction · gravity · dt` of speed per substep (0 = ice, 1 = a rubber sole). While a bone
+     *  rests on the floor or a collider, `stiffness` and `angleLimit` let go of it: the surface's
+     *  reaction outranks the spring, or a hem folded on the floor would run away along it. */
+    floorFriction: number;
+    /** Constraint passes per substep (1..8, default 4). Each pass shares every bone length between its
+     *  ends, so a pull needs passes to travel down a long chain: a long rope may want 8, a short tail is
+     *  fine with 2. */
+    iterations: number;
+    /** What the chain collides with (see DynamicBoneColliders). */
+    colliders: DynamicBoneColliders;
+    /** The cloth's outside — makes the colliders one-sided (see DynamicBoneSide). */
+    side: DynamicBoneSide;
+    /** How firmly `guide()` targets are HELD through the constraint passes, 0..1. At 0 a guide is applied once
+     *  before the passes and the length / link passes may drag the bone back toward its un-guided neighbours
+     *  within the same frame; at 0.5 it is re-pulled after every pass with half its weight (converges with the
+     *  passes), at 1 with its full weight (a target the bone length cannot reach then jitters). */
+    guideHold: number;
+    /** The chain's EDGES collide with the capsules too — every bone segment and every link, not only the bones'
+     *  particles: a capsule thinner than a bone's length (a forearm) no longer passes through the cloth between
+     *  two bones. Off = particles only. */
+    edges: boolean;
+    static fields: FieldMeta<DynamicBone>;
+    private _id;
+    private _chain;
+    private _depths;
+    private _blob;
+    private _sent;
+    private _floorKey;
+    private _colliderKey;
+    private _collidersDirty;
+    private _collidersRef;
+    private _own;
+    private _colliderSet;
+    /** The bones of the chain, the root first. */
+    get chain(): readonly Node[];
+    onAttach(): void;
+    onReconfigure(): void;
+    /** Every field is live: what changed since the last frame is pushed here, before the engine's stage. */
+    update(): void;
+    onDetach(): void;
+    /** Snap the chain onto the animated pose next frame (a teleport, a camera cut). */
+    reset(): void;
+    /** GUIDES: world points the bones' particles are drawn to each substep before the constraints —
+     *  weight 1 = there before them, the rest of the chain hangs, collides and links as before (a cape's
+     *  strips riding the arms). Replaces the previous set; an empty list clears. A late-phase script
+     *  (after the animator, before the engine's chain stage) refreshes it every frame. */
+    guide(rows: readonly {
+        bone: Node;
+        at: Vec3Like;
+        weight: number;
+    }[]): void;
+    /** The particles' world positions (the bones, then the leaves' virtual tips) — for a debug draw. */
+    get particles(): Vec3[];
+    private _collect;
+    private _fill;
+    /** Neighbour links: the bones at the same depth, in tree order, tied pairwise. */
+    private _links;
+    private _sync;
+    private _pushFloor;
+    private _pushColliders;
+    /** Capsules on the standard humanoid bones, sized like the Ragdoll's parts. */
+    private _makeHumanoid;
+}

package/dist/types/gl/{IK.d.ts → animation/IK.d.ts}

@@ -1,7 +1,7 @@
-import { Aspect } from "../core/Aspect";
-import { type Vec3Like } from "../math/vec";
-import { Quat } from "../math/quat";
-import type { Node } from "./Node";
+import { Aspect } from "../../core/Aspect";
+import { type Vec3Like } from "../../math/vec";
+import { Quat } from "../../math/quat";
+import type { Node } from "../Node";
 type Target = Node | Vec3Like;
 /** Two-bone analytic IK (limbs). Attach to the END bone: `foot.aspect(IK.TwoBone, { target })`
  *  solves upper (grandparent) + mid (parent) so the end reaches `target`; `pole` steers the bend

package/dist/types/gl/{Locomotion.d.ts → animation/Locomotion.d.ts}

@@ -1,9 +1,9 @@
-import { Aspect } from "../core/Aspect";
-import { Vec3, type Vec3Like } from "../math/vec";
-import { Animator } from "./animation/Animator";
-import type { FeetOptions } from "./animation/Feet";
-import type { WarpOptions } from "./animation/Warp";
-import type { Node } from "./Node";
+import { Aspect } from "../../core/Aspect";
+import { Vec3, type Vec3Like } from "../../math/vec";
+import { Animator } from "./Animator";
+import type { FeetOptions } from "./Feet";
+import type { WarpOptions } from "./Warp";
+import type { Node } from "../Node";
 /** How fast the character wants to go: the gait picks its clips and its speed. */
 export type Gait = "walk" | "run" | "sprint";
 /** What the engine shows: the idle, a start, the gait loop, a turn while moving, a stop, or a turn on the spot. */

package/dist/types/gl/animation/core.d.ts

@@ -6,18 +6,17 @@ import { Vec3 } from "../../math/vec";
 import type { Node } from "../Node";
 /** A position on a blend axis (1D) or plane (2D). */
 export type BlendPosition = number | readonly [number, number];
-/** The transition time (seconds) a play / playLoop without `fade` uses. */
-export declare const DEFAULT_FADE = 0.2;
 export type PlayOptions = {
-    /** Transition seconds — how long the difference to the pose the layer SHOWED takes to decay
-     *  (default 0.2; `0` = cut). Also the transition back at the end unless `fadeOut` overrides it. */
+    /** Transition seconds — how long the difference to the pose the layer SHOWED (its loop, a one-shot,
+     *  or rest) takes to decay. Default `0` = cut: a fade is always asked for, never implied. Also the
+     *  transition back to the loop at the end unless `fadeOut` overrides it. */
     fade?: number;
     /** Transition seconds for the way in only (overrides `fade`). */
     fadeIn?: number;
-    /** One-shots: the transition BACK at the end (overrides `fade`). It starts this long before the
-     *  clip ends — while it still plays — so the hand-over lands on the last pose, not after it. On a
-     *  layer with no loop to return to, giving `fadeOut` releases the layer at the end instead of
-     *  holding the last frame. */
+    /** One-shots: the transition BACK to the loop at the end (overrides `fade`; `0` = cut at the end).
+     *  It starts this long before the clip ends — while it still plays — so the hand-over lands on the
+     *  last pose, not after it. On a layer with no loop the clip HOLDS its last frame (a rock that broke
+     *  stays broken) — `anim.stop({ fade })` is the way back to rest. */
     fadeOut?: number;
     /** Playback rate for this clip (default 1). */
     speed?: number;
@@ -39,8 +38,8 @@ export type StopOptions = {
     fade?: number;
 };
 export type LoopOptions = {
-    /** Transition seconds from whatever the layer shows — its previous loop, or a one-shot still
-     *  playing (default 0.2; `0` = cut). */
+    /** Transition seconds from whatever the layer shows — its previous loop, a one-shot still playing,
+     *  or rest. Default `0` = cut: a loop wanting a transition asks for one (`{ fade: 0.2 }`). */
     fade?: number;
     /** Playback rate of the loop's clips (default 1). */
     speed?: number;
@@ -165,6 +164,12 @@ export type ClipInfo = {
     turnAt(time: number): number;
     /** the root's own speed at `time`, m/s — how fast the clip is moving the body right there */
     speedAt(time: number): number;
+    /** the PELVIS' yaw relative to the clip's heading at `time` (rad, + = left, wrapped to ±π): the stance twist
+     *  the heading leaves out — an idle stands ~43° off the course it starts along, a stop's tail turns into that
+     *  stance while the heading holds. A controller that switches clips mid-pose can keep the PELVIS continuous
+     *  (turn the node by the difference between the two clips' values) where keeping the course would swing
+     *  the body. Without a baked heading: the pelvis' yaw at frame 0 throughout. */
+    pelvisYawAt(time: number): number;
     /** the unit travel direction at `time` ([x, z], model space, held through stills) — integrate
      *  direction × d(travel) to reconstruct the root's 2D path (a treadmill display, a turn's arc) */
     directionAt(time: number): [number, number];

package/dist/types/gl/audio/AudioSource.d.ts

@@ -0,0 +1,60 @@
+import { Aspect } from "../../core/Aspect";
+import type { FieldMeta } from "../../core/fields";
+import { type PlaySoundOptions, type Rolloff } from "../../audio/audio";
+import type { Sound } from "../../audio/Sound";
+import type { Voice } from "../../audio/Voice";
+import type { Node } from "../Node";
+export type AudioCone = {
+    /** Degrees of full volume around the node's −Z. */
+    inner: number;
+    /** Degrees where the volume has fallen to `outerGain`. */
+    outer: number;
+    /** Volume behind the source, 0 … 1. */
+    outerGain?: number;
+};
+export declare class AudioSource extends Aspect<"audio", Node> {
+    static readonly aspect = "audio";
+    static fields: FieldMeta<AudioSource>;
+    private _minDistance;
+    private _maxDistance;
+    private _rolloff;
+    private _cone;
+    private _doppler;
+    private _spread;
+    private _occlusion;
+    private _bus;
+    /** Metres of full volume around the node. Default 1. */
+    get minDistance(): number;
+    set minDistance(v: number);
+    /** Metres beyond which the source no longer gets quieter. Default 50. */
+    get maxDistance(): number;
+    set maxDistance(v: number);
+    /** `inverse` (default), `linear`, `exponential`, `none`. */
+    get rolloff(): Rolloff;
+    set rolloff(v: Rolloff);
+    /** Directional source along the node's −Z; null = omnidirectional (default). */
+    get cone(): AudioCone | null;
+    set cone(v: AudioCone | null);
+    /** Doppler amount 0 … 1 (0 = off, the default) — needs the node to actually move. */
+    get doppler(): number;
+    set doppler(v: number);
+    /** 0 = pin-point panning (default) … 1 = the same on every speaker (a big, close source). */
+    get spread(): number;
+    set spread(v: number);
+    /** The engine raycasts listener → source (against solid bodies) and muffles the voices when
+     *  something is in the way. Default false. */
+    get occlusion(): boolean;
+    set occlusion(v: boolean);
+    /** Default bus for voices on this source. Default `sfx`. */
+    get bus(): string;
+    set bus(v: string);
+    /** Live voices on this source. */
+    get voices(): number;
+    onAttach(): void;
+    onDetach(): void;
+    /** Play a clip from this node. */
+    play(sound: Sound, options?: PlaySoundOptions): Voice;
+    /** Stop every voice on this source (fade in seconds). */
+    stopAll(fade?: number): void;
+    private _push;
+}

package/dist/types/gl/audio/AudioZone.d.ts

@@ -0,0 +1,32 @@
+import { Aspect } from "../../core/Aspect";
+import { type ReverbParams, type ReverbPreset } from "../../audio/Bus";
+import { type Vec3Like } from "../../math/vec";
+import type { Node } from "../Node";
+export declare class AudioZone extends Aspect<"audioZone", Node> {
+    static readonly aspect = "audioZone";
+    private _box;
+    private _sphere;
+    private _reverb;
+    private _blend;
+    private _bus;
+    /** The engine's zone id — what `audio.stats.listenerZone` reports while the listener is inside. */
+    get id(): number;
+    /** Half-extents [hx, hy, hz]; falls back to the node's Shape box, then a 1 m cube. */
+    get box(): Vec3Like | null;
+    set box(v: Vec3Like | null);
+    /** Radius; falls back to the node's Shape sphere. */
+    get sphere(): number | null;
+    set sphere(v: number | null);
+    /** A preset name or explicit params (see Bus.reverb). */
+    get reverb(): ReverbPreset | ReverbParams;
+    set reverb(v: ReverbPreset | ReverbParams);
+    /** Crossfade depth in metres inside the border (0 = a hard edge). Default 1. */
+    get blend(): number;
+    set blend(v: number);
+    /** The bus the zone's reverb rides on. Default `sfx`. */
+    get bus(): string;
+    set bus(v: string);
+    onAttach(): void;
+    onDetach(): void;
+    private _push;
+}

package/dist/types/gl/audio/SceneAudio.d.ts

@@ -0,0 +1,11 @@
+import type { Node } from "../Node";
+export declare class SceneAudio {
+    private _listener;
+    private _doppler;
+    /** The node the engine listens from; null (default) = the active camera. */
+    get listener(): Node | null;
+    set listener(node: Node | null);
+    /** Multiplies every source's doppler amount (0 = off everywhere). Default 1. */
+    get dopplerFactor(): number;
+    set dopplerFactor(v: number);
+}

package/dist/types/gl/{NavAgent.d.ts → nav/NavAgent.d.ts}

@@ -1,8 +1,8 @@
-import { Aspect } from "../core/Aspect";
-import type { FieldMeta } from "../core/fields";
-import { Vec3, type Vec3Like } from "../math/vec";
+import { Aspect } from "../../core/Aspect";
+import type { FieldMeta } from "../../core/fields";
+import { Vec3, type Vec3Like } from "../../math/vec";
 import { NavCrowd } from "./NavMesh";
-import type { Node } from "./Node";
+import type { Node } from "../Node";
 export type NavAgentState = "idle" | "moving" | "arrived" | "blocked" | "offmesh";
 export type NavAgentAvoidance = "off" | "low" | "medium" | "high";
 export type NavAgentDrive = "position" | "controller";

package/dist/types/gl/{NavMesh.d.ts → nav/NavMesh.d.ts}

@@ -1,7 +1,7 @@
-import { System } from "../core/Aspect";
-import { Vec3, type Vec3Like } from "../math/vec";
-import type { Node } from "./Node";
-import type { Scene } from "./Scene";
+import { System } from "../../core/Aspect";
+import { Vec3, type Vec3Like } from "../../math/vec";
+import type { Node } from "../Node";
+import type { Scene } from "../Scene";
 export declare const NAV_AGENT: {
     readonly RADIUS: 0;
     readonly HEIGHT: 1;