lecodes-sdk 0.20.0 → 1.0.0

package/dist/types/audio/Bus.d.ts

@@ -0,0 +1,45 @@
+export type ReverbPreset = "room" | "hall" | "cave" | "arena" | "bathroom" | "outdoor";
+export type ReverbParams = {
+    /** 0 (a closet) … 1 (a cathedral). */
+    roomSize?: number;
+    /** High-frequency loss per reflection, 0 … 1. */
+    damping?: number;
+    /** Stereo width of the tail, 0 … 1. */
+    width?: number;
+    /** Wet amount, 0 … 1. */
+    mix?: number;
+    /** Seconds before the tail starts (a big hall: 0.02 … 0.05). */
+    preDelay?: number;
+};
+export type EchoParams = {
+    /** Seconds between repeats (up to 2). */
+    delay?: number;
+    /** Feedback, 0 … 0.95 — how many repeats survive. */
+    decay?: number;
+    /** Wet amount, 0 … 1. */
+    mix?: number;
+};
+export declare const REVERB_PRESETS: Record<ReverbPreset, Required<ReverbParams>>;
+export declare class Bus {
+    readonly name: string;
+    private _volume;
+    private _muted;
+    private _reverb;
+    private _echo;
+    private _lowpass;
+    private get _live();
+    get volume(): number;
+    set volume(v: number);
+    get muted(): boolean;
+    set muted(v: boolean);
+    /** A preset name, explicit params, or null (off). */
+    get reverb(): ReverbPreset | ReverbParams | null;
+    set reverb(v: ReverbPreset | ReverbParams | null);
+    get echo(): EchoParams | null;
+    set echo(v: EchoParams | null);
+    /** Low-pass cutoff in Hz (20 … 20000), null = off. */
+    get lowpass(): number | null;
+    set lowpass(v: number | null);
+    /** Stop every voice on this bus (fade in seconds). */
+    stopAll(fade?: number): void;
+}

package/dist/types/audio/Sound.d.ts

@@ -0,0 +1,28 @@
+export type SoundOptions = {
+    /** Keep two channels (2D playback of stereo material — music beds, ambiences). Default: the clip
+     *  is decoded MONO, which is what 3D spatialization needs and what SFX are anyway. */
+    stereo?: boolean;
+};
+export declare class Sound {
+    /** The urls this clip was loaded from (one per variant). */
+    readonly urls: readonly string[];
+    private readonly _durations;
+    private _channels;
+    private _disposed;
+    private _last;
+    private constructor();
+    /** Fetch + decode. An array = variants: `play` picks a random one (never the same twice in a row
+     *  when there are 3 or more). Rejects with the failing url when a file cannot be decoded. */
+    static load(src: string | string[], options?: SoundOptions): Promise<Sound>;
+    /** Seconds (the first variant's). 0 for a silent clip. */
+    get duration(): number;
+    /** Decoded channel count: 1, or 2 with `{ stereo: true }`. */
+    get channels(): number;
+    /** How many variants this clip carries. */
+    get variants(): number;
+    /** True when the engine has this clip (false on hosts without audio, or after dispose). */
+    get ready(): boolean;
+    get disposed(): boolean;
+    /** Free the engine's PCM. Voices playing it stop at once. Idempotent. */
+    dispose(): void;
+}

package/dist/types/audio/Voice.d.ts

@@ -0,0 +1,27 @@
+import { Emitter } from "../core/events";
+export type VoiceEvents = {
+    /** The voice is over: the clip ended, `stop` completed, or the pool reused the slot. */
+    ended: () => void;
+};
+export declare class Voice extends Emitter<VoiceEvents> {
+    private _volume;
+    private _pitch;
+    private _pan;
+    private _over;
+    addEventListener<K extends keyof VoiceEvents>(channel: K, callback: VoiceEvents[K]): void;
+    /** True while the engine plays this voice. */
+    get playing(): boolean;
+    /** Seconds into the clip. */
+    get time(): number;
+    get volume(): number;
+    set volume(v: number);
+    get pitch(): number;
+    set pitch(v: number);
+    /** 2D voices only: -1 left … 1 right. */
+    get pan(): number;
+    set pan(v: number);
+    /** Stop now, or fade out over `fade` seconds. `ended` fires from the engine afterwards. */
+    stop(options?: {
+        fade?: number;
+    }): void;
+}

