lecodes-sdk 0.19.0

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

@@ -0,0 +1,169 @@
+import { System } from "../core/Aspect";
+import { Vec3, type Vec3Like } from "../math/vec";
+import type { Node } from "./Node";
+import type { Scene } from "./Scene";
+export declare const NAV_AGENT: {
+    readonly RADIUS: 0;
+    readonly HEIGHT: 1;
+    readonly MAX_SPEED: 2;
+    readonly MAX_ACCELERATION: 3;
+    readonly COLLISION_QUERY_RANGE: 4;
+    readonly PATH_OPTIMIZATION_RANGE: 5;
+    readonly SEPARATION_WEIGHT: 6;
+    readonly AVOIDANCE: 7;
+    readonly INCLUDE_FLAGS: 8;
+    readonly EXCLUDE_FLAGS: 9;
+    readonly ANTICIPATE_TURNS: 10;
+    readonly OPTIMIZE_VIS: 11;
+    readonly OPTIMIZE_TOPO: 12;
+    readonly COUNT: 13;
+};
+export declare const NAV_READ: {
+    readonly POS_X: 0;
+    readonly POS_Y: 1;
+    readonly POS_Z: 2;
+    readonly VEL_X: 3;
+    readonly VEL_Y: 4;
+    readonly VEL_Z: 5;
+    readonly DVEL_X: 6;
+    readonly DVEL_Y: 7;
+    readonly DVEL_Z: 8;
+    readonly STATE: 9;
+    readonly TARGET_STATE: 10;
+    readonly REMAINING: 11;
+    readonly PARTIAL: 12;
+    readonly STRIDE: 13;
+};
+/** The agent size a navmesh is built for (and the crowd's defaults). */
+export type NavAgentSize = {
+    /** metres — polygons are eroded by it. Default 0.4 */
+    radius?: number;
+    /** metres. Default 1.8 */
+    height?: number;
+    /** the highest step walked over, metres. Default 0.4 */
+    climb?: number;
+    /** the steepest walkable slope, degrees. Default 50 */
+    slope?: number;
+};
+export type NavMeshLoadOptions = {
+    /** `asset('./assets/nav/<scene>.navmesh')` — what `lecodes navmesh bake` writes. */
+    data: string;
+    /** The agent size the bake uses (the file records it; the crowd reads it back). */
+    agent?: NavAgentSize;
+    /** Named areas → traversal cost (1 = plain ground). Ids are assigned in this order (1..15); the
+     *  bake stores the names, queries and agents refer to them (`include` / `exclude`, `cost`). */
+    areas?: Record<string, number>;
+};
+/** The file header `lecodes navmesh bake` wrote. */
+export type NavMeshInfo = {
+    version: number;
+    agent: {
+        radius: number;
+        height: number;
+        climb: number;
+        slope: number;
+    };
+    cell: number;
+    cellHeight: number;
+    tileSize: number;
+    bounds: [[number, number, number], [number, number, number]];
+    stats: {
+        tiles: number;
+        polys: number;
+        verts: number;
+        triangles: number;
+        volumes: number;
+        links: number;
+    };
+    meta: {
+        scene?: string;
+        areas?: Record<string, number>;
+        costs?: Record<string, number>;
+        [k: string]: unknown;
+    } | null;
+};
+/** A straight path: the corners to walk, plus whether it stops short of the target. */
+export type NavPath = Vec3[] & {
+    partial: boolean;
+};
+export type NavQueryOptions = {
+    /** Only these areas (names). Default: every area. */
+    include?: string[];
+    /** Never these areas (names). */
+    exclude?: string[];
+    /** Search half-extents around each endpoint (how far off the mesh a point may be). Default [2, 4, 2]. */
+    extents?: Vec3Like;
+};
+export type NavRaycastHit = {
+    hit: boolean;
+    point: Vec3;
+    normal: Vec3;
+};
+/** The crowd behind a scene's agents — a system `NavMesh.load` attaches to the scene so the whole
+ *  crowd advances once per fixed step, BEFORE every `NavAgent` applies its slot (`static after`). */
+export declare class NavCrowd extends System<"navCrowd"> {
+    static readonly aspect = "navCrowd";
+    updateFixed(dt: number): void;
+    onDetach(): void;
+}
+export declare class NavMesh {
+    /** True while `lecodes navmesh bake` runs the app — skip menus and build the level straight away. */
+    static get baking(): boolean;
+    /** The navmesh agents bind to (the last one loaded; one per world at a time). */
+    static active: NavMesh | null;
+    private static byScene;
+    private static overrides;
+    private static warned;
+    private static baked;
+    /** Leave a static body out of the bake (`nav: false` in a scene file). */
+    static exclude(node: Node): void;
+    /** A static body nobody may walk on (`nav: 'unwalkable'`): its footprint is cut out. */
+    static unwalkable(node: Node): void;
+    /** A static body's surface belongs to a named area (`navArea: 'road'`; names from `load`'s `areas`). */
+    static area(node: Node, name: string): void;
+    /** Forget every override (a scene rebuild). */
+    static clear(): void;
+    static of(scene: Scene): NavMesh | null;
+    /** Load the level's navmesh — or, under `lecodes navmesh bake`, dump the collision geometry for
+     *  it. Resolves null when nothing was loaded (no bake yet, a host without navigation, bake mode). */
+    static load(scene: Scene, opts: NavMeshLoadOptions): Promise<NavMesh | null>;
+    readonly scene: Scene;
+    readonly info: NavMeshInfo;
+    /** The agent size the mesh was built for. */
+    readonly agent: {
+        radius: number;
+        height: number;
+        climb: number;
+        slope: number;
+    };
+    /** Named areas → ids (from the bake; `load`'s `areas` when the file has none). */
+    readonly areas: Record<string, number>;
+    private _debug;
+    private _seed;
+    private _disposed;
+    private constructor();
+    private static areaIds;
+    /** The include/exclude flag mask for a list of area names (undefined = every area). */
+    flags(names?: string[]): number;
+    private masks;
+    /** Traversal cost of a named area (1 = plain ground; > 1 = avoided when a cheaper way exists). */
+    cost(area: string, cost: number): void;
+    /** The straight (string-pulled) path from → to. Empty when an endpoint is off the mesh;
+     *  `.partial` when the target is unreachable (the path ends at the closest polygon). */
+    findPath(from: Vec3Like, to: Vec3Like, opts?: NavQueryOptions & {
+        maxCorners?: number;
+    }): NavPath;
+    /** The closest point on the mesh (within `extents` of `p`), or null. */
+    nearest(p: Vec3Like, opts?: NavQueryOptions): Vec3 | null;
+    /** Can an agent walk straight from → to? `hit` = a wall in between (at `point`, facing `normal`). */
+    raycast(from: Vec3Like, to: Vec3Like, opts?: NavQueryOptions): NavRaycastHit;
+    /** A random reachable point — within walking distance `radius` of `center`, or anywhere on the
+     *  mesh. Deterministic: the sequence depends only on the calls made (a seeded generator). */
+    randomPoint(center?: Vec3Like, radius?: number, opts?: NavQueryOptions): Vec3 | null;
+    /** Draw the polygon mesh (a flat unlit surface 3 cm above the walkable area). */
+    get debug(): boolean;
+    set debug(on: boolean);
+    /** Release the host handles (a scene teardown). Agents fall back to inert. */
+    dispose(): void;
+    private static bake;
+}

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

