lecodes-sdk 0.19.0

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

@@ -0,0 +1,219 @@
+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 { 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");
+    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. */
+    get clips(): readonly AnimationClip[];
+    /** One clip by name, or by index into `clips` — e.g. to `slice()` it. `undefined` if there is 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. */
+    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). */
+    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. */
+    playLoop(def: LoopDef, options?: LoopOptions): Loop | undefined;
+    /** Fade everything out, on every layer (loops included) → rest pose. */
+    stop(options?: StopOptions): this;
+    /** The base layer's 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. */
+    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). */
+    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. */
+    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). */
+    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. */
+    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. */
+    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`). */
+    get rootRotation(): boolean;
+    set rootRotation(on: boolean);
+}

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

@@ -0,0 +1,31 @@
+import type { ActiveClip, LoopDef, LoopOptions, PlayOptions, StopOptions } from "./core";
+import type { Loop } from "./Loop";
+import type { Playback } from "./Playback";
+export declare class Layer {
+    private readonly _r;
+    private readonly _c;
+    /** Play a one-shot on this layer (transitioned over `fade`); resolves at its hand-over. */
+    play(clip?: string | number, options?: PlayOptions): Playback;
+    /** Set / transition this layer's loop (a clip, or a blend space) — over `fade` from whatever the
+     *  layer shows, a one-shot included (it is cut short). */
+    playLoop(def: LoopDef, options?: LoopOptions): Loop | undefined;
+    /** Fade everything on this layer out — one-shots and its loop. */
+    stop(options?: StopOptions): this;
+    /** ANTICIPATION for the NEXT play / playLoop on this layer (consumed by it): the transition begins with
+     *  every joint moving AGAINST the new clip's motion - `amount` x its velocity - and the transition's
+     *  spring brings it round: a wind-up before the swing. Position and rotation, the joints the layer
+     *  drives. 0.3-1 reads as a natural anticipation; the duration is the transition's own fade.
+     *  Ignored by hosts without it. */
+    anticipate(amount: number): this;
+    /** This layer's current loop (the object the last `playLoop()` returned), if any. */
+    get loop(): Loop | undefined;
+    /** Where this layer is in the gait cycle, 0–1 (-1 = what it shows has no cycle). */
+    get phase(): number;
+    /** Layer contribution 0–1. */
+    get weight(): number;
+    set weight(v: number);
+    /** A one-shot on this layer hasn't handed over yet. */
+    get busy(): boolean;
+    /** What this layer shows this frame with its weight — its one-shot, or its loop's members. */
+    get active(): ActiveClip[];
+}

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

@@ -0,0 +1,17 @@
+import type { BlendPosition } from "./core";
+export declare class Loop {
+    private readonly _r;
+    private readonly _c;
+    /** Position on the axis (number) or plane (`[x, y]`) — units are whatever the positions use. Live
+     *  even while a one-shot plays (the loop returns at the new mix). */
+    get value(): BlendPosition;
+    set value(v: BlendPosition);
+    /** Where the loop is in its GAIT cycle, 0–1: 0 at a left-foot-down, 0.5 at a right-foot-down —
+     *  one clock for every member, aligned by their contacts (a walk and a run whose feet land at
+     *  different fractions of their clips still agree). Set it to jump the cycle: `playLoop(def,
+     *  { phase })` on the way in, or here to re-sync with something else. */
+    get phase(): number;
+    set phase(v: number);
+    /** Each member's share of the mix, 0–1. */
+    get weights(): Record<string, number>;
+}

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

@@ -0,0 +1,36 @@
+import type { AnimationClip } from "./AnimationClip";
+import type { StopOptions } from "./core";
+import type { Layer } from "./Layer";
+export declare class Playback implements PromiseLike<boolean> {
+    private readonly _r;
+    private readonly _c;
+    /** The clip that plays. */
+    get clip(): AnimationClip;
+    /** The layer it plays on. */
+    get layer(): Layer;
+    /** Clock (s). */
+    get time(): number;
+    /** 0–1 through the clip (the current cycle, when looping). */
+    get progress(): number;
+    /** Where this clip is in the GAIT cycle now, 0–1 (-1 when it has none). */
+    get phase(): number;
+    /** The root yaw the clip has turned the body by so far, radians (+ = left) — a turn clip's progress. */
+    get turned(): number;
+    /** The root yaw still to come: where this clip will leave the body facing, relative to now (rad). */
+    get turnLeft(): number;
+    /** The horizontal distance the clip's root has travelled so far, metres. */
+    get travelled(): number;
+    /** Not handed over yet (the clip still owns the layer). */
+    get playing(): boolean;
+    /** Contribution to the pose: 1 while this clip is the layer's source, 0 once something else took
+     *  the layer over (the difference between the two poses is what decays, not this weight). */
+    get weight(): number;
+    /** Resolves at the hand-over (`true`) or when cut short (`false`) — the promise `await playback`
+     *  uses; the one to return from async functions or put in `Promise.all`. */
+    get done(): Promise<boolean>;
+    then<A = boolean, B = never>(onFulfilled?: ((v: boolean) => A | PromiseLike<A>) | null, onRejected?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+    /** Move the clock (s). */
+    seek(time: number): this;
+    /** Cut this clip short (the layer's loop comes back if nothing else takes over), over `fade`. */
+    stop(options?: StopOptions): this;
+}