lecodes-sdk 0.19.0

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

@@ -0,0 +1,279 @@
+import { Aspect } from "../core/Aspect";
+import { Vec3, type Vec3Like } from "../math/vec";
+import { Animator, type FeetOptions, type WarpOptions } from "./animation/Animator";
+import type { Node } from "./Node";
+/** How fast the character wants to go: the gait picks its clips and its speed. */
+export type Gait = "walk" | "run" | "sprint";
+/** What the engine shows: the idle, a start, the gait loop, a turn while moving, a stop, or a turn on the spot. */
+export type LocomotionState = "idle" | "start" | "move" | "turn" | "stop" | "spin";
+/** Who moves the body:
+ *  `'hybrid'` (the default) — the clip's own recorded motion moves it; while the gait loop shows it
+ *    is ADJUSTED toward what the simulation wants by at most `tuning.adjust` metres a second, and a
+ *    start / turn / stop / spin moves it alone. The recording keeps the feet honest, the clamp keeps
+ *    the player in charge of the arcs. What a pack authored with root motion wants.
+ *  `'code'` — the simulation moves it and the animation has to be warped to follow (stride warping);
+ *    for packs recorded in place.
+ *  `'data'` — the clips' root motion moves it and nothing adjusts it; the simulation only predicts. */
+export type Displacement = "hybrid" | "code" | "data";
+/** One clip of the set: its name, or the name with what the clip itself cannot say — `gait` (which
+ *  gait a transition belongs to: a walking body plays the walking starts, stops and turns; left out =
+ *  any gait) — and overrides for what the engine would otherwise measure: `angle` (degrees the clip
+ *  turns the body, + = left) for a start / turn / spin, `speed` (m/s) for a gait clip. */
+export type LocomotionClip = string | {
+    clip: string;
+    gait?: Gait;
+    angle?: number;
+    speed?: number;
+};
+/** The clips the selector may show. Everything but `idle` is a list; an empty one simply means the
+ *  engine never shows that kind (a pack without turns steers through them instead). */
+export type LocomotionSet = {
+    /** standing still */
+    idle?: LocomotionClip;
+    /** the gait loop's members, slowest first — walk, run, sprint. Blended by the simulated speed. */
+    gaits?: LocomotionClip[];
+    /** standing → moving, one per direction (the engine picks by the turn each one makes) */
+    starts?: LocomotionClip[];
+    /** moving → standing */
+    stops?: LocomotionClip[];
+    /** turns taken while moving */
+    turns?: LocomotionClip[];
+    /** turns on the spot — what a facing still owed by a standing body plays */
+    spins?: LocomotionClip[];
+};
+/** The tuning. Times are seconds, speeds m/s, angles degrees. */
+export type LocomotionTuning = {
+    /** How briskly the simulated speed reaches the wanted one — the halflife of the difference, per
+     *  gait (default 0.27 walking, 0.2 running). Smaller = more responsive, larger = heavier. */
+    responseWalk?: number;
+    responseRun?: number;
+    /** How briskly the body brakes when nothing is asked for (default 0.15). Braking is not
+     *  acceleration backwards: a body plants and stops in far less than it takes to reach a run, and
+     *  with the gait's own number the tail of the curve is a long, visible glide. */
+    responseStop?: number;
+    /** The same for the facing (default 0.15). */
+    responseFacing?: number;
+    /** Top speed per gait. Left out (the default), each gait travels at the speed its own clip was
+     *  recorded at — which is what keeps the feet from sliding. */
+    speeds?: Partial<Record<Gait, number>>;
+    /** The step warp's split when a gait is asked for at a speed that is not its clip's own: the
+     *  STRIDE (spatial squash of the leg's reach) gets ratio^strideShare, clamped to `strideBand`,
+     *  and the cadence takes all the rest — the asked speed is always delivered exactly.
+     *  0 = all cadence (slow motion), 1 = all stride (within the band). Default 0.5. */
+    strideShare?: number;
+    /** How far the stride's share may squash or stretch the legs' reach (default [0.85, 1.15]) —
+     *  past it the warp re-bends legs the clip authored straight. */
+    strideBand?: [number, number];
+    /** PIN the step warp's stride ratio (a tuning bench's knob): the step width is held at exactly
+     *  this, whatever speed is asked — the body's speed falls out of stride × cadence instead of
+     *  driving the split. Leave out (or 0) for automatic. */
+    warpStride?: number;
+    /** PIN the step warp's cadence ratio the same way — the animation's pace held at exactly this.
+     *  With both pinned, stride and pace are fully independent. Leave out (or 0) for automatic. */
+    warpCadence?: number;
+    /** Cap on how fast the body may turn by STEERING, deg/s (default: uncapped) — the arc it walks when
+     *  the heading is off by less than `turnMin`. A start / turn / spin clip owns the facing while it
+     *  turns: the body then turns exactly as much as the (warped) animation does. */
+    turnRate?: number;
+    /** Heading error that plays a turn clip instead of steering through it (default 60°). Which turn
+     *  clip is not a threshold: every one is entered where the gait phase allows nearest to its pivot,
+     *  and the one whose turn LEFT from there best answers the error wins. */
+    turnMin?: number;
+    /** Facing still owed by a standing body that turns it on the spot (default 30°). Less than this it
+     *  accepts — a standing body never rotates by code, that is the one thing no tuning makes look right. */
+    spinMin?: number;
+    /** Transition seconds between clips (default 0.2), and into the idle after a stop (default 0.3). */
+    blend?: number;
+    stopBlend?: number;
+    /** How far a start / turn / spin clip's recorded turn may be SCALED so it delivers exactly the heading
+     *  asked for, as a fraction (default 0.3 = ×0.7 … ×1.3). What lies beyond the clamp is steered once
+     *  the body moves. 0 = the recording is law. */
+    yawWarp?: number;
+    /** A start or a turn hands over to the gait loop at the first foot-down after its turn is delivered
+     *  at which its pose is within this many metres of the loop's — the engine's baked fit curve —
+     *  instead of at its end (default 0.15). 0 = at the end. */
+    exitTolerance?: number;
+    /** A stop asked to move again resumes the gait loop while the body still travels at this fraction of
+     *  the gait's speed or more (default 0.5); slower, it starts afresh. */
+    resumeSpeed?: number;
+    /** …and then let it play this many more FOOT-DOWNS before handing over (default 0). `exitTolerance`
+     *  answers "when has this pose become the walk's", which is the earliest honest moment and not always
+     *  the best-looking one — a start that has just found the gait still reads as a start for another step
+     *  or two. 1 or 2 gives a take room to finish its thought; a take that runs out hands over at its own
+     *  end regardless, so nothing can hang. */
+    exitSteps?: number;
+    /** How much braking room, in metres, to trade for each second of a stop take's lead-in that would
+     *  otherwise be skipped (default 0). A stop cannot be rewound — the variants are one cycle long, so
+     *  no earlier frame has the same foot down — so the only way to begin a stop nearer its own start is
+     *  to prefer the VARIANT that starts there for the foot the body happens to be on. Raise it (0.5…1.5)
+     *  to see the whole braking gesture; leave it at 0 to land exactly where the body should stop. */
+    stopEarly?: number;
+    /** How much braking room, in metres, one extra FOOT-DOWN in the stop is worth (default 0). A stop
+     *  take is one cycle long, so wanting another step means wanting a LONGER variant, and a longer one
+     *  lands the body further along than it asked to stop — the trade is this number. Around 1 buys a
+     *  second step on a pack like Mobility Pro; 0 lands exactly where the body should stop. */
+    stopSteps?: number;
+    /** How far a stop take's pose may be from the one showing, in metres, for it to be entered BEFORE
+     *  its own first foot-down (default 0.25). Ahead of that footfall a take's phase curve is an
+     *  extrapolation: it can match the body's phase arithmetically with the legs at a different stage
+     *  of the stride, which is why the pose is asked directly. 0 = never enter a take early — the body
+     *  then takes whatever later entry matches its foot, which on a walk can be three quarters of the
+     *  way through a take, on top of one of its plants. */
+    stopFit?: number;
+    /** What a metre of POSE distance at the entry is worth against a metre of braking room when the
+     *  variants are ranked (default 1). Both are metres and the feet pay both: room the body has not
+     *  got is taken out of the root while a foot is planted, and a pose the transition has to hide is
+     *  dragged out of that same foot over the blend. 0 = rank by braking room alone, which picks a
+     *  take by where it ENDS and lets it start from any pose at all. */
+    stopPose?: number;
+    /** Input magnitude below which a stick counts as released (default 0.2). */
+    deadZone?: number;
+    /** `displacement: 'hybrid'`: how far, m/s, the body may be pushed off what the animation recorded,
+     *  toward what the simulation wants, while the gait loop shows (default 0.5) — a start, turn, stop
+     *  or spin moves the body alone, since pushing it there is its planted foot skating. 0 = the
+     *  recording is law; large = the code is law — responsive, and the feet start lying. */
+    adjust?: number;
+};
+/** One stop take as the selector weighed it, from `stopReport()`. A stop is chosen for the foot the
+ *  body stands on and the room it needs: `phaseOk` and `afterFirstStep` are the two pass/fail rules,
+ *  `score` ranks whatever passed (lower wins), and `chosen` marks the one that plays. */
+export type StopCandidate = {
+    /** the take's clip name */
+    clip: string;
+    /** seconds into it the entry would be — near its end means its braking gesture is skipped */
+    at: number;
+    /** metres it still travels from that entry */
+    room: number;
+    /** metres this body needs to come to rest (the same for every row) */
+    need: number;
+    /** seconds from the entry to its next foot-down */
+    wait: number;
+    /** foot-downs left after the entry: 0 = it plants where it stands */
+    steps: number;
+    /** does it have a frame at the body's own cycle phase (the right foot down)? */
+    phaseOk: boolean;
+    /** is that frame at or after its own first foot-down? Ahead of it the phase curve is an
+     *  extrapolation — it can match arithmetically at the wrong stage of the stride */
+    afterFirstStep: boolean;
+    /** …and it is ahead of it, but its POSE matched what is showing closely enough to be let in
+     *  anyway (`fit` under `tuning.stopFit`) */
+    earlyByPose: boolean;
+    /** the one that is playing */
+    chosen: boolean;
+    /** |room − need| + the pose distance + how late in the take (lower wins) */
+    score: number;
+    /** how far this entry's pose is from the one showing, in the fit measure's metres (-1 = not
+     *  measured). Under `tuning.stopFit` an entry ahead of the take's first foot-down is allowed. */
+    fit: number;
+};
+export type LocomotionEvents = {
+    /** What the selector shows changed. */
+    state: (state: LocomotionState) => void;
+};
+export declare class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
+    static readonly aspect = "loco";
+    /** The animator whose clips are shown. Default: the first one on this node or under it (a Model
+     *  child), which is the usual character — a capsule node with the model inside. */
+    animator?: Animator;
+    /** The clips the selector may show. */
+    set: LocomotionSet;
+    /** Who moves the body (see `Displacement`). */
+    displacement: Displacement;
+    /** The feel (see `LocomotionTuning`). */
+    tuning: LocomotionTuning;
+    /** Fit the POSE to what the body does — stride and orientation warping (see `Animator.warp`, which
+     *  this simply sets). The simulation feeds the engine the body's motion every frame, so here it
+     *  only has to be turned on: `warp: true`, or `{ stride: [0.7, 1.4], orientation: 45 }`. Off by
+     *  default — a pack whose gaits already cover the speeds it is played at does not need it. */
+    warp?: WarpOptions | boolean;
+    /** The FEET (see `Animator.feet`, which this simply sets). Default: the foot lock on, ground IK off
+     *  — a planted foot stays where it landed through every transition the selector makes, which is the
+     *  last of the slide once the recording moves the body. `true` = lock + ground IK (stairs, slopes);
+     *  `false` = neither; or the options themselves. */
+    feet?: FeetOptions | boolean;
+    private _loco;
+    private _dir;
+    private _face;
+    private _mag;
+    private _gait;
+    private _seq;
+    private readonly _in;
+    private readonly _out;
+    private readonly _names;
+    private _report?;
+    private get anim();
+    private get controller();
+    protected onAttach(): void;
+    protected onDetach(): void;
+    /** Re-read the set and the tuning — after changing either at runtime (a weapon that changes the
+     *  walk, a slowed-down character). */
+    rebuild(): void;
+    /** Register one clip of the set: the engine measures the clip's own turn / speed unless given. */
+    private enter;
+    /** Why the stop that is playing is the one that plays: every candidate the selector weighed, in
+     *  the order it weighed them. Read it when a stop looks wrong — the answer is usually that the
+     *  take that would have looked right was rejected by one of the two rules, not that the score
+     *  picked badly. Empty until a stop has been chosen (and on hosts without the debug read). */
+    stopReport(): StopCandidate[];
+    /** Re-push the TUNING alone — the numbers, not the clip set. What a live tweak wants (a debug
+     *  slider, a character that gets heavier when hurt): `rebuild()` also re-measures the set, which
+     *  mid-clip is more than a changed number asks for. */
+    retune(): void;
+    private pushTuning;
+    /** State the movement intent for this frame: a world direction (its length is the stick's pull,
+     *  clamped to 1) and the gait. `null` = no movement — the body stops, but it keeps facing where it
+     *  was last asked to, and turns there on the spot if it still owes the turn.
+     *  `face` states a facing of its own (aiming, strafing, a camera-relative shooter). */
+    move(direction: Vec3Like | null | undefined, options?: {
+        gait?: Gait;
+        face?: Vec3Like;
+    }): void;
+    /** Face this way without moving — the facing intent on its own (`Vec3`, or a heading in degrees,
+     *  0 = +Z, + = toward +X). A standing body turns to it on the spot. */
+    face(direction: Vec3Like | number): void;
+    /** The gait the intent asks for. */
+    get gait(): Gait;
+    set gait(g: Gait);
+    /** Is a movement intent standing right now? (The debug answer to "is a key held".) */
+    get moving(): boolean;
+    /** The direction the intent points, world. */
+    get direction(): Vec3;
+    /** The heading the intent asks the body to face, degrees (0 = +Z, + = toward +X). */
+    get heading(): number;
+    /** The speed the intent asks for, m/s — it jumps the moment a key goes down or the gait changes.
+     *  `speed` is what the body has made of it. */
+    get intentSpeed(): number;
+    /** What the selector shows. */
+    get state(): LocomotionState;
+    /** The body's speed, m/s — the simulation's, which is what the animation is fitted to. */
+    get speed(): number;
+    /** The body's velocity, world m/s. */
+    get velocity(): Vec3;
+    /** Where the body faces, degrees (0 = +Z, + = toward +X) — the node's yaw, which this drives. */
+    get facing(): number;
+    /** Where the base layer is in the gait cycle, 0–1 (-1 when what shows has no cycle). */
+    get phase(): number;
+    /** How far the STOP that is showing was entered from the phase the body was on, in cycles, signed —
+     *  measured at the switch. 0 while no stop shows; ±0.5 would be the other foot on the ground. */
+    get stopFootOffset(): number;
+    /** Foot-downs left in the stop that is showing, counted from the frame it was entered at. 0 means it
+     *  was entered past its own last footfall — the body will not step, it will only settle. -1 when no
+     *  stop shows. The number behind "he did not take a step, he just pulled the foot back". */
+    get stopStepsLeft(): number;
+    /** Seconds from the frame the shown stop was entered at to its next foot-down. Large means it was
+     *  entered just AFTER a footfall: the leg is planted and then held still until the one after, which
+     *  reads as a foot that sticks. -1 when no stop shows. */
+    get stopStepWait(): number;
+    /** Degrees the clip showing still turns the body by (a start / turn / spin, after its warp); 0 for
+     *  the loop and the idle — the heading the engine has committed to but not yet delivered. */
+    get yawLeft(): number;
+    /** The shown transition's clip time and the time it hands over at, seconds (-1 for the loop / idle;
+     *  `exitAt` -1 = at the clip's end). A debug readout. */
+    get clipTime(): number;
+    get exitAt(): number;
+    /** Where the body will be in 0.2 / 0.4 / 0.7 s if the intent holds — the path the selector judges
+     *  a turn by, and a debug overlay's dots. */
+    get trajectory(): Vec3[];
+    protected updateBefore(dt: number): void;
+    protected updateFixed(dt: number): void;
+}

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

