@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/input/xr-source.js

@@ -0,0 +1,164 @@
+/// <reference path="../platform/xr-types.d.ts" preserve="true" />
+/**
+ * XR controllers and hands as pointers (ws/xr; ARCHITECTURE "Input"). `XrPointerSource` is a
+ * `PointerSource` the router polls like any other: each `XRInputSource` of the session becomes
+ * one `PointerSample` whose ray is the source's target ray in the reference space (`x`, `y`
+ * NaN: there is no screen), with `xr.trigger` and `xr.squeeze` from the `xr-standard` gamepad
+ * (buttons 0 and 1) or, without a gamepad, from the session's select and squeeze events, and
+ * `xr.pinch` from the hand's index-finger tip and thumb tip when the Hand Input module reports
+ * joints. `select = trigger || pinch`, `secondary = squeeze`, `hand` is the handedness. Nothing in
+ * the router changes; `{ xr: 'trigger' | 'squeeze' | 'pinch', hand? }` bindings read these.
+ *
+ * Poses are only readable inside an `XRFrame`, so the source takes a getter for the frame that is
+ * running (`() => xrHost.frame`); polled outside one it reports no pointers.
+ */
+import { createSample } from './pointer-sources.js';
+/** Position of a joint pose's transform; the pose's `position` is read, not its matrix. */
+function dist(a, b) {
+    const p = a.transform.position;
+    const q = b.transform.position;
+    return Math.hypot(p.x - q.x, p.y - q.y, p.z - q.z);
+}
+export class XrPointerSource {
+    session;
+    referenceSpace;
+    frame;
+    samples = new Map();
+    pressed = new Map();
+    pinching = new Map();
+    out = [];
+    pinchStart;
+    pinchEnd;
+    nextKey = 0;
+    listening = false;
+    constructor(session, referenceSpace, 
+    /** The `XRFrame` running now, or null between frames (`() => xrHost.frame`). */
+    frame, opts = {}) {
+        this.session = session;
+        this.referenceSpace = referenceSpace;
+        this.frame = frame;
+        this.pinchStart = opts.pinchStart ?? 0.02;
+        this.pinchEnd = opts.pinchEnd ?? 0.035;
+        this.attach();
+    }
+    /** Listens to the session's select and squeeze events (the router calls this; idempotent). */
+    attach() {
+        if (this.listening)
+            return;
+        this.listening = true;
+        const s = this.session;
+        s.addEventListener('selectstart', this.onSelectStart);
+        s.addEventListener('selectend', this.onSelectEnd);
+        s.addEventListener('squeezestart', this.onSqueezeStart);
+        s.addEventListener('squeezeend', this.onSqueezeEnd);
+        s.addEventListener('inputsourceschange', this.onSourcesChange);
+    }
+    /** Stops listening and forgets every pointer. */
+    detach() {
+        if (!this.listening)
+            return;
+        this.listening = false;
+        const s = this.session;
+        s.removeEventListener('selectstart', this.onSelectStart);
+        s.removeEventListener('selectend', this.onSelectEnd);
+        s.removeEventListener('squeezestart', this.onSqueezeStart);
+        s.removeEventListener('squeezeend', this.onSqueezeEnd);
+        s.removeEventListener('inputsourceschange', this.onSourcesChange);
+        this.samples.clear();
+        this.pressed.clear();
+        this.pinching.clear();
+    }
+    poll(_camera) {
+        const out = this.out;
+        out.length = 0;
+        const frame = this.frame();
+        if (!frame)
+            return out;
+        const sources = this.session.inputSources;
+        for (let i = 0; i < sources.length; i++) {
+            const src = sources[i];
+            const pose = frame.getPose(src.targetRaySpace, this.referenceSpace);
+            if (!pose)
+                continue;
+            let s = this.samples.get(src);
+            if (!s) {
+                s = createSample(this.nextKey++, 'xr');
+                s.xr = { trigger: false, squeeze: false, pinch: false };
+                this.samples.set(src, s);
+            }
+            s.hand = src.handedness === 'left' || src.handedness === 'right' ? src.handedness : null;
+            const m = pose.transform.matrix;
+            const ray = s.ray;
+            ray.origin[0] = m[12];
+            ray.origin[1] = m[13];
+            ray.origin[2] = m[14];
+            // The target ray points down the space's -z: the negated third column, normalised.
+            const dx = -m[8];
+            const dy = -m[9];
+            const dz = -m[10];
+            const len = Math.hypot(dx, dy, dz) || 1;
+            ray.dir[0] = dx / len;
+            ray.dir[1] = dy / len;
+            ray.dir[2] = dz / len;
+            const gp = src.gamepad;
+            const ev = this.pressed.get(src);
+            const b = s.xr;
+            b.trigger = (gp?.buttons[0]?.pressed ?? false) || (ev?.select ?? false);
+            b.squeeze = (gp?.buttons[1]?.pressed ?? false) || (ev?.squeeze ?? false);
+            b.pinch = this.pinch(frame, src);
+            s.select = b.trigger || b.pinch;
+            s.secondary = b.squeeze;
+            out.push(s);
+        }
+        return out;
+    }
+    /** Index tip to thumb tip under `pinchStart` starts a pinch; over `pinchEnd` ends it. */
+    pinch(frame, src) {
+        const hand = src.hand;
+        const getJointPose = frame.getJointPose;
+        if (!hand || !getJointPose)
+            return false;
+        const index = hand.get('index-finger-tip');
+        const thumb = hand.get('thumb-tip');
+        if (!index || !thumb)
+            return false;
+        const a = getJointPose.call(frame, index, this.referenceSpace);
+        const b = getJointPose.call(frame, thumb, this.referenceSpace);
+        if (!a || !b)
+            return false;
+        const d = dist(a, b);
+        const was = this.pinching.get(src) ?? false;
+        const now = was ? d <= this.pinchEnd : d <= this.pinchStart;
+        if (now !== was)
+            this.pinching.set(src, now);
+        return now;
+    }
+    state(src) {
+        let p = this.pressed.get(src);
+        if (!p) {
+            p = { select: false, squeeze: false };
+            this.pressed.set(src, p);
+        }
+        return p;
+    }
+    onSelectStart = (e) => {
+        this.state(e.inputSource).select = true;
+    };
+    onSelectEnd = (e) => {
+        this.state(e.inputSource).select = false;
+    };
+    onSqueezeStart = (e) => {
+        this.state(e.inputSource).squeeze = true;
+    };
+    onSqueezeEnd = (e) => {
+        this.state(e.inputSource).squeeze = false;
+    };
+    /** A removed source's pointer ends (its key stops appearing) and its state is dropped. */
+    onSourcesChange = (e) => {
+        for (const src of e.removed) {
+            this.samples.delete(src);
+            this.pressed.delete(src);
+            this.pinching.delete(src);
+        }
+    };
+}

