lecodes-sdk 0.19.0

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

@@ -0,0 +1,86 @@
+import { Aspect } from "../core/Aspect";
+import type { FieldMeta } from "../core/fields";
+import { type Vec3Like } from "../math/vec";
+import { Node } from "./Node";
+export interface RagdollHinge {
+    /** The hinge axis in the MODEL's space (its rest pose: +Z forward, +Y up, +X the model's left in
+     *  glTF). Perpendicular to the bone; the engine drops any component along it. */
+    axis: Vec3Like;
+    /** The bend range about `axis` in degrees, relative to the pose the ragdoll was built in — a knee
+     *  is `{ axis: [1, 0, 0], min: 0, max: 140 }`: it folds one way only. */
+    min: number;
+    max: number;
+}
+export interface RagdollPart {
+    /** The bone the body sits on — its origin is the joint. */
+    bone: string;
+    /** The bone the capsule points at (the next joint down). Omitted = a leaf: `length` along the line
+     *  from the parent part's origin (a head, a hand, a foot without toes). */
+    to?: string;
+    /** The bone of the part this one hangs from (default: the previous part in the list). The root
+     *  has none. */
+    parent?: string;
+    /** Capsule radius in metres (default 0.05). */
+    radius?: number;
+    /** Length in metres: a leaf's, or an override of the distance to `to`. */
+    length?: number;
+    /** This part's share of the ragdoll's `mass` (relative weight, default 1). */
+    mass?: number;
+    /** Cone half-angle in degrees the part may swing off its parent (default 30). Ignored with `hinge`. */
+    swing?: number;
+    /** Twist half-angle in degrees about its own axis (default 20). */
+    twist?: number;
+    /** A one-way joint instead of the cone. */
+    hinge?: RagdollHinge;
+}
+export declare class Ragdoll extends Aspect<"ragdoll", Node> {
+    static readonly aspect = "ragdoll";
+    /** The parts: `'humanoid'` (default) finds the standard bones by name; a list places bodies on any
+     *  bones — parents before children. */
+    parts: RagdollPart[] | "humanoid";
+    /** Total mass in kg (default 70), split between the parts by their `mass` shares. */
+    mass: number;
+    /** Friction of every part (default 0.6 — the physics default). */
+    friction: number;
+    /** Linear / angular damping of every part; 0 = Jolt's own 0.05. More angular damping settles a
+     *  flailing body sooner. */
+    linearDamping: number;
+    angularDamping: number;
+    /** What the parts collide with. `'static'` (default): the static geometry and other such ragdolls
+     *  only — dynamic bodies, character controllers and vehicles pass through a fallen body, which then
+     *  never shoves or blocks anything and costs nothing when they meet. `'all'`: a regular dynamic
+     *  body that bumps into everything (and gets kicked awake by everything). */
+    collide: "static" | "all";
+    /** Once every part has come to rest the parts turn static where they lie (default true): the pose
+     *  holds, nothing can wake a settled body and it costs the solver nothing — `deactivate()` /
+     *  `activate()` still work (activate makes it dynamic again). */
+    freeze: boolean;
+    /** Seconds after `activate()` at which the body freezes whatever it is doing — a twitch on a slope
+     *  or a pile never sleeps on its own. 0 (default) = no cap. */
+    freezeAfter: number;
+    static fields: FieldMeta<Ragdoll>;
+    private _id;
+    private _active;
+    private _bones;
+    onAttach(): void;
+    onDetach(): void;
+    /** Hand the bones to physics from the pose they are in right now. `velocity` (world m/s) is given
+     *  to every part — pass the character's, so a running body keeps travelling. */
+    activate(opts?: {
+        velocity?: Vec3Like;
+    }): boolean;
+    /** Take the bones back: the animator's pose shows again from the next frame. */
+    deactivate(): void;
+    /** Physics owns the bones right now. */
+    get active(): boolean;
+    /** Active and every part asleep (or frozen) — the body has come to rest. */
+    get settled(): boolean;
+    /** The root part's bone (the hips): where the body is. */
+    get root(): Node | null;
+    /** The bones that carry a part, in order. */
+    get bones(): string[];
+    /** The rigid-body id of a part (0 if none) — for the plain body calls. */
+    bodyOf(bone: string): number;
+    /** Push one part: an impulse in N·s, at a world point (a hit) or through its centre. Wakes the body. */
+    impulse(bone: string, v: Vec3Like, at?: Vec3Like): boolean;
+}

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