@@ -0,0 +1,100 @@
+import { type ColorInput } from "../core/color";
+import { type FetchResponse } from "../runtime/fetch";
+import { Texture } from "./Texture";
+import type { Canvas } from "../canvas/Canvas";
+type UniformValue = string | Texture | number | boolean | number[] | Float32Array | null;
+export type MaterialColorOptions = {
+    color?: ColorInput;
+    map?: Texture | Canvas | null;
+};
+/** `Material.unlit` options. */
+export type UnlitMaterialOptions = MaterialColorOptions & {
+    /** 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
+     *  fading marker, a sprite whose texture has cut-out alpha. Only then does `color`'s own alpha
+     *  (`"#ffffff80"`) mean anything; the opaque material has no alpha channel at all. */
+    transparent?: boolean;
+};
+/** `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. */
+    map?: Texture | null;
+    /** Flipbook grid: `N` = an N×N sheet, `[cols, rows]` = a non-square one. Frames run
+     *  left-to-right, top-to-bottom; drive the index via `particles.frame`. Default 1. */
+    sheet?: number | [number, number];
+    /** Extra brightness multiplier for a glow look (0 = off). */
+    emissive?: number;
+    /** (`render` quad / stretch) a second sheet on the same grid, ADDED as `emissiveMap × emissiveColor`
+     *  — keyed by `map`'s alpha, not tinted by the particle colour. A fireball = a smoke `map` whose
+     *  colour curve goes dark + a fire `emissiveMap` that keeps glowing while alpha lasts. */
+    emissiveMap?: Texture | null;
+    /** Multiplier for `emissiveMap`; an `[r, g, b]` array may exceed 1 (HDR glow). Default 0 (off). */
+    emissiveColor?: ColorInput;
+    /** (`render` quad / stretch) crossfade each flipbook frame into the next by the fractional frame
+     *  index instead of snapping — smooth sheet playback at any frame rate. Default false. */
+    frameBlend?: boolean;
+    /** Compositing: `"alpha"` (default — smoke, dust) or `"add"` (fire, sparks, magic). */
+    blend?: "alpha" | "add";
+    /** Soft radial falloff toward the sprite edge. Defaults to true without a map, false with one. */
+    soft?: boolean;
+    /** Soft particles: fade each sprite out over this many metres as it cuts into the scene geometry
+     *  behind it (Unity's "Soft Particles Factor"), so smoke and dust no longer slice through the
+     *  ground and walls with a hard edge. 0 = off (default). Reads the scene's depth buffer, which the
+     *  engine keeps bound while any soft system is on screen — the extra depth pass is only paid then.
+     *  Filament hosts (desktop / web / Android / Apple); web-lite draws such sprites unfaded. */
+    depthFade?: number;
+    /** How each particle is drawn: `'point'` (default — GPU point sprites, cheapest), `'quad'`
+     *  (real camera-facing quads — no driver size cap, geometric rotation), or `'stretch'`
+     *  (quads stretched along velocity — sparks, rain, speed streaks). `'ribbon'` is what `Trail`
+     *  uses internally. */
+    render?: "point" | "quad" | "stretch" | "ribbon";
+    /** (`render: 'stretch'`) extra sprite length in world units per unit of speed:
+     *  length = size + stretch·|velocity|. Default 0.05. */
+    stretch?: number;
+};
+/** `Material.lit` options — PBR scalars on top of the color/map pair. */
+export type LitMaterialOptions = MaterialColorOptions & {
+    /** 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;
+};
+export declare class Material {
+    readonly shader: FetchResponse | "unknown";
+    readonly uniforms: Record<string, UniformValue>;
+    private _colorKey;
+    constructor(shader: FetchResponse | number);
+    /** Set a uniform (chainable). */
+    set(key: string, value: UniformValue): this;
+    set color(c: ColorInput);
+    set map(value: Texture | Canvas | null);
+    /** PBR lit material. */
+    static lit(options?: LitMaterialOptions): Material;
+    /** Unlit (flat) material — opaque unless `transparent` asks for alpha blending. */
+    static unlit(options?: UnlitMaterialOptions): Material;
+    /** Default particle material — camera-facing point sprites with tint/opacity/rotation/flipbook
+     *  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;
+    /** Material that samples a VideoPlayer's texture. */
+    static video(map?: Texture): Material;
+    /** The lightmap material (docs/lightmap-plan.md): PBR base colour × a baked shadow/AO atlas on UV1.
+     *  Models take it through `Model.load(…, { lightmap: true })`; `Lightmap.load` builds one per static
+     *  Mesh. Parameters use gltfio's names (`baseColorFactor`, `baseColorMap`, `roughnessFactor`,
+     *  `metallicFactor`) plus `lightmap`, `lightmapST`, `ambientScale`, `sunStrength` (the sun / IBL terms come from
+     *  filament's per-frame uniforms inside the shader). */
+    static lightmap(): Material;
+    /** The terrain splat material (docs/terrain-plan.md §1.5): four albedo (+ normal-map) layers blended by
+     *  a control map on the terrain's own grid, per-layer `tiling` (metres per repeat) / `roughness` /
+     *  `normalScale` / `triplanar`, lightmap-aware (the same `lightmap` / `lightmapST` block as
+     *  `Material.lightmap`). `Terrain` builds and owns one per terrain; the uniforms are primed here so an
+     *  unset layer is white and an unbaked terrain is fully lit. */
+    static terrain(): Material;
+    private static _lmTemplate;
+    /** Shadow-catcher material (transparent except where shadows fall). */
+    static shadow(color?: ColorInput): Material;
+    /** Load a custom compiled shader (.mat URL) as a material. */
+    static load(url: string): Promise<Material>;
+}
+export {};

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

