lecodes-sdk 0.19.0

package/dist/types/gl/animation/core.d.ts

@@ -0,0 +1,367 @@
+import { AnimationClip } from "./AnimationClip";
+import { Loop } from "./Loop";
+import { Layer } from "./Layer";
+import { Playback } from "./Playback";
+import { Vec3 } from "../../math/vec";
+import type { Node } from "../Node";
+/** A position on a blend axis (1D) or plane (2D). */
+export type BlendPosition = number | readonly [number, number];
+/** The transition time (seconds) a play / playLoop without `fade` uses. */
+export declare const DEFAULT_FADE = 0.2;
+export type PlayOptions = {
+    /** Transition seconds — how long the difference to the pose the layer SHOWED takes to decay
+     *  (default 0.2; `0` = cut). Also the transition back at the end unless `fadeOut` overrides it. */
+    fade?: number;
+    /** Transition seconds for the way in only (overrides `fade`). */
+    fadeIn?: number;
+    /** One-shots: the transition BACK at the end (overrides `fade`). It starts this long before the
+     *  clip ends — while it still plays — so the hand-over lands on the last pose, not after it. On a
+     *  layer with no loop to return to, giving `fadeOut` releases the layer at the end instead of
+     *  holding the last frame. */
+    fadeOut?: number;
+    /** Playback rate for this clip (default 1). */
+    speed?: number;
+    /** Rewind even if the clip is already playing (default: rewind only if it isn't). */
+    restart?: boolean;
+    /** Enter the clip at a point in the GAIT CYCLE instead of at its start: `'match'` = the phase the
+     *  layer shows right now (the walk's left foot is down → the turn clip starts where its left foot
+     *  is down too, so nothing slides), or a number 0–1. Clips without a gait cycle ignore it. */
+    phase?: number | "match";
+    /** TURN WARP (degrees, + = left): the node turns this much in total over the clip instead of what the
+     *  clip's baked heading says — its turn curve scaled, so the difference grows where the clip turns and
+     *  pivots about the planted foot. A 45° start played with `turn: 60` turns 60; played with `turn: 45`
+     *  it lands on 45 exactly whatever the clip's own run-off. Needs `rootMotion` + `rootRotation` and a
+     *  clip with a baked heading (`lecodes assets marks` / `retarget`); a clip that turns under 10° is
+     *  left alone. Ignored by hosts without it. */
+    turn?: number;
+};
+export type StopOptions = {
+    fade?: number;
+};
+export type LoopOptions = {
+    /** Transition seconds from whatever the layer shows — its previous loop, or a one-shot still
+     *  playing (default 0.2; `0` = cut). */
+    fade?: number;
+    /** Playback rate of the loop's clips (default 1). */
+    speed?: number;
+    /** Where in the CYCLE to start, 0–1, or `'match'` = where the layer is now (what a gait loop taking
+     *  over from a start / turn clip wants). The members share one clock, so this is every member's phase. */
+    phase?: number | "match";
+};
+/** What a layer loops: one clip (name / index), or a blend space `{ name: position }`. */
+export type LoopDef = string | number | Record<string, BlendPosition>;
+/** One clip the layer shows this frame — `layer.active` / `anim.active` (a debug overlay's list). */
+export type ActiveClip = {
+    name: string;
+    clip: AnimationClip;
+    /** contribution to the pose, 0–1: the shown one-shot 1, a loop member its blend share */
+    weight: number;
+    /** clock (s) */
+    time: number;
+    /** a member of the layer's loop (else the layer's one-shot) */
+    loop: boolean;
+};
+export type LayerOptions = {
+    /** Bone name(s): the layer drives only these subtrees (`'Spine1'` = upper body). Default: the whole rig. */
+    mask?: string | string[];
+    /** Blend each clip's DELTA from its own first frame on top of the layers below (lean, breathe, recoil)
+     *  instead of overriding them. */
+    additive?: boolean;
+    /** Layer contribution 0–1 (default 1). */
+    weight?: number;
+};
+export type ClipEventHandler = (clip: string, layer: Layer) => void;
+/** A foot planted: which one, and where in the world it landed. */
+export type StepHandler = (side: "left" | "right", position: Vec3) => void;
+/** What the engine measured on a clip once it was bound to this skeleton (`anim.curves('Walk')`).
+ *  The root curves are of the clip's ROOT bone — its travel is what root motion would move. */
+export type ClipCurves = {
+    /** total horizontal root travel, metres */
+    travel: number;
+    /** mean root speed over the clip, m/s */
+    speed: number;
+    /** total root yaw, radians (+ = left) */
+    turn: number;
+    /** the root barely moves — an in-place clip */
+    inPlace: boolean;
+    /** the clip has a gait cycle (feet planting in turn) — `phaseAt` is meaningful */
+    hasPhase: boolean;
+    /** When each foot TOUCHES the ground, seconds — the phase anchor. `still` is the window inside it
+     *  where the foot is genuinely STATIONARY (a touching foot still rolls for its first beats, and a
+     *  stop take's final plant touches long before the body has braked); absent = never still.
+     *  `at` = where the foot is at the touch's start ([x, y, z], model space). */
+    contacts: {
+        side: "left" | "right";
+        from: number;
+        to: number;
+        at: [number, number, number];
+        still?: {
+            from: number;
+            to: number;
+        };
+    }[];
+    /** the HANDS on the ground (a cartwheel, a roll, a vault) — from the clip's marks in the GLB; empty when none */
+    hands: {
+        side: "left" | "right";
+        from: number;
+        to: number;
+        at: [number, number, number];
+        still?: {
+            from: number;
+            to: number;
+        };
+    }[];
+    /** A CLIMBING clip's tread levels (a stair or slope take): the model-space heights its feet plant
+     *  at, sorted ascending, with the riser (median level spacing — the step height the clip was
+     *  authored for). Absent on a flat clip. */
+    treads?: {
+        riser: number;
+        levels: number[];
+    };
+    /** the gait phase at `time`: 0 at a left-foot-down, 0.5 at a right-foot-down; -1 without a cycle */
+    phaseAt(time: number): number;
+    /** cumulative root travel (m) at `time` */
+    travelAt(time: number): number;
+    /** cumulative root yaw (rad, + = left) at `time` */
+    turnAt(time: number): number;
+    /** the root's own speed at `time`, m/s — how fast the clip is moving the body right there */
+    speedAt(time: number): number;
+    /** the unit travel direction at `time` ([x, z], model space, held through stills) — integrate
+     *  direction × d(travel) to reconstruct the root's 2D path (a treadmill display, a turn's arc) */
+    directionAt(time: number): [number, number];
+    /** the first time the clip has turned `yaw` radians (+ = left): where to enter a turn a body has
+     *  already begun, so the clip continues the move instead of restarting it */
+    timeAtTurn(yaw: number): number;
+    /** How far this clip's pose is from `target`'s, in metres — the joint distance plus the velocity
+     *  difference over a tenth of a second, the planted foot weighted most. That difference is exactly
+     *  what a hand-over hands the transition to decay away, so it says what switching to `target` would
+     *  cost at `time`. The two are lined up by cycle PHASE (a clip that continues the walk) or by TIME
+     *  (`align: 'time'` — two clips that both begin from standing share no cycle). */
+    fitTo(target: string | number, time: number, options?: {
+        align?: "phase" | "time";
+    }): number | undefined;
+    /** The earliest moment (seconds) at which handing over to `target` costs no more than `within`
+     *  metres — a start's last steps ARE the walk, so this is where it stops being worth playing.
+     *  `atContact` (default true) snaps to the next foot-down: a switch under a planted foot is the one
+     *  the eye forgives. -1 = the clip never gets that close. */
+    exitTo(target: string | number, options?: {
+        within?: number;
+        atContact?: boolean;
+        align?: "phase" | "time";
+    }): number;
+    /** The knee's bend plane at `time`, predicted from the skeleton's calibrated hinge axis carried by
+     *  this clip's own thigh rotation — continuous even where the leg is straight (where a plane
+     *  derived from positions is pure noise). `pole` = unit direction from the hip→ankle line toward
+     *  the knee (a two-bone solver's bend direction), `normal` = the plane's normal; both in the model
+     *  pose's frame. Undefined = no leg chain, or no knee motion bound to calibrate from. */
+    kneePoleAt(side: "left" | "right", time: number): {
+        pole: [number, number, number];
+        normal: [number, number, number];
+    } | undefined;
+    /** The clip's baked physics at `time` (unit body mass, model space): `com` = the body's center of
+     *  mass (biomechanical segment fractions on the classified bones), `velocity` = its velocity
+     *  (= linear momentum per kg), `angular` = the angular momentum about the COM (m²/s per kg,
+     *  low-passed ~0.5 s — the REGULATED component, e.g. a turn's sustained yaw; the per-stride
+     *  pitch/roll exchange between the limbs and the trunk is filtered out),
+     *  `support` = per-foot load [left, right] — contact-gated, split by where the COM stands between
+     *  the feet, scaled by the vertical force proxy (above 1 on a landing impact, 0 in flight).
+     *  A model, not a measurement — meant for ranking transitions and display, both sides of any
+     *  comparison sharing the same model. Undefined = nothing classified on this skeleton. */
+    physicsAt(time: number): {
+        com: [number, number, number];
+        velocity: [number, number, number];
+        angular: [number, number, number];
+        support: [number, number];
+    } | undefined;
+    /** The clip's MATCHING FEATURE ROW at `time` — a fresh Float32Array(37) in the clip's heading
+     *  frame at that time (x lateral, + left; y up; z forward): 0–5 feet positions relative to the
+     *  pelvis' ground point, 6–11 feet velocities, 12–14 pelvis velocity, 15 pelvis height, 16–18
+     *  COM velocity, 19–20 support L/R, 21–22 contact phase L/R, 23 yaw angular momentum, 24–31 the
+     *  clip's own path 0.3/0.6/1.0/1.5 s ahead as (lateral, forward) pairs, 32–35 facing change at
+     *  those horizons (rad, + = left), 36 cyclic flag. What a trajectory-and-state matcher compares.
+     *  Undefined = no leg chain. */
+    featuresAt(time: number): Float32Array | undefined;
+    /** The take is a LOOP by measurement: its seam is continuous (feet back where they started
+     *  relative to the root, no turn). Starts, stops and turns are not. */
+    cyclic: boolean;
+};
+/** The calibrated knee hinge-axis report (`anim.kneeAxis('left')`): the axis in the thigh's local
+ *  frame, and the calibration's own confidence — the angular spread of its measurements (radians;
+ *  a real knee comes in at a few degrees) over `samples` consecutive-frame deltas of the pack.
+ *  `plant` = the calibrated PLANT HEIGHTS (model space): where the ankle / toe actually sit under
+ *  full weight, the median of the pack's still-window lows — absent when nothing plants. */
+export type KneeAxisReport = {
+    axis: [number, number, number];
+    spreadMean: number;
+    spreadMax: number;
+    samples: number;
+    plant?: {
+        ankleY: number;
+        toeY: number;
+    };
+};
+/** A clip bound to a layer — one per (clip, layer), reused by every play. `playback` = the most recent
+ *  one-shot on it (`playing` while it still owns the layer; kept after that so its handle can still be
+ *  read — a restart re-enters the same slot with a new record). */
+export type SlotRec = {
+    name: string;
+    clip: AnimationClip;
+    slot: number;
+    layer: LayerRec;
+    inBlend: boolean;
+    playback?: PlaybackRec;
+};
+export type PlaybackRec = {
+    slot: SlotRec;
+    playing: boolean;
+    done: Promise<boolean>;
+    resolve: (natural: boolean) => void;
+};
+export type LayerRec = {
+    index: number;
+    view: Layer;
+    slots: SlotRec[];
+    loop?: LoopRec;
+    weight: number;
+    mask: string;
+    additive: boolean;
+};
+export type LoopRec = {
+    layer: LayerRec;
+    members: {
+        name: string;
+        slot: SlotRec;
+    }[];
+    value: BlendPosition;
+    view: Loop;
+    dead: boolean;
+};
+export declare class Core {
+    id: number;
+    /** Added clips by name (`addClip`) — the lookup index; an added name overrides an embedded one. */
+    readonly table: Map<string, AnimationClip>;
+    readonly layers: LayerRec[];
+    speed: number;
+    private _embedded?;
+    private readonly _added;
+    private _list?;
+    private readonly _listeners;
+    readonly node: Node;
+    constructor(node: Node);
+    embedded(): AnimationClip[];
+    /** The ordered clip list: the GLB's clips in file order (an added clip of the same name takes the
+     *  embedded one's place), then the remaining added clips in insertion order. Cached until addClip. */
+    clips(): AnimationClip[];
+    addClip(name: string, clip: AnimationClip): void;
+    /** A clip by name (added first, then embedded), or by index into `clips()` (none = the first). */
+    resolveClip(ref: string | number | undefined): [string, AnimationClip] | undefined;
+    private clipNames;
+    /** Create the native animator on demand. False = nothing to animate (warned). */
+    ensure(): boolean;
+    destroy(): void;
+    newLayer(options?: LayerOptions): LayerRec;
+    addLayer(options: LayerOptions): Layer;
+    /** Arm the layer's next transition with a wind-up: see `Layer.anticipate`. */
+    anticipate(L: LayerRec, amount: number): void;
+    pushLayer(L: LayerRec): void;
+    /** The layer's slot for the clip — bound on first use, reused after that. */
+    slotFor(L: LayerRec, name: string, clip: AnimationClip): SlotRec | undefined;
+    /** The base layer's native slot for a clip, bound on first ask (-1 = no such clip / no animator). */
+    slotIndex(ref: string | number): number;
+    play(L: LayerRec, ref: string | number | undefined, o: PlayOptions): Playback;
+    /** A one-shot on the layer hasn't handed over yet. */
+    busy(L: LayerRec): boolean;
+    settle(p: PlaybackRec, natural: boolean): void;
+    /** Resolve every pending playback on the layer as cut short. */
+    private settleLayer;
+    stopSlot(s: SlotRec, fade: number): void;
+    stopLayer(L: LayerRec, fade: number): void;
+    stopAll(fade: number): void;
+    loop(L: LayerRec, def: LoopDef, o: LoopOptions): Loop | undefined;
+    /** The phase the layer shows, 0–1 through the gait cycle (-1 = nothing / no cycle). */
+    layerPhase(L: LayerRec): number;
+    /** The entry phase of a play / playLoop: a number as given, `'match'` = what the layer shows now
+     *  (undefined when it shows no cycle — then the clip starts at its own beginning). */
+    private entryPhase;
+    /** The loop's phase through its cycle, 0–1 (the members share one clock). */
+    loopPhase(b: LoopRec): number;
+    setLoopPhase(b: LoopRec, phase: number): void;
+    setLoopValue(b: LoopRec, v: BlendPosition): void;
+    /** What the layer shows this frame: its source — the one-shot, or the loop's members with their
+     *  blend shares — in binding order (stable rows). */
+    active(L: LayerRec): ActiveClip[];
+    slotWeight(s: SlotRec): number;
+    /** The slot's gait phase now, wrapped into 0–1 (-1 without a cycle). */
+    slotPhase(s: SlotRec): number;
+    /** A baked curve of the slot at its current time: 1 travel (m) / 2 yaw (rad) / 3 speed (m/s). */
+    slotCurveAt(s: SlotRec, which: 1 | 2 | 3): number;
+    /** The clip's total root yaw, radians (+ = left). */
+    slotTurn(s: SlotRec): number;
+    slotTime(s: SlotRec): number;
+    seek(s: SlotRec, time: number): void;
+    /** Scrub: set a bound clip's playhead directly, seconds — an inspector's tool. */
+    seekTime(ref: string | number, time: number): void;
+    /** Re-aim a playing clip's TURN WARP (see `PlayOptions.turn`): the clip's baked heading is scaled so that the
+     *  whole clip turns `deg` — set mid-play, the scale applies to what is still to come, so a controller that
+     *  wants a different heading while a turn plays asks for (the clip's total × what it still needs / what
+     *  the clip still turns). Undefined `deg` switches the warp off. */
+    setTurnOf(ref: string | number, deg: number | undefined): void;
+    /** A bound clip's current playhead, seconds (-1 = not bound). */
+    timeOf(ref: string | number): number;
+    /** What the engine measured on the clip once it was bound to this skeleton — binds it if needed. */
+    curves(ref: string | number): ClipCurves | undefined;
+    /** The skeleton's calibrated knee hinge axis for a side, with its confidence report — measured once
+     *  over every bound clip's knee rotation track. Undefined = no leg chain / no knee motion bound. */
+    kneeAxis(side: "left" | "right"): KneeAxisReport | undefined;
+    /** STEP WARP v2 (the warp rewrite's knobs): `stride` scales each foot's travel-direction offset
+     *  from its hip — the step shortens or lengthens, uniformly through stance and swing; `lift` is
+     *  METRES added to each foot's height, gated to the swing by the contact marks (0 = neutral,
+     *  negative = a shuffle — no probing), and half of what it adds raises the pelvis so the body
+     *  steps higher with the foot; `pitch` (degrees, + = toes up) rotates each foot about its
+     *  own lateral axis — a slope's foot rotation; `slope` (degrees, + = ascending) is the INVISIBLE
+     *  STAIRCASE: foot heights follow the incline (leading foot higher) and the feet auto-pitch by
+     *  the same angle — pair it with raising the character by tan(slope) × the stride-scaled clip
+     *  travel (`curves(clip).travelAt`), which holds every planted foot's world height constant on
+     *  its own tread. Solved in the calibrated knee hinge plane with a SOFT reach (a leg at its limit
+     *  keeps a residual knee bend instead of popping against the clamp), and whenever a leg would
+     *  overreach — a descent, a long stride — the pelvis lowers by exactly the excess (weighted by
+     *  the contact marks, spring-followed; zero when nothing overreaches, so an ascent or a shorter
+     *  stride is untouched). Omit / null = stage off. */
+    setStepWarp(options?: {
+        stride?: number;
+        lift?: number;
+        pitch?: number;
+        slope?: number;
+    } | null): void;
+    /** A slot for a clip on the base layer, bound on demand — what the pair-wise measures address. */
+    private slotOf;
+    /** The baked distance curve between two clips, cached per pair (the engine caches the bake itself;
+     *  this keeps the samples on the JS side so a controller can read them per frame without copying). */
+    private readonly _fit;
+    private fitCurve;
+    /** The earliest moment handing `src` over to `target` costs no more than `within` metres. */
+    private fitExit;
+    /** The contact bones, '
+  '-joined per side ("" = classify by name). */
+    private _feet?;
+    setFeet(left: string, right: string): void;
+    /** Stride / orientation warping, as the engine's fixed-order parameter array. */
+    private _warp?;
+    setWarp(params: Float32Array): void;
+    /** The feet stage (lock / ground IK), as the engine's fixed-order parameter array. */
+    private _feetParams?;
+    setFeetParams(params: Float32Array): void;
+    /** One foot's lock state after this frame's evaluation into `out` (8 floats); false = no such foot
+     *  or no feet stage on this host. */
+    footState(side: 0 | 1, out: Float32Array): boolean;
+    private readonly _steps;
+    onStepHandler(cb: StepHandler): void;
+    offStepHandler(cb: StepHandler): void;
+    private onStep;
+    setSpeed(v: number): void;
+    setRootMotion(on: boolean, rotation?: boolean): void;
+    on(event: string, cb: ClipEventHandler): void;
+    off(event: string, cb: ClipEventHandler): void;
+    /** Native slot event: 0 completed / 1 loop / 2 settled (no longer a source) / 3 hand-over / 4+i clip event i. */
+    private onEvent;
+}

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