@@ -0,0 +1,8 @@
+import { Vec3, type Vec3Like } from "../math/vec";
+export declare class Ray {
+    readonly origin: Vec3;
+    readonly dir: Vec3;
+    constructor(origin: Vec3Like, dir: Vec3Like);
+    /** The world-space point origin + t·dir. */
+    getPoint(t: number): Vec3;
+}

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

@@ -0,0 +1,221 @@
+import { type ColorInput } from "../core/color";
+import { type Aspect, type AspectCtor, type FieldOf, type TargetOf } from "../core/Aspect";
+import { Presentable, type PresentOptions } from "../ui/presentable";
+import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
+import type { FetchResponse } from "../runtime/fetch";
+import { Camera } from "./Camera";
+import { type ControlsHandle, type ControlsOptions } from "./controls";
+import { Material } from "./Material";
+import { Node } from "./Node";
+export type AmbientOcclusionOptions = {
+    /** Strength of the darkening (default 1). */
+    intensity?: number;
+    /** How far the occlusion reaches, in metres (default 0.3). */
+    radius?: number;
+    /** Falloff contrast; >1 tightens it into the crease (default 1). */
+    power?: number;
+    /** Sample count + filtering (default 'medium'). Not the buffer resolution — that stays half. */
+    quality?: "low" | "medium" | "high" | "ultra";
+};
+export type FogOptions = {
+    /** A TINT on the in-scattered ambient, not an absolute colour: the engine multiplies it by the
+     *  environment luminance, so white (the default) means "fog as bright as the ambient" and the fog
+     *  brightens with `environmentIntensity`. Do NOT expect the same hex to look like it does in
+     *  `skybox` — that one IS an absolute radiance and reads roughly an order of magnitude brighter.
+     *  Tint towards the sky's hue; leave it white to sit at the ambient level. */
+    color?: ColorInput;
+    /** Metres from the camera before the fog starts (default 0). */
+    start?: number;
+    /** Extinction per metre at `height`; 0.01 ≈ clearly visible over ~100 m (default 0.01). */
+    density?: number;
+    /** The fog's "sea level" in world Y (default 0). */
+    height?: number;
+    /** How fast it thins with altitude, 1/m. 0 = uniform everywhere; higher = a ground-hugging layer
+     *  you can see over (default 0). */
+    heightFalloff?: number;
+    /** Cap on how opaque it can get, 0–1 — keeps far shapes readable (default 1). */
+    maxOpacity?: number;
+    /** Metres after which fog stops applying; 0 = everywhere (default 0). */
+    cutoff?: number;
+    /** Take the colour from the environment in the view direction, tinted by `color`, instead of a
+     *  flat `color`. Convincing when the IBL is a real sky (default false). */
+    fromEnvironment?: boolean;
+};
+export type SceneOptions = {
+    /** Image-based ambient lighting (default on). `false` turns it off; a STRING is the scene's own
+     *  probe - `ibl: asset('../assets/ibl-interior.ktx')` - and is how two levels in one project get
+     *  different environments. Without it the host looks for a project-wide `ibl.ktx`, which is one
+     *  probe for every scene: swapping that file to suit an interior level silently relights the
+     *  outdoor one. A named probe also travels through `asset()`, so a build only carries the
+     *  environments its own entry point reaches. */
+    ibl?: boolean | string;
+    /** IBL intensity (default 20000). */
+    environmentIntensity?: number;
+    /** Camera exposure compensation in stops (default 0) - the same knob as
+     *  `scene.camera.exposureCompensation`, next to the rest of the scene's lighting so a LEVEL can
+     *  carry its own. The camera is a physical one at EV100 15 (f/16 - 1/125 - ISO 100), i.e. metered
+     *  for bright sun; an interior lit at real levels needs +7..+9 to read at all. Expose the camera
+     *  rather than inflating the lights: scaling lamps past what they physically emit gives bright
+     *  fixtures in a black room, because it changes the RATIO, not the level. */
+    exposureCompensation?: number;
+    /** Bloom post-processing. */
+    bloom?: boolean;
+    bloomIntensity?: number;
+    /** Tone mapping operator. `'aces'` (default, filament's ACES legacy) desaturates bright colours
+     *  towards white — HDR fire reads pale; `'neutral'` (Khronos PBR Neutral) keeps hue and
+     *  saturation until very bright; `'linear'` clips each channel (what an engine without a
+     *  tonemapper shows — saturated, Unity-without-post-processing look); `'filmic'` (Uncharted). */
+    toneMapping?: "aces" | "neutral" | "linear" | "filmic";
+    /** The sky. Three forms:
+     *  - a colour — a flat clear colour;
+     *  - `{ texture }` — a KTX1 **cubemap**, the sharp `<name>_skybox.ktx` that filament's `cmgen`
+     *    produces from an equirectangular .hdr/.exr. This is the one to use for a real sky. Pass an
+     *    `asset('../assets/sky.ktx')` handle or a bare staged filename;
+     *  - `'environment'` — reuse the scene's IBL cubemap. Cheapest (no second texture) but that file
+     *    is prefiltered for roughness, so the sky comes out soft; fine as a fallback, not as the goal.
+     *
+     *  Either texture form draws through filament's own skybox pass: a full-screen pass in device
+     *  space after the opaque queue. No geometry, no meridian seam, no pole distortion — do NOT build
+     *  a sky dome or a fullscreen equirect material by hand, both are strictly worse. */
+    skybox?: ColorInput | "environment" | {
+        texture: string;
+    };
+    /** Screen-space ambient occlusion — the contact darkening in creases and where props meet the
+     *  ground. Without it an IBL lights a crease exactly as brightly as an open face, so everything
+     *  reads as pasted onto the floor rather than standing on it. `true` takes defaults tuned for
+     *  human-scale props; `radius` is world-space metres and is the one knob that must follow the
+     *  scene's scale (~0.3 for objects on a table, ~0.6-1 for a yard of crates and containers). */
+    ambientOcclusion?: boolean | AmbientOcclusionOptions;
+    /** Distance fog / aerial perspective: distant geometry loses contrast so the eye reads depth, and
+     *  the hard edge where a finite level ends against the skybox goes away. By default the fog applies
+     *  at every distance — the skybox included — so the sky itself takes the fog colour and the horizon
+     *  blends on its own; `cutoff` opts geometry beyond a distance back out. */
+    fog?: FogOptions;
+    /** Multisample anti-aliasing: `true` = 4×, `2`/`4` = that many samples, `false` = off (FXAA
+     *  takes over). Unset keeps the host default (desktop 4×, mobile/web off). The biggest single
+     *  fill-rate cost after resolution — turn it down on big screens before anything else. */
+    antialias?: boolean | 2 | 4;
+    /** Render the 3D at this fraction of the viewport (0.25–1) and upscale; the UI stays at native
+     *  resolution. A fixed, predictable cut of per-pixel GPU work — `0.75` is ~45 % cheaper and
+     *  barely visible in motion, `0.5` quarters it. Headless renders ignore it. */
+    renderScale?: number;
+    /** Let the engine shrink the 3D buffers under `renderScale` only when frames run over budget
+     *  (Filament dynamic resolution, sharpened upscale) down to `min` (default 0.5). Off by default:
+     *  it makes the output frame-time dependent, so flow tests / headless renders never enable it. */
+    dynamicResolution?: boolean | {
+        min?: number;
+    };
+    /** Anisotropic filtering, 1 (off) … 16. Default 2. What it buys is detail on surfaces seen at a
+     *  GRAZING angle — a first-person weapon, a floor, a wall — where the sample footprint is far
+     *  longer in one axis than the other and isotropic filtering has to pick a mip for the long one,
+     *  several levels coarser than the short axis deserves. Measured on a weapon seen from the side
+     *  (local contrast): 8.18 at 1× → 10.02 at 2× → 10.84 at 4× → 11.29 at 8×. The default is 2
+     *  because it is where the curve is steepest per unit of memory bandwidth; raise it if you have
+     *  the headroom.
+     *
+     *  It is an ENGINE-WIDE default, not a property of this scene: a sampler is baked when its
+     *  texture is bound, so this reaches the models a scene loads AFTER it (which is every model in a
+     *  scene file — `env` is applied before the nodes build) and leaves already-loaded ones alone.
+     *  On the desktop host `CREATOR_TEXTURE_ANISOTROPY` overrides it, for tuning without a rebuild. */
+    anisotropy?: number;
+    /** The look on an HDR display (a screen with headroom above SDR white — Apple XDR panels, the
+     *  macOS host today); ignored on SDR. `strength` 0..1 is how much of the picture reaches for the
+     *  display's headroom (0 only what SDR clipped, 1 nearly everything; default 0.35). `paperWhite`
+     *  1..8 is where white lands as a multiple of SDR white — the "HDR brightness" of a console
+     *  calibration screen, where 1.5–2 is the norm; default 1 keeps a white wall at the UI's white,
+     *  faithful but dim next to what "HDR on" is expected to look like. Engine-wide like `anisotropy`;
+     *  `device.hdr` is the runtime form and tells you whether the display has any headroom at all. */
+    hdr?: {
+        strength?: number;
+        paperWhite?: number;
+    };
+};
+export declare class Scene implements Presentable {
+    readonly camera: Camera;
+    readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node | null>) => void>;
+    private _material?;
+    private static _active;
+    static get active(): Scene | null;
+    constructor(options?: SceneOptions);
+    /** Runtime form of `renderScale` / `dynamicResolution` (a graphics-settings menu). `renderScale`
+     *  0.25–1; older hosts without the method ignore it. */
+    setRenderOptions(renderScale: number, dynamicResolution?: boolean | {
+        min?: number;
+    }): void;
+    /** Scene occlusion material. */
+    get occlusionMaterial(): Material;
+    set skybox(sky: ColorInput | "environment" | {
+        texture: string;
+    });
+    /** Runtime form of `ambientOcclusion` (a graphics-settings menu). `false` turns it off. */
+    setAmbientOcclusion(options: boolean | AmbientOcclusionOptions): void;
+    /** Runtime form of `fog` (weather, entering a building). `false` turns it off. */
+    setFog(options: FogOptions | false): void;
+    setMaterialGlobalParameter(i: number, x: number, y: number, z: number, w: number): void;
+    setAntialias(enabled: boolean, scale?: number): void;
+    add(...nodes: Node[]): this;
+    remove(...nodes: Node[]): this;
+    /** Attach (and configure) a system, or reconfigure it if already present. Returns the scene typed
+     *  as now-having it (`scene.system(Hud).hud`). A `System<'x', Scene2D>` is rejected here. */
+    system<Self extends TargetOf<A>, A extends Aspect<any, any, any>>(this: Self, ctor: AspectCtor<A>, opts?: Partial<A>): Self & FieldOf<A>;
+    /** Safe access — undefined if the system isn't attached. */
+    get<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): A | undefined;
+    /** Existence check AND type guard: inside `if (scene.has(Hud))`, `scene.hud` is present. */
+    has<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): this is this & FieldOf<A>;
+    /** Detach a system (runs its onDetach). Chainable. */
+    removeSystem<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): this;
+    /** Tear the scene down: every system detaches (last-attached first) and the scene closes. Nodes
+     *  are yours — destroy the ones you own; the native scene object itself is not released. */
+    destroy(): void;
+    createOverlay(options?: SceneOptions): Scene;
+    warmRender(): Promise<void>;
+    readonly cl: (() => void)[];
+    _backButtonCallback?: () => void;
+    private _vd?;
+    /** Fires when the scene becomes the visible destination (incl. a pop revealing it). */
+    onOpen(callback: () => void): this;
+    /** Fires when the scene stops being visible (closed, replaced, or covered by a push). */
+    onClose(callback: () => void): this;
+    onBackPressed(callback: () => void): this;
+    /** Make this the active scene — shows it as the current destination (replaces a screen /
+     *  another scene; only the active scene renders). */
+    open(options?: PresentOptions): void | Promise<void>;
+    close(): void;
+    addEventListener(channel: "click", callback: (ev: ClickEvent<Node | null>) => void): void;
+    addEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<Node | null>) => void): void;
+    removeEventListener(channel: "click" | "touchstart", callback: (ev: any) => void): void;
+}
+export type ARMode = "default" | "markers" | "arcore" | "detached";
+export declare class ARScene<T extends ARMode = "default"> extends Scene {
+    readonly mode: T;
+    useWarmRender: boolean;
+    private _root?;
+    constructor(options?: SceneOptions & {
+        mode?: T;
+    });
+    /** Root anchor node (not available in marker mode). */
+    get root(): Node;
+    /** Create an anchor from a tracking source (e.g. an image target). */
+    createAnchor(source: FetchResponse, physicalWidth?: number): Node;
+    /**
+     * Let the user place & manipulate a node with touch gestures — the staple AR object-placement
+     * interaction: ONE finger drags it across the floor (relative to where the camera looks), TWO fingers
+     * pinch to scale and twist to rotate. Returns a handle; call `.remove()` to detach. Tunable via
+     * options (min/max scale, and toggles for `pan` / `pinch` / `twist`).
+     */
+    addControls(target: Node, options?: ControlsOptions): ControlsHandle;
+    open(options?: PresentOptions): Promise<void>;
+    close(): void;
+}
+/**
+ * A 3D scene rendered in a VR headset (OpenXR — e.g. Meta Quest). The headset drives the camera:
+ * every frame both eyes are rendered from the tracked head pose, so `scene.camera` position/lookAt
+ * have no effect while the scene is open. The world origin is at floor level (stage space) —
+ * author content with the ground at y = 0 and the user standing at the origin.
+ *
+ * `open()` rejects on hosts without a VR runtime ("VR is not supported on this device").
+ */
+export declare class VRScene extends Scene {
+    open(options?: PresentOptions): Promise<void>;
+    close(): void;
+}

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