@@ -0,0 +1,33 @@
+import { type Vec3Like } from "../math/vec";
+import { Geometry, type CylinderOptions, type PlaneOptions, type SphereOptions } from "./Geometry";
+import { Material } from "./Material";
+import { Node } from "./Node";
+/** Common transform/render options every primitive factory accepts. */
+export type MeshOptions = {
+    material?: Material;
+    position?: Vec3Like;
+    eulerAngles?: Vec3Like;
+    scale?: Vec3Like | number;
+    name?: string;
+    castShadows?: boolean;
+    receiveShadows?: boolean;
+};
+export declare class Mesh extends Node {
+    private _geometry?;
+    constructor(geometry?: Geometry, material?: Material);
+    get geometry(): Geometry | undefined;
+    /** 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);
+    set castShadows(v: boolean);
+    set receiveShadows(v: boolean);
+    static box(options?: MeshOptions & {
+        size?: Vec3Like | number;
+    }): Mesh;
+    static sphere(options?: MeshOptions & SphereOptions): Mesh;
+    static cylinder(options?: MeshOptions & CylinderOptions): Mesh;
+    static plane(options?: MeshOptions & PlaneOptions): Mesh;
+    /** Wrap a custom Geometry. */
+    static from(geometry: Geometry, options?: MeshOptions): Mesh;
+}

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