@@ -0,0 +1,99 @@
+import { AspectHost } from "../core/Aspect";
+import { Registry } from "../core/registry";
+import { Vec3, type Vec3Like } from "../math/vec";
+import { Quat, type QuatLike } from "../math/quat";
+import { Mat4, type Mat4Like } from "../math/mat4";
+import type { Geometry } from "./Geometry";
+import { Material } from "./Material";
+import type { CompAxis, CompWriter } from "../core/compWrite";
+import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
+/** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
+export declare const nodeRegistry: Registry<Node>;
+export type NodeEvents = {
+    click: (ev: ClickEvent<Node | null>) => void;
+    touchstart: (ev: TouchStartEvent<Node | null>) => void;
+    /** AR anchors only (`scene.root` / `scene.createAnchor()`): the anchor began tracking. */
+    track: () => void;
+    /** AR anchors only: the anchor lost tracking. */
+    untrack: () => void;
+    /** A physics contact/trigger overlap began (the other body's node). Needs a Shape + Physics/Trigger. */
+    enter: (other: Node) => void;
+    /** A physics contact/trigger overlap ended. */
+    exit: (other: Node) => void;
+};
+export declare class Node extends AspectHost<NodeEvents> implements CompWriter {
+    /** Native entity handle. */
+    readonly id: number;
+    /** AR anchors only — whether the anchor is currently being tracked. Kept in step with the
+     *  'track' / 'untrack' events; `false` for any non-anchor node. */
+    isTracked: boolean;
+    private _matrix?;
+    private _worldMatrix?;
+    private _boneCache?;
+    /** Materials assigned through setMaterial, by primitive slot (a Mesh fills slot 0 itself). */
+    protected _materials?: Material[];
+    constructor(internalId?: number);
+    /** Geometry, if this node is a Mesh (used by physics auto-shape). Overridden by Mesh. */
+    get geometry(): Geometry | undefined;
+    get name(): string;
+    set name(value: string);
+    get visible(): boolean;
+    set visible(value: boolean);
+    private _sync;
+    get matrix(): Mat4;
+    set matrix(m: Mat4Like);
+    get worldMatrix(): Mat4;
+    set worldMatrix(m: Mat4Like);
+    private _setOwnedPosition;
+    private _setOwnedRotation;
+    get position(): Vec3;
+    set position(v: Vec3Like);
+    get x(): number;
+    set x(v: number);
+    get y(): number;
+    set y(v: number);
+    get z(): number;
+    set z(v: number);
+    _writeComp(_prop: string, axis: CompAxis, v: number): void;
+    get scale(): Vec3;
+    set scale(v: Vec3Like | number);
+    get quaternion(): Quat;
+    set quaternion(v: QuatLike);
+    get eulerAngles(): Vec3;
+    set eulerAngles(v: Vec3Like);
+    get forward(): Vec3;
+    get worldPosition(): Vec3;
+    get worldScale(): Vec3;
+    get worldQuaternion(): Quat;
+    get worldEulerAngles(): Vec3;
+    get parent(): Node | null;
+    get children(): Node[];
+    get childCount(): number;
+    getChild(index: number): Node | null;
+    /** Parent the given nodes under this one. */
+    add(...children: Node[]): this;
+    setParent(parent: Node | null, worldPositionStays?: boolean): this;
+    traverse(callback: (node: Node) => void): void;
+    /** The material assigned to slot 0 through this API (null before one is set — a GLB part's own
+     *  glTF material stays native-side). */
+    get material(): Material | null;
+    set material(m: Material);
+    /** Replace the material of one primitive slot (`index` = the primitive's order in the glTF
+     *  mesh; a primitive-shape Mesh has one slot). */
+    setMaterial(material: Material, index?: number): this;
+    /** The material previously assigned to `index` (null when none was — see Mesh for the probe). */
+    getMaterial(index?: number): Material | null;
+    /** Find a descendant by name — bones of a loaded Model included (`hero.bone('RightHand').add(sword)`).
+     *  Same rule the Animator binds clips with: exact name first, then the part after the last `:` / `|`
+     *  (Mixamo `mixamorig:Hips` matches `Hips`); a skinned joint beats a plain node of the same name.
+     *  Cached per name; null if absent. */
+    bone(name: string): Node | null;
+    /** Orient the node so the given axis (default "-z", "forward") points at a world point. */
+    lookAt(point: Vec3Like, mode?: "z" | "-z" | "x" | "-x" | "y" | "-y", ortho?: Vec3Like): this;
+    addEventListener<K extends keyof NodeEvents>(channel: K, callback: NodeEvents[K]): void;
+    /** Destroy this node and its whole subtree. Every aspect in the subtree is detached first (its
+     *  `onDetach` runs: physics bodies released, updaters unregistered, listeners dropped) — native
+     *  `destroyEntity` frees the entity tree but knows nothing about JS-side aspects, and a destroyed
+     *  node's `update()` must not keep ticking. Deepest nodes go first, then this one. */
+    destroy(): void;
+}

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

