lecodes-sdk 0.20.2 → 1.1.0

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. */
@@ -164,11 +170,25 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
      *  spread evenly along the path — trail density independent of speed, no per-frame clumps.
      *  Meant for `space: 'world'`. */
     rateOverDistance?: number;
+    /** Spread those spawn points along a CURVE through the emitter's recent path instead of the
+     *  straight line between where it was last frame and where it is now. A straight line cuts the
+     *  corner by however far the path bows inside one frame, which grows with the frame TIME — so a
+     *  fast curving emitter looks faceted, and looks worse the slower the machine. Default false
+     *  (the straight line); costs three stored positions and one curve evaluation per spawn.
+     *
+     *  The curve needs a point one frame AHEAD, so each frame's spawns are placed provisionally and
+     *  nudged into place on the next frame, once it exists. Nothing else observes them in between. */
+    smooth?: boolean;
     /** Draw order among blended systems at the same depth — higher draws later, i.e. on top (Unity's
      *  sortingOrder). Systems are depth-sorted by their node, so the emitters of one effect tie and
      *  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;
@@ -211,7 +231,11 @@ export declare class Particles extends Node {
     set space(val: "local" | "world");
     set inheritVelocity(val: number);
     set rateOverDistance(val: number);
+    /** Lay a frame's spawns along a curve through the emitter's path, not the straight chord. */
+    set smooth(val: boolean);
     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. */
@@ -247,8 +271,28 @@ export type TrailOptions = Omit<ParticlesMaterialOptions, "render" | "stretch">
     width?: ParticleValue;
     /** Minimum emitter movement (world units) between recorded points. Default 0.05. */
     minDistance?: number;
-    /** Point capacity (default 128). */
+    /** Point capacity (default 128). A spawn that does not fit is DROPPED, so a fast emitter at a
+     *  small `minDistance` wants headroom: a sword tip covers metres inside one `time` window. */
     maxPoints?: number;
+    /** Follow a CURVE through the emitter's recent path instead of the straight line between frames.
+     *  A trail is where this shows most — the strip is the path — and it shows worse the lower the
+     *  frame rate, since a longer frame bows further off its own chord. Default false; see
+     *  `ParticlesOptions.smooth`. */
+    smooth?: boolean;
+    /** Which way the strip's WIDTH points.
+     *
+     *  `'camera'` (default) rolls the strip about its own length to stay flat to the viewer — it can
+     *  never disappear, which is why it is the default, but it bears no relation to the thing that drew
+     *  it. An AXIS (`'x'`/`'y'`/`'z'`) uses that axis of the emitter's own transform, as it was when
+     *  each point was laid: on a node riding a sword's blade, `'z'` (the blade) makes the strip the
+     *  surface the blade actually swept, and `width` stops being a made-up number — it is the blade. */
+    orient?: "camera" | "x" | "y" | "z";
+    /** With `orient` on an axis: the floor under the strip's APPARENT width, 0..1 of its real width,
+     *  below which it rolls back toward the camera. An honestly oriented strip goes edge-on — and
+     *  vanishes — whenever the swing happens in the plane of view; this is the hybrid that keeps it
+     *  readable. 0 = never roll (honest, and it will vanish), 1 = always (the same as `'camera'`).
+     *  Default 0.4: a sweep still reads as a sweep, and a swing toward the camera still shows. */
+    faceCamera?: number;
     color?: ParticleColor;
     /** Opacity along the trail. Defaults to fading the tail out (`curve().to(0)`). */
     opacity?: ParticleValue;
