lecodes-sdk 0.19.0

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

@@ -0,0 +1,79 @@
+import { Vec3 } from "../math/vec";
+import { Node } from "./Node";
+import { Ray } from "./Ray";
+/** Projection every host starts a scene with (creator-gl scene.cpp / the lite core agree on these). */
+export declare const CAMERA_DEFAULTS: {
+    fov: number;
+    near: number;
+    far: number;
+};
+export declare class Camera extends Node {
+    private _sceneId;
+    /** Live projection matrix (updated by the host when the viewport/fov changes). */
+    readonly projectionMatrix: Float32Array<ArrayBuffer>;
+    private _fov;
+    private _near;
+    private _far;
+    /** Stay quiet until the app actually sets something — hosts may be configured with their own
+     *  defaults (the headless core takes a `fov` option) and a blind push would overwrite them. */
+    private _projSet;
+    private _exposure;
+    private _ev;
+    private _exposureSet;
+    /** Exposure compensation in stops (default 0): +1 doubles how bright the scene renders, −2
+     *  quarters it. The one exposure knob most games need — a dark interior, a flash of white, or eye
+     *  adaptation when the sun swings into view (drop it, and the sun stays at the display's peak
+     *  while everything else darkens). Scene light follows it; particle `emissive` is post-exposure
+     *  and does not, so a fireball keeps its on-screen brightness. Cheap to animate every frame. */
+    get exposureCompensation(): number;
+    set exposureCompensation(stops: number);
+    /** The physical camera: `aperture` in f-stops, `shutterSpeed` in seconds, `iso`, plus the same
+     *  `compensation` in stops — any subset, one call. `camera.setExposure({ iso: 400 })` is two stops
+     *  brighter than the default f/16 · 1/125 · ISO 100. */
+    setExposure(exposure: {
+        aperture?: number;
+        shutterSpeed?: number;
+        iso?: number;
+        compensation?: number;
+    }): this;
+    /** Hosts that predate the call keep the fixed default (older wasm / native builds). */
+    private _applyExposure;
+    /** Vertical field of view in degrees (default 60) — a smaller angle is a longer lens. */
+    get fov(): number;
+    set fov(degrees: number);
+    get horizontalFov(): number;
+    /** Near clip distance (default 0.01) — nothing closer than this draws. */
+    get near(): number;
+    set near(distance: number);
+    /** Far clip distance / view range (default 1000) — geometry past it is culled. Shadows keep
+     *  their own (shorter) range, so a long view distance doesn't cost shadow sharpness. */
+    get far(): number;
+    set far(distance: number);
+    /** Set any of fov / near / far in one call: `camera.setProjection({ fov: 45, far: 5000 })`. */
+    setProjection(projection: {
+        fov?: number;
+        near?: number;
+        far?: number;
+    }): this;
+    /** Hosts that predate the call keep the fixed defaults (older wasm / native builds). */
+    private _applyProjection;
+    private _following;
+    /** The node the camera currently follows (`follow()`), or null. */
+    get following(): Node | null;
+    /**
+     * Make the camera ride a node: every late frame the camera takes the node's WORLD pose (−Z =
+     * view direction), so movement aspects / animation on that node are camera moves — dolly shots,
+     * a cutscene path, a `CameraPlace` in a scene file. A node carrying a `CameraPlace` also hands
+     * over its projection (fov / near / far). `follow(null)` releases the camera where it is.
+     * One camera per scene: following a new node stops following the previous one.
+     */
+    follow(target: Node | {
+        node: Node;
+        applyTo(camera: Camera): void;
+    } | null): this;
+    get displaySize(): [number, number];
+    /** World-space ray direction through a screen pixel. */
+    getViewDirection(screenX: number, screenY: number): Vec3;
+    /** A pick ray from the camera through a screen pixel. */
+    getRay(screenX: number, screenY: number): Ray;
+}

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

@@ -0,0 +1,26 @@
+import { Aspect } from "../core/Aspect";
+import type { FieldMeta } from "../core/fields";
+import type { Camera } from "./Camera";
+import type { Node } from "./Node";
+export declare class CameraPlace extends Aspect<"cameraPlace", Node> {
+    static readonly aspect = "cameraPlace";
+    /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+    fov: number;
+    /** Near clip distance. */
+    near: number;
+    /** Far clip distance = view range. */
+    far: number;
+    /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
+     *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
+    active: boolean;
+    /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
+    static fields: FieldMeta<CameraPlace>;
+    static editor: {
+        rebuild: boolean;
+    };
+    /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
+    applyTo(camera: Camera): void;
+    /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
+     *  clicking it selects the node. Play mode never calls this. */
+    rebuild(): void;
+}

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