@@ -0,0 +1,122 @@
+import { Aspect } from "../core/Aspect";
+import { type Vec3Like } from "../math/vec";
+import type { Node } from "./Node";
+/** Which geometry a Shape uses — the one-of the fields below encode (see `_build`'s order). */
+export type ShapeKind = "auto" | "box" | "sphere" | "cylinder" | "capsule" | "mesh" | "convex" | "heightfield";
+/** A node-local AABB, in the node's OWN frame (its own transform excluded), before world scale. */
+export type ShapeBounds = {
+    min: [number, number, number];
+    max: [number, number, number];
+};
+/** Dimensions measured from a node's rendered geometry — what `Shape.fit` writes, and the numbers
+ *  the scene editor's "Fit to mesh" button puts in the file. Exactly one dimension key is set (none
+ *  for a mesh/convex kind, whose geometry is the mesh itself); `origin` centres it on the art. */
+export type ShapeFit = {
+    box?: [number, number, number];
+    sphere?: number;
+    cylinder?: {
+        halfHeight: number;
+        radius: number;
+    };
+    capsule?: {
+        halfHeight: number;
+        radius: number;
+    };
+    origin: [number, number, number];
+};
+export declare class Shape extends Aspect<"shape", Node> {
+    static readonly aspect = "shape";
+    /** Box half-extents [hx, hy, hz] (world units). */
+    box?: Vec3Like;
+    /** Sphere radius. */
+    sphere?: number;
+    /** Cylinder aligned on Y: half-height + radius. */
+    cylinder?: {
+        halfHeight: number;
+        radius: number;
+    };
+    /** Capsule aligned on Y: half-height of the cylinder section + radius. */
+    capsule?: {
+        halfHeight: number;
+        radius: number;
+    };
+    /** The node's own triangles (a Mesh's geometry or a Model's GLB, world scale applied).
+     *  `true` = exact triangle mesh — static/kinematic bodies, triggers, characters' ground and picking
+     *  only (a dynamic body can't be a triangle mesh; Physics throws). `'convex'` = convex hull of the
+     *  vertices, works for dynamic bodies too. A Model uses its bind pose (skinned parts skipped). */
+    mesh?: boolean | "convex";
+    /** The node's terrain (`Terrain.create(...).node`) as a Jolt height field — the exact drawn grid,
+     *  holes included (docs/terrain-plan.md). Static / kinematic / picking / character ground only,
+     *  like `mesh: true`. `terrain.commit()` pushes edits into the live shape. */
+    heightfield?: boolean;
+    /**
+     * The shape's centre, relative to the node's origin — world units in the node's ROTATED frame
+     * (the node's scale is ignored, exactly like the explicit dimensions above). Default [0, 0, 0].
+     *
+     * A model's pivot is rarely its centre of volume (a character stands ON its origin, a wheel hangs
+     * off its axle), so a collider centred on the pivot is half sunk into the floor. `origin` lifts it
+     * without moving the node: `{ capsule: { halfHeight: 0.6, radius: 0.3 }, origin: [0, 0.9, 0] }`.
+     * `fit()` and the scene editor's "Fit to mesh" fill it in from the rendered bounds.
+     *
+     * On a DYNAMIC body the offset also moves the centre of mass, so a lopsided collider tips the way
+     * you would expect. With no `origin` an auto shape (`{}`) still centres itself on the node's own
+     * mesh bounds — only explicit dimensions sit on the pivot by default.
+     */
+    origin?: Vec3Like;
+    /** Whether pointer rays can hit this shape (click / touchstart). Default true. */
+    raycast: boolean;
+    private _shapeId;
+    private _bodyId;
+    /** Centre the "auto" box measured for itself — used when `origin` isn't set explicitly. */
+    private _autoOrigin;
+    /** Geometry props as of the last build (see onReconfigure). */
+    private _sig;
+    onAttach(): void;
+    onDetach(): void;
+    /** Re-configuring (`node.aspect(Shape, { origin })`) rebuilds the geometry when a dimension, the
+     *  kind or the origin changed, and re-applies pickability. The body keeps its id and velocity. */
+    onReconfigure(): void;
+    /**
+     * Measure the node's rendered geometry and size the collider to it — the code half of the scene
+     * editor's "Fit to mesh". Keeps the current kind unless one is passed; `auto` becomes an explicit
+     * box, and a mesh/convex shape only has its `origin` cleared (its geometry IS the mesh).
+     *
+     *   crate.aspect(Shape, {}).shape.fit()             // box around what the model actually draws
+     *   hero.aspect(Shape, {}).shape.fit('capsule')     // capsule of the same height + girth
+     *
+     * A model loads asynchronously, so fit AFTER its `load()` resolves — an empty subtree measures as
+     * nothing and the call is a no-op (it warns). Rebuilds the live shape, keeping the body.
+     */
+    fit(kind?: ShapeKind): this;
+    /** Which geometry this shape currently uses (the `_build` dispatch, as a name). */
+    get kind(): ShapeKind;
+    /**
+     * The node's subtree AABB in its OWN local frame (its own transform excluded), or null when there
+     * is nothing to measure. Reads the engine's bounds — which cover a loaded GLB and every child —
+     * and falls back to a Mesh node's own CPU geometry on hosts without them.
+     */
+    static boundsOf(node: Node): ShapeBounds | null;
+    /**
+     * Dimensions + origin that make `kind` hug what `node` renders — world units, so the node's world
+     * scale is baked in exactly as the Shape fields expect. Null when the node has no geometry (a
+     * model that hasn't loaded, an empty).
+     */
+    static fitTo(node: Node, kind?: ShapeKind): ShapeFit | null;
+    /**
+     * The measuring itself, over plain numbers: a node-local AABB + the node's world scale in, shape
+     * dimensions out. Separate from `fitTo` so the scene-editor harness can measure a node from
+     * ANOTHER bundle without touching accessors the bundler may have shaken out of it.
+     *
+     * A sphere takes the LARGEST half-extent and a cylinder/capsule the larger of X/Z, so the fit
+     * reads as the object's silhouette rather than as an enclosing ball; adjust from there.
+     */
+    static fitBounds(bounds: ShapeBounds, scale: Vec3Like, kind?: ShapeKind): ShapeFit;
+    private _createPickBody;
+    private _rebuild;
+    private _build;
+    private _applyOrigin;
+    private _signature;
+    private _buildHeightField;
+    private _buildMesh;
+    private _buildAutoBox;
+}