lecodes-sdk 2.4.9 → 2.5.0

package/dist/types/g2/Path2D.d.ts

@@ -0,0 +1,95 @@
+import { type ColorInput } from "../core/color";
+import { Vec2, type Vec2Like } from "../math/vec";
+import { Node2D } from "./Node2D";
+import type { Material2D } from "./Material2D";
+export type StrokeJoin2D = "miter" | "round" | "bevel";
+export type StrokeCap2D = "butt" | "round" | "square";
+export type Stroke2D = {
+    /** Line width. In `units: 'world'` (default) world units; in `'px'` logical screen pixels — constant
+     *  on screen while the camera zooms (map roads, debug lines). */
+    width: number;
+    /** Default white. */
+    color?: ColorInput;
+    units?: "world" | "px";
+    /** How segments meet; default 'miter'. */
+    join?: StrokeJoin2D;
+    /** How an OPEN path's ends look; default 'butt'. */
+    cap?: StrokeCap2D;
+    /** A band around the line, `width` in the stroke's units; default colour black. Drawn UNDER every
+     *  node's body at the same z, so two outlined roads merge at their junction (give a class of roads
+     *  one z; a different z isolates). */
+    outline?: {
+        width: number;
+        color?: ColorInput;
+    };
+};
+export type Path2DOptions = {
+    /** The outer ring, in the node's local frame. */
+    points: readonly Vec2Like[];
+    /** Close the ring (a polygon). Fills always close; this is about the stroke. Default false for
+     *  line() and a plain constructor, true for polygon() / rect() / circle(). */
+    closed?: boolean;
+    /** A number = `{ width }`. Omit = no stroke. */
+    stroke?: Stroke2D | number;
+    /** Omit = no fill. */
+    fill?: ColorInput;
+    /** Hole rings — fills only. */
+    holes?: readonly (readonly Vec2Like[])[];
+    /** Edge anti-aliasing (default true). Off for crisp pixel-art lines. */
+    antialias?: boolean;
+    position?: Vec2Like;
+    /** Degrees, CCW. */
+    rotation?: number;
+    scale?: Vec2Like | number;
+    /** Draw order within a renderPriority — see {@link Node2D.z}. */
+    z?: number;
+    /** Coarse draw order 0..7, default 4 — see {@link Node2D.renderPriority}. */
+    renderPriority?: number;
+    /** Only `blend` matters for a path (no texture); see Material2D. */
+    material?: Material2D;
+};
+type ShapeOptions = Omit<Path2DOptions, "points" | "closed">;
+export declare class Path2D extends Node2D {
+    private _pts;
+    private _closed;
+    private _stroke;
+    private _outlined;
+    private _fill;
+    private _holes;
+    private _antialias;
+    private _material?;
+    constructor(options: Path2DOptions);
+    /** An open polyline. */
+    static line(points: readonly Vec2Like[], stroke: Stroke2D | number, options?: Omit<Path2DOptions, "points" | "stroke" | "fill" | "closed">): Path2D;
+    /** A closed polygon; give it a `fill` and / or a `stroke`. */
+    static polygon(points: readonly Vec2Like[], options?: ShapeOptions): Path2D;
+    /** A rectangle of `size` centred on the node's origin. */
+    static rect(size: Vec2Like, options?: ShapeOptions): Path2D;
+    /** A circle centred on the node's origin. `segments` defaults to clamp(round(radius / 2), 12, 96) —
+     *  generous, because a fill is not re-tessellated when the camera zooms in. */
+    static circle(radius: number, options?: ShapeOptions & {
+        segments?: number;
+    }): Path2D;
+    /** The outer ring (local frame). A write re-tessellates natively — move the node instead when you can. */
+    get points(): Vec2[];
+    set points(points: readonly Vec2Like[]);
+    /** Whether the stroke closes the ring (fills always close). */
+    get closed(): boolean;
+    set closed(v: boolean);
+    /** The stroke, or null = none. A number = `{ width }`. */
+    get stroke(): Stroke2D | null;
+    set stroke(s: Stroke2D | number | null);
+    /** The fill colour, or null = no fill. */
+    get fill(): ColorInput | null;
+    set fill(c: ColorInput | null);
+    /** Hole rings (fills only). A write replaces them all. */
+    get holes(): Vec2[][];
+    set holes(rings: readonly (readonly Vec2Like[])[]);
+    /** Edge anti-aliasing (default true); off for crisp pixel-art lines. */
+    get antialias(): boolean;
+    set antialias(v: boolean);
+    /** Blend ({@link Material2D}) — only `blend` matters for a path. Undefined = the default (alpha). */
+    get material(): Material2D | undefined;
+    set material(m: Material2D);
+}
+export {};