@@ -0,0 +1,98 @@
+import { Aspect } from "../core/Aspect";
+import type { FieldMeta } from "../core/fields";
+import { Vec3, type Vec2Like, type Vec3Like } from "../math/vec";
+import type { CompWriter } from "../core/compWrite";
+import type { Node } from "./Node";
+/** Where the character's feet are, as reported by the solver after the last step. */
+export type GroundState = "ground" | "slope" | "unsupported" | "air";
+export declare class CharacterController extends Aspect<"controller", Node> implements CompWriter {
+    static readonly aspect = "controller";
+    static fields: FieldMeta<CharacterController>;
+    private _charId;
+    private _gravityScale;
+    private _maxSlope;
+    onAttach(): void;
+    onDetach(): void;
+    /** Native character id (0 until attached / no physics support). */
+    get id(): number;
+    /**
+     * This frame's movement command, in world units/s — NOT normalized, NOT a per-frame displacement
+     * (that is what Unity's `Move` takes; passing `v * dt` here gives a character 60× too slow).
+     *
+     * Two components = horizontal `(x, z)`, the everyday call. Three = the whole velocity, for free mode
+     * (`gravityScale = 0`); with gravity on, the vertical component fights the ballistic one and the
+     * character barely falls, so that combination warns.
+     *
+     * Sticky only within the frame: the command expires once the engine consumes it. It also **takes the
+     * axis back from a latched `velocity`** — commanding is claiming ownership, which is what keeps the
+     * two horizontal sources from ever fighting.
+     */
+    move(x: number, z: number): void;
+    move(v: Vec2Like | Vec3Like): void;
+    /** Vertical velocity (world units/s) — LATCHED: gravity works on it, you seed it. `= 7` to jump,
+     *  `+= 3` to stack an explosion on top of the current motion. No ground check: guard it yourself
+     *  with `grounded` (or don't, for a double jump). Overridden every frame by a 3-component `move()`.
+     *  `velocity.y = 7` is the same channel — pick whichever reads better. */
+    get velocityY(): number;
+    set velocityY(v: number);
+    /** Multiplier over the world gravity (`Physics.configure({ gravity })`); default 2, for the snappier
+     *  fall games want. **0 = free mode**: no gravity, no stick-to-floor, no stair stepping — a swimmer
+     *  or a drone, driven by the 3-component `move()`. */
+    get gravityScale(): number;
+    set gravityScale(v: number);
+    /** Max ground slope (degrees) the character treats as walkable; default 45. Live. */
+    get maxSlope(): number;
+    set maxSlope(v: number);
+    /**
+     * True while a requested collider resize hasn't taken — you asked to stand up and there is something
+     * overhead. Resizing goes through the `Shape` aspect itself:
+     *
+     *     hero.aspect(Shape, { capsule: CROUCHED })   // always fits — you are shrinking
+     *     hero.aspect(Shape, { capsule: STANDING })   // may be refused under a low ceiling
+     *     if (hero.controller.resizing) …             // still crouched; call it again next frame
+     *
+     * A refusal changes nothing, so the retry is just the same call again — and it is an exact headroom
+     * test against the real capsule, unlike a hand-rolled raycast (a ray is a line; a capsule has girth).
+     * The FEET stay planted across a resize, so the character neither hovers nor sinks.
+     */
+    get resizing(): boolean;
+    /** True while standing on walkable ground. */
+    get grounded(): boolean;
+    /** Where the feet are after the last step: on walkable ground, on too-steep ground, touching
+     *  something that can't support it, or in the air. */
+    get groundState(): GroundState;
+    /**
+     * READ — the velocity the solver ended up with after the most recent step (world units/s, fresh
+     * Vec3): what HAPPENED, not what you asked for. Walking into a wall reads ~0, sliding along one
+     * reads the tangent. Unlike Unity's synchronous `Move`, our step runs later in the frame, so a read
+     * is up to one frame old — irrelevant for animation speed, fall damage or "am I blocked", which is
+     * what it is for. (Exact wall contact would need a contact normal; the engine has none yet.)
+     *
+     * WRITE — LATCH the whole velocity: a knockback, a wall jump, a launch pad. Unlike `move()` it does
+     * not expire, so the character keeps flying, and gravity still pulls the vertical down into a real
+     * ballistic arc. It stays until `move()` takes the axis back — so a game simply doesn't call
+     * `move()` while the throw lasts, and ends it on its own terms:
+     *
+     *     hero.controller.velocity = [dir.x * 12, 6, dir.z * 12]   // hit by the blast
+     *     // …in the loop:
+     *     if (thrown) { if (hero.controller.grounded) thrown = false }   // landing ends it
+     *     else hero.controller.move(ix * SPEED, iz * SPEED)              // …and this reclaims the axis
+     *
+     * Note nothing clears the latch by itself, landing included — so a thrown character that never gets
+     * a `move()` keeps sliding along the ground (a kinematic controller has no friction).
+     *
+     * Reading is not the inverse of writing: `c.velocity = c.velocity` is NOT a no-op, because the read
+     * reports the measured result (against a wall it is ~0 and would cancel the throw). In flight the
+     * two agree closely, so read-modify-write mid-air behaves as expected.
+     *
+     * `c.velocity.y = 7` (the direct spelling) is a jump — the compiler routes it to the exact
+     * `velocityY` channel via `_writeComp` below, no vector allocated — and `c.velocity.x = 3` latches
+     * the whole vector with the measured velocity filling in the other two, i.e. the read-modify-write
+     * above spelled naturally. A STORED copy is still a copy: `const v = c.velocity; v.y = 7` does nothing.
+     */
+    get velocity(): Vec3;
+    set velocity(v: Vec3Like);
+    /** Compile-time list (chisel reads it, then strips it): the getters whose `c.<getter>.<axis> = v`
+     *  spelling is routed to `_writeComp` below. See core/compWrite.ts. */
+    static _comps: string[];
+}

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

