lecodes-sdk 0.19.2 → 0.20.2

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

@@ -1,6 +1,8 @@
 import { Aspect } from "../core/Aspect";
 import { Vec3, type Vec3Like } from "../math/vec";
-import { Animator, type FeetOptions, type WarpOptions } from "./animation/Animator";
+import { Animator } from "./animation/Animator";
+import type { FeetOptions } from "./animation/Feet";
+import type { WarpOptions } from "./animation/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";

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

@@ -7,8 +7,47 @@ export type MaterialColorOptions = {
     color?: ColorInput;
     map?: Texture | Canvas | null;
 };
+/** How a stencil test / write on a material compares and what it writes. `test` runs against the
+ *  scene's stencil buffer (`Scene.stencil` must be on); the ops say what the buffer gets when the
+ *  fragment passes / fails the stencil test / fails the depth test (`replace` writes `ref`). */
+export type StencilTest = "always" | "never" | "less" | "lessEqual" | "greater" | "greaterEqual" | "equal" | "notEqual";
+export type StencilOp = "keep" | "zero" | "replace" | "increment" | "decrement" | "invert";
+export type MaterialStencil = {
+    /** Write the stencil buffer at all. Default `false`. */
+    write?: boolean;
+    /** The reference value, 0..255. Default 0. */
+    ref?: number;
+    /** Default `"always"`. */
+    test?: StencilTest;
+    onPass?: StencilOp;
+    onFail?: StencilOp;
+    onDepthFail?: StencilOp;
+    readMask?: number;
+    writeMask?: number;
+};
+/** Render state a material instance can override at run time (Filament keeps the defaults in the
+ *  shader package; these are per-instance overrides on top). */
+export type MaterialStateOptions = {
+    /** Test against the scene's depth buffer. `false` draws over everything already drawn — an
+     *  editor gizmo, a marker that must never hide behind a wall. Pair it with a high
+     *  `Mesh.renderPriority` so nothing drawn later covers it. Default `true`. */
+    depthTest?: boolean;
+    /** Write to the depth buffer. Leave it on for something drawn over the scene whose own parts must
+     *  still occlude each other (a gizmo's cone in front of its shaft). Unset = the shader's default
+     *  (on for opaque, off for a blended one). */
+    depthWrite?: boolean;
+    /** Draw both faces (no back-face culling): a plane seen from behind, a ribbon, cloth, a flat
+     *  marker. Default `false` = the shader's culling (back faces dropped). */
+    doubleSided?: boolean;
+    /** A stencil test / write for this material — see `MaterialStencil`. The selection-outline
+     *  recipe: the object writes `{ write: true, ref: 1, onPass: "replace" }`, and a slightly larger
+     *  copy of it draws with `{ test: "notEqual", ref: 1 }` + `depthTest: false` in `renderPriority` 7. */
+    stencil?: MaterialStencil;
+};
+/** @deprecated the name before doubleSided / stencil joined it — the same type */
+export type MaterialDepthOptions = MaterialStateOptions;
 /** `Material.unlit` options. */