package/dist/nav/astar.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A* over a `NavGrid` into a `NavPath`, and string pulling over the result. The open heap,
+ * scores and parents are allocated once per grid (the first query is the warm-up) and reused by
+ * every query after it.
+ */
+import { type NavCell, type NavGrid } from './grid.js';
+import { type NavPath } from './path.js';
+export interface FindPathOptions {
+    /** Allow the eight-neighbour moves (√2 steps). Default: `grid.neighbours === 8`. */
+    diagonal?: boolean;
+    /**
+     * Corner cutting is never allowed: a diagonal step needs both cells beside it walkable, so a
+     * path never squeezes between two diagonal walls. The option exists to say so in a call.
+     */
+    cutCorners?: false;
+    /** Give up (return false) after expanding this many cells. Default: the whole grid. */
+    maxExpand?: number;
+    /**
+     * The most a path may cost (cost-weighted, inclusive). A cell beyond it is never opened, so
+     * an unreachable goal costs the budget's area, not the grid's. Default: no cap.
+     */
+    maxCost?: number;
+    /**
+     * Multiplies the heuristic (weighted A*): > 1 expands fewer cells and may return a path up
+     * to that factor longer than the best; 1 (default) is exact; 0 is Dijkstra.
+     */
+    heuristicWeight?: number;
+}
+/**
+ * Finds the cheapest walkable route from cell `from` to cell `to` and writes its cell centres,
+ * in world XZ, into `out` (`out.cursor` 0, `out.version` = `grid.version`). Returns false, with
+ * `out.length` 0, when either end is unwalkable or outside the grid, when no route exists, or
+ * when `maxExpand` is hit. A step costs its length (1 or √2) times the destination cell's cost;
+ * the octile (or Manhattan) heuristic is admissible for costs ≥ 1. `from === to` is a one-point
+ * path. Allocates nothing after the grid's first query, except to grow `out`.
+ */
+export declare function findPath(grid: NavGrid, from: Readonly<NavCell>, to: Readonly<NavCell>, out: NavPath, opts?: FindPathOptions): boolean;
+/**
+ * String pulling: drops every waypoint that a straight line of walkable cells can skip, in
+ * place, so a staircase of cell centres becomes a few straight legs. On a 4-neighbour grid a
+ * leg never leaves its row or column: only collinear waypoints are dropped, so the path keeps
+ * every corner and makes no diagonal cut. `path.cursor` is reset to 0. Returns the path.
+ * Allocation-free.
+ */
+export declare function smoothPath(grid: NavGrid, path: NavPath): NavPath;