@@ -0,0 +1,53 @@
+import { type FetchResponse } from "../runtime/fetch";
+import { Node } from "./Node";
+import { Animator, type LodMode } from "./animation/Animator";
+export declare class Model extends Node {
+    /** The model's Animator — always present, its clip table = the GLB's embedded clips. Configure
+     *  more (external clips, blend spaces, layers) with `model.aspect(Animator, {...})`. */
+    readonly anim: Animator;
+    constructor(internalId: number);
+    /** Does this model cast a real-time shadow? Unlike Mesh (one renderable) a GLB is a whole
+     *  hierarchy, so the flag goes to EVERY renderable of the instance. A first-person viewmodel —
+     *  arms, weapon, attachments — sets it false: it lives in front of the camera and its shadow
+     *  is never wanted. */
+    get castShadows(): boolean;
+    set castShadows(v: boolean);
+    /** Is this model lit by other casters' shadows? Same instance-wide reach as castShadows. */
+    get receiveShadows(): boolean;
+    set receiveShadows(v: boolean);
+    /** Frustum culling for the whole instance: a model the camera cannot see skips the draw and the
+     *  shadow pass. ON by default where the host keeps a skinned mesh's bounds honest — the engine refits
+     *  them to the joints every frame, so a walking, kneeling or ragdolled body is never culled while on
+     *  screen (`_creator.skinnedCullingSupported`); OFF (always draw) on hosts without that, where
+     *  Filament would cull an animated body by its bind-pose box. `false` = always draw (a skybox-sized
+     *  mesh, a debugging aid); `true` forces it on regardless of the host. */
+    get culling(): boolean;
+    set culling(v: boolean);
+    /** Level of detail (docs/lod-plan.md). `'auto'` (default): the engine shows the `_LOD<n>` mesh level
+     *  that fits the model's size on screen (`lecodes assets doctor --lod` makes them) and scales the
+     *  animation rate with it; a number 0–3 pins that level for both — `0` = always full detail (a hero,
+     *  a showcase), `2`/`3` = always cheap (a crowd filler). `model.anim.lod = 'full'` keeps the animation
+     *  exact while the mesh still switches. No-op on hosts without the LOD pass. */
+    get lod(): LodMode;
+    set lod(v: LodMode);
+    private static _cullDefault;
+    /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
+     *  the same parent and scene and sharing this model's current transform. The clone has its own
+     *  independent animation state (reach it via clone.anim). Mirrors this model's culling flag. */
+    clone(): Model;
+    /** Load a GLB model. Returns its root as a Model; play its baked clips via model.anim. */
+    static load(source: string | FetchResponse, options?: {
+        /** Frustum culling — see `culling` (default: on where the host refits skinned bounds, else off). */
+        culling?: boolean;
+        onProgress?: (p: {
+            loaded: number;
+            total?: number;
+        }) => void;
+        /** Baked lighting (docs/lightmap-plan.md). `true` = a STATIC: loads through the lightmap material so
+         *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 — `lecodes assets doctor
+         *  --lightmap-uv`). `'dynamic'` = a mover: the same material, lit by the level's light VOLUME instead
+         *  (no UV1 needed). Omitted: `'dynamic'` while a scene file with `env.lightmap.volume` is running,
+         *  else off. `false` = the standard shader. Hosts without lightmap support ignore it. */
+        lightmap?: boolean | "dynamic";
+    }): Promise<Model>;
+}

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