@@ -0,0 +1,19 @@
+import type { Node } from "./Node";
+import type { Scene } from "./Scene";
+export type ControlsOptions = {
+    /** Smallest uniform scale the pinch gesture allows (default 0.08). */
+    minScale?: number;
+    /** Largest uniform scale the pinch gesture allows (default 2). */
+    maxScale?: number;
+    /** One-finger drag moves the target across the ground plane (default true). */
+    pan?: boolean;
+    /** Two-finger pinch scales the target (default true). */
+    pinch?: boolean;
+    /** Two-finger twist rotates the target around its Y axis (default true). */
+    twist?: boolean;
+};
+/** Returned by `addControls` — call `remove()` to detach the gesture listeners. */
+export type ControlsHandle = {
+    remove(): void;
+};
+export declare const attachControls: (scene: Scene, target: Node, options?: ControlsOptions) => ControlsHandle;

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

@@ -0,0 +1 @@
+export declare const ensurePhysicsEvents: () => void;

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

@@ -0,0 +1,98 @@
+import { Aspect } from "../core/Aspect";
+import type { FieldMeta } from "../core/fields";
+import type { InspectorUI } from "../core/InspectorUI";
+import { Node } from "./Node";
+import { Model } from "./Model";
+type LoopMode = "once" | "loop" | "pingpong";
+/** Travel from the node's starting position to a target node in `duration` seconds. */
+export declare class MoveTo extends Aspect<"moveTo"> {
+    /** Where to travel — place an Empty node and pick it. */
+    target: Node | null;
+    /** Seconds for the full trip. */
+    duration: number;
+    /** Seconds to wait before starting. */
+    delay: number;
+    /** once = stop at the target · loop = restart from the start point · pingpong = back and forth. */
+    mode: LoopMode;
+    /** Motion curve. */
+    easing: "smooth" | "linear";
+    static readonly aspect = "moveTo";
+    static editor: {
+        rebuild: boolean;
+    };
+    static fields: FieldMeta<MoveTo>;
+    private _t;
+    private _start;
+    update(dt: number): void;
+    /** Editor-only path line (edit mode; play mode never calls this). */
+    rebuild(): void;
+}
+/** Travel through the children of a path node (add an Empty per waypoint) in `duration` seconds.
+ *  `loop` runs the circuit closed (last → first); `pingpong` goes back and forth along the open
+ *  path; `once` stops at the last waypoint. */
+export declare class FollowPath extends Aspect<"followPath"> {
+    /** A node whose CHILDREN are the waypoints, in file order. */
+    path: Node | null;
+    /** Seconds for one full pass of the path. */
+    duration: number;
+    /** Seconds to wait before starting. */
+    delay: number;
+    mode: LoopMode;
+    /** Turn to face the direction of travel. */
+    orient: boolean;
+    /** Which local axis leads when orienting. */
+    forward: "-z" | "z" | "x" | "-x";
+    static readonly aspect = "followPath";
+    static editor: {
+        rebuild: boolean;
+    };
+    static fields: FieldMeta<FollowPath>;
+    private _t;
+    private _points;
+    update(dt: number): void;
+    /** Editor-only waypoint polyline (edit mode; play mode never calls this). */
+    rebuild(): void;
+}
+/** Continuous rotation about one of the node's local axes, degrees per second. */
+export declare class Spin extends Aspect<"spin"> {
+    /** Degrees per second. */
+    speed: number;
+    /** Local axis to spin around. */
+    axis: "x" | "y" | "z";
+    static readonly aspect = "spin";
+    static fields: FieldMeta<Spin>;
+    update(dt: number): void;
+}
+/** Keep the node facing a target node (a turret tracking, a signpost, a camera aimed at a hero).
+ *  Accessor `node.facing` — NOT `lookAt`, which would shadow the `Node.lookAt()` method. */
+export declare class LookAt extends Aspect<"facing"> {
+    /** The node to face. */
+    target: Node | null;
+    /** Which local axis points at the target. */
+    forward: "-z" | "z" | "x" | "-x";
+    /** 0 = snap instantly; otherwise seconds of turn lag (bigger = slower, smoother). */
+    smoothing: number;
+    static readonly aspect = "facing";
+    static editor: {
+        rebuild: boolean;
+    };
+    static fields: FieldMeta<LookAt>;
+    update(dt: number): void;
+    /** Editor-only sight line (edit mode; play mode never calls this). */
+    rebuild(): void;
+}
+/** Start a GLB animation clip when the scene runs. Attach to a `model:` node; the inspector card
+ *  lists the model's clips live and can preview them while editing. */
+export declare class PlayAnimation extends Aspect<"playAnimation", Model> {
+    /** Clip name; empty = the model's first clip. */
+    clip: string;
+    loop: boolean;
+    /** Playback rate (1 = authored speed). */
+    speed: number;
+    static readonly aspect = "playAnimation";
+    static fields: FieldMeta<PlayAnimation>;
+    private _preview?;
+    onAttach(): void;
+    static inspector(ui: InspectorUI, a: PlayAnimation): void;
+}
+export {};

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