-export type UnlitMaterialOptions = MaterialColorOptions & {
+export type UnlitMaterialOptions = MaterialColorOptions & MaterialStateOptions & {
     /** Alpha-blend this material instead of drawing it opaque. Opaque is the default: a blended draw
      *  writes no depth, is sorted back-to-front and casts no shadow, which is rarely what a flat
      *  colour wants. Turn it on for anything that must show what is behind it — a glass pane, a
@@ -16,6 +55,26 @@ export type UnlitMaterialOptions = MaterialColorOptions & {
      *  (`"#ffffff80"`) mean anything; the opaque material has no alpha channel at all. */
     transparent?: boolean;
 };
+/** `Material.decal` options — the projected-decal material a `DecalSet` draws with. */
+export type DecalMaterialOptions = {
+    /** The atlas (a `DecalSet`'s `sheet` cuts it into cells). */
+    map?: Texture;
+    /** A tangent-space normal atlas (same cell grid; +X = the image's right, +Y = its top; LINEAR —
+     *  `Texture.fromPixels(…, { srgb: false })`). Turns the decal into a RELIEF decal: instead of
+     *  painting a colour it bends the surface's lighting, so a footprint or a dent shows on any
+     *  surface without a colour of its own. With `map` too, the colour multiplies in (a crater
+     *  darkens by the map's alpha). The sun term applies in shadow as well (no shadow read). */
+    normalMap?: Texture;
+    /** Relief strength — the normal map's xy scale. Default 1. */
+    bump?: number;
+    /** Soft fraction (0..1) of the box's half depth at both ends. Default 0.3. */
+    edge?: number;
+    /** Cosine of the surface angle past which the decal fades (0.3 ≈ 72°); 0 = project onto
+     *  anything. Default 0.3. */
+    angleFade?: number;
+    /** HDR boost of the image (0 = none). */
+    emissive?: number;
+};
 /** `Material.particles` options — the default point-sprite material for particle systems. */
 export type ParticlesMaterialOptions = {
     /** Sprite texture — a single image or a flipbook sheet of frames. Unset = soft round dot. */
@@ -54,12 +113,14 @@ export type ParticlesMaterialOptions = {
     stretch?: number;
 };
 /** `Material.lit` options — PBR scalars on top of the color/map pair. */
-export type LitMaterialOptions = MaterialColorOptions & {
+export type LitMaterialOptions = MaterialColorOptions & MaterialStateOptions & {
     /** Perceptual roughness, 0 (mirror) … 1 (matte). Unset = the shader's default. */
     roughness?: number;
     /** Metallic factor, 0 (dielectric) … 1 (metal). Unset = the shader's default. */
     metallic?: number;
 };
+/** `Material.lightmapShading` tiers — see the setter. */
+export type LightmapShading = "full" | "baked" | "baked-lite";
 export declare class Material {
     readonly shader: FetchResponse | "unknown";
     readonly uniforms: Record<string, UniformValue>;
@@ -68,6 +129,15 @@ export declare class Material {
     /** Set a uniform (chainable). */
     set(key: string, value: UniformValue): this;
     set color(c: ColorInput);
+    /** Depth test against the scene (write-only; see `MaterialDepthOptions`). A host that predates
+     *  the call leaves the material as the shader has it. */
+    set depthTest(on: boolean);
+    /** Depth write (write-only; see `MaterialStateOptions`). */
+    set depthWrite(on: boolean);
+    /** Both faces drawn (write-only; see `MaterialStateOptions`). */
+    set doubleSided(on: boolean);
+    /** The stencil test / write (write-only; `null` = back to none). See `MaterialStencil`. */
+    set stencil(s: MaterialStencil | null);
     set map(value: Texture | Canvas | null);
     /** PBR lit material. */
     static lit(options?: LitMaterialOptions): Material;
@@ -77,6 +147,10 @@ export declare class Material {
      *  driven by the particle curves. Uniforms all default to 0 on a fresh instance, so every look
      *  knob is primed here; JS writes after construction override them. */
     static particles(options?: ParticlesMaterialOptions): Material;
+    /** Projected-decal material (`DecalSet`): samples the atlas where the decal's box meets the opaque
+     *  scene behind it. Blended, no depth write, no shadows — the engine keeps the scene depth bound
+     *  while a set with live decals is on screen. */
+    static decal(options?: DecalMaterialOptions): Material;
     /** Material that samples a VideoPlayer's texture. */
     static video(map?: Texture): Material;
     /** The lightmap material (docs/lightmap-plan.md): PBR base colour × a baked shadow/AO atlas on UV1.
@@ -92,6 +166,16 @@ export declare class Material {
      *  unset layer is white and an unbaked terrain is fully lit. */
     static terrain(): Material;
     private static _lmTemplate;
+    static _lightmapShading: LightmapShading;
+    /** Which shader lightmapped models take — a graphics-quality tier, engine-wide. `"full"` is filament's
+     *  lit path over the baked atlas (IBL specular, real-time point lights such as a muzzle flash, sun
+     *  shadows on dynamic objects). `"baked"` keeps the baked light and an approximated ambient but drops
+     *  the lit path: ~40 % cheaper per pixel on a fill-bound GPU. `"baked-lite"` is that minus the normal,
+     *  metallic/roughness and occlusion map reads (the factors stand in, the atlas keeps the baked AO;
+     *  emissive still glows): +20 % more at 1080p on the same GPU. Read when a lightmapped model LOADS, so set
+     *  it before the level (a settings menu applies it on the next level load), like `Texture.maxSize`. */
+    static get lightmapShading(): LightmapShading;
+    static set lightmapShading(mode: LightmapShading);
     /** Shadow-catcher material (transparent except where shadows fall). */
     static shadow(color?: ColorInput): Material;
     /** Load a custom compiled shader (.mat URL) as a material. */

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

@@ -11,15 +11,26 @@ export type MeshOptions = {
     name?: string;
     castShadows?: boolean;
     receiveShadows?: boolean;
+    /** Coarse draw order, 0 (first) … 7 (last); default 4. See `Mesh.renderPriority`. */
+    renderPriority?: number;
 };
 export declare class Mesh extends Node {
     private _geometry?;
     constructor(geometry?: Geometry, material?: Material);
     get geometry(): Geometry | undefined;
+    /** Replace the geometry in place — the node, its transform and its material stay, the vertex and
+     *  index buffers are rebuilt. What an editor overlay or a debug drawer redraws with. */
+    setGeometry(geometry: Geometry): this;
     /** A Mesh always carries a material (slot 0) — see Node.setMaterial for the slot API. */
     get material(): Material;
     set material(m: Material);
     set culling(v: boolean);
+    /** Coarse draw order within the frame: 0 draws first, 7 last, 4 is the default (Filament's
+     *  renderable priority; within one priority opaque draws sort front-to-back, blended back-to-front).
+     *  Something drawn over the scene with `Material.depthTest = false` goes in 7, so nothing drawn
+     *  after it can cover it. Write-only; a host that predates the call ignores it. */
+    set renderPriority(v: number);
+    private static _warnedPriority;
     set castShadows(v: boolean);
     set receiveShadows(v: boolean);
     static box(options?: MeshOptions & {

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 "./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/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/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/Animator.d.ts

@@ -1,219 +1,87 @@
 import { Aspect } from "../../core/Aspect";
-import { Vec3 } from "../../math/vec";
 import type { Node } from "../Node";
 import type { AnimationClip } from "./AnimationClip";
-import { type ActiveClip, type ClipCurves, type ClipEventHandler, type KneeAxisReport, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StepHandler, type StopOptions } from "./core";
+import { type ActiveClip, type ClipInfo, type ClipEventHandler, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StopOptions } from "./core";
+import { Feet } from "./Feet";
+import { Warp } from "./Warp";
 import type { Loop } from "./Loop";
 import type { Layer } from "./Layer";
 import type { Playback } from "./Playback";
 /** Level of detail for a GLB instance (docs/lod-plan.md): `'auto'` = the engine's pick by screen size and
  *  visibility, or a fixed level 0 (full) … 3 (coarsest mesh, animation every 4th frame without fingers). */
 export type LodMode = "auto" | 0 | 1 | 2 | 3;
-/** What `Animator.warp` turns on. Speeds are m/s, angles degrees, distances metres. */
-export type WarpOptions = {
-    /** Fit the stride to the speed the body actually travels at. `[min, max]` clamps the scale
-     *  (default 0.85…1.2). It is a CORRECTION: a pack whose takes already read right at the speeds it
-     *  is played at wants none of this, and a wide range only lets the legs be stretched into shapes
-     *  nobody recorded. Open it for a pack that must cover speeds it was never recorded at. */
-    stride?: boolean | [number, number];
-    /** Turn the lower body toward where the body really travels; a number caps the turn in degrees
-     *  (default 20). The spine counter-turns, so the chest keeps facing where it faced — the whole twist
-     *  lives in one joint, which is why a few degrees read as a lean and a lot reads as a broken back.
-     *  Only applied while the gait LOOP shows: a start, a turn or a stop walks a path of its own. */
-    orientation?: boolean | number;
-    /** Below this speed — the game's or the clip's — both warps are off (default 0.2). */
-    minSpeed?: number;
-    /** How far the pelvis may drop to keep a stretched leg from locking straight (default 0.25). */
-    pelvis?: number;
-    /** The stride scale's own spring, seconds (default 0.15). The body's speed is continuous but the
-     *  shown clip's recorded one steps at every switch, so the scale is smoothed rather than followed. */
-    strideTime?: number;
-};
-/** What `Animator.feet` sets: which bones the feet are, and what the engine does with them. Distances
- *  are metres, times seconds. Every key is optional and only the keys given change — set the bones
- *  once, switch the lock on somewhere else. */
-export type FeetOptions = {
-    /** The contact bones per side — `'LeftFoot'`, or with a toe / ball `['LeftFoot', 'LeftToeBase']`.
-     *  Default: classified from the bone names (Mixamo / Unity / Blender / UE). Set them for a rig the
-     *  classifier misses; it re-bakes every clip's contacts and phase. */
-    left?: string | string[];
-    right?: string | string[];
-    /** FOOT LOCK: a foot the shown clip calls planted (its baked contacts, else a runtime detector) is
-     *  pinned where it landed — heel to ball, rolling as the clip rolls — and the leg re-solved to keep it
-     *  there while the body moves on. What hides the last of a transition's slide: the pose the new clip
-     *  starts from is not the one the old clip ended in, and the difference used to be dragged out of
-     *  the standing foot over the blend. Off by default; a `Locomotion` turns it on. */
-    lock?: boolean;
-    /** GROUND IK: each foot is put on the ground the engine probes under it (stairs, a slope, a kerb),
-     *  aligned to its normal, and the pelvis lowered so the lower leg can reach — the feet stop hanging
-     *  in the air on a step down and sinking into a step up. Needs a physics world to probe; without
-     *  one the ground is the node's own plane. Off by default. */
-    ik?: boolean;
-    /** How far the pelvis may drop for the ground (default 0.35). */
-    pelvis?: number;
-    /** The anchor's leash: a locked foot never absorbs more residual than this — beyond it the anchor
-     *  follows the animation instead of fighting it (default 0.10). */
-    unlockDistance?: number;
-    /** The lock's ease in / out, seconds (default 0.08 / 0.12). */
-    lockIn?: number;
-    lockOut?: number;
-    /** 0..1: how much the foot tilts onto the ground normal (default 1). */
-    align?: number;
-    /** The probe ray's reach above and below the ankle (default 0.6) — a step taller than this is a
-     *  hole to the probe. */
-    probe?: number;
-    /** The lock plants only once the animated ankle moves slower than this, m/s (default 0.2: a foot
-     *  the take itself holds still). Raise it to pin a foot a transition is still dragging — a run
-     *  entered from standing lands its first foot while the offset from the idle still decays. */
-    plantSpeed?: number;
-};
-/** One foot after this frame's evaluation (`Animator.foot`): whether the lock holds it, the lock's
- *  weight (eased 0…1), where it was pinned and where the leg was asked to put the ankle — all world. */
-export type FootState = {
-    locked: boolean;
-    weight: number;
-    anchor: Vec3;
-    target: Vec3;
-};
 export declare class Animator extends Aspect<"anim", Node> {
     static readonly aspect = "anim";
     private _c;
     private _rootMotion;
     private _rootRotation;
-    /** Animation level of detail. `'auto'` (default): a character small on screen or out of view is
-     *  evaluated every 2nd / 4th frame and stops sampling its finger, toe and twist joints; `'full'`:
-     *  every frame, every joint, whatever the distance — a hero seen through a scope, a cutscene actor.
-     *  Independent of `Model.lod` (the mesh level). No-op on hosts without the LOD pass. */
-    get lod(): "auto" | "full";
-    set lod(v: "auto" | "full");
+    /** The feet: the contact bones, the foot lock, ground IK, footstep events. See `Feet`. */
+    feet: Feet;
+    /** The warp: stride and orientation fitted to the body's real motion, the step warp dials. See `Warp`. */
+    warp: Warp;
     onAttach(): void;
     onDetach(): void;
-    /** The clip list, in order: the GLB's embedded clips (file order), then the clips you added. An
-     *  added clip with an embedded clip's name takes its place. */
+    /** The clip list, in order: the GLB's embedded clips, then the clips you added (an added clip with an
+     *  embedded clip's name takes its place). */
     get clips(): readonly AnimationClip[];
-    /** One clip by name, or by index into `clips` — e.g. to `slice()` it. `undefined` if there is none. */
+    /** One clip by name or index — the resource: its name, duration, tracks, events. `undefined` if none. */
     clip(ref: string | number): AnimationClip | undefined;
-    /** Add a clip under a name (default: its own `name`) — from another file, procedural, or sliced.
-     *  Overrides an embedded clip of the same name. Chainable. */
+    /** Add a clip under a name (default: its own) — from another file, procedural, or sliced. Chainable. */
     addClip(name: string | AnimationClip, clip?: AnimationClip): this;
-    /** Play a one-shot on the base layer — by name, index, or the first clip with no argument. It
-     *  takes the layer over from whatever it showed, transitioned over `fade` (default 0.2 s).
-     *  Returns a Playback: `await` it — it resolves at the clip's hand-over (`true`; `false` if cut
-     *  short), and what you start right after is what the clip hands the layer to (another one-shot,
-     *  `playLoop(next)`; nothing = back to the loop). */
+    /** What the engine measured about a clip on THIS skeleton (unlike `clip()`, which is the file's data):
+     *  speed, travel, turn, the foot contacts, the gait phase, its cycle, and comparisons with other clips.
+     *  Binds the clip on first ask. `undefined` if there is no such clip. */
+    clipInfo(clip: string | number): ClipInfo | undefined;
+    /** Play a one-shot: by name, index, or the first clip. It takes the layer over from whatever it showed,
+     *  transitioned over `fade`. `await` the Playback: it resolves at the hand-over (`true`, or `false` if cut
+     *  short), and what you start right then is what the clip hands over to (nothing = back to the loop). */
     play(clip?: string | number, options?: PlayOptions): Playback;
-    /** Set the base layer's LOOP — what it shows when no one-shot plays: a clip (`playLoop('Idle')`) or
-     *  a blend space (`playLoop({ Idle: 0, Run: 6 })`, drive the returned object's `value`). Takes the
-     *  layer over from whatever plays — a one-shot included (it is cut short) — transitioned over
-     *  `fade`. `stop()` removes it. */
+    /** Set the LOOP — what shows when no one-shot plays: a clip, or a blend space (`{ Idle: 0, Run: 6 }`, drive
+     *  the returned object's `value`). Takes the layer over, a one-shot included. `stop()` removes it. */
     playLoop(def: LoopDef, options?: LoopOptions): Loop | undefined;
-    /** Fade everything out, on every layer (loops included) → rest pose. */
+    /** Fade everything out, on every layer → the rest pose. */
     stop(options?: StopOptions): this;
-    /** The base layer's current loop (the object the last `playLoop()` returned), if any. */
+    /** The current loop (the object the last `playLoop()` returned), if any. */
     get loop(): Loop | undefined;
-    /** A one-shot on the base layer hasn't handed over yet. */
+    /** A one-shot hasn't handed over yet. */
     get busy(): boolean;
-    /** What every layer shows this frame with its weight: one one-shot, or a loop's members with their
-     *  blend shares (a debug overlay's list). */
+    /** What every layer shows this frame, with weights: a one-shot, or a loop's members with their shares. */
     get active(): ActiveClip[];
-    /** Where the base layer is in the GAIT CYCLE: 0 at a left-foot-down, 0.5 at a right-foot-down,
-     *  whether a loop or a one-shot shows it. -1 when what plays has no cycle (an idle, a hit reaction).
-     *  This is the number `play(clip, { phase: 'match' })` matches against. */
+    /** Where the base layer is in the GAIT CYCLE: 0 at a left-foot-down, 0.5 at a right-foot-down; -1 when
+     *  what plays has no cycle. What `play(clip, { phase: 'match' })` matches against. */
     get phase(): number;
-    /** The native animator's id — 0 until something is played or bound. Engine-facing code only. */
-    get _id(): number;
-    /** Bind a clip to the base layer without playing it and return its native slot (-1 = no such clip);
-     *  creates the native animator on first use. What a Locomotion registers its set with. */
-    _slot(clip: string | number): number;
-    /** What the engine measured on a clip once it was bound to this skeleton: foot contacts, the gait
-     *  phase φ(t), and the root's travel / yaw / speed — a controller reads these instead of shipping
-     *  measured tables. Binds the clip on first ask. `undefined` if there is no such clip. */
-    curves(clip: string | number): ClipCurves | undefined;
-    /** The skeleton's calibrated KNEE HINGE AXIS for a side (thigh-local, unit) with its confidence
-     *  report — measured once over every bound clip's knee rotation track; the ground truth
-     *  `curves(clip).kneePoleAt` predicts bend planes from. Undefined = no leg chain, or no knee
-     *  motion bound to calibrate from. */
-    kneeAxis(side: "left" | "right"): KneeAxisReport | undefined;
-    /** STEP WARP v2 knobs (the warp rewrite): `stride` scales each foot's travel-direction offset
-     *  from its hip (the step shortens / lengthens), `lift` = metres ADDED to its height
-     *  (swing-gated; 0 = neutral, negative = a shuffle; half of what it adds raises the pelvis —
-     *  the body steps higher with the foot), `pitch` (degrees, + = toes up) rotates each foot about
-     *  its lateral axis, `slope` (degrees, + = ascending) the invisible staircase — feet on the
-     *  incline + auto pitch; raise the character by tan(slope) × the stride-scaled clip travel to
-     *  hold each planted foot on its tread. Solved in the calibrated knee hinge plane.
-     *  Omit / null = off. A tuning bench's dial — locomotion will drive this itself later. */
-    setStepWarp(options?: {
-        stride?: number;
-        lift?: number;
-        pitch?: number;
-        slope?: number;
-    } | null): void;
-    /** Scrub: set `clip`'s playhead directly, seconds — for inspectors and debug boards (pair with
-     *  `speed = 0`). The clip should be the one showing; nothing is faded or re-picked. */
-    seek(clip: string | number, time: number): void;
-    /** `clip`'s current playhead, seconds (-1 = not bound). */
+    /** A clip's playhead, seconds (-1 = not bound). */
     time(clip: string | number): number;
-    /** Re-aim a playing turn clip's warp (`play({ turn })`) to `deg` for the whole clip — the scale lands on what is
-     *  still to come; `undefined` = off. */
+    /** Scrub a clip's playhead, seconds — inspectors and debug boards (pair with `speed = 0`). Nothing is
+     *  faded or re-picked. */
+    seek(clip: string | number, time: number): void;
+    /** Re-aim a playing turn clip's warp (`play({ turn })`) to `deg` for the rest of the clip; `undefined` = off. */
     setTurn(clip: string | number, deg: number | undefined): void;
-    /** THE FEET (docs/animation-v2-plan.md §2.9): which bones they are, and what the engine does with
-     *  them after the clips are composited — the foot LOCK (a planted foot stays where it landed while the
-     *  body moves on) and GROUND IK (each foot on the ground probed under it, the pelvis lowered). Only
-     *  the keys given change, so the bones and the behaviour can be set from different places:
-     *
-     *      model.anim.feet = { left: 'LeftFoot', right: 'RightFoot' }   // a rig the classifier misses
-     *      model.anim.feet = { lock: true }                              // (a Locomotion does this itself)
-     *      model.anim.feet = { lock: true, ik: true, pelvis: 0.3 }       // stairs and slopes
-     *
-     *  The engine probes the ground itself (against what a character can stand on) and reads the
-     *  CharacterController's ground state; nothing is fed per frame. See `FeetOptions`. */
-    set feet(f: FeetOptions);
-    private readonly _feetOpts;
-    /** One foot's state after this frame's evaluation — where the lock holds it and with what weight
-     *  (a debug beam under the foot). `undefined` on a host without the feet stage, or before anything
-     *  played. */
-    foot(side: "left" | "right"): FootState | undefined;
-    /** WARPING (docs/animation-v2-plan.md §2.7) — the pose is fitted to what the body actually does,
-     *  after the clips are composited and before the feet:
-     *
-     *  `stride` — each leg's hip→foot vector is scaled ALONG the travel direction by the ratio of the
-     *    game speed to the shown clip's own (clamped, default 0.6…1.5), the foot height kept, and the
-     *    pelvis lowered when that would overextend a leg. A walk played at 1.9 m/s stops skating; a
-     *    speed between two gaits becomes continuous instead of "two clips and a crossfade".
-     *  `orientation` — the lower body turns from the clip's travel direction toward the one the body
-     *    really travels in (capped, default 60°) and the spine counter-turns, so the chest keeps its
-     *    facing. Arcs and strafing stop needing a clip per angle.
-     *
-     *  Both need to know the body's motion, which a `Locomotion` feeds every frame; without one, set
-     *  `_creator.animatorSetMotion` yourself or leave warping off. Off by default.
-     *
-     *      model.anim.warp = true                                  // both, with the defaults
-     *      model.anim.warp = { stride: [0.7, 1.4], orientation: 45 }
-     */
-    set warp(w: WarpOptions | boolean);
-    /** A foot planted (world position) — audio, dust, decals. Fires for what the BASE layer shows,
-     *  from the clip's own contacts; a clip with no contacts fires nothing. */
-    onStep(cb: StepHandler): this;
-    offStep(cb: StepHandler): this;
-    /** A new layer on top (masked override / additive). The returned object is its handle. */
-    addLayer(options?: LayerOptions): Layer;
-    on(event: string, cb: ClipEventHandler): this;
-    off(event: string, cb: ClipEventHandler): this;
     /** Global playback rate: 0.3 = slow-mo, 0 = pause. */
     get speed(): number;
     set speed(v: number);
-    /** Root motion: the root bone's horizontal travel comes OFF the pose and moves the node instead —
-     *  or its CharacterController (on this node or an ancestor) as a velocity, so it collides. For
-     *  clips whose hips actually travel (Mixamo without "In Place", lunges, rolls). A character that
-     *  moves under a `Locomotion` gets this from its displacement mode instead. */
+    /** Clip events (`clip.addEvent(0.4, 'hit')` → `anim.on('hit', …)`). */
+    on(event: string, cb: ClipEventHandler): this;
+    off(event: string, cb: ClipEventHandler): this;
+    /** A new layer on top (masked override / additive); the returned object is its handle. */
+    addLayer(options?: LayerOptions): Layer;
+    /** The root bone's horizontal travel comes OFF the pose and moves the node — or its CharacterController
+     *  (on this node or an ancestor) as a velocity, so it collides. For clips whose hips actually travel. A
+     *  character under a `Locomotion` gets this from its displacement mode instead. */
     get rootMotion(): boolean;
     set rootMotion(on: boolean);
-    /** With `rootMotion`, the root bone's TURN (its yaw about the node's up, since the clip's first
-     *  frame) is root motion too: it comes off the pose and turns the node the travel lands on — the
-     *  character (or the model) faces where a turn-start / turn-in-place / arc clip took it, and the
-     *  crossfade into the next clip keeps that heading instead of swinging back. Off by default: a
-     *  walk cycle's hip sway is a turn too, and most rigs want it in the pose; turn it on for a rig
-     *  whose root bone carries the heading (`lecodes assets retarget --root-rotation yaw`). */
+    /** With `rootMotion`: the root bone's TURN is root motion too — it comes off the pose and turns the node,
+     *  so a turn clip leaves the character facing where it took it. Off by default (a walk's hip sway is a
+     *  turn too); on for a rig whose root carries the heading (`lecodes assets retarget --root-rotation yaw`). */
     get rootRotation(): boolean;
     set rootRotation(on: boolean);
+    /** `'auto'` (default): a character small on screen or out of view is evaluated every 2nd / 4th frame
+     *  without its finger, toe and twist joints; `'full'`: every frame, every joint (a hero seen through a
+     *  scope). Independent of `Model.lod`, the mesh level. */
+    get lod(): "auto" | "full";
+    set lod(v: "auto" | "full");
+    /** The native animator's id — 0 until something is played or bound. */
+    get _id(): number;
+    /** Bind a clip to the base layer without playing it; its native slot (-1 = no such clip). */
+    _slot(clip: string | number): number;
 }