lecodes-sdk 0.20.0 → 0.20.2

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

@@ -0,0 +1,60 @@
+import { Aspect } from "../core/Aspect";
+import type { FieldMeta } from "../core/fields";
+import { type PlaySoundOptions, type Rolloff } from "../audio/audio";
+import type { Sound } from "../audio/Sound";
+import type { Voice } from "../audio/Voice";
+import type { Node } from "./Node";
+export type AudioCone = {
+    /** Degrees of full volume around the node's −Z. */
+    inner: number;
+    /** Degrees where the volume has fallen to `outerGain`. */
+    outer: number;
+    /** Volume behind the source, 0 … 1. */
+    outerGain?: number;
+};
+export declare class AudioSource extends Aspect<"audio", Node> {
+    static readonly aspect = "audio";
+    static fields: FieldMeta<AudioSource>;
+    private _minDistance;
+    private _maxDistance;
+    private _rolloff;
+    private _cone;
+    private _doppler;
+    private _spread;
+    private _occlusion;
+    private _bus;
+    /** Metres of full volume around the node. Default 1. */
+    get minDistance(): number;
+    set minDistance(v: number);
+    /** Metres beyond which the source no longer gets quieter. Default 50. */
+    get maxDistance(): number;
+    set maxDistance(v: number);
+    /** `inverse` (default), `linear`, `exponential`, `none`. */
+    get rolloff(): Rolloff;
+    set rolloff(v: Rolloff);
+    /** Directional source along the node's −Z; null = omnidirectional (default). */
+    get cone(): AudioCone | null;
+    set cone(v: AudioCone | null);
+    /** Doppler amount 0 … 1 (0 = off, the default) — needs the node to actually move. */
+    get doppler(): number;
+    set doppler(v: number);
+    /** 0 = pin-point panning (default) … 1 = the same on every speaker (a big, close source). */
+    get spread(): number;
+    set spread(v: number);
+    /** The engine raycasts listener → source (against solid bodies) and muffles the voices when
+     *  something is in the way. Default false. */
+    get occlusion(): boolean;
+    set occlusion(v: boolean);
+    /** Default bus for voices on this source. Default `sfx`. */
+    get bus(): string;
+    set bus(v: string);
+    /** Live voices on this source. */
+    get voices(): number;
+    onAttach(): void;
+    onDetach(): void;
+    /** Play a clip from this node. */
+    play(sound: Sound, options?: PlaySoundOptions): Voice;
+    /** Stop every voice on this source (fade in seconds). */
+    stopAll(fade?: number): void;
+    private _push;
+}

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

@@ -0,0 +1,32 @@
+import { Aspect } from "../core/Aspect";
+import { type ReverbParams, type ReverbPreset } from "../audio/Bus";
+import { type Vec3Like } from "../math/vec";
+import type { Node } from "./Node";
+export declare class AudioZone extends Aspect<"audioZone", Node> {
+    static readonly aspect = "audioZone";
+    private _box;
+    private _sphere;
+    private _reverb;
+    private _blend;
+    private _bus;
+    /** The engine's zone id — what `audio.stats.listenerZone` reports while the listener is inside. */
+    get id(): number;
+    /** Half-extents [hx, hy, hz]; falls back to the node's Shape box, then a 1 m cube. */
+    get box(): Vec3Like | null;
+    set box(v: Vec3Like | null);
+    /** Radius; falls back to the node's Shape sphere. */
+    get sphere(): number | null;
+    set sphere(v: number | null);
+    /** A preset name or explicit params (see Bus.reverb). */
+    get reverb(): ReverbPreset | ReverbParams;
+    set reverb(v: ReverbPreset | ReverbParams);
+    /** Crossfade depth in metres inside the border (0 = a hard edge). Default 1. */
+    get blend(): number;
+    set blend(v: number);
+    /** The bus the zone's reverb rides on. Default `sfx`. */
+    get bus(): string;
+    set bus(v: string);
+    onAttach(): void;
+    onDetach(): void;
+    private _push;
+}

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