package/dist/nav/astar.js

@@ -0,0 +1,182 @@
+/**
+ * A* over a `NavGrid` into a `NavPath`, and string pulling over the result. The open heap,
+ * scores and parents are allocated once per grid (the first query is the warm-up) and reused by
+ * every query after it.
+ */
+import { hasLineOfWalkable, NEIGHBOUR_X, NEIGHBOUR_Y, stepCost, } from './grid.js';
+import { CellHeap } from './heap.js';
+import { reservePath } from './path.js';
+const SQRT2 = Math.SQRT2;
+const NX = NEIGHBOUR_X;
+const NY = NEIGHBOUR_Y;
+const scratchFor = new WeakMap();
+/** Octile distance with diagonals, Manhattan without: admissible for cell costs ≥ 1. */
+function heuristic(x, y, tx, ty, diagonal) {
+    const dx = x > tx ? x - tx : tx - x;
+    const dy = y > ty ? y - ty : ty - y;
+    if (!diagonal)
+        return dx + dy;
+    return dx > dy ? dx + (SQRT2 - 1) * dy : dy + (SQRT2 - 1) * dx;
+}
+function scratch(grid) {
+    let s = scratchFor.get(grid);
+    if (!s) {
+        const n = grid.size;
+        const f = new Float64Array(n);
+        s = {
+            g: new Float64Array(n),
+            f,
+            parent: new Int32Array(n),
+            seen: new Uint32Array(n),
+            closed: new Uint32Array(n),
+            heap: new CellHeap(n, f),
+            stamp: 0,
+        };
+        scratchFor.set(grid, s);
+    }
+    return s;
+}
+/**
+ * Finds the cheapest walkable route from cell `from` to cell `to` and writes its cell centres,
+ * in world XZ, into `out` (`out.cursor` 0, `out.version` = `grid.version`). Returns false, with
+ * `out.length` 0, when either end is unwalkable or outside the grid, when no route exists, or
+ * when `maxExpand` is hit. A step costs its length (1 or √2) times the destination cell's cost;
+ * the octile (or Manhattan) heuristic is admissible for costs ≥ 1. `from === to` is a one-point
+ * path. Allocates nothing after the grid's first query, except to grow `out`.
+ */
+export function findPath(grid, from, to, out, opts = {}) {
+    out.length = 0;
+    out.cursor = 0;
+    out.version = grid.version;
+    if (!grid.isWalkable(from.x, from.y) || !grid.isWalkable(to.x, to.y))
+        return false;
+    const diagonal = opts.diagonal ?? grid.neighbours === 8;
+    const maxExpand = opts.maxExpand ?? grid.size;
+    const maxCost = opts.maxCost ?? Infinity;
+    const weight = opts.heuristicWeight ?? 1;
+    const width = grid.width;
+    const s = scratch(grid);
+    const { g, f, parent, seen, closed, heap } = s;
+    // Stamps wrap at 2^32; a wrap to 0 would alias a stale entry, so skip 0.
+    s.stamp = (s.stamp + 1) >>> 0 || 1;
+    const stamp = s.stamp;
+    heap.clear();
+    const tx = to.x;
+    const ty = to.y;
+    const start = from.y * width + from.x;
+    const goal = ty * width + tx;
+    g[start] = 0;
+    f[start] = weight * heuristic(from.x, from.y, tx, ty, diagonal);
+    parent[start] = -1;
+    seen[start] = stamp;
+    heap.pushOrDecrease(start);
+    const dirs = diagonal ? 8 : 4;
+    let expanded = 0;
+    let found = false;
+    while (heap.size > 0) {
+        const cur = heap.pop();
+        if (cur === goal) {
+            found = true;
+            break;
+        }
+        if (++expanded > maxExpand)
+            break;
+        closed[cur] = stamp;
+        const cx = cur % width;
+        const cy = (cur - cx) / width;
+        const gc = g[cur];
+        for (let d = 0; d < dirs; d++) {
+            const step = stepCost(grid, cur, cx, cy, d);
+            if (step === Infinity)
+                continue;
+            const nx = cx + NX[d];
+            const ny = cy + NY[d];
+            const ni = ny * width + nx;
+            if (closed[ni] === stamp)
+                continue;
+            const ng = gc + step;
+            if (ng > maxCost)
+                continue;
+            if (seen[ni] === stamp && ng >= g[ni])
+                continue;
+            seen[ni] = stamp;
+            g[ni] = ng;
+            f[ni] = ng + weight * heuristic(nx, ny, tx, ty, diagonal);
+            parent[ni] = cur;
+            heap.pushOrDecrease(ni);
+        }
+    }
+    if (!found)
+        return false;
+    let count = 0;
+    for (let i = goal; i >= 0; i = parent[i])
+        count++;
+    reservePath(out, count);
+    const p = out.points;
+    const cs = grid.cellSize;
+    const ox = grid.origin.x;
+    const oz = grid.origin.z;
+    let k = count - 1;
+    for (let i = goal; i >= 0; i = parent[i], k--) {
+        const x = i % width;
+        const y = (i - x) / width;
+        p[k * 2] = ox + (x + 0.5) * cs;
+        p[k * 2 + 1] = oz + (y + 0.5) * cs;
+    }
+    out.length = count;
+    return true;
+}
+const sa = { x: 0, y: 0 };
+const sb = { x: 0, y: 0 };
+/**
+ * String pulling: drops every waypoint that a straight line of walkable cells can skip, in
+ * place, so a staircase of cell centres becomes a few straight legs. On a 4-neighbour grid a
+ * leg never leaves its row or column: only collinear waypoints are dropped, so the path keeps
+ * every corner and makes no diagonal cut. `path.cursor` is reset to 0. Returns the path.
+ * Allocation-free.
+ */
+export function smoothPath(grid, path) {
+    const n = path.length;
+    path.cursor = 0;
+    if (n < 3)
+        return path;
+    const p = path.points;
+    let write = 1;
+    if (grid.neighbours === 4) {
+        for (let i = 1; i < n - 1; i++) {
+            const ax = p[i * 2] - p[write * 2 - 2];
+            const az = p[i * 2 + 1] - p[write * 2 - 1];
+            const bx = p[i * 2 + 2] - p[i * 2];
+            const bz = p[i * 2 + 3] - p[i * 2 + 1];
+            // Keep the waypoint when the run bends (the cross product of the two legs is not zero).
+            if (ax * bz - az * bx !== 0) {
+                p[write * 2] = p[i * 2];
+                p[write * 2 + 1] = p[i * 2 + 1];
+                write++;
+            }
+        }
+        p[write * 2] = p[n * 2 - 2];
+        p[write * 2 + 1] = p[n * 2 - 1];
+        path.length = write + 1;
+        return path;
+    }
+    let anchor = 0;
+    while (anchor < n - 1) {
+        grid.toCell(p[anchor * 2], p[anchor * 2 + 1], sa);
+        // The furthest waypoint visible from the anchor; the next one is always reachable.
+        let far = anchor + 1;
+        for (let j = n - 1; j > anchor + 1; j--) {
+            grid.toCell(p[j * 2], p[j * 2 + 1], sb);
+            if (hasLineOfWalkable(grid, sa.x, sa.y, sb.x, sb.y)) {
+                far = j;
+                break;
+            }
+        }
+        p[write * 2] = p[far * 2];
+        p[write * 2 + 1] = p[far * 2 + 1];
+        write++;
+        anchor = far;
+    }
+    path.length = write;
+    return path;
+}