@@ -0,0 +1,86 @@
+import { Aspect } from "../core/Aspect";
+import type { FieldMeta } from "../core/fields";
+import type { Node } from "./Node";
+import type { Vehicle } from "./Vehicle";
+export declare class Gearbox extends Aspect<"gearbox", Node> {
+    static readonly aspect = "gearbox";
+    /** Forward gear ratios, first gear first. Engine RPM = wheel speed × ratio × the differential. */
+    ratios: number[];
+    /** Reverse ratio — negative, because a ratio's SIGN is what reverse means to the engine. */
+    reverse: number;
+    /** Shift up when the engine passes this fraction of its redline. */
+    shiftUp: number;
+    /** Shift down when it falls below this fraction. */
+    shiftDown: number;
+    /** How long a shift takes, in seconds — the clutch is out for this long. */
+    shiftTime: number;
+    /** How long the clutch takes to re-engage afterwards. */
+    clutchTime: number;
+    /** How long to wait after a shift before another is allowed — without it a car sitting on a
+     *  threshold hunts between two gears. */
+    latency: number;
+    /** How far the clutch bites the instant drive is asked for from rest, 0..1. It only has to COUPLE
+     *  the shafts — how much torque that passes is the engine's business, so a feathered throttle
+     *  still pulls away gently at the same bite point. */
+    bite: number;
+    static fields: FieldMeta<Gearbox>;
+    /** Current gear: −1 reverse, 0 neutral, 1… forward. Read it for a HUD. */
+    gear: number;
+    /** True while a shift is in progress — the clutch is out and the engine is not driving the wheels. */
+    get shifting(): boolean;
+    private _shiftLeft;
+    private _engageLeft;
+    private _waitLeft;
+    private _take;
+    /** EARLY phase: the pair has to be latched before this frame's step consumes it. */
+    updateBefore(dt: number): void;
+    /**
+     * The driver's left foot: where the clutch pedal is, ignoring shifts. Returns the new engagement.
+     *
+     * A driver does not compute anything. They watch the tacho: **revs sinking to idle means the
+     * wheels are about to drag the engine under, and that is when you push the clutch in.** That
+     * single test replaces every ratio and threshold — the crossover it finds is the exact speed where
+     * engine braking stops and the engine would start PUSHING instead, and it finds it per gear
+     * without being told the gear.
+     *
+     * The pedal comes back UP only for the throttle. Healthy revs are not on their own a reason to
+     * engage: a car standing still shows healthy revs too — the wheels simply are not turning to say
+     * otherwise — and a clutch dropped on that evidence lurches the car off with no throttle at all.
+     *
+     * Three things fall out of it for free:
+     *
+     * - **A braked car stops.** The engine cannot stall, so a clutch left in at 0 km/h feeds idle
+     *   torque to the wheels forever and the car creeps against its own brakes. Here the revs pin at
+     *   idle, so the pedal goes down and the brakes have nothing to fight.
+     * - **Reverse is not a special case.** No ratio takes part, so it needs no separate number — which
+     *   is exactly why a fixed road-speed threshold got reverse wrong.
+     * - **Hill starts judder instead of stalling.** Let the pedal out, the load pulls the revs down,
+     *   the rule pushes it straight back in, and the clutch sits slipping at the bite point until the
+     *   car moves. So the test deliberately ignores the throttle — gating it on "no throttle" would
+     *   stall the car under load. Throttle only holds the floor at `bite`.
+     *
+     * The cost is honest and small: once the pedal is down the revs sit at idle and cannot rise on
+     * their own, so **coasting downhill gives no engine braking until you touch the throttle** — which
+     * is precisely what a car with the clutch in does. Slipping it permanently to keep listening would
+     * bring the creep straight back.
+     */
+    protected takeUp(v: Vehicle, dt: number): number;
+    /**
+     * Which gear the car should be in. The default is an ordinary automatic: pull away from neutral in
+     * the direction of the throttle, shift up past `shiftUp` of the redline and down below `shiftDown`,
+     * and refuse to shift again for `latency` seconds. Override this and nothing else.
+     */
+    select(v: Vehicle): number;
+    /** Change gear now, with the clutch envelope. Safe to call from `select()` or from game code
+     *  (a sequential manual is `if (Input.key('KeyE')) car.gearbox.shift(car.gearbox.gear + 1)`). */
+    shift(gear: number): void;
+    /** The ratio the engine should be running: 0 in neutral, negative in reverse. */
+    get ratio(): number;
+    /**
+     * The clutch scalar 0..1 the engine is given: the SHIFT envelope (out during a shift, ramping back
+     * over `clutchTime`) times the driver's pedal (`takeUp`). Two independent reasons for the clutch
+     * to be out, so they multiply: mid-shift is out however healthy the revs are, and an engine being
+     * dragged to idle is out whatever gear it just picked.
+     */
+    get clutch(): number;
+}

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