@@ -0,0 +1,20 @@
+export declare class Noise {
+    private readonly _id;
+    constructor();
+    /** Sample 2D noise. */
+    get(x: number, y: number): number;
+    /** Sample 3D noise. */
+    get3d(x: number, y: number, z: number): number;
+    private _frequency;
+    get frequency(): number;
+    set frequency(v: number);
+    private _octaves;
+    get octaves(): number;
+    set octaves(v: number);
+    private _fractalLacunarity;
+    get fractalLacunarity(): number;
+    set fractalLacunarity(v: number);
+    private _fractalGain;
+    get fractalGain(): number;
+    set fractalGain(v: number);
+}

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

@@ -0,0 +1,277 @@
+import { type ColorInput } from "../core/color";
+import { type Vec3Like } from "../math/vec";
+import type { Geometry } from "./Geometry";
+import { Material, type ParticlesMaterialOptions } from "./Material";
+import { Node } from "./Node";
+type Range<T> = T | {
+    min: T;
+    max: T;
+};
+export declare class CurveBuilder {
+    private _kind;
+    private _lo;
+    private _hi;
+    private _stops;
+    constructor(base: Range<number>, mode: "multiply" | "add");
+    /** Curve value at birth (t = 0). Must come before any other stop. */
+    from(v: Range<number>): this;
+    /** Curve value at `t` (0..1 of the particle's life). Stops must be added in ascending t order. */
+    via(t: number, v: Range<number>): this;
+    /** Curve value at death (t = 1). */
+    to(v: Range<number>): this;
+    /** The classic opacity envelope: rise over the first `fadeIn`, fall over the last `fadeOut`. */
+    fade(fadeIn?: number, fadeOut?: number): this;
+    /** The PARAM_CURVE record payload (sans slot): [kind, baseLo, baseHi, n, (t, lo, hi)×n]. */
+    get _data(): Float32Array;
+}
+export declare class ColorCurveBuilder {
+    private _lo;
+    private _hi;
+    private _stops;
+    constructor(base: Range<ColorInput>);
+    /** Curve color at birth (t = 0). Must come first. The curve multiplies the base color. */
+    from(c: Range<ColorInput>): this;
+    /** Curve color at `t` (0..1 of the particle's life), in ascending t order. */
+    via(t: number, c: Range<ColorInput>): this;
+    /** Curve color at death (t = 1). */
+    to(c: Range<ColorInput>): this;
+    /** The COLOR_CURVE record payload: [baseLo rgba, baseHi rgba, n, (t, lo rgba, hi rgba)×n]. */
+    get _data(): Float32Array;
+}
+/** A value curve over each particle's lifetime. Default mode `multiply` (the curve scales the
+ *  base); `add` offsets it instead. */
+export declare const curve: (base?: Range<number>, mode?: "multiply" | "add") => CurveBuilder;
+/** A color curve over each particle's lifetime — always multiplies the base color. */
+export declare const colorCurve: (base?: Range<ColorInput>) => ColorCurveBuilder;
+export type ParticleValue = Range<number> | CurveBuilder | {
+    _data: Float32Array;
+};
+export type ParticleColor = ColorInput | {
+    min: ColorInput;
+    max: ColorInput;
+} | ColorCurveBuilder | {
+    _data: Float32Array;
+};
+type VelocityValue = {
+    speed?: Range<number>;
+    /** Cone half-angle in radians — jitter the launch direction uniformly within it. */
+    spread?: number;
+    /** Asymmetric jitter: two angles (u, v — the x/y components) in radians. */
+    randomizeAngle?: {
+        min: Vec3Like;
+        max: Vec3Like;
+    };
+} & ({
+    from: Vec3Like;
+} | {
+    to: Vec3Like;
+} | {
+    dir: Vec3Like;
+} | {});
+/** Where particles are born, in emitter space. Sphere / hemisphere / cone have an axis of +Y (the
+ *  hemisphere is the +Y half, the cone opens along +Y from its base disc at `center`) — aim the
+ *  node with `lookAt(target, 'y')`. `thickness` 0 emits from the surface only, 1 (default) from the
+ *  whole volume. A sphere or cone also sets the LAUNCH DIRECTION (outward / from the cone's apex)
+ *  when `startVelocity` gives a speed but no direction, like Unity's shapes. */
+type Shape = {
+    type: "point";
+    v: Vec3Like;
+} | {
+    type: "box";
+    min: Vec3Like;
+    max: Vec3Like;
+} | {
+    type: "circle";
+    center: Vec3Like;
+    radius: number;
+} | {
+    type: "sphere";
+    center?: Vec3Like;
+    radius: number;
+    thickness?: number;
+} | {
+    type: "hemisphere";
+    center?: Vec3Like;
+    radius: number;
+    thickness?: number;
+} | {
+    type: "cone";
+    center?: Vec3Like;
+    radius: number; /** half-angle, radians */
+    angle?: number; /** emit this far up the axis too */
+    length?: number;
+    thickness?: number;
+};
+/** Extra velocity over each particle's life — evaluated from the curves every frame and ADDED as a
+ *  displacement (not accumulated like `acceleration`): `radial` pushes outward along the particle's
+ *  birth direction (a burst that decays: `curve(4).to(0)`), `x`/`y`/`z` drift in the simulation
+ *  space (rising smoke: `y: curve(2).from(0).to(1)`). Unity's velocityOverLifetime. */
+export type VelocityOverLife = {
+    radial?: ParticleValue;
+    x?: ParticleValue;
+    y?: ParticleValue;
+    z?: ParticleValue;
+};
+type Noise = {
+    strength?: number;
+    frequency?: number;
+    speed?: number;
+};
+/** Ground plane for bouncing particles (all render modes). `height` is in the simulation space:
+ *  world y with `space: 'world'`, emitter-local y otherwise. */
+export type ParticleGround = {
+    /** Plane height (default 0). */
+    height?: number;
+    /** Contact radius — particles stop `radius` above the plane (a mesh's half-extent; default 0). */
+    radius?: number;
+    /** Fraction of the vertical speed kept on impact, 0..1 (default 0.3). */
+    bounce?: number;
+    /** Tangential damping while in contact, per second — like `drag` (default 8). */
+    friction?: number;
+};
+export type ParticlesOptions = ParticlesMaterialOptions & {
+    /** Draw every particle as this mesh — lit, tumbling 3D debris (shell casings, rubble, leaves,
+     *  shrapnel) in one draw call. The system switches to the mesh render mode; the default
+     *  material becomes `Material.lit()` (pass `material` for color/roughness/metallic — the
+     *  sprite look options are ignored). `size` scales the mesh (default 1); `rotation`/`opacity`/
+     *  `frame` don't apply. See `angularVelocity` and `ground`. */
+    mesh?: Geometry;
+    /** (mesh) Spin, radians per second about the particle's own axes — a vector, or a per-component
+     *  `{ min, max }` range randomized at spawn. Particles are born in the emitter's orientation. */
+    angularVelocity?: Vec3Like | {
+        min: Vec3Like;
+        max: Vec3Like;
+    };
+    /** A ground plane the particles bounce on and come to rest on (any render mode); `null`
+     *  disables it. */
+    ground?: ParticleGround | null;
+    /** Custom draw material. Unset = the default point-sprite material, configured by the
+     *  `ParticlesMaterialOptions` sugar (map/sheet/emissive/blend/soft) — which is ignored
+     *  when an explicit material is passed. */
+    material?: Material;
+    /** Particle pool capacity (default 1000). */
+    maxParticles?: number;
+    /** Particles emitted per second. */
+    rate?: number;
+    /** Simulation space. `'local'` (default) — particles ride the node's transform; `'world'` —
+     *  each particle stays where it was born as the emitter moves on (trails: drift smoke, mud,
+     *  wake). Switching at runtime resets live particles. */
+    space?: "local" | "world";
+    /** Fraction (usually 0..1) of the emitter's own velocity added to each particle at spawn —
+     *  smoke "thrown" off a moving car. Takes effect with `space: 'world'`. */
+    inheritVelocity?: number;
+    /** Particles emitted per world unit the emitter MOVES, on top of `rate`, with spawn points
+     *  spread evenly along the path — trail density independent of speed, no per-frame clumps.
+     *  Meant for `space: 'world'`. */
+    rateOverDistance?: number;
+    /** Draw order among blended systems at the same depth — higher draws later, i.e. on top (Unity's
+     *  sortingOrder). Systems are depth-sorted by their node, so the emitters of one effect tie and
+     *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
+     *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
+    order?: number;
+    shape?: Shape;
+    /** Extra velocity over life (radial burst that decays, axis drift) — see `VelocityOverLife`. */
+    velocityOverLife?: VelocityOverLife;
+    startVelocity?: Vec3Like | VelocityValue;
+    /** Downward acceleration, world units/s² — positive pulls particles DOWN (sugar for
+     *  `acceleration: [0, -g, 0]`). */
+    gravity?: number;
+    /** Constant acceleration vector (gravity, wind, …). Wins over `gravity` when both are set. */
+    acceleration?: Vec3Like;
+    drag?: number;
+    lifetime?: Range<number>;
+    color?: ParticleColor;
+    /** World-unit diameter (alias of custom[0]). Default 1. */
+    size?: ParticleValue;
+    /** Radians (alias of custom[1]). */
+    rotation?: ParticleValue;
+    /** Per-particle opacity 0..1 (alias of custom[2]). Default 1. */
+    opacity?: ParticleValue;
+    /** Flipbook frame index (alias of custom[3]). With `sheet` set and no explicit frame, the
+     *  default is one full sheet cycle over each particle's lifetime, starting at `startFrame`. */
+    frame?: ParticleValue;
+    /** Where the default flipbook cycle begins: `'random'` (default — desynchronized loops like
+     *  fire/smoke) or a frame index (`0` plays the sheet in order — explosions, one-shot bursts).
+     *  Only shapes the default; an explicit `frame` wins. */
+    startFrame?: number | "random";
+    noise?: Noise | null;
+    /** Fixed random seed for deterministic tests. */
+    seed?: number;
+};
+export declare class Particles extends Node {
+    private _material;
+    /** Custom curve-param slots (0..3); size/rotation/opacity/frame alias slots 0-3. */
+    readonly custom: ParticleValue[];
+    constructor(options?: ParticlesOptions);
+    /** Emit `count` particles immediately (a burst). */
+    spawn(count: number): this;
+    private _send;
+    set rate(val: number);
+    /** `'world'` leaves particles behind where they were born (trails). Switching resets live ones. */
+    set space(val: "local" | "world");
+    set inheritVelocity(val: number);
+    set rateOverDistance(val: number);
+    set order(val: number);
+    set velocityOverLife(v: VelocityOverLife);
+    set shape(shape: Shape);
+    /** (mesh mode) Replace the particle mesh; live particles keep flying as the new shape. */
+    set mesh(g: Geometry);
+    set angularVelocity(v: Vec3Like | {
+        min: Vec3Like;
+        max: Vec3Like;
+    });
+    set ground(g: ParticleGround | null);
+    set startVelocity(val: Vec3Like | VelocityValue);
+    /** Positive pulls particles down — sugar for `acceleration = [0, -g, 0]`. */
+    set gravity(val: number);
+    set acceleration(a: Vec3Like);
+    set drag(val: number);
+    set seed(val: number);
+    set lifetime(val: Range<number>);
+    set size(val: ParticleValue);
+    set rotation(val: ParticleValue);
+    set opacity(val: ParticleValue);
+    set frame(val: ParticleValue);
+    set color(value: ParticleColor);
+    get material(): Material;
+    set material(material: Material);
+    set noise(noise: Noise | null);
+}
+/** `Trail` options. The look options (map/sheet/emissive/blend/soft) come from
+ *  `ParticlesMaterialOptions`, same as `Particles`. */
+export type TrailOptions = Omit<ParticlesMaterialOptions, "render" | "stretch"> & {
+    /** Seconds each trail point lives — the trail's length in time. Default 0.5. */
+    time?: number;
+    /** Strip width in world units; a curve tapers it over each point's life (head → tail).
+     *  Default 0.1. */
+    width?: ParticleValue;
+    /** Minimum emitter movement (world units) between recorded points. Default 0.05. */
+    minDistance?: number;
+    /** Point capacity (default 128). */
+    maxPoints?: number;
+    color?: ParticleColor;
+    /** Opacity along the trail. Defaults to fading the tail out (`curve().to(0)`). */
+    opacity?: ParticleValue;
+};
+/** A ribbon strip that follows this node through the world — sword swings, skid marks, missile
+ *  trails. Attach it to (or under) the moving node and just move; points are laid down per
+ *  `minDistance` of movement, live for `time` seconds, and the strip stays glued to the node at
+ *  its head. Width/opacity/color accept the same curves as `Particles`, evaluated over each
+ *  point's life — i.e. along the trail from head (fresh) to tail (dying). */
+export declare class Trail extends Node {
+    private _material;
+    private _rateDistance;
+    constructor(options?: TrailOptions);
+    private _send;
+    /** Trail length in seconds — how long each laid-down point lives. */
+    set time(val: number);
+    set width(val: ParticleValue);
+    set opacity(val: ParticleValue);
+    set color(value: ParticleColor);
+    set minDistance(val: number);
+    /** Pause/resume laying down points — existing ones still age out, so the trail fades naturally
+     *  after e.g. a sword swing ends. */
+    set emitting(val: boolean);
+    get material(): Material;
+}
+export {};

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

