lecodes-sdk 0.20.2 → 1.1.0

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

@@ -24,6 +24,14 @@ export type DecalOptions = {
     fadeIn?: number;
     /** Seconds of fade at the end of `life` (ignored with life 0). Default 0. */
     fadeOut?: number;
+    /** Opacity multipliers at the image's BOTTOM and TOP edge (−Y / +Y), interpolated along it — a
+     *  tire mark that darkens as the slide deepens. Default `[1, 1]`. */
+    gradient?: [number, number];
+    /** Tilt of the image's bottom and top edge, as a unit-space slope (Δy per Δx across the box):
+     *  the edge pivots on the corner of the side it keeps and cuts INTO the box on the other, so two
+     *  boxes can meet on one shared line — what `DecalTrail` uses to mitre its joints. `0` = square.
+     *  Default `[0, 0]`. */
+    caps?: [number, number];
 };
 export type DecalSetOptions = DecalOptions & {
     /** The material — `Material.decal({ map })` by default (`map` below is its shortcut). A custom
@@ -51,8 +59,10 @@ export type DecalSetOptions = DecalOptions & {
     /** HDR boost of the image (0 = none). Default material only. */
     emissive?: number;
     name?: string;
-    /** Coarse draw order, 0 (first) … 7 (last); default 4 — see `Mesh.renderPriority`. Decals are
-     *  blended and sort with the other blended draws of their priority. */
+    /** Coarse draw order, 0 (first) … 7 (last) — see `Mesh.renderPriority`. Default 3: a decal is
+     *  part of the surface it sits on, so it draws before every other blended thing (meshes 4,
+     *  particles 5) — the engine's depth sort compares object centres, and a set spread over the
+     *  level has no useful centre. */
     renderPriority?: number;
 };
 /** `spawn` placement: where the image sits on the surface. */
@@ -99,5 +109,40 @@ export declare class DecalSet extends Node {
     remove(slot: number): this;
     clear(): this;
     private _writePlacement;
-    private _write;
+}
+/** A `DecalTrail`'s look: the strip's width, and what every segment carries. */
+export type DecalTrailOptions = Omit<DecalOptions, "size" | "caps" | "gradient"> & {
+    /** Width of the strip on the surface, world units. */
+    width: number;
+};
+/**
+ * A continuous strip of decals along a path — a tire's skid mark, a dragged body, a tread track.
+ * Feed it points (`add`) as the thing moves; every new point becomes one box-decal SEGMENT from the
+ * previous point, its image's up along the travel, and the joints between segments are MITRED: each
+ * box is cut along the bisector it shares with its neighbour (`caps`), so the strip has no overlaps
+ * darkening the outside of a bend and no wedges of gap on the inside. The opacity given with each
+ * point is interpolated along the segment (`gradient`), so a mark can darken as a slide deepens and
+ * fade as it ends. Segments are the set's decals — same ring, same `max` budget: a set of 900 holds
+ * 900 segments across every trail drawn from it.
+ *
+ * The previous segment is REWRITTEN when the next point arrives (its far cap becomes the shared
+ * mitre), through `DecalSet.update`'s path — a recycled slot is simply left alone by the engine.
+ */
+export declare class DecalTrail {
+    private _prev;
+    private _seg;
+    readonly set: DecalSet;
+    readonly options: DecalTrailOptions;
+    constructor(set: DecalSet, options: DecalTrailOptions);
+    /** Extend the strip to `point` on a surface with `normal`, `opacity` (0..1) at that point. The
+     *  first call after a start / `end()` only anchors the strip. Returns the new segment's slot, or
+     *  −1 when nothing was drawn (the anchor, a point that did not move, no host support). */
+    add(point: Vec3Like, normal: Vec3Like, opacity?: number): number;
+    /** Finish the strip. With a `point`, one last segment runs out to it at opacity 0 — a mark that
+     *  tapers away instead of stopping dead. The next `add` anchors a new strip. */
+    end(point?: Vec3Like, normal?: Vec3Like): this;
+    private _rewrite;
+    /** Write one segment's box: the strip between its joints, extended past each mitred joint by the
+     *  mitre's reach (w/2 · |slope|) so the tilted cap still passes through the joint's centre. */
+    private _box;
 }

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

