lecodes-sdk 1.0.0 → 1.2.0

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

@@ -2,46 +2,102 @@ 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;
-/** 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. */
-declare class TwoBone extends Aspect<"ik", Node> {
-    static readonly aspect = "ik";
-    /** Where the end bone should be (Node or world position). */
-    target?: Target;
-    /** Bend hint — the mid joint is pulled toward it (Node or world position). */
-    pole?: Target;
-    /** World rotation the END bone takes after the solve — a Node (its world rotation) or a Quat.
-     *  Unset = the end bone keeps its animated local rotation (a hand on a grip, a foot on a slope
-     *  want it set). Blended by `weight · rotationWeight`. */
-    rotation?: Node | Quat;
-    /** 0–1 contribution of `rotation` (on top of `weight`). */
-    rotationWeight: number;
+/** 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). */
-    weight: number;
-    /** Solve every frame (default). Set false to drive `solve()` yourself. */
-    enabled: boolean;
-    update(): void;
-    /** One solve at the current pose. Safe to call manually (e.g. from a later-ordered aspect). */
-    solve(): void;
+    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 Aspect<"lookAt", Node> {
+declare class LookAt extends Chain<"lookAt"> {
     static readonly aspect = "lookAt";
-    target?: Target;
+    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. */
-    axis: Vec3Like;
+    get axis(): Vec3Like;
+    set axis(v: Vec3Like);
     /** Max deflection from the animated direction, in degrees (default 80). */
-    limit: number;
-    /** 0–1 contribution. */
-    weight: number;
-    enabled: boolean;
-    update(): void;
-    solve(): void;
+    get limit(): number;
+    set limit(v: number);
+    protected push(): void;
 }
 /** Inverse kinematics aspects — attach to bones (see file header). */
 export declare const IK: {

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

@@ -6,8 +6,9 @@ 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. */
-export type LocomotionState = "idle" | "start" | "move" | "turn" | "stop" | "spin";
+/** What the engine shows: the idle, a start, the gait loop, a turn while moving, a stop, a turn on the spot —
+ *  an ACTION (`act()`): a one-shot that owns the body until it hands over — or the STRAFE blend (`move({ strafe })`). */
+export type LocomotionState = "idle" | "start" | "move" | "turn" | "stop" | "spin" | "action" | "strafe";
 /** Who moves the body:
  *  `'hybrid'` (the default) — the clip's own recorded motion moves it; while the gait loop shows it
  *    is ADJUSTED toward what the simulation wants by at most `tuning.adjust` metres a second, and a
@@ -42,6 +43,10 @@ export type LocomotionSet = {
     turns?: LocomotionClip[];
     /** turns on the spot — what a facing still owed by a standing body plays */
     spins?: LocomotionClip[];
+    /** the STRAFE set: the same gait recorded forward, backward, to either side and on the diagonals — the members of
+     *  the directional blend `move(dir, { face, strafe: true })` shows. `angle` = the way a take travels in the body's
+     *  frame (degrees, + = left); left out, the engine reads it off the take's root. */
+    strafes?: LocomotionClip[];
 };
 /** The tuning. Times are seconds, speeds m/s, angles degrees. */
 export type LocomotionTuning = {
@@ -199,6 +204,8 @@ export declare class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     private _mag;
     private _gait;
     private _seq;
+    private _act;
+    private _strafe;
     private readonly _in;
     private readonly _out;
     private readonly _names;
@@ -225,11 +232,53 @@ export declare class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     /** State the movement intent for this frame: a world direction (its length is the stick's pull,
      *  clamped to 1) and the gait. `null` = no movement — the body stops, but it keeps facing where it
      *  was last asked to, and turns there on the spot if it still owes the turn.
-     *  `face` states a facing of its own (aiming, strafing, a camera-relative shooter). */
+     *  `face` states a facing of its own (aiming, a camera-relative shooter) — and with `strafe: true` the body MOVES
+     *  where the direction points while it faces there: the loop becomes the directional blend of `set.strafes` (a
+     *  guard, a lock-on), the facing is steered standing too, state `'strafe'`. Stated every frame like the rest. */
     move(direction: Vec3Like | null | undefined, options?: {
         gait?: Gait;
         face?: Vec3Like;
+        strafe?: boolean;
     }): void;
+    /** Play an ACTION: a one-shot that OWNS the body the way a start or a stop does — a roll, a backstep, a lunging
+     *  attack. Its recording moves the body alone (in every displacement mode but `'data'`, where the host does),
+     *  the steering and the selector stand by, and when it hands over the usual rules carry on: a direction held
+     *  starts (or, still carrying speed, runs on), nothing held stands.
+     *
+     *  `direction` is where its TRAVEL must go, world (`Vec3`, or a heading in degrees, 0 = +Z, + = toward +X). A
+     *  clip travels some way relative to the body — forward, left, back; measured off its own root, or `angle`
+     *  (degrees, + = left) — and the body is turned by what is left between that and `direction`, over `turn`
+     *  seconds (default 0.12), so the travel lands exactly where it was pointed. Which clip to play is yours to
+     *  pick: the one whose travel is nearest the direction IN THE BODY'S FRAME (`direction − facing`) leaves the
+     *  least to turn. Left out = it plays where the body faces.
+     *
+     *  `at` enters the clip that many seconds in (a wind-up skipped), `rate` plays it faster or slower (its metres
+     *  stay, the time changes), `travel` takes only that share of its recorded travel (an attack aimed at a target:
+     *  0.3 to stop at the blade's length from one that is close, 1.3 to reach one a step too far — the pose is
+     *  untouched, so keep it to a fast step; `{ share, at, after }` takes another share from clip time `at` on: a
+     *  swing's take travels on after its cut, into a body that stands at the blade's length), `fade` is the transition into it and `out` the one out of it (default: the tuning's
+     *  `blend`; an action ends in ITS stance, not the idle's, and a longer way out is what hides that), and `exit` is the
+     *  clip time from which a MOVE intent may take over — the cancel window: along the way the body faces at once, a
+     *  heading that needs a turn as soon as the body has slowed to where a start can answer; with nothing asked for it plays out, to
+     *  its end (an action ends in its own recovery, at rest), and the body then STANDS THE WAY THE ACTION LEFT IT:
+     *  the facing intent that outlives a released key is not a demand after an action — no turn on the spot.
+     *  WHEN an action may be asked for (out of another one, out of a start) is the caller's rule: this cuts into
+     *  whatever shows. `state` reads `'action'` while it does. False = no such clip. */
+    act(clip: string, options?: {
+        direction?: Vec3Like | number;
+        angle?: number;
+        turn?: number;
+        at?: number;
+        exit?: number;
+        fade?: number;
+        out?: number;
+        rate?: number;
+        travel?: number | {
+            share: number;
+            at: number;
+            after: number;
+        };
+    }): boolean;
     /** Face this way without moving — the facing intent on its own (`Vec3`, or a heading in degrees,
      *  0 = +Z, + = toward +X). A standing body turns to it on the spot. */
     face(direction: Vec3Like | number): void;

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

@@ -33,6 +33,31 @@ export interface RagdollPart {
     /** A one-way joint instead of the cone. */
     hinge?: RagdollHinge;
 }
+/** How the body lies: on its back (the chest points up), prone (the chest points down), or on a side. */
+export type RagdollFacing = "up" | "down" | "side";
+export interface RagdollActivateOptions {
+    /** A LAUNCH added to every part's own motion (world m/s) — an explosion, a throw. The bones' own
+     *  motion (the run, the swinging arms) is measured by the engine and needs no help. */
+    velocity?: Vec3Like;
+    /** The motors' strength from the first step (default: the current `strength`). */
+    strength?: number;
+    /** The root anchored to the animation from the first step (default: the current `anchored`). */
+    anchored?: boolean;
+}
+export interface RagdollDeactivateOptions {
+    /** Seconds the animator takes to transition OUT of the fallen pose into whatever plays next (a
+     *  get-up take started right after, or the loop). 0 (default) = a cut. Move the model node under
+     *  the hips before this call: the bones are handed back against its new transform. */
+    blend?: number;
+}
+export interface RagdollHitOptions {
+    /** How long the body stays powered before the bones go back to the animator (s, default 0.6). */
+    duration?: number;
+    /** The transition out of the reaction's last physical pose (s, default 0.25). */
+    blend?: number;
+    /** The motors' strength during the reaction (default 1). */
+    strength?: number;
+}
 export declare class Ragdoll extends Aspect<"ragdoll", Node> {
     static readonly aspect = "ragdoll";
     /** The parts: `'humanoid'` (default) finds the standard bones by name; a list places bodies on any
@@ -51,36 +76,86 @@ export declare class Ragdoll extends Aspect<"ragdoll", Node> {
      *  never shoves or blocks anything and costs nothing when they meet. `'all'`: a regular dynamic
      *  body that bumps into everything (and gets kicked awake by everything). */
     collide: "static" | "all";
-    /** Once every part has come to rest the parts turn static where they lie (default true): the pose
-     *  holds, nothing can wake a settled body and it costs the solver nothing — `deactivate()` /
-     *  `activate()` still work (activate makes it dynamic again). */
+    /** Once every part of a LIMP body has come to rest the parts turn static where they lie (default
+     *  true): the pose holds, nothing can wake a settled body and it costs the solver nothing —
+     *  `deactivate()` / `activate()` still work (activate makes it dynamic again). A driven or anchored
+     *  body never freezes. */
     freeze: boolean;
-    /** Seconds after `activate()` at which the body freezes whatever it is doing — a twitch on a slope
-     *  or a pile never sleeps on its own. 0 (default) = no cap. */
+    /** Seconds limp after which the body freezes whatever it is doing — a twitch on a slope or a pile
+     *  never sleeps on its own. 0 (default) = no cap. */
     freezeAfter: number;
+    /** The joint motors: the position spring's frequency in Hz (default 6 — higher = a stiffer, quicker
+     *  return to the animated pose) and damping ratio (default 1 = critical, no overshoot). */
+    driveFrequency: number;
+    driveDamping: number;
+    /** The motors' torque limit at strength 1, in N·m per kg of the part (default 12: ~180 N·m at the
+     *  hips of an 80 kg body, ~25 at a forearm). Lower = a hit displaces a limb more before the
+     *  animation wins it back. */
+    driveTorque: number;
+    /** Joint friction in N·m per kg of the part (default 0.3): a torque that resists any joint motion,
+     *  motor or not — a limp body folds instead of flopping like jelly. */
+    jointFriction: number;
+    /** Where the joint limits come from. `'clips'` (default): measured from the animation — at the first
+     *  activation that finds clips on the model's animator, every joint's swing and twist range over
+     *  every bound clip becomes its limit (plus `limitsMargin` on each side), so the motors never
+     *  target a pose the limits forbid and a limp body settles into poses the clips use; until clips
+     *  are bound the part table's cones apply. `'table'`: the part table's cones and hinges only. */
+    limits: "clips" | "table";
+    /** Degrees added on each side of a learned range (default 10). */
+    limitsMargin: number;
     static fields: FieldMeta<Ragdoll>;
     private _id;
     private _active;
     private _bones;
+    private _strength;
+    private _anchored;
+    private _hipsFwd;
+    private _hipsUp;
+    private _ramp;
+    private _release;
     onAttach(): void;
     onDetach(): void;
-    /** Hand the bones to physics from the pose they are in right now. `velocity` (world m/s) is given
-     *  to every part — pass the character's, so a running body keeps travelling. */
-    activate(opts?: {
-        velocity?: Vec3Like;
-    }): boolean;
-    /** Take the bones back: the animator's pose shows again from the next frame. */
-    deactivate(): void;
+    /** Hand the bones to physics from the pose they are in right now, each moving as it did over the
+     *  last two frames (the engine measures: a runner keeps travelling, a swinging arm keeps swinging). */
+    activate(opts?: RagdollActivateOptions): boolean;
+    /** Take the bones back: the animator's pose shows again from the next frame — through a `blend`
+     *  out of the fallen pose when asked (play the get-up take right after, with its own fade: it
+     *  starts from where the body lies). */
+    deactivate(opts?: RagdollDeactivateOptions): void;
     /** Physics owns the bones right now. */
     get active(): boolean;
     /** Active and every part asleep (or frozen) — the body has come to rest. */
     get settled(): boolean;
+    /** The joint motors' strength, 0..1: how hard every joint is pulled toward the pose the animator
+     *  shows (0 = off — a limp body). Kept across activations. */
+    get strength(): number;
+    set strength(v: number);
+    /** The hips follow the animation kinematically (the body stands in its clip while physics moves the
+     *  limbs — hit reactions, a stagger). Off = the hips are a free body (a fall). */
+    get anchored(): boolean;
+    set anchored(v: boolean);
+    /** The joints give way: the strength ramps to 0 over `seconds` and the anchor comes off — a body
+     *  shot mid-stride keeps its pose for a moment and then collapses, instead of switching off. */
+    goLimp(seconds?: number): void;
+    /** A flinch: the body powers up anchored to its animation (if it is not already active), the struck
+     *  part gets the impulse (N·s, at a world point), and after `duration` the bones go back to the
+     *  animator through `blend`. On a limp body (a corpse) it is just the impulse. */
+    hit(bone: string, v: Vec3Like, at?: Vec3Like, opts?: RagdollHitOptions): boolean;
     /** The root part's bone (the hips): where the body is. */
     get root(): Node | null;
+    /** How the body lies: `'up'` on its back (the chest points up), `'down'` prone, `'side'` otherwise.
+     *  Read while it is down, to pick the get-up take. */
+    get facing(): RagdollFacing;
+    /** Where the head points along the ground, as a yaw in degrees (the model node's `eulerAngles` y
+     *  that faces that way): where a get-up take that rises head-first ends up facing. A body still
+     *  upright answers with the way its chest faces. */
+    get heading(): number;
     /** The bones that carry a part, in order. */
     get bones(): string[];
     /** The rigid-body id of a part (0 if none) — for the plain body calls. */
     bodyOf(bone: string): number;
     /** Push one part: an impulse in N·s, at a world point (a hit) or through its centre. Wakes the body. */
     impulse(bone: string, v: Vec3Like, at?: Vec3Like): boolean;
+    /** The strength ramp (goLimp) and the hit reaction's hand-back. */
+    update(dt: number): void;
 }

package/dist/types/gl/terrain/Terrain.d.ts

@@ -5,11 +5,13 @@ import { Geometry } from "../Geometry";
 import { type ColorInput } from "../../core/color";
 import { Vec3, type Vec3Like } from "../../math/vec";
 export type TerrainLayer = {
-    /** Albedo texture (a URL / `asset()` handle, or a loaded Texture). Unset = white. */
+    /** Albedo texture (a URL / `asset()` handle, or a loaded Texture). Unset = white. Its ALPHA is the layer's roughness
+     *  map (`lecodes assets terrain-pack --roughness` puts it there): an opaque albedo reads 1. */
     albedo?: string | Texture;
     /** Metres per texture repeat. Default 8. */
     tiling?: number;
-    /** Perceptual roughness of the layer. Default 1. */
+    /** Perceptual roughness of the layer — a factor on the albedo's alpha (its roughness map), the whole value when the
+     *  albedo is opaque. A terrain has no metallic: ground is a dielectric. Default 1. */
     roughness?: number;
     /** Normal-map strength (0 = the layer's slot of the pack is not read). Default 0 — set 1 when the
      *  layer has a normal map in `normals`. */
@@ -174,6 +176,14 @@ export declare class Terrain {
     heightAt(x: number, z: number): number;
     /** The drawn triangle's normal at a local (x, z) (unit Vec3, +Y up). */
     normalAt(x: number, z: number): Vec3;
+    /** The LAYER WEIGHTS at a local (x, z) — what the splat shader blends there: the control map read bilinearly
+     *  between its samples and normalised to sum 1 (`[1, 0, 0, 0]` where the map is empty, as the shader has
+     *  it). Index = the layer's in `layers`. Outside the grid the edge answers. This is how a game asks WHAT the
+     *  ground is under a point — footprints in the sand and none on the cobble, a footstep sound per layer, dust
+     *  by surface — and the blend is already in the numbers, so a transition is a fade and not a line. */
+    weightsAt(x: number, z: number): [number, number, number, number];
+    /** The heaviest layer's index at a local (x, z) — `weightsAt` when only "which one" is asked. */
+    layerAt(x: number, z: number): number;
     /** The smooth (vertex) normal at integer sample (ix, iz). */
     sampleNormal(ix: number, iz: number): Vec3;
     /** Extent in local metres: `[width, depth]`. */

package/dist/types/inject.d.ts

@@ -58,8 +58,12 @@ export { Presentable } from "./ui/UI";
 export type { PresentOptions, Transition, TransitionName, TransitionSpec, TransitionTransform } from "./ui/UI";
 export type { UINode, UINodeChild } from "./ui/UINode";
 export { theme, type ThemeValues, type ThemeAccessors } from "./ui/theme";
-export { animate, animateMat4, stopAnimation, pauseAnimation, resumeAnimation } from "./animate/animate";
+export { animate, type AnimateOptions, type AnimateValue, type AnimateOut } from "./animate/tween/animateValue";
 export { cubicBezier } from "./animate/bezier";
+export { Timeline, type TimelineOptions, type TimelineAddOptions, type TimelinePosition } from "./animate/tween/Timeline";
+export { type Animation } from "./animate/tween/Animation";
+export { type TweenMeta } from "./animate/tween/spec";
+export { type EasingInput } from "./animate/tween/easing";
 export { easeIn, easeOut, easeInOut } from "./animate/easings";
 export { QRScanner } from "./plugins/qr";
 export { CameraView, type CameraFacing } from "./plugins/camera";
@@ -96,7 +100,7 @@ export { Vehicle } from "./gl/vehicle/Vehicle";
 export type { DriveLayout, DifferentialMode, EngineConfig, SteeringConfig, SteeringFeedback, SteeringDriver, AeroConfig } from "./gl/vehicle/Vehicle";
 export { Wheel, Tire, resolveTire } from "./gl/vehicle/Wheel";
 export { Ragdoll } from "./gl/physics/Ragdoll";
-export type { RagdollPart, RagdollHinge } from "./gl/physics/Ragdoll";
+export type { RagdollPart, RagdollHinge, RagdollFacing, RagdollActivateOptions, RagdollDeactivateOptions, RagdollHitOptions } from "./gl/physics/Ragdoll";
 export type { Point, WheelSuspension } from "./gl/vehicle/Wheel";
 export { AnimationClip } from "./gl/animation/AnimationClip";
 export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/animation/AnimationClip";
@@ -117,6 +121,8 @@ export type { DynamicBoneCurve, DynamicBoneFloor, DynamicBoneColliders } from ".
 export type { IKTwoBone, IKLookAt } from "./gl/animation/IK";
 export { Light } from "./gl/Light";
 export { Lightmap } from "./gl/Lightmap";
+export { Foliage } from "./gl/Foliage";
+export type { FoliageOptions, FoliageWind } from "./gl/Foliage";
 export { Terrain } from "./gl/terrain/Terrain";
 export type { TerrainOptions, TerrainLayer, TerrainRegion, ConformOptions, RibbonOptions, AutoPaintRules, SculptOptions, TerrainHit, TerrainSnapshot } from "./gl/terrain/Terrain";
 export { NavMesh, NavCrowd } from "./gl/nav/NavMesh";

package/dist/types/runtime/input.d.ts

@@ -82,6 +82,13 @@ export interface GamepadState {
     axis(name: GamepadAxisName, deadzone?: number): number;
     /** Held? Same as `Input.key(code, index)`. */
     button(code: string): boolean;
+    /** Rumble: `strong` = the heavy low-frequency motor, `weak` = the light high-frequency one, both
+     *  0..1, for `durationMs` (default 200, hosts cap at 5000). A new call replaces the running
+     *  effect. The host stops the motors by itself — after the duration, on focus loss and when the
+     *  project is swapped — so there is nothing to clean up. False when the pad or host has no motors. */
+    rumble(strong: number, weak?: number, durationMs?: number): boolean;
+    /** Stop the running rumble now. */
+    stopRumble(): void;
 }
 export declare const Input: {
     /**

package/dist/types/scene/defineScene.d.ts

@@ -5,6 +5,8 @@ import { Scene, type SceneOptions } from "../gl/Scene";
 import { Node } from "../gl/Node";
 import { Mesh } from "../gl/Mesh";
 import { Model } from "../gl/Model";
+import { type LightmapTransmit } from "../gl/Lightmap";
+import { type FoliageOptions } from "../gl/Foliage";
 import { type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/terrain/Terrain";
 import { Light, type SunOptions } from "../gl/Light";
 import { type MaterialDef } from "./material";
@@ -130,6 +132,12 @@ export type SceneNodeDef = {
      *  Default: static unless a `Physics` aspect moves the node (`dynamic` — Physics' default — or
      *  `kinematic`). Set it only to override that rule; prefab subtrees inherit the verdict. */
     lightmap?: boolean;
+    /** `model` nodes: vegetation — load through the FOLIAGE tier (wind, touch bending, per-copy tint; see
+     *  `Foliage`). `{ fade: [start, end] }` also thins the cards out over that distance range (m) and drops the
+     *  copy past `end` — for ground cover. The fade is per ASSET: every node of the same GLB shares it. */
+    foliage?: boolean | {
+        fade?: [number, number];
+    };
     /** Navigation (a scene with `env.navmesh`, see navmesh.md): every STATIC body is walkable by
      *  default. `false` leaves this one out of the bake; `'unwalkable'` cuts its footprint out
      *  (nobody stands on or crosses it). */
@@ -144,41 +152,44 @@ export type SceneCameraDef = CameraProjectionDef & {
     /** Point the camera looks at. */
     target?: Vec3Like;
 };
-/** `env.lightmap` — the level's baked lighting (see lightmap.md): the two files
- *  `lecodes lightmap bake` writes, plus how the bake is applied. Absent = real-time only. */
+/** `env.lightmap` — the level's baked lighting (packages/creator-bake): the files `lecodes lightmap bake`
+ *  writes. Absent = real-time only. */
 export type SceneLightmapDef = {
-    /** `asset('./assets/lightmap/lightmap.bake')` */
+    /** `asset('./assets/lightmap/level.bake')` */
     data: string;
-    /** `asset('./assets/lightmap/lightmap.ktx2')` — or, for a bake that took more than one atlas PAGE
-     *  (`lecodes lightmap bake --pages`), every page in order: `[asset('x.ktx2'), asset('x_1.ktx2')]`. */
-    texture: string | string[];
-    /** `asset('./assets/lightmap/lightmap-light.ktx2')` (pages like `texture`) — the point lights' baked
-     *  irradiance the bake writes when the level holds point lights; the real-time lights it carries are
-     *  switched off once it applies. Absent = the lamps stay real-time. */
-    light?: string | string[];
-    /** `asset('./assets/lightmap/lightmap.volume')` — the light VOLUME for everything that moves (the
-     *  same bake writes it): dynamic nodes, and every model loaded in code while the level runs, read
-     *  the baked sun/ambient at their own position. Absent = movers stay real-time only. */
+    /** `asset('./assets/lightmap/level-light.ktx2')` — or, for a bake that took more than one atlas PAGE
+     *  (`lecodes lightmap bake --pages`), every page in order: `[asset('x-light.ktx2'), asset('x-light_1.ktx2')]`. */
+    light: string | string[];
+    /** `asset('./assets/lightmap/level-aux.ktx2')` (pages like `light`) — sun / sky visibility + light direction. */
+    aux: string | string[];
+    /** DEBUG: the page sets a `lecodes lightmap bake --split` wrote (`<stem>-direct[_n].ktx2`, `<stem>-indirect[_n].ktx2`),
+     *  pages like `light` — the `Lightmap.debug("direct" | "indirect")` views bind them in place of `light`. */
+    direct?: string | string[];
+    indirect?: string | string[];
+    /** `asset('./assets/lightmap/level-probes.ktx2')` — the bake's reflection probes (one prefiltered cubemap of the level's
+     *  radiance per probe; every static reflects the nearest). Absent = statics reflect the sky's SH alone. */
+    probes?: string;
+    /** FOR THE BAKE: the radiance in cd / m² of emission 1.0 on this level (emissive factor x strength x map) - every lit
+     *  region of an emissive surface bakes as a rectangle lamp. An imported pack's emission is a LOOK (the school's panels
+     *  say 10); this is where the level says what they give: a 1.3 m ceiling panel of ~8000 lm is ~1600 nits. Default: what
+     *  the camera makes of 1.0 (`1.2 x 2^EV100`). 0 = emissive surfaces light nothing. `--emissive-nits` overrides. */
+    emissiveNits?: number;
+    /** `false` = the emissive surfaces light nothing in the bake - the level is lit by its lamps (`Light.point` with a
+     *  `bakeArea` next to every panel, the Unity packs' way) and the panels are decoration; `emissiveNits` then only says how
+     *  bright their glow is DRAWN (scene-referred: nits through the camera's exposure). Default true. */
+    emissiveBake?: boolean;
+    /** FOR THE BAKE: materials that let light THROUGH them, by glTF material name (`"name*"` = every name with that start) →
+     *  the share of a shadow ray that passes, tinted by the material's base colour x map: `{ mat_awning: 0.3 }` puts the
+     *  awning's warm, patterned light on the sand. The surface stays opaque - baked, drawn as before, a shadow caster.
+     *  `{ through, diffuse }` splits it: `through` goes straight (the picture of the map), `diffuse` is scattered by the
+     *  fibres (the underside glows, a soft fill with no picture) - dense canvas: `{ through: 0.08, diffuse: 0.25 }`. */
+    transmit?: Record<string, LightmapTransmit>;
+    /** `asset('./assets/lightmap/level.lgrid')` — THE LIGHT GRID for movers: every node a Physics aspect or a
+     *  CharacterController moves (and what code marks with `Lightmap.track`) takes its ambient light from the bake at the
+     *  place it is at, whatever its shader. Absent = movers keep the scene's IBL. */
     volume?: string;
-    /** 1 = baked sun shadows at full strength, 0 = ambient occlusion only. Default 1. */
-    sunStrength?: number;
-    /** Multiplier on the ambient share in the shadow math (1 = filament's own darkness). Default 1. */
-    ambientScale?: number;
-    /** How much of the baked ambient occlusion applies: 1 = all of it, 0 = none. An interior lit by its
-     *  ambient probe alone can want less than the geometric truth. Default 1. */
-    aoStrength?: number;
-    /** Multiplier on the baked point lights' irradiance (default 1) - dial the lamps up or down
-     *  without a re-bake, since their irradiance lives in the atlas. Scales the light volume with the
-     *  atlas, so movers match the statics. See `LightmapLoadOptions.lightBoost`. */
-    lightBoost?: number;
-    /** Multiplier on the light VOLUME's irradiance alone (default = `lightBoost`). Since the volume is an
-     *  ambient cube (2026-08-31) movers shade like the statics and the default is right; it stays as a
-     *  trim. See `LightmapLoadOptions.volumeBoost`. */
-    volumeBoost?: number;
-    /** Occluder-only statics (props without lightmap UVs): `"baked"` (default) = their shadow is in the
-     *  atlas, they stop casting in real time and the shadow pass draws only the movers; `"realtime"` =
-     *  they keep casting (their shadow on other non-receiver props). See `LightmapLoadOptions.occluderShadows`. */
-    occluderShadows?: "baked" | "realtime";
+    /** A DEBUG multiplier on the atlas' lux (default 1). */
+    lightScale?: number;
 };
 /** `env.navmesh` — the level's navigation mesh (see navmesh.md): the file `lecodes navmesh bake`
  *  writes, the agent size it is built for, and the named areas. Absent = no navigation. */
@@ -199,6 +210,7 @@ export type SceneDef = {
     env?: SceneOptions & {
         lightmap?: SceneLightmapDef;
         navmesh?: SceneNavmeshDef;
+        foliage?: FoliageOptions;
     };
     camera?: SceneCameraDef;
     nodes?: Record<string, SceneNodeDef>;