package/dist/nav/corridor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A corridor: the polygon list a mesh path crossed, kept beside a moving agent. `advance(x, z)`
+ * drops the polygons the agent has left and string-pulls the rest to the target, so each frame
+ * costs one funnel over what remains, never a new search. `valid(mesh)` says whether the mesh
+ * changed under it (a carve, an obstacle) and a replan is due. Allocated once for
+ * `maxWaypoints`.
+ */
+import { type NavPath3 } from './mesh/mesh-path.js';
+import type { NavMesh, NavPoint3 } from './mesh/navmesh.js';
+export interface Corridor {
+    /** The remaining polygons, `offset .. offset + count` into `polys`. */
+    readonly polys: Int32Array;
+    readonly offset: number;
+    readonly count: number;
+    /** The target the corridor leads to (the path's last point). */
+    readonly target: NavPoint3;
+    /** The mesh version the corridor was set from. */
+    readonly version: number;
+    /** The pulled string from the last `advance`: the agent, every corner, the target. */
+    readonly path: NavPath3;
+    /** Takes a path (its `polys` corridor and last point); an empty path clears the corridor. */
+    set(path: Readonly<NavPath3>): void;
+    /** Empties the corridor. */
+    clear(): void;
+    /** The polygon the agent stands in, or -1 when the corridor is empty. */
+    current(): number;
+    /**
+     * Moves the corridor's head to the polygon holding `(x, z)` (searching forward through the
+     * remaining polygons, the first few of them) and writes the next corner to steer to into
+     * `out`. Returns false, leaving `out` untouched, when the corridor is empty.
+     */
+    advance(x: number, z: number, out: NavPoint3): boolean;
+    /**
+     * True while the mesh is still at the corridor's version (a carve or an obstacle bumps it) and
+     * no remaining polygon after the agent's own is an obstacle.
+     */
+    valid(mesh: NavMesh): boolean;
+}
+/** A corridor over `mesh` with room for `maxWaypoints` polygons. */
+export declare function createCorridor(mesh: NavMesh, maxWaypoints?: number): Corridor;