@@ -261,6 +305,8 @@ export type TrailOptions = Omit<ParticlesMaterialOptions, "render" | "stretch">
 export declare class Trail extends Node {
     private _material;
     private _rateDistance;
+    private _orient;
+    private _faceCamera;
     constructor(options?: TrailOptions);
     private _send;
     /** Trail length in seconds — how long each laid-down point lives. */
@@ -269,6 +315,12 @@ export declare class Trail extends Node {
     set opacity(val: ParticleValue);
     set color(value: ParticleColor);
     set minDistance(val: number);
+    /** Follow a curve through the emitter's path instead of the straight chord between frames. */
+    set smooth(val: boolean);
+    /** Which way the strip's width points — see `TrailOptions.orient`. Keeps the current `faceCamera`. */
+    set orient(val: "camera" | "x" | "y" | "z");
+    /** The hybrid's floor — see `TrailOptions.faceCamera`. */
+    set faceCamera(val: number);
     /** Pause/resume laying down points — existing ones still age out, so the trail fades naturally
      *  after e.g. a sword swing ends. */
     set emitting(val: boolean);

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

@@ -4,7 +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 { SceneAudio } from "./audio/SceneAudio";
 import { type ControlsHandle, type ControlsOptions } from "./controls";
 import { Material } from "./Material";
 import { Node } from "./Node";
@@ -174,6 +174,19 @@ export declare class Scene implements Presentable {
     setLodBias(bias: number): void;
     /** Runtime form of `bloom` / `bloomIntensity` (a graphics-settings menu). */
     setBloom(enabled: boolean, intensity?: number): void;
+    /**
+     * How bright the environment (IBL) lights the scene, in lux — `SceneOptions.environmentIntensity`
+     * after the fact. Live: it changes the probe's intensity, not the probe, so it costs nothing and
+     * can be dragged. (`setDefaultIbl`, the call that installs a probe, rebuilds the cubemap from the
+     * ktx every time — never drive a slider through a scene option that has to re-open.)
+     *
+     * `lecodes lightmap bake` reads the same number off the live probe, so a scene dimmed here bakes
+     * dimmed. Hosts without the call keep whatever the scene opened with, and the getter still
+     * reports what was asked for.
+     */
+    get environmentIntensity(): number;
+    set environmentIntensity(lux: number);
+    private static _warnedEnvIntensity;
     /** The scene's stencil buffer on / off (see `SceneOptions.stencil`). */
     setStencil(enabled: boolean): void;
     add(...nodes: Node[]): this;
@@ -192,6 +205,13 @@ export declare class Scene implements Presentable {
     destroy(): void;
     createOverlay(options?: SceneOptions): Scene;
     warmRender(): Promise<void>;
+    /** Precompile the scene's shader variants so nothing is compiled mid-game. Every material the host
+     *  knows is queued for the sun / shadow / fog / skinning variants and the dynamic-light key — the
+     *  first point light (a muzzle flash, an explosion) would otherwise rebuild every lit shader in view
+     *  on that frame. Call it once the sun and fog are set, typically under a loading screen; materials
+     *  loaded later are queued in the background as they are created. Resolves at once on a host
+     *  without the bridge. */
+    precompileShaders(): Promise<void>;
     readonly cl: (() => void)[];
     _backButtonCallback?: () => void;
     private _vd?;

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

@@ -50,6 +50,25 @@ export declare class AnimationClip {
      *  keeps the ones inside the window, re-timed. Chainable. */
     addEvent(time: number, name: string): this;
     private _pushEvents;
+    /** ANCHOR SPANS for a bone — what an anchored IK chain ending in `bone` rides while this clip plays
+     *  (`IK.TwoBone` with `anchor`; the sockets come from `anim.sockets(...)`). `donor` names the socket
+     *  set of the gun the take was AUTHORED on ('' = the live set: no delta); `spans` = `[from, to,
+     *  socket, rotation?, pin?]` in SECONDS — the socket the hand is on through that window (`''` = free:
+     *  it rides the joint itself), `rotation` 0..1 how much of the socket's turn it takes (default 1),
+     *  `pin` 0..1 how much it sits ON the socket instead of keeping its own relation to it (default 0: a
+     *  magazine is REACHED, and the take's motion is what carries the hand there).
+     *  Gaps between spans = the chain's own socket, pinned by the chain's `anchorPin` — that is where a
+     *  hand holding the gun is nailed to the grip, so the layers below cannot slide it. A clip WITHOUT
+     *  anchors takes no part: the hand keeps the take's own relation to the gun. Part of the clip, like
+     *  events; `AnimationClip.from` carries them re-timed. Chainable.
+     *    reload.anchors('hand_l', { donor: 'tr15', spans: [[0.9, 1.4, 'mag'], [1.4, 2.0, ''], [2.0, 2.4, 'mag'], [2.4, 2.7, 'bolt']] }) */
+    anchors(bone: string, def: {
+        donor?: string;
+        spans?: readonly (readonly [number, number, string, number?, number?])[];
+    }): this;
+    /** Drop a bone's anchor spans. */
+    clearAnchors(bone: string): this;
+    private _pushAnchors;
     /** Load ONE clip from a GLB: the file's only/first clip, or the one named / at the given index. */
     static load(source: string | FetchResponse, clip?: string | number): Promise<AnimationClip>;
     /** Load EVERY clip of a GLB (library files), keyed by clip name. */

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

@@ -1,4 +1,6 @@
 import { Aspect } from "../../core/Aspect";
+import { type Vec3Like } from "../../math/vec";
+import { type QuatLike } from "../../math/quat";
 import type { Node } from "../Node";
 import type { AnimationClip } from "./AnimationClip";
 import { type ActiveClip, type ClipInfo, type ClipEventHandler, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StopOptions } from "./core";
@@ -75,6 +77,31 @@ export declare class Animator extends Aspect<"anim", Node> {
      *  turn too); on for a rig whose root carries the heading (`lecodes assets retarget --root-rotation yaw`). */
     get rootRotation(): boolean;
     set rootRotation(on: boolean);
+    /** The body's WORLD velocity this frame (m/s): what `anim.warp`'s stride and orientation fit the clips
+     *  to. A `Locomotion` feeds it itself; when you drive the gait by hand set it every frame (the
+     *  CharacterController's velocity, or your own). Reads back the last value fed. */
+    get motion(): readonly [number, number, number];
+    set motion(v: {
+        x: number;
+        y: number;
+        z: number;
+    } | readonly [number, number, number]);
+    private _motion;
+    /** SOCKETS: named frames on a bone of this rig — a weapon's grip / magazine / bolt empties, placed in
+     *  the scene editor. A NODE socket is read by the engine every frame (a socket on a moving part
+     *  follows it); a `{ position, quaternion }` one is fixed in the bone's space. The default set is the
+     *  LIVE one (the weapon in the hands); `set: 'tr15'` names a DONOR set — the same sockets on the gun a
+     *  take was authored on, which a clip's `anchors()` refer to. Chainable.
+     *    arms.anim.sockets('ik_hand_gun', { grip_r: w.gripR, grip_l: w.gripL, mag: w.mag })
+     *    arms.anim.sockets('ik_hand_gun', { grip_l: { position: [0.03, -0.12, -0.05] } }, { set: 'tr15' }) */
+    sockets(joint: Node | string, table: Record<string, Node | {
+        position?: Vec3Like;
+        quaternion?: QuatLike;
+    }>, options?: {
+        set?: string;
+    }): this;
+    /** Drop a socket (the live set, or `set`). */
+    removeSocket(name: string, set?: string): this;
     /** `'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. */

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

@@ -0,0 +1,184 @@
+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 SIDE of every collider marked `oneSided`: `'none'` = no side, every 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 hanging BEHIND
+ *  the arms: the body's backward). A one-sided collider that is moving AWAY from that side — an arm swinging
+ *  forward under the cape — puts a bone it has run into over to the side instead of carrying it: the arm
+ *  passes through the cloth and the cape hangs behind it again, instead of being dragged round the body.
+ *  Still, or moving toward the cloth, it pushes like any other collider, so cloth draped on an arm at rest
+ *  stays where it is. Two-sided colliders (the body's) never read the 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;
+    /** ONE-SIDED: the cloth belongs on the chain's `side` of this capsule (see DynamicBone.side). While the capsule
+     *  moves away from that side it puts a bone it has run into over to the side instead of carrying it — an arm
+     *  under a cape may push the cape back, never drag it forward round the body. Needs a `side` on the DynamicBone. */
+    oneSided: boolean;
+    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 — neighbours in THIS order, so list the strips round the ring
+     *  (front-left … back … front-right); the front stays open. */
+    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 tied pairwise, the columns in the order of `pinned` (a cloak's
+     *  strips listed round the ring) — columns not listed there follow in tree order. Tree order alone is the
+     *  engine's child order, which for a GLB is the file's node order REVERSED (Filament prepends each child), so
+     *  strips added to a rig later were tied across the body instead of to their neighbours: the ermine's cloak
+     *  had one true neighbour pair out of eight, the rest were rods through the chest. */
+    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/animation/IK.d.ts

@@ -0,0 +1,109 @@
+import { Aspect } from "../../core/Aspect";
+import { type Vec3Like } from "../../math/vec";
+import { Quat } from "../../math/quat";
+import type { Node } from "../Node";
+import type { Core } from "./core";
+type Target = Node | Vec3Like;
+/** What both chains share: the native handle, the parameter push, the readback. */
+declare abstract class Chain<Name extends string> extends Aspect<Name, Node> {
+    protected _rig?: Core;
+    protected _ik: number;
+    protected _weight: number;
+    protected _enabled: boolean;
+    protected abstract readonly kind: 0 | 1;
+    /** 0–1 contribution (blend in/out, e.g. foot planting only while grounded). */
+    get weight(): number;
+    set weight(v: number);
+    /** Solve every frame (default). */
+    get enabled(): boolean;
+    set enabled(v: boolean);
+    /** After the last solve: how far the end bone still is from its target, metres (0 = reached). */
+    get error(): number;
+    onAttach(): void;
+    onDetach(): void;
+    onReconfigure(): void;
+    protected params(): Float32Array;
+    /** Push the description to the engine (a no-op until attached). */
+    protected abstract push(): void;
+}
+/** 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 (knee /
+ *  elbow) — a Node or world point; `anchor` makes it ride a socket of the rig instead (see the file
+ *  header). */
+declare class TwoBone extends Chain<"ik"> {
+    static readonly aspect = "ik";
+    protected readonly kind: 0;
+    private _target?;
+    private _pole?;
+    private _rotation?;
+    private _rotationWeight;
+    private _anchor;
+    private _anchorTime;
+    private _anchorPin;
+    /** Where the end bone should be (a Node — read by the engine every frame — or a world position). */
+    get target(): Target | undefined;
+    set target(v: Target | undefined);
+    /** Bend hint — the mid joint is pulled toward it (a Node or a world point). */
+    get pole(): Target | undefined;
+    set pole(v: Target | undefined);
+    /** World rotation the END bone takes after the solve — a Node (its world rotation) or a Quat. Unset =
+     *  the end bone keeps its animated rotation (a hand on a grip, a foot on a slope want it set). Blended
+     *  by `weight · rotationWeight`. An anchored chain takes its rotation from the socket instead. */
+    get rotation(): Node | Quat | undefined;
+    set rotation(v: Node | Quat | undefined);
+    /** 0–1 contribution of `rotation` (on top of `weight`); for an anchored chain, of the socket's turn. */
+    get rotationWeight(): number;
+    set rotationWeight(v: number);
+    /** ANCHORED: the name of the LIVE socket the end bone rides (`anim.sockets(...)`) — its target and
+     *  rotation come from the socket and the playing clips' anchor spans; `target` / `pole` / `rotation`
+     *  are ignored. '' = a plain chain. */
+    get anchor(): string;
+    set anchor(v: string);
+    /** Anchored: how fast the hand moves between sockets — the halflife (s) of the spring the applied
+     *  delta follows the wanted one with (default 0.05). */
+    get anchorTime(): number;
+    set anchorTime(v: number);
+    /** Anchored: 0..1 how hard the end bone is PINNED on its socket while the playing clips leave it there
+     *  (a GAP in their spans — the hand is holding the gun). 1 = it sits exactly on the socket, so nothing
+     *  in the pose below can slide it along the gun; 0 (default) = it keeps the take's own relation to the
+     *  socket, moved by the delta. A clip's SPANS carry their own pin and default to 0, because a hand on
+     *  its way to a magazine must keep the take's motion — so this knob is about holding, not reaching. */
+    get anchorPin(): number;
+    set anchorPin(v: number);
+    /** After the last solve: the anchor delta applied — how far (m) and how much (rad) the live socket
+     *  moved the hand off the take's own pose. 0 for a plain chain. */
+    get anchorDelta(): {
+        distance: number;
+        angle: number;
+    };
+    protected push(): void;
+}
+/** Aim a bone at a target (head / eyes / turret). Attach to the bone itself:
+ *  `head.aspect(IK.LookAt, { target: camera, limit: 70 })`. `axis` is the bone's LOCAL forward
+ *  (the direction that should point at the target) — rigs differ; default −Z, Mixamo heads look
+ *  along +Z of the head bone in most exports, so pass `axis: [0, 0, 1]` there if it faces backwards. */
+declare class LookAt extends Chain<"lookAt"> {
+    static readonly aspect = "lookAt";
+    protected readonly kind: 1;
+    private _target?;
+    private _axis;
+    private _limit;
+    /** What to look at (a Node — read by the engine every frame — or a world position). */
+    get target(): Target | undefined;
+    set target(v: Target | undefined);
+    /** The bone's local axis that should point at the target. */
+    get axis(): Vec3Like;
+    set axis(v: Vec3Like);
+    /** Max deflection from the animated direction, in degrees (default 80). */
+    get limit(): number;
+    set limit(v: number);
+    protected push(): void;
+}
+/** Inverse kinematics aspects — attach to bones (see file header). */
+export declare const IK: {
+    TwoBone: typeof TwoBone;
+    LookAt: typeof LookAt;
+};
+export type IKTwoBone = TwoBone;
+export type IKLookAt = LookAt;
+export {};

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

@@ -2,7 +2,8 @@
 export type WarpOptions = {
     /** Fit the stride to the speed the body actually travels at. `[min, max]` clamps the scale (default
      *  0.85…1.2). A CORRECTION: a pack whose takes already read right at the speeds it is played at wants
-     *  none of this; open the range for a pack that must cover speeds it was never recorded at. */
+     *  none of this; open the range for a pack that must cover speeds it was never recorded at. The clip's
+     *  own speed is its root motion — an in-place loop takes part only with a declared pace (see above). */
     stride?: boolean | [number, number];
     /** Turn the lower body toward where the body really travels; a number caps the turn in degrees
      *  (default 20). The whole twist lives in one joint: a few degrees read as a lean, a lot as a broken

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

@@ -13,15 +13,24 @@ export type PlayOptions = {
     fade?: number;
     /** Transition seconds for the way in only (overrides `fade`). */
     fadeIn?: number;
-    /** 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. */
+    /** One-shots: the transition BACK to the loop after the end (overrides `fade`; `0` = cut at the end).
+     *  The clip plays to its last frame; the loop then takes over and the difference between the two poses
+     *  (and their velocities) decays over this time, so no part of the clip is cut — to play less of it,
+     *  give it an `end`. 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;
     /** Rewind even if the clip is already playing (default: rewind only if it isn't). */
     restart?: boolean;
+    /** Play a WINDOW of the clip, seconds of the clip: enter at `start` (default 0; only when the play
+     *  rewinds — see `restart`) and treat `end` (default the clip's end) as the end — the hand-over fires
+     *  there, the last frame held there, events beyond it never fire. Only the swing of a longer take, the
+     *  wind-up without the recovery. A window that lives in the clip table belongs in
+     *  `AnimationClip.from(clip, { from, to })` instead. Not combined with `phase`. Hosts without the
+     *  window play the whole clip. */
+    start?: number;
+    end?: number;
     /** Enter the clip at a point in the GAIT CYCLE instead of at its start: `'match'` = the phase the
      *  layer shows right now (the walk's left foot is down → the turn clip starts where its left foot
      *  is down too, so nothing slides), or a number 0–1. Clips without a gait cycle ignore it. */
@@ -302,6 +311,9 @@ export declare class Core {
     private clipNames;
     /** Create the native animator on demand. False = nothing to animate (warned). */
     ensure(): boolean;
+    /** The native animator for the RIG alone — an IK chain or a socket on a model that has no clips
+     *  still needs the joint tree described to the engine. False = no transform hierarchy (warned). */
+    ensureRig(): boolean;
     destroy(): void;
     newLayer(options?: LayerOptions): LayerRec;
     addLayer(options: LayerOptions): Layer;
@@ -392,12 +404,31 @@ export declare class Core {
     /** Stride / orientation warping, as the engine's fixed-order parameter array. */
     private _warp?;
     setWarp(params: Float32Array): void;
+    /** The body's world velocity this frame (m/s) — the game side of the stride / orientation fit. Nothing
+     *  to feed before the animator exists; hosts without the warp stage have no method. */
+    setMotion(vx: number, vy: number, vz: number): void;
     /** The feet stage (lock / ground IK), as the engine's fixed-order parameter array. */
     private _feetParams?;
     setFeetParams(params: Float32Array): void;
     /** One foot's lock state after this frame's evaluation into `out` (8 floats); false = no such foot
      *  or no feet stage on this host. */
     footState(side: 0 | 1, out: Float32Array): boolean;
+    private static _warnedIk;
+    private hasIk;
+    /** A chain ending in `endEntity` (kind 0 two-bone: the bone, its parent, its grandparent; 1 look-at). 0 = none. */
+    ikCreate(kind: 0 | 1, endEntity: number): number;
+    ikDestroy(ik: number): void;
+    ikSet(ik: number, params: Float32Array): void;
+    ikNodes(ik: number, target: number, pole: number, rotation: number): void;
+    ikAnchor(ik: number, socket: string): void;
+    ikState(ik: number, out: Float32Array): boolean;
+    /** Sockets by "set/name", replayed when the animator is (re)created. */
+    private readonly _sockets;
+    /** Define a socket on joint `joint` (a bone's entity): a NODE socket (read by the engine every frame) or a
+     *  fixed TRS in the joint's space. set "" = the live set, any other name = a donor's. */
+    setSocket(set: string, name: string, joint: number, node: number, trs: Float32Array | null): void;
+    removeSocket(set: string, name: string): void;
+    private pushSocket;
     private readonly _steps;
     onStepHandler(cb: StepHandler): void;
     offStepHandler(cb: StepHandler): void;

package/dist/types/gl/{AudioSource.d.ts → audio/AudioSource.d.ts}

@@ -1,9 +1,9 @@
-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";
+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;

package/dist/types/gl/{AudioZone.d.ts → audio/AudioZone.d.ts}

@@ -1,7 +1,7 @@
-import { Aspect } from "../core/Aspect";
-import { type ReverbParams, type ReverbPreset } from "../audio/Bus";
-import { type Vec3Like } from "../math/vec";
-import type { Node } from "./Node";
+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;

package/dist/types/gl/{SceneAudio.d.ts → audio/SceneAudio.d.ts}

@@ -1,4 +1,4 @@
-import type { Node } from "./Node";
+import type { Node } from "../Node";
 export declare class SceneAudio {
     private _listener;
     private _doppler;