@@ -0,0 +1,5 @@
+import type { Scene } from "./Scene";
+export declare const glState: {
+    activeScene: Scene | null;
+    frame: number;
+};

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

@@ -0,0 +1,46 @@
+import { Geometry } from "./Geometry";
+export type TerrainGrid = {
+    sizeX: number;
+    sizeZ: number;
+    cellSize: number;
+    /** sizeX × sizeZ heights, row-major (z rows). */
+    heights: Float32Array;
+    /** One byte per sample, 1 = hole; null = no holes. */
+    holes: Uint8Array | null;
+};
+/** The sample at integer (x, z), clamped to the grid. */
+export declare const sampleAt: (g: TerrainGrid, x: number, z: number) => number;
+export declare const isHole: (g: TerrainGrid, x: number, z: number) => boolean;
+/** Surface normal at a sample from central differences (one-sided at the borders). Writes `out` (xyz). */
+export declare const normalAt: (g: TerrainGrid, x: number, z: number, out?: Float32Array | number[]) => typeof out;
+/**
+ * Height at a LOCAL (x, z) in metres, interpolated on the drawn triangles (the i00–i11 diagonal), so a
+ * character's feet and a raycast agree with what is rendered to the millimetre. NaN inside a hole
+ * triangle or outside the grid.
+ */
+export declare const heightAt: (g: TerrainGrid, x: number, z: number) => number;
+/** The geometric normal at a LOCAL (x, z): the drawn triangle's normal (not the smoothed vertex one). */
+export declare const faceNormalAt: (g: TerrainGrid, x: number, z: number, out?: Float32Array | number[]) => typeof out;
+/** Chunks along X and Z for a grid: a chunk covers `chunk` cells (chunk + 1 samples). */
+export declare const chunkCounts: (g: TerrainGrid, chunk: number) => [number, number];
+/**
+ * One chunk as a Geometry (positions, smooth normals, UV0 = local XZ metres, UV1 = the terrain's unit
+ * square, u16 indices), or null when every cell of it is a hole.
+ */
+export declare const buildTerrainChunk: (g: TerrainGrid, cx: number, cz: number, chunk: number) => Geometry | null;
+export type GridHit = {
+    x: number;
+    y: number;
+    z: number;
+    distance: number;
+    nx: number;
+    ny: number;
+    nz: number;
+};
+/**
+ * Nearest hit of a LOCAL ray (origin + direction, metres) on the drawn triangles — the same
+ * i00–i11 split and hole rule as `heightAt`, so a pick lands on what is rendered. Walks the cells
+ * the ray crosses (2D DDA on XZ), testing each cell's two triangles; holes let the ray through.
+ * Null when it misses (or never enters the grid within `maxDistance`).
+ */
+export declare const gridRaycast: (g: TerrainGrid, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDistance?: number) => GridHit | null;

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

@@ -0,0 +1,2 @@
+export declare const registerTouchStartEvent: () => void;
+export declare const registerTouchEndEvent: () => void;