@@ -0,0 +1,39 @@
+import { type Vec3Like } from "../math/vec";
+export type MeshKind = "triangles" | "vertices" | "edges";
+export declare class Geometry {
+    vertices: Float32Array;
+    normals: Float32Array;
+    indices: Uint16Array;
+    uv: Float32Array;
+    /** Lightmap UV set (2 floats per vertex, non-overlapping, inside the unit square) — the
+     *  `Lightmap` atlas samples a Mesh through it. The box and cylinder builders fill it (their `uv`
+     *  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;
+    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;
+    scaleUV(x: number, y: number): this;
+    set kind(kind: MeshKind);
+    /** A box; `size` (default 1) scales the vertices AND lays the lightmap chart out in proportion to
+     *  the faces' areas (a floor's top face gets the texels, not its 1 m side strips). */
+    static box(size?: Vec3Like | number): Geometry;
+    static sphere(options?: SphereOptions): Geometry;
+    static cylinder(options?: CylinderOptions): Geometry;
+    static plane(options?: PlaneOptions): Geometry;
+}
+export type SphereOptions = {
+    radius?: number;
+    widthSegments?: number;
+    heightSegments?: number;
+};
+export type CylinderOptions = {
+    radius?: number;
+    radiusTop?: number;
+    radiusBottom?: number;
+    edges?: number;
+    smooth?: boolean;
+};
+export type PlaneOptions = {
+    normal?: Vec3Like;
+};

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