package/dist/nav/corridor.js

@@ -0,0 +1,95 @@
+/**
+ * A corridor: the polygon list a mesh path crossed, kept beside a moving agent. `advance(x, z)`
+ * drops the polygons the agent has left and string-pulls the rest to the target, so each frame
+ * costs one funnel over what remains, never a new search. `valid(mesh)` says whether the mesh
+ * changed under it (a carve, an obstacle) and a replan is due. Allocated once for
+ * `maxWaypoints`.
+ */
+import { OBSTACLE_AREA } from './mesh/areas.js';
+import { createNavPath3, pullString, reservePolys3 } from './mesh/mesh-path.js';
+const from = { x: 0, y: 0, z: 0 };
+/** A corridor over `mesh` with room for `maxWaypoints` polygons. */
+export function createCorridor(mesh, maxWaypoints = 64) {
+    const polys = new Int32Array(Math.max(1, maxWaypoints));
+    const path = createNavPath3(Math.max(2, maxWaypoints));
+    let offset = 0;
+    let count = 0;
+    let version = -1;
+    const target = { x: 0, y: 0, z: 0 };
+    const corridor = {
+        polys,
+        get offset() {
+            return offset;
+        },
+        get count() {
+            return count;
+        },
+        target,
+        get version() {
+            return version;
+        },
+        path,
+        set(p) {
+            version = p.version;
+            offset = 0;
+            count = Math.min(p.polyCount, polys.length);
+            polys.set(p.polys.subarray(0, count));
+            if (p.length > 0) {
+                target.x = p.points[(p.length - 1) * 3];
+                target.y = p.points[(p.length - 1) * 3 + 1];
+                target.z = p.points[(p.length - 1) * 3 + 2];
+            }
+            else {
+                count = 0;
+            }
+            reservePolys3(path, count);
+            path.length = 0;
+            path.polyCount = 0;
+        },
+        clear() {
+            count = 0;
+            offset = 0;
+            path.length = 0;
+        },
+        current() {
+            return count > 0 ? polys[offset] : -1;
+        },
+        advance(x, z, out) {
+            if (count === 0)
+                return false;
+            // Drop every polygon the agent has passed: look ahead a few, take the furthest that holds it.
+            const look = Math.min(count, 4);
+            let at = -1;
+            for (let i = 0; i < look; i++) {
+                if (mesh.containsXZ(polys[offset + i], x, z))
+                    at = i;
+            }
+            if (at > 0) {
+                offset += at;
+                count -= at;
+            }
+            from.x = x;
+            from.z = z;
+            from.y = mesh.polyHeight(polys[offset], x, z);
+            pullString(mesh, polys, offset, count, from, target, path);
+            // The first corner after the agent's own position.
+            const k = path.length > 1 ? 1 : 0;
+            out.x = path.points[k * 3];
+            out.y = path.points[k * 3 + 1];
+            out.z = path.points[k * 3 + 2];
+            return true;
+        },
+        valid(m) {
+            if (count === 0 || m.version !== version)
+                return false;
+            // The polygon the agent stands in is exempt: an obstacle stamped under it must be walked
+            // out of, and a replan from inside it would find the same corridor again.
+            for (let i = 1; i < count; i++) {
+                if (m.area[polys[offset + i]] === OBSTACLE_AREA)
+                    return false;
+            }
+            return true;
+        },
+    };
+    return corridor;
+}