@@ -0,0 +1,103 @@
+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;
+};
+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); default 4 — see `Mesh.renderPriority`. Decals are
+     *  blended and sort with the other blended draws of their priority. */
+    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;
+    private _write;
+}

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;

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/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.
@@ -92,6 +166,16 @@ export declare class Material {
      *  unset layer is white and an unbaked terrain is fully lit. */
     static terrain(): 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);
     /** 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

@@ -11,15 +11,26 @@ 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;
     /** 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 & {

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

@@ -4,6 +4,7 @@ import { Presentable, type PresentOptions } from "../ui/presentable";
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
 import type { FetchResponse } from "../runtime/fetch";
 import { Camera } from "./Camera";
+import { SceneAudio } from "./SceneAudio";
 import { type ControlsHandle, type ControlsOptions } from "./controls";
 import { Material } from "./Material";
 import { Node } from "./Node";
@@ -95,6 +96,9 @@ export type SceneOptions = {
      *  takes over). Unset keeps the host default (desktop 4×, mobile/web off). The biggest single
      *  fill-rate cost after resolution — turn it down on big screens before anything else. */
     antialias?: boolean | 2 | 4;
+    /** Keep a stencil buffer for this scene (off by default: it costs memory and a clear per frame).
+     *  Needed before any material's `stencil` test or write does anything. */
+    stencil?: boolean;
     /** Render the 3D at this fraction of the viewport (0.25–1) and upscale; the UI stays at native
      *  resolution. A fixed, predictable cut of per-pixel GPU work — `0.75` is ~45 % cheaper and
      *  barely visible in motion, `0.5` quarters it. Headless renders ignore it. */
@@ -118,6 +122,10 @@ export type SceneOptions = {
      *  scene file — `env` is applied before the nodes build) and leaves already-loaded ones alone.
      *  On the desktop host `CREATOR_TEXTURE_ANISOTROPY` overrides it, for tuning without a rebuild. */
     anisotropy?: number;
+    /** Engine-wide cap on texture size, 0 / unset = none (see `Texture.maxSize`): a KTX2 above it
+     *  loses its top mip levels on load, a glTF image is downsampled. Applied before this scene's
+     *  assets load; like `anisotropy` it does not touch textures already loaded. */
+    maxTextureSize?: number;
     /** The look on an HDR display (a screen with headroom above SDR white — Apple XDR panels, the
      *  macOS host today); ignored on SDR. `strength` 0..1 is how much of the picture reaches for the
      *  display's headroom (0 only what SDR clipped, 1 nearly everything; default 0.35). `paperWhite`
@@ -132,6 +140,8 @@ export type SceneOptions = {
 };
 export declare class Scene implements Presentable {
     readonly camera: Camera;
+    /** The listener + global 3D audio knobs (docs/audio-plan.md). */
+    readonly audio: SceneAudio;
     readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node | null>) => void>;
     private _material?;
     private static _active;
@@ -153,6 +163,19 @@ export declare class Scene implements Presentable {
     setFog(options: FogOptions | false): void;
     setMaterialGlobalParameter(i: number, x: number, y: number, z: number, w: number): void;
     setAntialias(enabled: boolean, scale?: number): void;
+    /** Depth-reading effects on / off (a graphics-settings menu): soft particles and projected decals
+     *  read the scene depth, which costs a depth pre-pass of every opaque draw (~12 % of a fill-bound
+     *  frame). Off = hard-edged particles, no decals, no pre-pass. Engine-wide, live. */
+    setDepthEffects(enabled: boolean): void;
+    /** LOD distance (a graphics-settings menu): the engine's LOD thresholds × `bias`. 2 = every level
+     *  switches at half the distance (a model must look twice as big on screen to keep its detail),
+     *  0.5 = full detail twice as far, 1 = the defaults. Engine-wide, live. Only GLBs that carry
+     *  `_LOD<n>` meshes (`lecodes assets doctor --lod`) have levels to switch. */
+    setLodBias(bias: number): void;
+    /** Runtime form of `bloom` / `bloomIntensity` (a graphics-settings menu). */
+    setBloom(enabled: boolean, intensity?: number): void;
+    /** The scene's stencil buffer on / off (see `SceneOptions.stencil`). */
+    setStencil(enabled: boolean): void;
     add(...nodes: Node[]): this;
     remove(...nodes: Node[]): this;
     /** Attach (and configure) a system, or reconfigure it if already present. Returns the scene typed

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

@@ -0,0 +1,11 @@
+import type { Node } from "./Node";
+export declare class SceneAudio {
+    private _listener;
+    private _doppler;
+    /** The node the engine listens from; null (default) = the active camera. */
+    get listener(): Node | null;
+    set listener(node: Node | null);
+    /** Multiplies every source's doppler amount (0 = off everywhere). Default 1. */
+    get dopplerFactor(): number;
+    set dopplerFactor(v: number);
+}