@@ -0,0 +1,47 @@
+import { Model } from "./Model";
+import { Node } from "./Node";
+export type FoliageWind = {
+    /** Direction on the ground (x, z); normalised by the engine. Default [1, 0.3]. */
+    direction?: [number, number];
+    /** Metres of sway at `bendHeight` (taller parts sway more). Default 0.07. 0 = still. */
+    strength?: number;
+    /** Radians per second of the main sway. Default 1.2. */
+    speed?: number;
+    /** 0..1: how much the strength breathes over a slow envelope. Default 0.6. */
+    gust?: number;
+};
+export type FoliageOptions = {
+    /** The wind, or `false` for none. */
+    wind?: FoliageWind | false;
+    /** Height above the instance origin (m) where the full sway / touch applies; the base never moves.
+     *  Default 1.5. */
+    bendHeight?: number;
+    /** Metres the TOP of a small plant leans away from a bender standing at its centre; the whole plant leans
+     *  as one, rooted at its base. Plants over ~2 m react less, trees over ~5 m not at all (the engine
+     *  measures each asset). Default 0.6. 0 = no touch reaction. */
+    touch?: number;
+    /** 0..1: how far each copy's tint drifts from the texture (warmer/darker to cooler/lighter, by a hash
+     *  of its position). Default 0.35. */
+    variation?: number;
+    /** 0..1: wrapped sun lighting — thin leaves let light through. Default 0.5. */
+    sunWrap?: number;
+};
+export declare const Foliage: {
+    /** Level-wide options; each field given replaces the current value (a scene file's `env.foliage`
+     *  goes through here). */
+    configure(options: FoliageOptions): void;
+    /** The wind: fields given replace the current ones; `false` = calm. Live. */
+    wind(wind: FoliageWind | false): void;
+    /** A node whose live position pushes the vegetation within `radius` metres (the hero: ~0.7; a
+     *  boulder: its size). Any number may be registered; the 8 nearest the camera act each frame. The
+     *  engine also tracks the node's velocity (smoothed over ~0.2 s): a plant you run through is brushed
+     *  forward and settles behind you instead of flipping as you cross its centre.
+     *  Returns the unregister function; a destroyed node drops out on its own. */
+    bend(node: Node, radius?: number): () => void;
+    /** Stop a node from bending the vegetation. */
+    unbend(node: Node): void;
+    /** Distance fade for EVERY copy of this model's asset (present and future): the cards thin out
+     *  from `start` to `end` metres from the camera and past `end` the copy leaves the frame entirely.
+     *  Small ground cover (grass, clover, flowers) is the target; `end` 0 = no fade. */
+    fade(model: Model, start: number, end: number): void;
+};

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

@@ -1,5 +1,19 @@
 import { type Vec3Like } from "../math/vec";
 export type MeshKind = "triangles" | "vertices" | "edges";