@@ -0,0 +1,53 @@
+import { Aspect } from "../core/Aspect";
+import { type Vec3Like } from "../math/vec";
+import { Quat } from "../math/quat";
+import type { Node } from "./Node";
+type Target = Node | Vec3Like;
+/** Two-bone analytic IK (limbs). Attach to the END bone: `foot.aspect(IK.TwoBone, { target })`
+ *  solves upper (grandparent) + mid (parent) so the end reaches `target`; `pole` steers the bend
+ *  (knee/elbow) — a Node or world point. */
+declare class TwoBone extends Aspect<"ik", Node> {
+    static readonly aspect = "ik";
+    /** Where the end bone should be (Node or world position). */
+    target?: Target;
+    /** Bend hint — the mid joint is pulled toward it (Node or world position). */
+    pole?: Target;
+    /** World rotation the END bone takes after the solve — a Node (its world rotation) or a Quat.
+     *  Unset = the end bone keeps its animated local rotation (a hand on a grip, a foot on a slope
+     *  want it set). Blended by `weight · rotationWeight`. */
+    rotation?: Node | Quat;
+    /** 0–1 contribution of `rotation` (on top of `weight`). */
+    rotationWeight: number;
+    /** 0–1 contribution (blend in/out, e.g. foot planting only while grounded). */
+    weight: number;
+    /** Solve every frame (default). Set false to drive `solve()` yourself. */
+    enabled: boolean;
+    update(): void;
+    /** One solve at the current pose. Safe to call manually (e.g. from a later-ordered aspect). */
+    solve(): void;
+}
+/** Aim a bone at a target (head / eyes / turret). Attach to the bone itself:
+ *  `head.aspect(IK.LookAt, { target: camera, limit: 70 })`. `axis` is the bone's LOCAL forward
+ *  (the direction that should point at the target) — rigs differ; default −Z, Mixamo heads look
+ *  along +Z of the head bone in most exports, so pass `axis: [0, 0, 1]` there if it faces backwards. */
+declare class LookAt extends Aspect<"lookAt", Node> {
+    static readonly aspect = "lookAt";
+    target?: Target;
+    /** The bone's local axis that should point at the target. */
+    axis: Vec3Like;
+    /** Max deflection from the animated direction, in degrees (default 80). */
+    limit: number;
+    /** 0–1 contribution. */
+    weight: number;
+    enabled: boolean;
+    update(): void;
+    solve(): void;
+}
+/** Inverse kinematics aspects — attach to bones (see file header). */
+export declare const IK: {
+    TwoBone: typeof TwoBone;
+    LookAt: typeof LookAt;
+};
+export type IKTwoBone = TwoBone;
+export type IKLookAt = LookAt;
+export {};

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

@@ -0,0 +1,46 @@
+import { Mat4, type Mat4Like } from "../math/mat4";
+import { type QuatLike } from "../math/quat";
+import { type Vec3Like } from "../math/vec";
+import type { Geometry } from "./Geometry";
+import { Material } from "./Material";
+import type { MeshOptions } from "./Mesh";
+import { Node } from "./Node";
+/** One instance's placement, local to the InstancedMesh node. Omitted fields mean identity. */
+export type InstanceTransform = {
+    position?: Vec3Like;
+    /** Quaternion; wins over `eulerAngles`. */
+    rotation?: QuatLike;
+    /** Degrees (YXZ), like `Node.eulerAngles`. */
+    eulerAngles?: Vec3Like;
+    scale?: Vec3Like | number;
+};
+export declare class InstancedMesh extends Node {
+    /** Instance capacity, fixed at construction. Unset instances are hidden. */
+    readonly count: number;
+    private _geometry;
+    private _material;
+    private _data;
+    private _lo;
+    private _hi;
+    constructor(geometry: Geometry, count: number, options?: MeshOptions);
+    get geometry(): Geometry;
+    get material(): Material;
+    set material(m: Material);
+    /** Shadow flags for all instances (both at once — the engine sets them per draw). */
+    setShadows(cast: boolean, receive?: boolean): this;
+    private _touch;
+    /** Place instance `i`. Pending until `commit()`. */
+    setAt(i: number, t: InstanceTransform): this;
+    /** Place instance `i` from a 4×4 column-major matrix (local to this node). */
+    setMatrixAt(i: number, m: Mat4Like): this;
+    /** Hide instance `i` (a zero matrix — no geometry is emitted for it). */
+    hideAt(i: number): this;
+    /** Bulk write: `matrices` holds 16 floats per instance, starting at instance `offset`. */
+    setMatrices(matrices: ArrayLike<number>, offset?: number): this;
+    /** The 4×4 of instance `i` as stored (a copy). */
+    matrixAt(i: number): Mat4;
+    /** Upload every change since the last commit (one bridge call covering the dirty range). */
+    commit(): this;
+    /** Whether edits are waiting for `commit()`. */
+    get dirty(): boolean;
+}

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

