lecodes-sdk 1.0.0 → 1.1.0

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

@@ -1,6 +1,13 @@
 import { type ColorInput } from "../core/color";
 import type { Vec3Like } from "../math/vec";
-import { Node } from "./Node";
+import { Node, type NodeTweenProps } from "./Node";
+import { type TweenMeta } from "../animate/tween/spec";
+import type { Animation } from "../animate/tween/Animation";
+/** Animatable light props on top of the node transform. */
+export type LightTweenProps = NodeTweenProps & {
+    intensity?: number | number[];
+    color?: ColorInput | ColorInput[];
+};
 export type SunOptions = {
     /** Light direction (points where the light travels). Defaults to a typical key-light angle. */
     direction?: Vec3Like;
@@ -41,17 +48,27 @@ export type PointOptions = {
     /** Point-light shadows are a cubemap render per light; off by default. */
     castShadows?: boolean;
     /**
-     * Whether `lecodes lightmap bake` bakes this light into the level's lightmap (docs/lightmap-plan.md).
-     * A baked light is switched OFF at runtime once the bake applies — statics read it from the atlas,
-     * movers from the light volume — so it costs nothing per frame; a light that must stay live (a
-     * flicker, a lamp the player can shoot out) says `baked: false` and is kept out of the bake.
-     * Lights created after the level loads (a muzzle flash) are never in a bake. Default true.
+     * Whether `lecodes lightmap bake` bakes this light into the level's lightmap. A baked lamp lights the statics
+     * from the atlas and the MOVERS from the level's light grid, and is held dark in real time while that grid is
+     * loaded (without a grid it keeps lighting the movers live); a light
+     * that must reach the statics live too — a flicker, a lamp the player can shoot out, a muzzle flash —
+     * says `baked: false`: it is kept out of the bake and put on the statics' light channel. Default true.
      */
     baked?: boolean;
+    /**
+     * THE BAKE'S SHAPE of this lamp: `[width, height]` in metres = an AREA light - a rectangle in the light's local XZ
+     * plane, emitting along its local -Y (down, for an unrotated node) with the same lumens: a ceiling panel. The bake
+     * lights from the whole rectangle (soft shadows, light from where the panel is and not from a point inside the
+     * fixture). Real time it is still the point light above. Ignored with `baked: false`.
+     */
+    bakeArea?: readonly [number, number];
 };
 export declare class Light extends Node {
     private _intensity;
-    /** The most recently created sun — what `Lightmap.load` uses unless told otherwise. */
+    /** Tween `intensity` / `color` (a flash, a sunrise) and the transform — see {@link Node.animateTo}. */
+    animateTo(props: LightTweenProps & TweenMeta): Animation;
+    animateFrom(props: LightTweenProps & TweenMeta): Animation;
+    /** The most recently created sun. */
     static lastSun: Light | null;
     _shadowDistance: number;
     /** A directional sun light. */
@@ -69,6 +86,7 @@ export declare class Light extends Node {
     /** Live intensity (sun: lux, point: lumens) — animate a flash without rebuilding the light. */
     get intensity(): number;
     set intensity(value: number);
+    _holdDark(dark: boolean): void;
     destroy(): void;
     set color(value: ColorInput);
     get color(): ColorInput;

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

@@ -1,94 +1,124 @@
 import { Node } from "./Node";
 import type { Scene } from "./Scene";
 export type LightmapLoadOptions = {
-    /** 1 = baked sun shadows at full strength, 0 = ambient occlusion only. Default 1. */
-    sunStrength?: number;
-    /** Multiplier on the ambient (IBL) share in the shadow math — how bright a fully shadowed texel
-     *  stays. 1 reproduces filament's own real-time shadow darkness (the shader reads the scene's sun
-     *  and IBL from filament's per-frame uniforms); raise it for lighter shadows, lower for deeper. 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). Purely ARTISTIC: the bake is
-     *  physical (verified against the analytic 1/d^2 sum over the level's lamps - where line of sight
-     *  is clear the two agree within ~17 %), and a room lit to its real illuminance simply reads dim
-     *  against an ambient fill. This dials the lamps up without a re-bake, since their irradiance is
-     *  IN the atlas and `--lamp-gain` would cost a full one.
-     *  It scales the atlas AND the light volume together, so statics and movers stay consistent - but
-     *  note they are NOT equally forgiving: a static surface carries the bake's own cosine and
-     *  shadowing, while a mover reads the volume through a flat half-cosine, so a large boost blows
-     *  movers out long before it blows out the level. Past ~x100 expect to light the movers
-     *  separately. */
-    lightBoost?: number;
-    /** Multiplier on the light VOLUME's irradiance alone — the movers' own `lightBoost`. Default =
-     *  `lightBoost`, and since 2026-08-31 that default is the right one: the volume is an ambient cube
-     *  (irradiance per axis face, blended by the pixel's normal), so a mover's top takes a lamp above it
-     *  and its underside does not — the same shading the atlas gives the statics. Before that the volume
-     *  was one flat 0.5·E on every face and this knob was the workaround. Kept as a trim. */
-    volumeBoost?: number;
-    /** What an OCCLUDER-only static (a prop without lightmap UVs — traced into the receivers' atlas but
-     *  carrying no rect of its own) does in real time. `"baked"` (default): its shadow is in the bake, so
-     *  it stops casting and the shadow pass draws only the movers — on a level of thousands of foliage
-     *  cards that is a third of the GPU frame. `"realtime"`: it keeps casting, which is the only way its
-     *  shadow reaches OTHER non-receiver props (a rock under a tree); the honest fix for that is lightmap
-     *  UVs on the props (`lecodes assets doctor --lightmap-uv`), which makes them receivers. */
-    occluderShadows?: "baked" | "realtime";
+    /** A DEBUG multiplier on the atlas' lux (default 1): the atlas is physical, so this is a knob for looking,
+     *  not a look. */
+    lightScale?: number;
+    /** The level's own radiance of emission 1.0 for the BAKE (cd / m², `BakeConfig.emissiveNits`): an imported pack's
+     *  emissive values are tuned for a look, not for light - this is where the level says how much its panels really give.
+     *  The CLI's `--emissive-nits` wins over it; without either the camera's exposure decides. */
+    emissiveNits?: number;
+    /** `false` = the emissive surfaces light NOTHING in the bake (the level is lit by its lamps, the panels are decoration)
+     *  while `emissiveNits` still says how bright their glow is drawn. Default true. */
+    emissiveBake?: boolean;
+    /** FOR THE BAKE: materials that let light THROUGH them, by their glTF name (`"name*"` = every name with that start):
+     *  the share of a shadow ray that passes, tinted by the material's base colour x map - an awning's warm, patterned light
+     *  on the sand. The surface itself stays opaque: baked, drawn as before, a real-time shadow caster.
+     *  A number = the share that goes STRAIGHT through (the gaps of a weave: it draws the map's picture on the ground);
+     *  `{ through, diffuse }` adds the share the fibres SCATTER - the cloth's underside glows like a matte panel and lights
+     *  what is under it by the solid angle it fills, with no picture. Dense canvas: `{ through: 0.08, diffuse: 0.25 }`. */
+    transmit?: Record<string, LightmapTransmit>;
+};
+/** one `transmit` entry (LightmapLoadOptions.transmit): the straight share, or both shares */
+export type LightmapTransmit = number | {
+    through?: number;
+    diffuse?: number;
 };
 export type LightmapInfo = {
     size: number;
     texel: number;
-    /** Atlas pages the bake took (`texture` lists them in order). */
+    /** Atlas pages the bake took (`light` / `aux` list them in order). */
     pages: number;
-    /** The light volume, when one was loaded: grid dims + cell size in metres. */
-    volume?: {
-        dims: number[];
-        cell: number;
-    };
-    /** Point lights the bake carries and this load switched off (statics read them from the atlas,
-     *  movers from the volume); 0 without a `light` atlas. */
-    lights: number;
     /** keys applied / keys in the file / registered statics without a rect */
     applied: number;
     total: number;
     missing: string[];
-    /** Occluder-only statics whose real-time shadow was switched off (`occluderShadows: "baked"`). */
-    occluders: number;
 };
 export type LightmapFiles = {
     data: string;
-    /** The atlas — one page, or every page in order for a bake that took several. */
-    texture: string | string[];
-    /** The point lights' baked irradiance (pages like `texture`). */
-    light?: string | string[];
+    /** The irradiance atlas — one page, or every page in order for a bake that took several. */
+    light: string | string[];
+    /** The aux atlas (sun / sky visibility + light direction), pages like `light`. */
+    aux: string | string[];
+    /** DEBUG: the direct-light-only pages a `--split` bake wrote (`<stem>-direct[_n].ktx2`), for the "direct" view. */
+    direct?: string | string[];
+    /** DEBUG: the bounce-only pages of a `--split` bake (`<stem>-indirect[_n].ktx2`), for the "indirect" view. */
+    indirect?: string | string[];
+    /** The reflection probes (`<stem>-probes.ktx2`), when the bake placed some (`lecodes lightmap bake --probe-spacing`). */
+    probes?: string;
+    /** THE LIGHT GRID for movers (`<stem>.lgrid`, `lecodes lightmap bake --volume`): the baked ambient light of every
+     *  place a mover can be. Absent = movers keep the scene's IBL. */
     volume?: string;
 };
+/** The lightmap material's data views (`Lightmap.debug`); "direct" / "indirect" bind a `--split` bake's pages instead. */
+export type LightmapDebugMode = "off" | "irradiance" | "albedo" | "normal" | "shadingNormal" | "share" | "skyVis" | "atlas" | "direction" | "lux" | "relief" | "direct" | "indirect" | "probe" | "probeMap" | "skyPath" | "probePath";
+export type LightmapDebugParams = {
+    /** `lux`: the false-colour ramp's log10 range (default 0..5, i.e. 1 lux .. 100 000). */
+    luxRange?: [number, number];
+};
+/** What `Lightmap.probe` answers: the baked texel under a screen point. */
+export type LightmapProbe = {
+    key: string;
+    entity: number;
+    node: string;
+    material: string;
+    page: number;
+    /** The texel's column / row on its page. */
+    texel: [number, number];
+    uv1: [number, number];
+    world: [number, number, number];
+    distance: number;
+};
 export declare class Lightmap {
     /** True while `lecodes lightmap bake` runs the app — skip menus and build the scene straight away. */
     static get baking(): boolean;
     private static entries;
-    private static dynamics;
     private static ordinals;
     private static warned;
-    private static switchedOff;
+    /** The bake bound last (`load`): what `probe` reads rects from. */
+    private static bound;
     /** Register static geometry — a Model, a Mesh, or any node whose subtree holds them. Statics are
-     *  both receivers and occluders in the bake. `key` names the entry in lightmap.bake (default:
+     *  both receivers and occluders in the bake. `key` names the entry in the .bake (default:
      *  the node's name + a running number, `container#3`); pass one when names are not stable. */
     static add(node: Node, key?: string): Node;
     private static next;
-    /** Forget every registration (a scene rebuild); baked-off lights come back to the real-time path. */
+    private static movers;
+    private static volumeOn;
+    /** A MOVER takes its ambient light from the level's baked LIGHT GRID (`env.lightmap.volume`) at the place it is at,
+     *  every frame — whatever its shader: the standard glTF one or a custom lit material. Every Model / Mesh under `node`
+     *  is marked (a character, a weapon with its parts). A scene file does this itself for every node a Physics aspect or
+     *  a CharacterController moves; call it for what CODE spawns — an enemy, a pickup, a projectile. `on = false` hands
+     *  the subtree back to the scene's IBL. Safe before the level's bake has loaded. */
+    static track(node: Node, on?: boolean): void;
+    private static loadVolume;
+    /** Forget every registration (a scene rebuild). */
     static clear(): void;
     /** Apply a bake — or, under `lecodes lightmap bake`, run it. Resolves to null when nothing was
      *  applied (no bake yet, a host without the feature, bake mode). */
+    private static scene;
     static load(scene: Scene, files: LightmapFiles, options?: LightmapLoadOptions): Promise<LightmapInfo | null>;
-    /** Every live point light within 5 cm of a baked one is held dark (a moved lamp keeps lighting live
-     *  — and double, until the next bake, which is the honest state of a stale bake). */
-    private static switchOffBaked;
-    /** lightmap.volume → the engine's 3D textures → THE volume for every dynamic lightmap-material instance,
-     *  plus the registered dynamic Meshes. Null when the file is a placeholder or the host lacks the feature. */
-    private static loadVolume;
-    /** A Mesh keeps its look (colour / map / roughness / metallic) but moves to the lightmap material. */
+    /** The bake's `<key>#k` instances by their base key: the parts of a GLB unwrapped in groups (k = extras.lightmapGroup). */
+    private static groupsOf;
+    /** Switch every lightmapped surface to a DATA view (or back with `"off"` / 0). Level-wide, instant —
+     *  except "direct" / "indirect", which load that page set the first time (a `--split` bake listed in the scene). */
+    static debug(mode: LightmapDebugMode | number, params?: LightmapDebugParams): void;
+    /** Bind another page set of the bound bake to every surface (the "direct" / "indirect" views). */
+    private static show;
+    private static balls;
+    /** DEBUG: a mirror ball at every reflection probe of the bound bake (`on`), or none (`off`) — a ball reflects the
+     *  probes around its point unoccluded (at a probe's own position that is the probe itself), so a probe inside a
+     *  wall, a black one or a leak across a wall shows at a glance. Metallic, roughness 0; view "probe" shows the
+     *  probes alone. */
+    static debugProbes(on: boolean, radius?: number): number;
+    /** The view names in `lightmapDebug`'s order — for a knob that cycles them. */
+    static get debugModes(): readonly LightmapDebugMode[];
+    /** The baked texel under a screen point (logical px): its instance key, page and texel column / row,
+     *  so the value can be looked up in the bake's debug layers (`lecodes lightmap inspect`). null when
+     *  nothing baked is under the point or the host has no triangle pick. */
+    static probe(screenX: number, screenY: number): LightmapProbe | null;
+    /** A hex colour as the 9-char form the float4 uniform path expects ("#rrggbbaa"). */
+    private static hex8;
+    /** The lightmap material for a static Mesh, from whatever lit material it carried (colour, map, roughness, metallic). */
     private static meshMaterial;
-    private static swapMeshMaterial;
     private static bake;
 }

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

@@ -119,8 +119,6 @@ export type LitMaterialOptions = MaterialColorOptions & MaterialStateOptions & {
     /** Metallic factor, 0 (dielectric) … 1 (metal). Unset = the shader's default. */
     metallic?: number;
 };
-/** `Material.lightmapShading` tiers — see the setter. */
-export type LightmapShading = "full" | "baked" | "baked-lite";
 export declare class Material {
     readonly shader: FetchResponse | "unknown";
     readonly uniforms: Record<string, UniformValue>;
@@ -153,33 +151,43 @@ export declare class Material {
     static decal(options?: DecalMaterialOptions): Material;
     /** Material that samples a VideoPlayer's texture. */
     static video(map?: Texture): Material;
-    /** The lightmap material (docs/lightmap-plan.md): PBR base colour × a baked shadow/AO atlas on UV1.
-     *  Models take it through `Model.load(…, { lightmap: true })`; `Lightmap.load` builds one per static
-     *  Mesh. Parameters use gltfio's names (`baseColorFactor`, `baseColorMap`, `roughnessFactor`,
-     *  `metallicFactor`) plus `lightmap`, `lightmapST`, `ambientScale`, `sunStrength` (the sun / IBL terms come from
-     *  filament's per-frame uniforms inside the shader). */
+    /** The lightmap material (packages/creator-bake): a lit PBR material whose whole DIFFUSE light is the
+     *  baked irradiance atlas on UV1 (`lightmapLight`, lux) — the real-time sun, lamps and diffuse IBL do not
+     *  touch it; the specular IBL stays, occluded by the baked sky visibility. Models take it through
+     *  `Model.load(…, { lightmap: true })`; a static Mesh gets one from here. Parameters use gltfio's names
+     *  (`baseColorFactor`, `baseColorMap`, `roughnessFactor`, `metallicFactor`) plus `lightmapLight`, `lightmapAux`,
+     *  `lightmapST`, `lightScale` (the level-wide value `Lightmap.load` sets) and the debug view knobs. */
     static lightmap(): Material;
     /** `Material.lightmap()`'s masked twin (`blending: masked`, same shader and parameters): what the engine
      *  gives a lightmapped model's alpha-MASK materials. The cutoff comes from the glTF material. */
     static lightmapMasked(): Material;
     /** The terrain splat material (docs/terrain-plan.md §1.5): four albedo (+ normal-map) layers blended by
      *  a control map on the terrain's own grid, per-layer `tiling` (metres per repeat) / `roughness` /
-     *  `normalScale` / `triplanar`, lightmap-aware (the same `lightmap` / `lightmapST` block as
-     *  `Material.lightmap`). `Terrain` builds and owns one per terrain; the uniforms are primed here so an
-     *  unset layer is white and an unbaked terrain is fully lit. */
+     *  `normalScale` / `triplanar`. `Terrain` builds and owns one per terrain; the uniforms are primed here so an
+     *  unset layer is white. Lit real-time; a BAKED terrain takes `Material.terrainLightmap()`. */
     static terrain(): Material;
+    /** `Material.terrain()` for a BAKED terrain (terrain-lightmap.mat): the same layers and uniforms, shaded like
+     *  `Material.lightmap()` — the whole diffuse light is the baked atlas on the terrain's UV1 (one rect), which
+     *  `Lightmap.load` binds. A scene file's `terrain:` node that is a lightmap static is built with it; without a
+     *  bound bake it draws black, like any lightmapped static. No reflection probes (the sampler budget): it reflects the
+     *  sky through the baked sky visibility. */
+    static terrainLightmap(): Material;
     private static _lmTemplate;
     private static _lmMaskedTemplate;
-    static _lightmapShading: LightmapShading;
-    /** Which shader lightmapped models take — a graphics-quality tier, engine-wide. `"full"` is filament's
-     *  lit path over the baked atlas (IBL specular, real-time point lights such as a muzzle flash, sun
-     *  shadows on dynamic objects). `"baked"` keeps the baked light and an approximated ambient but drops
-     *  the lit path: ~40 % cheaper per pixel on a fill-bound GPU. `"baked-lite"` is that minus the normal,
-     *  metallic/roughness and occlusion map reads (the factors stand in, the atlas keeps the baked AO;
-     *  emissive still glows): +20 % more at 1080p on the same GPU. Read when a lightmapped model LOADS, so set
-     *  it before the level (a settings menu applies it on the next level load), like `Texture.maxSize`. */
-    static get lightmapShading(): LightmapShading;
-    static set lightmapShading(mode: LightmapShading);
+    /** The FOLIAGE tier (`Model.load(…, { foliage: true })`, see `Foliage`): an unlit shader with its own cheap
+     *  lighting plus a vertex shader that sways in the wind, bends away from benders and thins out with distance,
+     *  and a per-copy tint. glTF parameters like `Material.lightmap()` plus `wind` / `sway` / `fade` / `benders`,
+     *  which the engine writes itself. Not baked by the rewritten bake yet. */
+    static foliage(): Material;
+    /** `Material.foliage()`'s masked twin (`blending: masked`): what the engine gives a foliage model's alpha-MASK
+     *  materials — the cards. */
+    static foliageMasked(): Material;
+    /** the glTF-side identity values every provider-handed material starts from */
+    private static _glbDefaults;
+    private static _lightmapDefaults;
+    private static _folTemplate;
+    static _foliageMaskedTemplate(): Material;
+    private static _folMaskedTemplate;
     /** Shadow-catcher material (transparent except where shadows fall). */
     static shadow(color?: ColorInput): Material;
     /** Load a custom compiled shader (.mat URL) as a material. */

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

@@ -77,11 +77,13 @@ export declare class Model extends Node {
             loaded: number;
             total?: number;
         }) => void;
-        /** Baked lighting (docs/lightmap-plan.md). `true` = a STATIC: loads through the lightmap material so
+        /** Baked lighting (packages/creator-bake). `true` = a STATIC: loads through the lightmap material so
          *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 — `lecodes assets doctor
-         *  --lightmap-uv`). `'dynamic'` = a mover: the same material, lit by the level's light VOLUME instead
-         *  (no UV1 needed). Omitted: `'dynamic'` while a scene file with `env.lightmap.volume` is running,
-         *  else off. `false` = the standard shader. Hosts without lightmap support ignore it. */
-        lightmap?: boolean | "dynamic";
+         *  --lightmap-uv`) and takes nothing from the real-time lights once the bake applies. Omitted / `false` =
+         *  the standard shader, lit real-time (movers). Hosts without lightmap support ignore it. */
+        lightmap?: boolean;
+        /** Vegetation: load through the FOLIAGE tier (see `Foliage`) — wind, touch bending, distance fade,
+         *  per-copy tint. Hosts without the tier fall back to the standard shader. */
+        foliage?: boolean;
     }): Promise<Model>;
 }

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

@@ -7,6 +7,17 @@ import type { Geometry } from "./Geometry";
 import { Material } from "./Material";
 import type { CompAxis, CompWriter } from "../core/compWrite";
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
+import type { Animation } from "../animate/tween/Animation";
+import { type TweenMeta } from "../animate/tween/spec";
+/** Animatable transform props of a 3D node: a value tweens from the current one, an ARRAY OF
+ *  VALUES is a keyframe list (`position: [[0,0,0], [0,2,0]]`). */
+export type NodeTweenProps = {
+    position?: Vec3Like | Vec3Like[];
+    scale?: number | Vec3Like | (number | Vec3Like)[];
+    quaternion?: QuatLike | QuatLike[];
+    /** Degrees, YXZ; interpolated per axis without shortest-arc, so `[0, 720, 0]` spins twice. */
+    eulerAngles?: Vec3Like | Vec3Like[];
+};
 /** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
 export declare const nodeRegistry: Registry<Node>;
 export type NodeEvents = {
@@ -59,6 +70,13 @@ export declare class Node extends AspectHost<NodeEvents> implements CompWriter {
     set scale(v: Vec3Like | number);
     get quaternion(): Quat;
     set quaternion(v: QuatLike);
+    /** Tween the transform to the given values — `node.animateTo({ position: [0, 2, 0], duration: 800,
+     *  easing: 'inOutCubic' })`; arrays of values are keyframes. Runs on the game clock (pauses with
+     *  the game) unless `clock: 'ui'`. Returns the {@link Animation} handle. Phase 1: plain nodes —
+     *  a physics-owned node (a body / character) is not routed through its engine object yet. */
+    animateTo(props: NodeTweenProps & TweenMeta): Animation;
+    /** Tween FROM the given values to the node's current transform (an entrance). */
+    animateFrom(props: NodeTweenProps & TweenMeta): Animation;
     get eulerAngles(): Vec3;
     set eulerAngles(v: Vec3Like);
     get forward(): Vec3;

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

@@ -170,6 +170,15 @@ 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).
@@ -222,6 +231,8 @@ 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);
@@ -260,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;
@@ -274,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. */
@@ -282,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

@@ -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

@@ -11,12 +11,14 @@ export type DynamicBoneFloor = "none" | "probe" | number | Vec3Like;
  *  on the standard humanoid bones (hips, spine, head, limbs — the Ragdoll's layout); `'none'`; or the
  *  nodes carrying the colliders to use. */
 export type DynamicBoneColliders = "auto" | "humanoid" | "none" | Node[];
-/** The cloth's OUTSIDE, which makes every collider one-sided: `'none'` = a collider pushes a bone to its
- *  nearest surface (tails, ropes); `'auto'` = away from the root bone's own axis (a cloak's strips round a
- *  spine face out from it); a vector = a fixed direction in the root bone's frame (a cape on the back:
- *  `[0, 0, -1]`). With a side the body is under the cloth by definition: an arm that swung through the
- *  cape pushes it away, and a bone that ended up inside a capsule leaves it on the outside — never
- *  through it to be held against the chest from the wrong side. */
+/** 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
@@ -33,6 +35,10 @@ export declare class DynamicBoneCollider extends Aspect<"dynamicBoneCollider", N
     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;
@@ -64,7 +70,8 @@ export declare class DynamicBone extends Aspect<"dynamicBone", Node> {
     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. */
+     *  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
@@ -163,7 +170,11 @@ export declare class DynamicBone extends Aspect<"dynamicBone", Node> {
     get particles(): Vec3[];
     private _collect;
     private _fill;
-    /** Neighbour links: the bones at the same depth, in tree order, tied pairwise. */
+    /** 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;