package/dist/types/audio/audio.d.ts

@@ -0,0 +1,83 @@
+import { type Vec3Like } from "../math/vec";
+import { Bus } from "./Bus";
+import type { Sound } from "./Sound";
+import { Voice } from "./Voice";
+export type PlaySoundOptions = {
+    /** 0 … 1 (and above, at your own risk). Default 1. */
+    volume?: number;
+    /** Playback rate, 1 = unchanged. Default 1. */
+    pitch?: number;
+    loop?: boolean;
+    /** Bus name; default: the source's bus, `sfx` for 2D. */
+    bus?: string;
+    /** Higher survives voice stealing when the pool is full. Default 0. */
+    priority?: number;
+    /** Fade-in seconds. Default 0. */
+    fade?: number;
+    /** Seconds into the clip to start from. */
+    startAt?: number;
+    /** 2D only: -1 left … 1 right. */
+    pan?: number;
+};
+export type Rolloff = "none" | "inverse" | "linear" | "exponential";
+/** Distance model of an AudioSource / playAt. */
+export type SpatialOptions = {
+    /** Metres of full volume around the source. Default 1. */
+    minDistance?: number;
+    /** Metres beyond which the source no longer gets quieter. Default 50. */
+    maxDistance?: number;
+    /** How volume falls between the two: `inverse` (default, physical), `linear`, `exponential`, `none`. */
+    rolloff?: Rolloff;
+};
+export declare const ROLLOFF: Record<Rolloff, number>;
+export type AudioStats = {
+    voicesPlaying: number;
+    voicesMono: number;
+    voicesStereo: number;
+    /** Voices displaced (or dropped) by a fuller pool since start. */
+    stolen: number;
+    clips: number;
+    clipBytes: number;
+    /** Master peak since the previous read, linear (1 = full scale). */
+    peak: number;
+    sampleRate: number;
+    /** The reverb zone the listener is in (0 = none) and how far inside (0 … 1). */
+    listenerZone: number;
+    zoneBlend: number;
+    /** Voices rendered binaurally right now (see `audio.hrtf`). */
+    hrtfVoices: number;
+};
+declare class AudioSystem {
+    private readonly _buses;
+    private _hrtf;
+    private _hrtfVoices;
+    private _timeScalePitch;
+    /** True when this host mixes sound. Everything below is a silent no-op otherwise. */
+    get supported(): boolean;
+    /** HRTF binaural rendering (MIT KEMAR filters on the CPU): sounds get a real up / down / behind in
+     *  HEADPHONES. Off by default — on speakers it only smears the image. Applies to the `hrtfVoices`
+     *  nearest 3D voices; the rest keep plain panning. */
+    get hrtf(): boolean;
+    set hrtf(v: boolean);
+    /** `Time.scale` also pitches the sfx bus: slow motion drops every effect's tone, like a film. Default
+     *  false — a pause only mutes sfx, the menu click keeps its pitch. */
+    get timeScalePitch(): boolean;
+    set timeScalePitch(v: boolean);
+    /** How many voices get the (CPU-heavier) binaural path. Default 16. */
+    get hrtfVoices(): number;
+    set hrtfVoices(n: number);
+    /** A bus by name — the five built-ins, or an app-defined one created on first use. */
+    bus(name: string): Bus;
+    get master(): Bus;
+    /** 2D playback (UI, stingers, music one-shots). */
+    play(sound: Sound, options?: PlaySoundOptions): Voice;
+    /** A one-shot at a world position with its own transient source — impacts, ricochets, debris.
+     *  The source is freed when the voice ends. */
+    playAt(sound: Sound, position: Vec3Like, options?: PlaySoundOptions & SpatialOptions): Voice;
+    /** Stop every voice on every bus (fade in seconds). */
+    stopAll(fade?: number): void;
+    /** Engine counters for a debug overlay or a perf log. */
+    get stats(): AudioStats;
+}
+export declare const audio: AudioSystem;
+export type { AudioSystem };