@@ -0,0 +1,73 @@
+import { type ColorInput } from "../core/color";
+import type { Vec3Like } from "../math/vec";
+import { Node } from "./Node";
+export type SunOptions = {
+    /** Light direction (points where the light travels). Defaults to a typical key-light angle. */
+    direction?: Vec3Like;
+    /** Luminous intensity. */
+    intensity?: number;
+    color?: ColorInput;
+    /**
+     * Shadow quality (default 1):
+     *   0 - no shadows
+     *   1 - 1024 map, hard edges (one filtered tap; the cheap level, ~3 % of a frame on an iGPU)
+     *   2 - 1024 map, soft edges (variance shadows + blur; ~+15 % of a frame on an iGPU)
+     *   3 - 2048 map, contact-hardening soft edges (PCSS: sharp where the caster touches, softer
+     *       away; discrete-GPU territory, ~+60 % of a frame on an iGPU)
+     * A lightmapped level already carries every static shadow, so 0 is a legitimate choice there.
+     */
+    shadowsQuality?: 0 | 1 | 2 | 3;
+    /**
+     * Metres from the camera within which the sun casts shadows (default 100). Shadows fade out by
+     * this distance and the shadow map covers only this range, so a shorter distance is crisper for
+     * the same quality and puts fewer casters in the shadow pass. 30-40 is plenty in first person.
+     */
+    shadowDistance?: number;
+};
+export type PointOptions = {
+    /**
+     * Luminous POWER in lumens — the same physical scale as the sun's lux and `environmentIntensity`,
+     * so a light keeps its look when the scene's exposure changes. A candle is ~12 lm, a bare 60 W
+     * bulb ~800, a car headlight ~1500, a fireball millions. Default 1000.
+     */
+    intensity?: number;
+    color?: ColorInput;
+    /**
+     * Metres of influence — past it the light contributes nothing. This is the performance knob:
+     * overlapping point lights are the expensive case, so keep it as small as the look allows.
+     * Default 10.
+     */
+    range?: number;
+    /** Point-light shadows are a cubemap render per light; off by default. */
+    castShadows?: boolean;
+    /**
+     * Whether `lecodes lightmap bake` bakes this light into the level's lightmap (docs/lightmap-plan.md).
+     * A baked light is switched OFF at runtime once the bake applies — statics read it from the atlas,
+     * movers from the light volume — so it costs nothing per frame; a light that must stay live (a
+     * flicker, a lamp the player can shoot out) says `baked: false` and is kept out of the bake.
+     * Lights created after the level loads (a muzzle flash) are never in a bake. Default true.
+     */
+    baked?: boolean;
+};
+export declare class Light extends Node {
+    private _intensity;
+    /** The most recently created sun — what `Lightmap.load` uses unless told otherwise. */
+    static lastSun: Light | null;
+    /** A directional sun light. */
+    static sun(options?: SunOptions): Light;
+    /**
+     * A point light — a lamp, a muzzle flash, a fireball. Position it like any node.
+     *
+     * Feature-detected: hosts that predate it create the node and light nothing, which keeps a scene
+     * that adds atmosphere on top of its sun renderable everywhere. Check `Light.supportsPoint`
+     * before making one carry the scene.
+     */
+    static point(options?: PointOptions): Light;
+    /** Whether this host can create point lights at all. */
+    static get supportsPoint(): boolean;
+    /** Live intensity (sun: lux, point: lumens) — animate a flash without rebuilding the light. */
+    get intensity(): number;
+    set intensity(value: number);
+    destroy(): void;
+    set color(value: ColorInput);
+}

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