+/** A geometry file — what `lecodes assets geometry <model.glb>` writes (`<model>.geometry.json`):
+ *  one merged, world-space triangle buffer. `Geometry.load(asset('./casing.geometry.json'))`. */
+export type GeometryData = {
+    format?: "lecodes-geometry";
+    version?: number;
+    /** xyz per vertex. */
+    vertices: ArrayLike<number>;
+    /** xyz per vertex (unit length). */
+    normals: ArrayLike<number>;
+    /** uv per vertex. */
+    uv: ArrayLike<number>;
+    /** Triangle list, ≤ 65535 vertices addressed. */
+    indices: ArrayLike<number>;
+};
 export declare class Geometry {
     vertices: Float32Array;
     normals: Float32Array;
@@ -25,13 +39,35 @@ export declare class Geometry {
     static box(size?: Vec3Like | number): Geometry;
     static sphere(options?: SphereOptions): Geometry;
     static cylinder(options?: CylinderOptions): Geometry;
+    /** A capsule along Y, centred at the origin: a cylinder `length` long (between the two cap centres)
+     *  with a hemisphere of `radius` on each end — one closed surface, smooth across the seams. */
+    static capsule(options?: CapsuleOptions): Geometry;
     static plane(options?: PlaneOptions): Geometry;
+    /** A Geometry from a geometry file's contents (`GeometryData` — see `Geometry.load`). The arrays
+     *  are copied into typed buffers, so the source object can be dropped. */
+    static fromData(data: GeometryData): Geometry;
+    /** Load a geometry file: `lecodes assets geometry casing.glb` → `casing.geometry.json` →
+     *  `await Geometry.load(asset('./casing.geometry.json'))`. A GLB's triangles as a plain buffer,
+     *  for `Particles({ mesh })` debris (shell casings, rubble) and `Mesh.from`.
+     *  A `.json` project file is INLINED by the compiler — `asset('./x.json')` is the parsed data, not
+     *  a URL — so that form (and `import data from './x.json'`) is read directly, no fetch; a string
+     *  (a URL, a non-`.json` asset such as `.geo`) is fetched. */
+    static load(source: string | GeometryData): Promise<Geometry>;
 }
 export type SphereOptions = {
     radius?: number;
     widthSegments?: number;
     heightSegments?: number;
 };
+export type CapsuleOptions = {
+    radius?: number;
+    /** Distance between the two cap centres (the straight part); 0 = a sphere. Default 1. */
+    length?: number;
+    /** Segments around the axis. */
+    widthSegments?: number;
+    /** Rings per hemisphere (pole to equator). */
+    capSegments?: number;
+};
 export type CylinderOptions = {
     radius?: number;
     radiusTop?: number;

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,46 +1,34 @@
 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;
+    /** 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;
@@ -48,38 +36,89 @@ export type LightmapInfo = {
 };
 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,29 +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;
-    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);
+    private static _lmMaskedTemplate;
+    /** 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/Mesh.d.ts

@@ -1,5 +1,5 @@
 import { type Vec3Like } from "../math/vec";
-import { Geometry, type CylinderOptions, type PlaneOptions, type SphereOptions } from "./Geometry";
+import { Geometry, type CapsuleOptions, type CylinderOptions, type PlaneOptions, type SphereOptions } from "./Geometry";
 import { Material } from "./Material";
 import { Node } from "./Node";
 /** Common transform/render options every primitive factory accepts. */
@@ -21,6 +21,10 @@ export declare class Mesh extends Node {
     /** Replace the geometry in place — the node, its transform and its material stay, the vertex and
      *  index buffers are rebuilt. What an editor overlay or a debug drawer redraws with. */
     setGeometry(geometry: Geometry): this;
+    private _renderPriority?;
+    private _culling?;
+    private _castShadows?;
+    private _receiveShadows?;
     /** A Mesh always carries a material (slot 0) — see Node.setMaterial for the slot API. */
     get material(): Material;
     set material(m: Material);
@@ -38,6 +42,8 @@ export declare class Mesh extends Node {
     }): Mesh;
     static sphere(options?: MeshOptions & SphereOptions): Mesh;
     static cylinder(options?: MeshOptions & CylinderOptions): Mesh;
+    /** A capsule along Y (`radius`, `length` between the cap centres) — a character's or a collider's shape in one mesh. */
+    static capsule(options?: MeshOptions & CapsuleOptions): Mesh;
     static plane(options?: MeshOptions & PlaneOptions): Mesh;
     /** Wrap a custom Geometry. */
     static from(geometry: Geometry, options?: MeshOptions): Mesh;

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

@@ -1,6 +1,34 @@
 import { type FetchResponse } from "../runtime/fetch";
 import { Node } from "./Node";
 import { Animator, type LodMode } from "./animation/Animator";
+/** One polygon under a screen point — what `Model.pickTriangle` returns. `bones` are the vertex's raw
+ *  JOINTS_0 / WEIGHTS_0 pairs (weight > 0; empty = unweighted), `bind` its position in mesh space,
+ *  `world` its skinned position this frame. */
+export interface TrianglePick {
+    /** the Model's root entity, and the mesh node's own entity (0 when the host has no entity for it) */
+    entity: number;
+    node: number;
+    nodeName: string;
+    mesh: string;
+    primitive: number;
+    material: string;
+    /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
+    triangle: number;
+    backface: boolean;
+    distance: number;
+    point: [number, number, number];
+    bary: [number, number, number];
+    skin: string;
+    vertices: {
+        index: number;
+        bind: [number, number, number];
+        world: [number, number, number];
+        bones: {
+            name: string;
+            weight: number;
+        }[];
+    }[];
+}
 export declare class Model extends Node {
     /** The model's Animator — always present, its clip table = the GLB's embedded clips. Configure
      *  more (external clips, blend spaces, layers) with `model.aspect(Animator, {...})`. */
@@ -31,6 +59,12 @@ export declare class Model extends Node {
     get lod(): LodMode;
     set lod(v: LodMode);
     private static _cullDefault;
+    /** DEBUG: the closest polygon of this model under a screen point (logical px — `Input.mouse.position`,
+     *  a touch event's clientX/Y), tested against the CPU-skinned CURRENT pose, both faces. Names the
+     *  triangle, its three vertices (bind + skinned positions) and their raw bone weights, so a stretched
+     *  or misbound polygon can be traced to its binding. One full CPU skin of the model per call: click-rate
+     *  only. null = miss, or a host without the pick (desktop today). */
+    pickTriangle(screenX: number, screenY: number): TrianglePick | null;
     /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
      *  the same parent and scene and sharing this model's current transform. The clone has its own
      *  independent animation state (reach it via clone.anim). Mirrors this model's culling flag. */
@@ -43,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;