@@ -0,0 +1,99 @@
+import { Aspect } from "../core/Aspect";
+import type { FieldMeta } from "../core/fields";
+import { Vec3, type Vec3Like } from "../math/vec";
+import { NavCrowd } from "./NavMesh";
+import type { Node } from "./Node";
+export type NavAgentState = "idle" | "moving" | "arrived" | "blocked" | "offmesh";
+export type NavAgentAvoidance = "off" | "low" | "medium" | "high";
+export type NavAgentDrive = "position" | "controller";
+export type NavAgentEvents = {
+    /** Reached the target (within `stopDistance`). */
+    arrive: () => void;
+    /** The target cannot be reached — the agent stopped at the closest point (or nowhere near). */
+    blocked: () => void;
+};
+export declare class NavAgent extends Aspect<"agent", Node, NavAgentEvents> {
+    static readonly aspect = "agent";
+    /** The crowd advances first, then every agent applies its slot. */
+    static after: (typeof NavCrowd)[];
+    static fields: FieldMeta<NavAgent>;
+    private _radius;
+    private _height;
+    private _speed;
+    private _acceleration;
+    private _avoidance;
+    private _separation;
+    private _include;
+    private _exclude;
+    /** deg/s the node turns toward its velocity; 0 = never touch the rotation. */
+    turnSpeed: number;
+    /** How the node follows its slot. */
+    drive: NavAgentDrive;
+    /** Reached = within this many metres (along the corridor) of the target. */
+    stopDistance: number;
+    /** Agent radius (metres). Defaults to the navmesh's. */
+    get radius(): number;
+    set radius(v: number);
+    get height(): number;
+    set height(v: number);
+    /** Top speed (m/s). */
+    get speed(): number;
+    set speed(v: number);
+    get acceleration(): number;
+    set acceleration(v: number);
+    /** Local (agent-vs-agent) avoidance quality. */
+    get avoidance(): NavAgentAvoidance;
+    set avoidance(v: NavAgentAvoidance);
+    /** Separation force weight (0 = none). */
+    get separation(): number;
+    set separation(v: number);
+    /** Area names this agent may walk (default: all). */
+    get include(): string[] | undefined;
+    set include(v: string[] | undefined);
+    /** Area names this agent never enters. */
+    get exclude(): string[] | undefined;
+    set exclude(v: string[] | undefined);
+    state: NavAgentState;
+    /** The current velocity after avoidance (m/s). */
+    readonly velocity: Vec3;
+    /** The velocity the corridor asked for, before avoidance. */
+    readonly desiredVelocity: Vec3;
+    /** Metres left along the corridor (-1 = no target). */
+    remainingDistance: number;
+    /** Where the agent is going, or null. */
+    get target(): Vec3 | null;
+    get hasPath(): boolean;
+    private _crowd;
+    private _slot;
+    private _target;
+    /** velocity-driven (`move`) rather than target-driven */
+    private _steering;
+    private _dirty;
+    private _faceX;
+    private _faceZ;
+    private _retryAt;
+    private _lastSeen;
+    private _still;
+    private _near;
+    private _slow;
+    onAttach(): void;
+    onReconfigure(): void;
+    onDetach(): void;
+    /** Walk to a point. False = no walkable polygon near it (or no navmesh) — the current target stays. */
+    goTo(target: Vec3Like): boolean;
+    /** Drop the target and decelerate to a stop. */
+    stop(): void;
+    /**
+     * Steer by velocity instead of a target — a player on WASD, a scripted push: the crowd keeps
+     * the node on the mesh and avoids the other agents, no path and no arrival. Call it every fixed
+     * step (the last velocity holds until the next call); `move(0, 0)` stops. Cancels `goTo`.
+     * False = no navmesh / off the mesh.
+     */
+    move(vx: number, vz: number): boolean;
+    /** Teleport (a spawn, a respawn). The target, if any, is kept. */
+    warp(p: Vec3Like): void;
+    private params;
+    updateFixed(dt: number): void;
+    private finish;
+    private face;
+}