package/dist/types/audio/support.d.ts

@@ -0,0 +1 @@
+export declare const audioSupported: boolean;

package/dist/types/canvas/Canvas.d.ts

@@ -56,6 +56,8 @@ export declare class Canvas {
     private _surfaceId;
     private _tex2d?;
     private _uiBound;
+    private _lastBakeLen;
+    private _warnedGrowth;
     constructor(width: number, height: number, opts?: {
         pixelRatio?: number;
     });

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

@@ -0,0 +1,148 @@
+import { Node } from "./Node";
+import { Material } from "./Material";
+import type { Texture } from "./Texture";
+import { type Vec3Like } from "../math/vec";
+import { type QuatLike } from "../math/quat";
+import { type ColorInput } from "../core/color";
+/** Per-decal look and life — defaults come from the set's options. */
+export type DecalOptions = {
+    /** Image width and height on the surface (world units); a number = square. Default 0.2. */
+    size?: number | [number, number];
+    /** Projection depth (world units): how far in front of and behind the hit point the decal still
+     *  lands. Default = the smaller of width / height. */
+    depth?: number;
+    /** Atlas cell (row-major from the top-left) for a set with a `sheet`; `"random"` picks one.
+     *  Default 0. */
+    frame?: number | "random";
+    /** Tint multiplied into the image. Default white. */
+    tint?: ColorInput;
+    /** 0..1 on top of the tint's alpha. Default 1. */
+    opacity?: number;
+    /** Seconds until the decal is gone; 0 = stays until recycled. Default 0. */
+    life?: number;
+    /** Seconds to fade in after spawning. Default 0. */
+    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
+     *  material must keep decal.mat's vertex contract. */
+    material?: Material;
+    /** Atlas texture for the default material. */
+    map?: Texture;
+    /** Tangent-space normal atlas (same cell grid) → a RELIEF decal that bends the surface's
+     *  lighting instead of painting a colour (`Material.decal` `normalMap`). Footprints and dents
+     *  need only this; a bullet hole gives `map` too and its colour multiplies in. */
+    normalMap?: Texture;
+    /** Relief strength for `normalMap`. Default 1. Default material only. */
+    bump?: number;
+    /** Atlas grid of the map: columns, or [columns, rows]. Default 1 (the whole texture). */
+    sheet?: number | [number, number];
+    /** Slot budget — the most decals alive at once. Default 256. */
+    max?: number;
+    /** Soft fraction (0..1) of the box's half depth at both ends, so an oblique surface leaves the
+     *  box gently. Default 0.3. Default material only. */
+    edge?: number;
+    /** Surfaces turned more than this away from the projection axis fade out — the cosine of the
+     *  angle (0.3 ≈ 72°) keeps a floor hit off the wall it meets; 0 = project onto anything.
+     *  Default 0.3. Default material only. */
+    angleFade?: number;
+    /** HDR boost of the image (0 = none). Default material only. */
+    emissive?: number;
+    name?: string;
+    /** 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. */
+export type DecalSpawnOptions = DecalOptions & {
+    /** World direction the image's top points along the surface (projected onto it) — a footprint's
+     *  travel direction. Default: a random spin. */
+    up?: Vec3Like;
+    /** Extra spin around the normal, radians. Default: random when `up` is not given, else 0. */
+    rotation?: number;
+};
+/** `place` / `update` placement: a full frame, like a node looking INTO the surface (its −Z is the
+ *  projection direction, +Y the image's top). */
+export type DecalPlacement = DecalOptions & {
+    position: Vec3Like;
+    /** A quaternion, or Euler degrees (YXZ) like `Node.eulerAngles`. Default identity = projecting
+     *  down −Z. */
+    rotation?: QuatLike | Vec3Like;
+};
+export declare class DecalSet extends Node {
+    private _material;
+    private readonly _max;
+    private readonly _cols;
+    private readonly _rows;
+    private readonly _defaults;
+    private readonly _rec;
+    private readonly _slots;
+    private static _warned;
+    constructor(options?: DecalSetOptions);
+    get material(): Material;
+    /** Decals alive right now. */
+    get count(): number;
+    /** The slot budget the set was created with. */
+    get max(): number;
+    /** Coarse draw order, 0 … 7 — see `Mesh.renderPriority`. Write-only. */
+    set renderPriority(v: number);
+    /** Stamp a decal on a surface: `point` on it, `normal` out of it (a raycast hit, a foot plant
+     *  with `Vec3.up`). Returns the slot for `update` / `remove` (−1 when the host draws none). */
+    spawn(point: Vec3Like, normal: Vec3Like, options?: DecalSpawnOptions): number;
+    /** Place a decal by a full frame (an editor-placed stain, a moving marker). Returns the slot. */
+    place(placement: DecalPlacement): number;
+    /** Move / restyle a placed decal; fields left out keep the values it was placed with. Its birth
+     *  time (the life clock) is kept. */
+    update(slot: number, placement: Partial<DecalPlacement>): this;
+    remove(slot: number): this;
+    clear(): this;
+    private _writePlacement;
+}
+/** 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/Geometry.d.ts

@@ -10,6 +10,11 @@ export declare class Geometry {
      *  tiles per face, which would fold every face onto the same texels); absent = the host reuses
      *  `uv`, which is right for a plane. */
     uv1?: Float32Array;
+    /** Per-vertex COLOURS: 4 bytes (r, g, b, a) per vertex, 0..255. A material that declares
+     *  `requires: [color]` reads them through `getColor()` — one mesh, many colours, no material per
+     *  shade (a debug drawer, a gradient along a curve). Absent = every vertex white, which is what
+     *  the built-in materials expect. */
+    colors?: Uint8Array;
     constructor(vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array);
     translate(x: number, y: number, z: number): this;
     scale(x: number, y: number, z: number): this;
@@ -20,6 +25,9 @@ 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;
 }
 export type SphereOptions = {
@@ -27,6 +35,15 @@ export type SphereOptions = {
     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

@@ -53,6 +53,7 @@ export declare class Light extends Node {
     private _intensity;
     /** The most recently created sun — what `Lightmap.load` uses unless told otherwise. */
     static lastSun: Light | null;
+    _shadowDistance: number;
     /** A directional sun light. */
     static sun(options?: SunOptions): Light;
     /**
@@ -70,4 +71,10 @@ export declare class Light extends Node {
     set intensity(value: number);
     destroy(): void;
     set color(value: ColorInput);
+    get color(): ColorInput;
+    /** Sun direction as created (the engine keeps it; a settings menu rebuilds a sun from it). */
+    get direction(): [number, number, number];
+    /** Sun shadow options as created — creation-time in the engine, so a change means a new sun. */
+    get shadowsQuality(): number;
+    get shadowDistance(): number;
 }

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

@@ -27,6 +27,13 @@ export type LightmapLoadOptions = {
      *  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";
 };
 export type LightmapInfo = {
     size: number;
@@ -45,6 +52,8 @@ export type LightmapInfo = {
     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;

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

@@ -7,8 +7,47 @@ export type MaterialColorOptions = {
     color?: ColorInput;
     map?: Texture | Canvas | null;
 };
+/** How a stencil test / write on a material compares and what it writes. `test` runs against the
+ *  scene's stencil buffer (`Scene.stencil` must be on); the ops say what the buffer gets when the
+ *  fragment passes / fails the stencil test / fails the depth test (`replace` writes `ref`). */
+export type StencilTest = "always" | "never" | "less" | "lessEqual" | "greater" | "greaterEqual" | "equal" | "notEqual";
+export type StencilOp = "keep" | "zero" | "replace" | "increment" | "decrement" | "invert";
+export type MaterialStencil = {
+    /** Write the stencil buffer at all. Default `false`. */
+    write?: boolean;
+    /** The reference value, 0..255. Default 0. */
+    ref?: number;
+    /** Default `"always"`. */
+    test?: StencilTest;
+    onPass?: StencilOp;
+    onFail?: StencilOp;
+    onDepthFail?: StencilOp;
+    readMask?: number;
+    writeMask?: number;
+};
+/** Render state a material instance can override at run time (Filament keeps the defaults in the
+ *  shader package; these are per-instance overrides on top). */
+export type MaterialStateOptions = {
+    /** Test against the scene's depth buffer. `false` draws over everything already drawn — an
+     *  editor gizmo, a marker that must never hide behind a wall. Pair it with a high
+     *  `Mesh.renderPriority` so nothing drawn later covers it. Default `true`. */
+    depthTest?: boolean;
+    /** Write to the depth buffer. Leave it on for something drawn over the scene whose own parts must
+     *  still occlude each other (a gizmo's cone in front of its shaft). Unset = the shader's default
+     *  (on for opaque, off for a blended one). */
+    depthWrite?: boolean;
+    /** Draw both faces (no back-face culling): a plane seen from behind, a ribbon, cloth, a flat
+     *  marker. Default `false` = the shader's culling (back faces dropped). */
+    doubleSided?: boolean;
+    /** A stencil test / write for this material — see `MaterialStencil`. The selection-outline
+     *  recipe: the object writes `{ write: true, ref: 1, onPass: "replace" }`, and a slightly larger
+     *  copy of it draws with `{ test: "notEqual", ref: 1 }` + `depthTest: false` in `renderPriority` 7. */
+    stencil?: MaterialStencil;
+};
+/** @deprecated the name before doubleSided / stencil joined it — the same type */
+export type MaterialDepthOptions = MaterialStateOptions;
 /** `Material.unlit` options. */
-export type UnlitMaterialOptions = MaterialColorOptions & {
+export type UnlitMaterialOptions = MaterialColorOptions & MaterialStateOptions & {
     /** Alpha-blend this material instead of drawing it opaque. Opaque is the default: a blended draw
      *  writes no depth, is sorted back-to-front and casts no shadow, which is rarely what a flat
      *  colour wants. Turn it on for anything that must show what is behind it — a glass pane, a
@@ -16,6 +55,26 @@ export type UnlitMaterialOptions = MaterialColorOptions & {
      *  (`"#ffffff80"`) mean anything; the opaque material has no alpha channel at all. */
     transparent?: boolean;
 };
+/** `Material.decal` options — the projected-decal material a `DecalSet` draws with. */
+export type DecalMaterialOptions = {
+    /** The atlas (a `DecalSet`'s `sheet` cuts it into cells). */
+    map?: Texture;
+    /** A tangent-space normal atlas (same cell grid; +X = the image's right, +Y = its top; LINEAR —
+     *  `Texture.fromPixels(…, { srgb: false })`). Turns the decal into a RELIEF decal: instead of
+     *  painting a colour it bends the surface's lighting, so a footprint or a dent shows on any
+     *  surface without a colour of its own. With `map` too, the colour multiplies in (a crater
+     *  darkens by the map's alpha). The sun term applies in shadow as well (no shadow read). */
+    normalMap?: Texture;
+    /** Relief strength — the normal map's xy scale. Default 1. */
+    bump?: number;
+    /** Soft fraction (0..1) of the box's half depth at both ends. Default 0.3. */
+    edge?: number;
+    /** Cosine of the surface angle past which the decal fades (0.3 ≈ 72°); 0 = project onto
+     *  anything. Default 0.3. */
+    angleFade?: number;
+    /** HDR boost of the image (0 = none). */
+    emissive?: number;
+};
 /** `Material.particles` options — the default point-sprite material for particle systems. */
 export type ParticlesMaterialOptions = {
     /** Sprite texture — a single image or a flipbook sheet of frames. Unset = soft round dot. */
@@ -54,12 +113,14 @@ export type ParticlesMaterialOptions = {
     stretch?: number;
 };
 /** `Material.lit` options — PBR scalars on top of the color/map pair. */
-export type LitMaterialOptions = MaterialColorOptions & {
+export type LitMaterialOptions = MaterialColorOptions & MaterialStateOptions & {
     /** Perceptual roughness, 0 (mirror) … 1 (matte). Unset = the shader's default. */
     roughness?: number;
     /** 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>;
@@ -68,6 +129,15 @@ export declare class Material {
     /** Set a uniform (chainable). */
     set(key: string, value: UniformValue): this;
     set color(c: ColorInput);
+    /** Depth test against the scene (write-only; see `MaterialDepthOptions`). A host that predates
+     *  the call leaves the material as the shader has it. */
+    set depthTest(on: boolean);
+    /** Depth write (write-only; see `MaterialStateOptions`). */
+    set depthWrite(on: boolean);
+    /** Both faces drawn (write-only; see `MaterialStateOptions`). */
+    set doubleSided(on: boolean);
+    /** The stencil test / write (write-only; `null` = back to none). See `MaterialStencil`. */
+    set stencil(s: MaterialStencil | null);
     set map(value: Texture | Canvas | null);
     /** PBR lit material. */
     static lit(options?: LitMaterialOptions): Material;
@@ -77,6 +147,10 @@ export declare class Material {
      *  driven by the particle curves. Uniforms all default to 0 on a fresh instance, so every look
      *  knob is primed here; JS writes after construction override them. */
     static particles(options?: ParticlesMaterialOptions): Material;
+    /** Projected-decal material (`DecalSet`): samples the atlas where the decal's box meets the opaque
+     *  scene behind it. Blended, no depth write, no shadows — the engine keeps the scene depth bound
+     *  while a set with live decals is on screen. */
+    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.
@@ -85,6 +159,9 @@ export declare class Material {
      *  `metallicFactor`) plus `lightmap`, `lightmapST`, `ambientScale`, `sunStrength` (the sun / IBL terms come from
      *  filament's per-frame uniforms inside the shader). */
     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
@@ -92,6 +169,17 @@ export declare class Material {
      *  unset layer is white and an unbaked terrain is fully lit. */
     static terrain(): 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);
     /** 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. */
@@ -11,15 +11,30 @@ export type MeshOptions = {
     name?: string;
     castShadows?: boolean;
     receiveShadows?: boolean;
+    /** Coarse draw order, 0 (first) … 7 (last); default 4. See `Mesh.renderPriority`. */
+    renderPriority?: number;
 };
 export declare class Mesh extends Node {
     private _geometry?;
     constructor(geometry?: Geometry, material?: Material);
     get geometry(): Geometry | undefined;
+    /** 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);
     set culling(v: boolean);
+    /** Coarse draw order within the frame: 0 draws first, 7 last, 4 is the default (Filament's
+     *  renderable priority; within one priority opaque draws sort front-to-back, blended back-to-front).
+     *  Something drawn over the scene with `Material.depthTest = false` goes in 7, so nothing drawn
+     *  after it can cover it. Write-only; a host that predates the call ignores it. */
+    set renderPriority(v: number);
+    private static _warnedPriority;
     set castShadows(v: boolean);
     set receiveShadows(v: boolean);
     static box(options?: MeshOptions & {
@@ -27,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;