@@ -0,0 +1,91 @@
+import { Aspect } from "../core/Aspect";
+import type { FieldMeta } from "../core/fields";
+import type { CompAxis, CompWriter } from "../core/compWrite";
+import { Vec3, type Vec3Like } from "../math/vec";
+import { type Node } from "./Node";
+export type MotionType = "static" | "dynamic" | "kinematic";
+export interface PhysicsConfig {
+    /** Gravity in world units/s² (Y-up: down is negative). Default [0, -9.81, 0]. */
+    gravity?: Vec3Like;
+    /** Max simultaneous bodies (resizes the world; only before any body exists). Default 4096. */
+    maxBodies?: number;
+}
+/** Closest raycast hit. */
+export interface RayHit {
+    node: Node | null;
+    point: Vec3;
+    normal: Vec3;
+    fraction: number;
+}
+/**
+ * What a body's friction already is the moment the host creates it. This is part of the ABI, not an
+ * assumption: bridges.d.ts states it, so every host owes us this value. Knowing it lets attach skip
+ * a bridge call per body whenever nobody named a surface.
+ */
+export declare const DEFAULT_FRICTION = 0.6;
+export declare class Physics extends Aspect<"physics", Node> implements CompWriter {
+    static readonly aspect = "physics";
+    /** Render interpolation of body transforms between the fixed 60 Hz steps (global; default on). Turn
+     *  off to save per-frame transform writes when you have many moving bodies / don't need >60 Hz
+     *  smoothness — bodies then advance in discrete steps. */
+    private static _interpolation;
+    static get interpolation(): boolean;
+    static set interpolation(on: boolean);
+    /** Default "dynamic". */
+    motion: MotionType;
+    /** Mass in kg for dynamic bodies (default 1). Ignored for static/kinematic. */
+    mass: number;
+    /**
+     * Surface friction: 0 = ice, ~1 = grippy asphalt, and values above 1 are allowed (rubber on
+     * tarmac).
+     *
+     * The engine COMBINES the two touching bodies as `sqrt(a * b)`, so the LOWER value dominates and
+     * the floor caps everything standing on it. The default **0.6** is a neutral solid surface (the
+     * raw Jolt default of 0.2 is ice by game standards); dry tarmac a car should corner on wants a
+     * `1`, ice `0.02`. A Vehicle's tires read the GROUND body's value, so this is the single number
+     * that decides how well a car corners.
+     *
+     * Change it at runtime by re-configuring — `floor.aspect(Physics, { friction: 0.02 })` (an ice
+     * patch) — or by assigning `floor.physics.friction = 0.02`; either way the setter pushes the new
+     * surface to the live body at once. (chisel keeps an instance setter whose name appears as an
+     * object-literal key anywhere in the bundle, so the config-object route survives tree-shaking
+     * even when no code reads `.friction`.)
+     */
+    get friction(): number;
+    set friction(v: number);
+    private _friction;
+    /** Scene-editor inspector: `motion` as a dropdown (a string default alone infers a text box). */
+    static fields: FieldMeta<Physics>;
+    private _bodyId;
+    onAttach(): void;
+    onDetach(): void;
+    /** Native Jolt body id. 0 until attached, or if the build has no physics support. */
+    get id(): number;
+    /** Linear velocity in world units/second (fresh Vec3 on read; `velocity.y = 5` written directly on
+     *  the aspect is compiled to a component write — see `_writeComp`). */
+    get velocity(): Vec3;
+    set velocity(v: Vec3Like);
+    /**
+     * Angular velocity — **degrees/second about each world axis** (the SDK's angle unit everywhere;
+     * the engine works in radians and converts here). Fresh Vec3 on read.
+     *
+     * This is the only handle on a body's spin, and placing an object usually needs it: a `position`
+     * write is a pure teleport, so a crate that was tumbling keeps tumbling at its new home. Putting
+     * something down is `body.velocity = [0,0,0]; body.angularVelocity = [0,0,0]; node.position = p`.
+     */
+    get angularVelocity(): Vec3;
+    set angularVelocity(v: Vec3Like);
+    _writeComp(prop: string, axis: CompAxis, v: number): void;
+    /** Apply an instantaneous impulse (kg·m/s) and wake the body. */
+    applyImpulse(v: Vec3Like): this;
+    /** The same impulse applied at a WORLD-SPACE point instead of the centre of mass: the lever arm
+     *  becomes angular impulse, so the body spins as well as moves (a bullet hitting a crate off
+     *  centre, a blast lifting it by its base). Falls back to the central impulse on an older host. */
+    applyImpulseAt(v: Vec3Like, point: Vec3Like): this;
+    /** Configure gravity / limits. Call once before creating bodies. */
+    static configure(config?: PhysicsConfig): void;
+    /** Whether this build has physics support (CREATOR_GL_PHYSICS). */
+    static get supported(): boolean;
+    /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. */
+    static raycast(origin: Vec3Like, dir: Vec3Like, maxDist?: number): RayHit | null;
+}

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

@@ -0,0 +1,19 @@
+import { Vec3, type Vec3Like } from "../math/vec";
+import type { Ray } from "./Ray";
+export declare class Plane {
+    /** Unit normal. */
+    readonly normal: Vec3;
+    /** Scalar offset: dot(normal, point). */
+    readonly d: number;
+    constructor(normal: Vec3Like, point: Vec3Like);
+    static fromPoints(a: Vec3Like, b: Vec3Like, c: Vec3Like): Plane;
+    static fromCoefficients(a: number, b: number, c: number, d: number): Plane;
+    /** Ray-plane parameter t (≥0), or null on a miss (parallel / behind origin). */
+    intersectRay(ray: Ray): number | null;
+    /** Like intersectRay but allows hits behind the origin (line-plane). */
+    intersectLine(ray: Ray): number | null;
+    /** Signed distance from a point (positive on the normal's side). */
+    signedDistance(point: Vec3Like): number;
+    /** Project a point onto the plane. */
+    projectPoint(point: Vec3Like): Vec3;
+}