package/dist/types/g2/Physics2D.d.ts

@@ -124,7 +124,7 @@ export declare class Physics2D extends Aspect<"physics", Node2D> {
      *  between us". Capped at 32 hits. */
     static raycastAll(from: Vec2Like, to: Vec2Like, q?: Query2D): RayHit[];
     /** Topmost body (solid or sensor) whose shape contains the world point, or null. "Topmost" means
-     *  by DRAW order - layer, then z - so picking agrees with what the player sees. */
+     *  by DRAW order - renderPriority, then z - so picking agrees with what the player sees. */
     static overlapPoint(p: Vec2Like, q?: Query2D): Node2D | null;
     /** Everything within `radius` of a point - an explosion, an aura, an aggro range. */
     static overlapCircle(centre: Vec2Like, radius: number, q?: Query2D): Node2D[];

package/dist/types/g2/Scene2D.d.ts

@@ -9,21 +9,16 @@ import { type Node2D } from "./Node2D";
 export type Scene2DOptions = {
     /** Background color — '#10131a', 0x10131a, or [r,g,b]/[r,g,b,a] in 0..1. */
     background?: ColorInput;
-    /** Texture sampling for the 2D renderer: `'nearest'` (default — crisp pixel art) or `'linear'`
-     *  (smooth — for hi-res / non-pixel-art assets). Applied when the scene is opened, so switching
-     *  scenes restores the active scene's choice. NOTE: this is a GLOBAL renderer setting (one sampler
-     *  for ALL textures, not per-texture), so the currently-open scene's filter wins. Omit to leave the
-     *  current setting (engine default is nearest). */
+    /** The renderer's DEFAULT texture sampling: `'nearest'` (crisp pixel art — the engine default) or
+     *  `'linear'` (smooth — hi-res / non-pixel-art assets). A node's `Material2D` `filter` overrides it
+     *  per sprite / tilemap; this is what a material without one samples with. A GLOBAL renderer
+     *  setting, so it is reasserted when the scene is opened (switching scenes restores the active
+     *  scene's choice). Omit to leave the current setting. */
     filter?: 'nearest' | 'linear';
+    /** Top-down depth: among nodes of one renderPriority and one z, the one lower on screen (smaller
+     *  world Y) draws on top. See {@link Scene2D.ySort}. */
+    ySort?: boolean;
 };
-/** Returned by scene2d.layer(n); chain .ySort() to enable top-down depth sorting for that layer. */
-declare class LayerHandle {
-    private readonly sceneId;
-    private readonly layer;
-    constructor(sceneId: number, layer: number);
-    /** In this layer, lower-on-screen sprites overlap higher ones (top-down feet sorting). */
-    ySort(enabled?: boolean): this;
-}
 export declare class Scene2D implements Presentable {
     /** Native scene handle. */
     readonly id: number;
@@ -34,12 +29,16 @@ export declare class Scene2D implements Presentable {
      *  engine variant of an app built with `lecodes app`; there `new Scene2D()` throws. */
     static get supported(): boolean;
     readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node2D | null>) => void>;
-    /** Texture filter to (re)assert on open(); the sampler is global, so each scene reclaims it. */
+    /** Default texture filter to (re)assert on open(); the setting is global, so each scene reclaims it. */
     private readonly _filter?;
+    private _ySort;
     constructor(options?: Scene2DOptions);
     set background(color: ColorInput);
-    /** Address a draw layer to configure it, e.g. scene2d.layer(1).ySort(). */
-    layer(n: number): LayerHandle;
+    /** Top-down depth sorting, one flag for the scene: among nodes of one `renderPriority` and one `z`,
+     *  the one lower on screen (smaller world Y) draws on top — give characters and props a feet anchor
+     *  (`[0.5, 1]`). Draw order is renderPriority, then z, then this. Default off. */
+    get ySort(): boolean;
+    set ySort(v: boolean);
     /** Topmost visible sprite whose world bounds contain the world point, or null. Body-free
      *  hit-test for tap/click picking — pair with camera.screenToWorld(). */
     pick(worldPoint: Vec2Like): Node2D | null;
@@ -84,4 +83,3 @@ export declare class Scene2D implements Presentable {
     close(options?: DismissOptions): this;
     destroy(): void;
 }
-export {};

package/dist/types/g2/Sprite.d.ts

@@ -3,6 +3,7 @@ import { Vec2, type Vec2Like } from "../math/vec";
 import { Canvas } from "../canvas/Canvas";
 import { Node2D, type Node2DTweenProps } from "./Node2D";
 import type { Texture2D } from "./Texture2D";
+import type { Material2D } from "./Material2D";
 import { type TweenMeta } from "../animate/tween/spec";
 import type { Animation } from "../animate/tween/Animation";
 /** Animatable sprite props on top of the 2D transform. */
@@ -13,6 +14,7 @@ export type SpriteTweenProps = Node2DTweenProps & {
 /** Anything that can back a sprite: a texture, or a Canvas (baked to a texture on assign). */
 export type TextureSource = Texture2D | Canvas;
 export type SpriteOptions = {
+    /** Omit the texture for a solid rect of `color` with `size`. */
     texture?: TextureSource;
     /** Pivot, [0,0] = top-left .. [1,1] = bottom-right. Use [0.5, 1] (feet) for Y-sorted depth. */
     anchor?: Vec2Like;
@@ -23,7 +25,10 @@ export type SpriteOptions = {
     /** Tint multiplied with the texture. */
     color?: ColorInput;
     opacity?: number;
-    layer?: number;
+    /** Coarse draw order 0..7, default 4 — see {@link Node2D.renderPriority}. */
+    renderPriority?: number;
+    /** Blend + sampling — see {@link Material2D}. Default `Material2D.default`. */
+    material?: Material2D;
     position?: Vec2Like;
 };
 export declare class Sprite extends Node2D {
@@ -34,7 +39,9 @@ export declare class Sprite extends Node2D {
     private _flipX;
     private _flipY;
     private _size;
+    private _material?;
     constructor(options?: SpriteOptions);
+    /** The art; undefined = a solid rect of `color` (the engine's white texture). */
     get texture(): Texture2D | undefined;
     set texture(t: TextureSource | undefined);
     /** Current world size: explicit override if set, else the texture's pixel dimensions (a Canvas-backed
@@ -54,6 +61,10 @@ export declare class Sprite extends Node2D {
     set color(c: ColorInput);
     get opacity(): number;
     set opacity(a: number);
+    /** Blend + sampling ({@link Material2D}); undefined = the default (alpha, renderer filter, clamp).
+     *  A material is data: assign a new one to change it. */
+    get material(): Material2D | undefined;
+    set material(m: Material2D);
     get flipX(): boolean;
     set flipX(v: boolean);
     get flipY(): boolean;

package/dist/types/g2/SpriteSheet.d.ts

@@ -33,7 +33,10 @@ export type SpriteSheetDef = {
 };
 export type SpriteMakeOptions = {
     position?: Vec2Like;
-    layer?: number;
+    /** Coarse draw order 0..7, default 4 — see {@link Node2D.renderPriority}. */
+    renderPriority?: number;
+    /** Draw order within a renderPriority — see {@link Node2D.z}. */
+    z?: number;
     /** Overrides the sheet/sprite anchor. */
     anchor?: Vec2Like;
     /** Start this clip immediately (sliced sprites with clips). */

package/dist/types/g2/Text2D.d.ts

@@ -0,0 +1,96 @@
+import { type ColorInput } from "../core/color";
+import { Vec2, type Vec2Like } from "../math/vec";
+import { Node2D } from "./Node2D";
+import type { Font2D } from "./Font2D";
+import type { Material2D } from "./Material2D";
+export type TextAlign2D = "left" | "center" | "right";
+export type TextOutline2D = {
+    /** Halo width in em: 0.05 thin … 0.15 the maximum. 0 = none. */
+    width: number;
+    /** Default black. */
+    color?: ColorInput;
+};
+export type Text2DOptions = {
+    font: Font2D;
+    text: string;
+    /** Em height. `units: 'world'` (default) world units; `'px'` logical screen px — constant while the
+     *  camera zooms (map labels, nameplates). Default 16. */
+    fontSize?: number;
+    units?: "world" | "px";
+    /** Default white. */
+    color?: ColorInput;
+    /** Line alignment inside the block; default 'left'. */
+    align?: TextAlign2D;
+    /** Wrap width in fontSize units; omit = no wrap. '\n' always breaks. */
+    maxWidth?: number;
+    /** Multiplier of the font's own line height (default: the font's). */
+    lineHeight?: number;
+    /** Extra spacing between letters, in em. Default 0. */
+    letterSpacing?: number;
+    /** A halo around the glyphs; omit = none. */
+    outline?: TextOutline2D;
+    /** Block anchor, [0,0] top-left … [1,1] bottom-right; default [0.5, 0.5] (centred on the node). */
+    anchor?: Vec2Like;
+    position?: Vec2Like;
+    /** Degrees, CCW. */
+    rotation?: number;
+    scale?: Vec2Like | number;
+    /** Draw order within a renderPriority — see {@link Node2D.z}. */
+    z?: number;
+    /** Coarse draw order 0..7, default 4 — see {@link Node2D.renderPriority}. */
+    renderPriority?: number;
+    /** Only `blend` matters for a text; see Material2D. */
+    material?: Material2D;
+};
+export declare class Text2D extends Node2D {
+    private _font;
+    private _text;
+    private _fontSize;
+    private _units;
+    private _color;
+    private _align;
+    private _maxWidth?;
+    private _lineHeight?;
+    private _letterSpacing;
+    private _outline;
+    private _anchor;
+    private _material?;
+    constructor(options: Text2DOptions);
+    private _sendText;
+    private _sendStyle;
+    /** The string; '\n' breaks a line. A write re-lays out the block natively. */
+    get text(): string;
+    set text(v: string);
+    get font(): Font2D;
+    set font(f: Font2D);
+    /** Em height, in `units`. */
+    get fontSize(): number;
+    set fontSize(v: number);
+    /** 'world' (default) scales with the camera; 'px' = logical screen px, constant while zooming. */
+    get units(): "world" | "px";
+    set units(v: "world" | "px");
+    get color(): ColorInput;
+    set color(c: ColorInput);
+    get align(): TextAlign2D;
+    set align(v: TextAlign2D);
+    /** Wrap width in fontSize units; undefined = no wrap. */
+    get maxWidth(): number | undefined;
+    set maxWidth(v: number | undefined);
+    /** Multiplier of the font's own line height; undefined = the font's. */
+    get lineHeight(): number | undefined;
+    set lineHeight(v: number | undefined);
+    /** Extra spacing between letters, in em. */
+    get letterSpacing(): number;
+    set letterSpacing(v: number);
+    /** The halo, or null = none. */
+    get outline(): TextOutline2D | null;
+    set outline(o: TextOutline2D | null);
+    /** Block anchor, [0,0] top-left … [1,1] bottom-right. */
+    get anchor(): Vec2;
+    set anchor(v: Vec2Like);
+    /** Blend ({@link Material2D}) — only `blend` matters for a text. Undefined = the default (alpha). */
+    get material(): Material2D | undefined;
+    set material(m: Material2D);
+    /** The laid-out block [width, height] in fontSize units (from the engine). */
+    get bounds(): Vec2;
+}

package/dist/types/g2/Tilemap.d.ts

@@ -1,5 +1,6 @@
 import { Node2D } from "./Node2D";
 import type { Texture2D } from "./Texture2D";
+import type { Material2D } from "./Material2D";
 export type TilemapOptions = {
     texture: Texture2D;
     /** Map grid size (in tiles). */
@@ -11,10 +12,17 @@ export type TilemapOptions = {
     atlas: [number, number];
     /** Row-major tile indices into the atlas (-1 = empty), length cols*rows. Row 0 is the top row. */
     data: number[] | Int32Array;
+    /** Blend + sampling — see {@link Material2D}. Default `Material2D.default`. */
+    material?: Material2D;
 };
 export declare class Tilemap extends Node2D {
     readonly cols: number;
     readonly rows: number;
+    private _material?;
     constructor(options: TilemapOptions);
+    /** Blend + sampling ({@link Material2D}); undefined = the default (alpha, renderer filter, clamp).
+     *  A material is data: assign a new one to change it. */
+    get material(): Material2D | undefined;
+    set material(m: Material2D);
     setTile(x: number, y: number, index: number): this;
 }

package/dist/types/g2/defineScene2d.d.ts

@@ -5,6 +5,10 @@ import { Scene2D } from "./Scene2D";
 import { Node2D } from "./Node2D";
 import { Sprite } from "./Sprite";
 import { Tilemap } from "./Tilemap";
+import { Path2D, type Stroke2D } from "./Path2D";
+import { Text2D, type TextAlign2D, type TextOutline2D } from "./Text2D";
+import { Particles2D, type Particles2DOptions } from "./Particles2D";
+import { type Material2DOptions } from "./Material2D";
 import { SpriteSheet } from "./SpriteSheet";
 import type { SpriteAnimation } from "./SpriteAnimation";
 import type { CellsData } from "./cells";
@@ -12,8 +16,12 @@ import type { With } from "../core/Aspect";
 export type Scene2dEnv = {
     /** Background color — '#5a6b3b', 0x5a6b3b, or [r,g,b] in 0..1. */
     background?: ColorInput;
-    /** Texture sampling: 'nearest' (crisp pixel art, engine default) or 'linear'. */
+    /** Default texture sampling: 'nearest' (crisp pixel art, engine default) or 'linear'. A node's
+     *  `material.filter` overrides it. */
     filter?: "nearest" | "linear";
+    /** Top-down depth: among nodes of one renderPriority and one z, the one lower on screen draws on
+     *  top (see Scene2D.ySort). */
+    ySort?: boolean;
     /** Pixel-art crispness: snap the camera to whole screen pixels (seeds CameraFollow's
      *  `pixelSnap`, and the initial camera position lands on whole world units). */
     pixelPerfect?: boolean;
@@ -47,6 +55,48 @@ export type TilemapSourceDef = {
         data: number[] | Int32Array;
     };
 };
+/** A vector node (Path2D): a polyline / polygon in the node's local frame. */
+export type PathSourceDef = {
+    points: readonly Vec2Like[];
+    /** Close the stroke's ring (fills always close). Default false. */
+    closed?: boolean;
+    /** A number = `{ width }`. Omit = no stroke. */
+    stroke?: Stroke2D | number;
+    /** Omit = no fill. */
+    fill?: ColorInput;
+    /** Hole rings — fills only. */
+    holes?: readonly (readonly Vec2Like[])[];
+    /** Edge anti-aliasing (default true). */
+    antialias?: boolean;
+};
+/** A text node (Text2D). `font` is a STRING: a family registered by `font("…")` (what the macro
+ *  compiles to, e.g. "Inter") or a font file URL — `asset('./fonts/Brand.ttf')`. */
+export type TextSourceDef = {
+    font: string;
+    text: string;
+    /** Em height (default 16), in `units`. */
+    fontSize?: number;
+    /** 'world' (default) or 'px' — logical screen px, constant while the camera zooms. */
+    units?: "world" | "px";
+    /** Default white. */
+    color?: ColorInput;
+    align?: TextAlign2D;
+    /** Wrap width in fontSize units; omit = no wrap. */
+    maxWidth?: number;
+    /** Multiplier of the font's own line height. */
+    lineHeight?: number;
+    /** Extra spacing in em. */
+    letterSpacing?: number;
+    outline?: TextOutline2D;
+    /** Block anchor, [0,0] top-left … [1,1] bottom-right; default [0.5, 0.5]. */
+    anchor?: Vec2Like;
+};
+/** A particle system node (Particles2D): the Particles2D options, with `texture` as a STRING — the
+ *  sheet image's URL (`asset('./spark.png')`), loaded with Texture2D.load. The blend is the node's
+ *  generic `material`; position / z / renderPriority are the node's too. */
+export type Particles2DSourceDef = Omit<Particles2DOptions, "texture" | "material" | "position" | "z" | "renderPriority"> & {
+    texture?: string;
+};
 /** A camera marker node: seeds the scene camera's starting position (+ zoom). To MOVE the camera
  *  in play, attach `CameraFollow` to the node being followed — not aspects on this marker. */
 export type Camera2dNodeDef = {
@@ -55,6 +105,9 @@ export type Camera2dNodeDef = {
 export type Scene2dNodeDef = {
     sprite?: SpriteSourceDef;
     tilemap?: TilemapSourceDef;
+    path?: PathSourceDef;
+    text?: TextSourceDef;
+    particles?: Particles2DSourceDef;
     camera?: Camera2dNodeDef;
     /** A code-built subtree — `make(factoryFn, { ...literal args })`, factory returns a Node2D. */
     make?: SharedMakeEntry<any, Node2D>;
@@ -62,11 +115,14 @@ export type Scene2dNodeDef = {
     /** Degrees, CCW. */
     rotation?: number;
     scale?: Vec2Like | number;
-    /** Draw layer (int) — higher renders on top. */
-    layer?: number;
-    /** Intra-layer depth for non-Y-sorted layers. */
+    /** Coarse draw order 0 (first) … 7 (last), default 4 — see Node2D.renderPriority. */
+    renderPriority?: number;
+    /** Draw order within a renderPriority (higher = on top); with `env.ySort`, equal z sorts by Y. */
     z?: number;
-    /** Sprite tint (sprite nodes only). */
+    /** Blend + sampling (sprite, tilemap, text and particles nodes; only `blend` matters for a text) —
+     *  see Material2D. */
+    material?: Material2DOptions;
+    /** Sprite tint / text colour (sprite and text nodes). */
     color?: ColorInput;
     /** Sprite opacity 0..1 (sprite nodes only). */
     opacity?: number;
@@ -84,10 +140,6 @@ export type Scene2dCameraDef = {
 };
 export type Scene2dDef = {
     env?: Scene2dEnv;
-    /** Per-layer config, keyed by layer number: `layers: { 1: { ySort: true } }`. */
-    layers?: Record<number | string, {
-        ySort?: boolean;
-    }>;
     /** Starting camera when there's no camera NODE (a camera node wins). */
     camera?: Scene2dCameraDef;
     nodes?: Record<string, Scene2dNodeDef>;
@@ -102,7 +154,13 @@ type SourceNodeOf<N extends Scene2dNodeDef> = N extends {
     sprite: SpriteSourceDef;
 } ? Sprite : N extends {
     tilemap: TilemapSourceDef;
-} ? Tilemap : Node2D;
+} ? Tilemap : N extends {
+    path: PathSourceDef;
+} ? Path2D : N extends {
+    text: TextSourceDef;
+} ? Text2D : N extends {
+    particles: Particles2DSourceDef;
+} ? Particles2D : Node2D;
 type AspectsOf<N extends Scene2dNodeDef> = N extends {
     aspects: readonly AspectEntry<infer A>[];
 } ? A : never;
@@ -135,7 +193,7 @@ export declare class Scene2dHandle<D extends Scene2dDef = Scene2dDef> {
 /**
  * Define a 2D scene as data — the default export of a `.scene2d.ts` file. Returns a typed handle:
  * `const { scene, nodes } = await handle.open()` gives `nodes.<name>` typed by its source block
- * (Sprite / Tilemap / Node2D) with its `use(...)`d aspects attached.
+ * (Sprite / Tilemap / Path2D / Text2D / Particles2D / Node2D) with its `use(...)`d aspects attached.
  */
 export declare const defineScene2d: <const D extends Scene2dDef>(def: D) => Scene2dHandle<D>;
 export {};

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

@@ -38,13 +38,6 @@ export type FoliageOptions = {
     /** 0..1: how far the baked per-vertex sky visibility (the crown's interior, the trunk under it) darkens the ambient.
      *  Default 0.7. */
     skyAo?: number;
-    /** 0..1: a leaf card's shading normal, from the card's own plane (0) to the crown's hull normal (1) — what hides that a
-     *  crown is flat quads: each card is lit as the part of the volume it sits in. Default 0.7. */
-    canopy?: number;
-    /** The cards' normal-map strength (a strong map brings the planes back). Default 0.5. */
-    normalMap?: number;
-    /** A card seen edge-on dissolves over this much of |N·V| — no paper edges on the silhouette. Default 0.15, 0 = none. */
-    edgeFade?: number;
     /** Coverage held over distance: the cards' alpha × (1 + coverage × mip level), so a far crown does not thin out as its
      *  atlas mips away. Default 0.25, 0 = none; past ~0.5 a crown turns into a solid mass. */
     coverage?: number;

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

@@ -1,3 +1,4 @@
+import { Texture } from "./Texture";
 import { Node } from "./Node";
 import type { Scene } from "./Scene";
 /** The level's bake / load options: `bake()`'s second argument (an object literal, copied into the def as written). */
@@ -25,7 +26,7 @@ export type LightmapOptions = {
      *  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>;
     /** FOR THE BAKE: CUBES BY NAME — regular expressions (ECMAScript, case-sensitive) searched in every record's key
-     *  (`<node key>@<ordinal>`: `"SM_pipe"` takes every pipe node, `"@1$"` the second mesh of each): a record that matches
+     *  (`<node key>@<ordinal>`: `"SM_pipe"` takes every pipe node, `"@1$"` the second node primitive of each): a record that matches
      *  leaves the atlas like a small or thin one — an occluder lit by ambient cubes baked where it stands — whatever its size
      *  or charts. Added to the CLI's `--cube` patterns (both apply). */
     cube?: string[];
@@ -69,6 +70,9 @@ export type LightmapFiles = {
     /** THE PACKED LIGHTMAP UV1 (`<stem>-uv1.bin`): the bake packs every mesh's lightmap charts into a square of their own
      *  and its rects map that uv1 — the engine swaps it into the models' TEXCOORD_1 before the rects go on. */
     uv1?: string;
+    /** THE STATIC LEVEL CACHE (`<stem>.static`, gl/Statics.ts): the snapshot `lecodes static` wrote beside the bake; the macro
+     *  stages it when it exists, and `load()` rebuilds the level's statics from it when its digest still matches. */
+    statics?: string;
 };
 /** What `bake('<path>.bake', options)` compiles to — the files of the bake and the level's options in one literal:
  *  `env.lightmap` in a scene file, `Lightmap.load`'s argument in a hand-built scene. */
@@ -81,6 +85,7 @@ export type LightmapDebugParams = {
 };
 /** What `Lightmap.probe` answers: the baked texel under a screen point. */
 export type LightmapProbe = {
+    /** the bake's record (`<key>@<ordinal>`) whose rect holds the texel; "" when none does */
     key: string;
     entity: number;
     node: string;
@@ -100,6 +105,91 @@ export type LightmapAddOptions = {
      *  (`--object-slab`). Default false. */
     cube?: boolean;
 };
+/** a small static's light where it stands (creator-bake objects.h): its SLABS along `axis` (0 x, 1 y, 2 z; its bounds run
+ *  from `from` to `to` along it) — one for a small one, round(length / objectSlab) for a long one — and per slab per side
+ *  of its box (+x -x +y -y +z -z) the irradiance rgb in lux + the sky visibility; probes = a, b, a's weight (-1 = none,
+ *  -2 = the sky) */
+export type BakeObjectLight = {
+    at: number[];
+    axis: number;
+    from: number;
+    to: number;
+    cubes: number[][][];
+    probes: number[];
+};
+/** a RECORD of the .bake: a registered node's key, or `<key>@<ordinal>` for one mesh of a model (creator-bake atlas.h) */
+export type BakeInstance = {
+    key: string;
+    receiver: boolean;
+    small?: boolean;
+    light?: BakeObjectLight;
+    page?: number;
+    rect?: number[];
+    st?: number[];
+};
+type BakeProbes = {
+    file: string;
+    size: number;
+    levels: number;
+    count: number;
+    oct: number;
+    tile: number[];
+    perRow: number;
+    atlas: number[];
+    spacing: number;
+    layout: "rooms" | "grid";
+    /** the block size of the pages' probe maps (atlas texels) and the range their records decode with: lo xyz, size xyz */
+    map: number;
+    encode: number[];
+    positions: number[][];
+    boxes: number[][];
+    /** per probe: its open share of the sphere (0 = a room, over 0.15 = under the sky) */
+    sky: number[];
+};
+export type BakeData = {
+    version: number;
+    size: number;
+    pages: number;
+    texel: number;
+    lightScale: number;
+    texels?: number;
+    light: string[];
+    aux: string[];
+    direct?: string[];
+    indirect?: string[];
+    probes?: BakeProbes | null;
+    /** the light grid (creator-bake volume.h): its file and lattice */
+    volume?: {
+        file: string;
+        n: number[];
+        origin: number[];
+        cell: number[];
+        valid: number;
+    } | null;
+    /** the packed lightmap uv1 the rects map (creator-bake atlas.h), null = the models' own */
+    uv1?: string | null;
+    sun?: {
+        direction: number[];
+        color: number[];
+        lux: number;
+    } | null;
+    sunMap?: boolean;
+    sunMapLevels?: number;
+    mips?: number;
+    emissiveNits?: number;
+    instances: BakeInstance[];
+};
+/** What `Lightmap.prepare` hands `apply`: the bake read and its pages loaded. */
+export type LightmapPrepared = {
+    def: LightmapDef;
+    data: BakeData;
+    n: number;
+    light: Texture[];
+    aux: Texture[];
+    probes: number;
+    probeAtlas?: Texture;
+    t: 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;
@@ -145,6 +235,14 @@ export declare class Lightmap {
      *  to (a scene file's `env.lightmap`). Resolves to null when nothing was applied (no bake yet, a host without the
      *  feature, bake mode). */
     private static scene;
+    /** `load` in two halves (the static level cache binds records as it clones, so the pages must be in BEFORE the
+     *  statics build): `prepare` reads the bake, swaps the uv1 in, loads the pages / probes and sets the level-wide
+     *  options; `apply` binds the rects of the statics the SDK registered, then the light grid. */
+    static prepare(scene: Scene, def: LightmapDef): Promise<LightmapPrepared | null>;
+    /** The bake's page texture ids, light / aux interleaved per page — what the static level cache binds with. */
+    static pageIds(p: LightmapPrepared): Uint32Array;
+    static apply(p: LightmapPrepared): Promise<LightmapInfo | null>;
+    /** Bind a bake to the level: the statics registered so far take their rects, the movers the light grid. */
     static load(scene: Scene, def: LightmapDef): Promise<LightmapInfo | null>;
     /** The bake's `<key>@k` records by their node key: a model's meshes (k = the primitive's ordinal in its file). */
     private static recordsOf;
@@ -161,7 +259,7 @@ export declare class Lightmap {
     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,
+    /** The baked texel under a screen point (logical px): its record 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;
@@ -176,3 +274,4 @@ export declare class Lightmap {
     private static meshMaterial;
     private static bake;
 }
+export {};