@@ -0,0 +1,85 @@
+import { Node } from "./Node";
+import type { Scene } from "./Scene";
+export type LightmapLoadOptions = {
+    /** 1 = baked sun shadows at full strength, 0 = ambient occlusion only. Default 1. */
+    sunStrength?: number;
+    /** Multiplier on the ambient (IBL) share in the shadow math — how bright a fully shadowed texel
+     *  stays. 1 reproduces filament's own real-time shadow darkness (the shader reads the scene's sun
+     *  and IBL from filament's per-frame uniforms); raise it for lighter shadows, lower for deeper. Default 1. */
+    ambientScale?: number;
+    /** How much of the baked ambient occlusion applies: 1 = all of it, 0 = none. An interior lit by
+     *  its ambient probe alone can want less than the geometric truth. Default 1. */
+    aoStrength?: number;
+    /** Multiplier on the baked point lights' irradiance (default 1). Purely ARTISTIC: the bake is
+     *  physical (verified against the analytic 1/d^2 sum over the level's lamps - where line of sight
+     *  is clear the two agree within ~17 %), and a room lit to its real illuminance simply reads dim
+     *  against an ambient fill. This dials the lamps up without a re-bake, since their irradiance is
+     *  IN the atlas and `--lamp-gain` would cost a full one.
+     *  It scales the atlas AND the light volume together, so statics and movers stay consistent - but
+     *  note they are NOT equally forgiving: a static surface carries the bake's own cosine and
+     *  shadowing, while a mover reads the volume through a flat half-cosine, so a large boost blows
+     *  movers out long before it blows out the level. Past ~x100 expect to light the movers
+     *  separately. */
+    lightBoost?: number;
+    /** Multiplier on the light VOLUME's irradiance alone — the movers' own `lightBoost`. Default =
+     *  `lightBoost`, and since 2026-08-31 that default is the right one: the volume is an ambient cube
+     *  (irradiance per axis face, blended by the pixel's normal), so a mover's top takes a lamp above it
+     *  and its underside does not — the same shading the atlas gives the statics. Before that the volume
+     *  was one flat 0.5·E on every face and this knob was the workaround. Kept as a trim. */
+    volumeBoost?: number;
+};
+export type LightmapInfo = {
+    size: number;
+    texel: number;
+    /** Atlas pages the bake took (`texture` lists them in order). */
+    pages: number;
+    /** The light volume, when one was loaded: grid dims + cell size in metres. */
+    volume?: {
+        dims: number[];
+        cell: number;
+    };
+    /** Point lights the bake carries and this load switched off (statics read them from the atlas,
+     *  movers from the volume); 0 without a `light` atlas. */
+    lights: number;
+    /** keys applied / keys in the file / registered statics without a rect */
+    applied: number;
+    total: number;
+    missing: string[];
+};
+export type LightmapFiles = {
+    data: string;
+    /** The atlas — one page, or every page in order for a bake that took several. */
+    texture: string | string[];
+    /** The point lights' baked irradiance (pages like `texture`). */
+    light?: string | string[];
+    volume?: string;
+};
+export declare class Lightmap {
+    /** True while `lecodes lightmap bake` runs the app — skip menus and build the scene straight away. */
+    static get baking(): boolean;
+    private static entries;
+    private static dynamics;
+    private static ordinals;
+    private static warned;
+    private static switchedOff;
+    /** Register static geometry — a Model, a Mesh, or any node whose subtree holds them. Statics are
+     *  both receivers and occluders in the bake. `key` names the entry in lightmap.bake (default:
+     *  the node's name + a running number, `container#3`); pass one when names are not stable. */
+    static add(node: Node, key?: string): Node;
+    private static next;
+    /** Forget every registration (a scene rebuild); baked-off lights come back to the real-time path. */
+    static clear(): void;
+    /** Apply a bake — or, under `lecodes lightmap bake`, run it. Resolves to null when nothing was
+     *  applied (no bake yet, a host without the feature, bake mode). */
+    static load(scene: Scene, files: LightmapFiles, options?: LightmapLoadOptions): Promise<LightmapInfo | null>;
+    /** Every live point light within 5 cm of a baked one is held dark (a moved lamp keeps lighting live
+     *  — and double, until the next bake, which is the honest state of a stale bake). */
+    private static switchOffBaked;
+    /** lightmap.volume → the engine's 3D textures → THE volume for every dynamic lightmap-material instance,
+     *  plus the registered dynamic Meshes. Null when the file is a placeholder or the host lacks the feature. */
+    private static loadVolume;
+    /** A Mesh keeps its look (colour / map / roughness / metallic) but moves to the lightmap material. */
+    private static meshMaterial;
+    private static swapMeshMaterial;
+    private static bake;
+}