package/dist/nav/crowd.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `Crowd`: local avoidance for many agents on the XZ plane by ORCA (the RVO2 method). Each tick,
+ * every agent picks the velocity nearest its preferred one that keeps it clear of its neighbours
+ * (and of the obstacles of an `ObstacleSet`, as static lines) for `timeHorizon` seconds, then
+ * moves by it. Neighbours come from a hashed uniform grid. Attached to a `NavMesh`, agents walk
+ * corridors to targets (`setTarget`, searched through a `PathQueue` or synchronously), their
+ * preferred velocity steers along the pulled string, and after each move they are clamped onto
+ * the mesh with `y` from its height. Everything is allocated at creation (and at `attach`) for
+ * `maxAgents`; `update` allocates nothing.
+ */
+import { type Corridor } from './corridor.js';
+import type { NavMesh } from './mesh/navmesh.js';
+import type { ObstacleSet } from './obstacles.js';
+import type { PathQueue } from './query-queue.js';
+export interface CrowdOptions {
+    maxAgents: number;
+    /** Neighbours considered per agent, nearest first. Default 10. */
+    maxNeighbors?: number;
+    /** Seconds ahead an agent keeps clear of the others. Default 2. */
+    timeHorizon?: number;
+    /** Agents farther apart than this ignore each other (grid cell size). Default 4. */
+    neighborDist?: number;
+}
+export interface CrowdAgentOptions {
+    x: number;
+    z: number;
+    radius: number;
+    maxSpeed: number;
+    /** Where it wants to go, world units per second. Default still. */
+    prefVelocity?: {
+        x: number;
+        z: number;
+    };
+}
+export interface CrowdAgent {
+    /** False for an empty slot. */
+    active: boolean;
+    x: number;
+    z: number;
+    /** The velocity the last `update` chose. */
+    vx: number;
+    vz: number;
+    radius: number;
+    maxSpeed: number;
+    prefX: number;
+    prefZ: number;
+    /** On a mesh: the surface height under the agent (0 otherwise). */
+    y: number;
+    /** On a mesh: the polygon the agent stands in, -1 off the mesh or unattached. */
+    poly: number;
+    /** On a mesh: the corridor to the agent's target (null unattached). */
+    corridor: Corridor | null;
+    /** True once the agent came within `arriveRadius` of its target; false when no target. */
+    targetReached: boolean;
+}
+export interface CrowdAttachOptions {
+    /** Searches go through this queue when given, else `findMeshPath` runs inside `setTarget`. */
+    queue?: PathQueue;
+    /** Corridor capacity per agent. Default 64. */
+    maxWaypoints?: number;
+    /** An agent this close to its target has reached it. Default: its radius. */
+    arriveRadius?: number;
+    /** `steer.arrive` slows an agent inside this distance of its target. Default 1. */
+    slowRadius?: number;
+}
+export interface Crowd {
+    /** One slot per index up to `maxAgents`; check `active`. The array and its objects never change identity. */
+    readonly agents: readonly CrowdAgent[];
+    /** Adds an agent and returns its index, or -1 when the crowd is full. */
+    add(agent: CrowdAgentOptions): number;
+    remove(index: number): void;
+    setPrefVelocity(index: number, x: number, z: number): void;
+    setPosition(index: number, x: number, z: number): void;
+    /** Chooses every agent's velocity, then moves them by `dt` seconds. */
+    update(dt: number): void;
+    /**
+     * Keeps the agents on `mesh`: every agent gets a corridor, `setTarget` plans through it, and
+     * each `update` steers along it and clamps positions (and `y`) onto the mesh. Allocates per
+     * agent; call once at setup.
+     */
+    attach(mesh: NavMesh, opts?: CrowdAttachOptions): void;
+    /**
+     * Sends an attached agent to `(x, y, z)`: through the queue when attached with one (the agent
+     * waits until its path arrives), else by a synchronous search. A corridor that becomes invalid
+     * (the mesh version changed) replans the same way. `targetReached` resets to false.
+     */
+    setTarget(index: number, x: number, y: number, z: number): void;
+    /** Keeps agents clear of the set's obstacles (discs and boxes as static ORCA lines); null detaches. */
+    obstacles(set: ObstacleSet | null): void;
+    /** Corridor replans since creation (a changed mesh under a corridor, or a target set). */
+    readonly replans: number;
+}
+/** A crowd with room for `maxAgents`. */
+export declare function createCrowd(opts: CrowdOptions): Crowd;