@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/nav/mesh/flow3.js

@@ -0,0 +1,229 @@
+/**
+ * A flow field over a `NavMesh`: one Dijkstra from the goal polygons outward (centre to portal
+ * midpoint to centre, from the goal point itself in a goal polygon, priced by area) gives every
+ * polygon a distance and the neighbour it flows to, so any number of agents read a direction in
+ * O(1) with no search of their own.
+ * `direction3` points from the query to the portal midpoint into the next polygon (or to the
+ * nearest goal inside a goal polygon). `update()` rebuilds on a mesh version change.
+ * Allocated once per field; `update` allocates nothing.
+ */
+import { CellHeap } from '../heap.js';
+import { areaAllowed } from './mesh-path.js';
+const snapped = { x: 0, y: 0, z: 0 };
+/** Builds a flow field toward `goals` (points on the mesh) and keeps it current. */
+export function createFlowField3(mesh, goals, opts = {}) {
+    const n = Math.max(1, mesh.polyCount);
+    const distances = new Float64Array(n);
+    const next = new Int32Array(n);
+    const portal = new Int32Array(n);
+    const heap = new CellHeap(n, distances);
+    const closed = new Uint8Array(n);
+    const goalPoly = new Int32Array(goals.length);
+    const goalX = new Float64Array(goals.length);
+    const goalY = new Float64Array(goals.length);
+    const goalZ = new Float64Array(goals.length);
+    const centreX = new Float64Array(n);
+    const centreY = new Float64Array(n);
+    const centreZ = new Float64Array(n);
+    /** The exit portal's midpoint per polygon (its centre at a goal). */
+    const exitX = new Float64Array(n);
+    const exitY = new Float64Array(n);
+    const exitZ = new Float64Array(n);
+    const areaCost = opts.areaCost;
+    const areaMask = opts.areaMask;
+    const snap = opts.snapRadius ?? Number.POSITIVE_INFINITY;
+    let version = -1;
+    let reached = 0;
+    const nvp = mesh.maxVertsPerPoly;
+    const build = () => {
+        version = mesh.version;
+        distances.fill(Number.POSITIVE_INFINITY);
+        next.fill(-1);
+        portal.fill(-1);
+        closed.fill(0);
+        heap.clear();
+        reached = 0;
+        for (let p = 0; p < mesh.polyCount; p++) {
+            mesh.polyCenter(p, snapped);
+            centreX[p] = snapped.x;
+            centreY[p] = snapped.y;
+            centreZ[p] = snapped.z;
+        }
+        for (let i = 0; i < goals.length; i++) {
+            const g = goals[i];
+            const p = mesh.findNearestPoly(g.x, g.y, g.z, snapped, snap);
+            goalPoly[i] = p;
+            goalX[i] = snapped.x;
+            goalY[i] = snapped.y;
+            goalZ[i] = snapped.z;
+            if (p < 0 || !areaAllowed(mesh.area[p], areaCost, areaMask))
+                continue;
+            if (distances[p] !== 0) {
+                // A goal polygon's legs are measured from the goal itself, not its centre.
+                centreX[p] = snapped.x;
+                centreY[p] = snapped.y;
+                centreZ[p] = snapped.z;
+            }
+            distances[p] = 0;
+            heap.pushOrDecrease(p);
+        }
+        const verts = mesh.verts;
+        const polys = mesh.polys;
+        const adjacency = mesh.adjacency;
+        while (heap.size > 0) {
+            const cur = heap.pop();
+            closed[cur] = 1;
+            reached++;
+            const dc = distances[cur];
+            const cx = centreX[cur];
+            const cy = centreY[cur];
+            const cz = centreZ[cur];
+            const count = mesh.polyVertexCount(cur);
+            for (let e = 0; e < count; e++) {
+                const nb = adjacency[cur * nvp + e];
+                if (nb < 0 || closed[nb] === 1)
+                    continue;
+                const na = mesh.area[nb];
+                if (!areaAllowed(na, areaCost, areaMask))
+                    continue;
+                const a = polys[cur * nvp + e] * 3;
+                const b = polys[cur * nvp + (e + 1 === count ? 0 : e + 1)] * 3;
+                const mx = (verts[a] + verts[b]) * 0.5;
+                const my = (verts[a + 1] + verts[b + 1]) * 0.5;
+                const mz = (verts[a + 2] + verts[b + 2]) * 0.5;
+                const mul = areaCost === undefined ? 1 : areaCost[na];
+                // Into `cur` from `nb`: the leg from nb's centre to the portal is priced by nb's area, the
+                // leg from the portal to cur's centre by cur's.
+                const curMul = areaCost === undefined ? 1 : areaCost[mesh.area[cur]];
+                const d = dc +
+                    dist3(cx, cy, cz, mx, my, mz) * curMul +
+                    dist3(mx, my, mz, centreX[nb], centreY[nb], centreZ[nb]) * mul;
+                if (d >= distances[nb])
+                    continue;
+                distances[nb] = d;
+                next[nb] = cur;
+                exitX[nb] = mx;
+                exitY[nb] = my;
+                exitZ[nb] = mz;
+                // The edge of `nb` shared with `cur`.
+                const nc = mesh.polyVertexCount(nb);
+                let pe = 0;
+                while (pe < nc && adjacency[nb * nvp + pe] !== cur)
+                    pe++;
+                portal[nb] = pe < nc ? pe : -1;
+                heap.pushOrDecrease(nb);
+            }
+        }
+    };
+    build();
+    /**
+     * A point on the portal out of `p` lies in `next[p]` too; the field answers for the polygon
+     * furthest downstream that holds it, so a walker standing on a portal is never sent back to it.
+     */
+    const downstream = (p, x, z) => {
+        let cur = p;
+        for (let nb = next[cur]; nb >= 0 && mesh.containsXZ(nb, x, z); nb = next[cur])
+            cur = nb;
+        return cur;
+    };
+    return {
+        mesh,
+        distances,
+        next,
+        portal,
+        get version() {
+            return version;
+        },
+        get stale() {
+            return version !== mesh.version;
+        },
+        get reached() {
+            return reached;
+        },
+        update(force = false) {
+            if (!force && version === mesh.version)
+                return false;
+            build();
+            return true;
+        },
+        direction3(x, y, z, out) {
+            out.x = 0;
+            out.y = 0;
+            out.z = 0;
+            let p = mesh.findPolyAt(x, y, z);
+            if (p < 0 || distances[p] === Number.POSITIVE_INFINITY)
+                return p;
+            p = downstream(p, x, z);
+            let tx;
+            let ty;
+            let tz;
+            const nb = next[p];
+            if (nb < 0) {
+                // A goal polygon: head for the nearest goal inside it.
+                let best = -1;
+                let bestD = Number.POSITIVE_INFINITY;
+                for (let i = 0; i < goalPoly.length; i++) {
+                    if (goalPoly[i] !== p)
+                        continue;
+                    const d = dist3(x, y, z, goalX[i], goalY[i], goalZ[i]);
+                    if (d < bestD) {
+                        bestD = d;
+                        best = i;
+                    }
+                }
+                if (best < 0)
+                    return p;
+                tx = goalX[best];
+                ty = goalY[best];
+                tz = goalZ[best];
+            }
+            else {
+                tx = exitX[p];
+                ty = exitY[p];
+                tz = exitZ[p];
+            }
+            const dx = tx - x;
+            const dy = ty - y;
+            const dz = tz - z;
+            const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            if (len === 0)
+                return p;
+            out.x = dx / len;
+            out.y = dy / len;
+            out.z = dz / len;
+            return p;
+        },
+        distanceAt(x, y, z) {
+            let p = mesh.findPolyAt(x, y, z);
+            if (p < 0 || distances[p] === Number.POSITIVE_INFINITY)
+                return Number.POSITIVE_INFINITY;
+            p = downstream(p, x, z);
+            const mul = areaCost === undefined ? 1 : areaCost[mesh.area[p]];
+            if (next[p] < 0) {
+                let best = Number.POSITIVE_INFINITY;
+                for (let i = 0; i < goalPoly.length; i++) {
+                    if (goalPoly[i] !== p)
+                        continue;
+                    const d = dist3(x, y, z, goalX[i], goalY[i], goalZ[i]);
+                    if (d < best)
+                        best = d;
+                }
+                return best * mul;
+            }
+            // The polygon's distance is measured from its centre through its exit portal: swap the
+            // centre leg for the query's own.
+            const ex = exitX[p];
+            const ey = exitY[p];
+            const ez = exitZ[p];
+            return (distances[p] -
+                dist3(centreX[p], centreY[p], centreZ[p], ex, ey, ez) * mul +
+                dist3(x, y, z, ex, ey, ez) * mul);
+        },
+    };
+}
+function dist3(ax, ay, az, bx, by, bz) {
+    const dx = bx - ax;
+    const dy = by - ay;
+    const dz = bz - az;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}

package/dist/nav/mesh/links.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Off-mesh links: a jump, ladder or teleport between two points of the navmesh that the
+ * pathfinder may take as one edge. Links live on the mesh; adding or removing one rebuilds the
+ * per-polygon link index (edit-time, allocates) and bumps `mesh.version`.
+ */
+import type { NavMesh, NavPoint3 } from './navmesh.js';
+export interface OffMeshLinkOptions {
+    from: NavPoint3;
+    to: NavPoint3;
+    /** How far from `from` (and `to`, when bidirectional) an agent may be to take the link. */
+    radius: number;
+    bidirectional?: boolean;
+    /** Traversal cost in world units; default the straight distance from `from` to `to`. */
+    cost?: number;
+    /** Anything the game wants back from `path.links`; not serialised. */
+    userData?: unknown;
+}
+export interface OffMeshLink {
+    readonly id: number;
+    readonly from: NavPoint3;
+    readonly to: NavPoint3;
+    readonly radius: number;
+    readonly bidirectional: boolean;
+    /** The cost given, or `undefined` for the straight distance. */
+    readonly cost: number | undefined;
+    readonly userData: unknown;
+    /** The polygons the ends landed on (-1 when an end is off the mesh; such a link is never taken). */
+    readonly fromPoly: number;
+    readonly toPoly: number;
+}
+/** Adds a link and returns its id (0 is never an id). An end farther than `radius` from the mesh never connects. */
+export declare function addOffMeshLink(mesh: NavMesh, opts: OffMeshLinkOptions): number;
+/** Removes the link with `id`; false when there is none. */
+export declare function removeOffMeshLink(mesh: NavMesh, id: number): boolean;
+/** The link with `id`, or `undefined`. */
+export declare function getOffMeshLink(mesh: NavMesh, id: number): OffMeshLink | undefined;
+/** Rebuilds `mesh.linkStart` / `mesh.linkItems`: per polygon the `link * 2 + end` records that start there. */
+export declare function rebuildLinkIndex(mesh: NavMesh): void;

package/dist/nav/mesh/links.js

@@ -0,0 +1,72 @@
+/** Adds a link and returns its id (0 is never an id). An end farther than `radius` from the mesh never connects. */
+export function addOffMeshLink(mesh, opts) {
+    const id = mesh.nextLinkId++;
+    const tmp = { x: 0, y: 0, z: 0 };
+    const fromPoly = mesh.findNearestPoly(opts.from.x, opts.from.y, opts.from.z, tmp, opts.radius);
+    const toPoly = mesh.findNearestPoly(opts.to.x, opts.to.y, opts.to.z, tmp, opts.radius);
+    const link = {
+        id,
+        from: { x: opts.from.x, y: opts.from.y, z: opts.from.z },
+        to: { x: opts.to.x, y: opts.to.y, z: opts.to.z },
+        radius: opts.radius,
+        bidirectional: opts.bidirectional ?? false,
+        cost: opts.cost,
+        userData: opts.userData,
+        fromPoly,
+        toPoly,
+    };
+    mesh.links.push(link);
+    rebuildLinkIndex(mesh);
+    return id;
+}
+/** Removes the link with `id`; false when there is none. */
+export function removeOffMeshLink(mesh, id) {
+    const i = mesh.links.findIndex((l) => l !== null && l.id === id);
+    if (i < 0)
+        return false;
+    mesh.links[i] = null;
+    // Trim trailing holes so the array does not grow without bound.
+    while (mesh.links.length > 0 && mesh.links[mesh.links.length - 1] === null)
+        mesh.links.pop();
+    rebuildLinkIndex(mesh);
+    return true;
+}
+/** The link with `id`, or `undefined`. */
+export function getOffMeshLink(mesh, id) {
+    for (const l of mesh.links)
+        if (l !== null && l.id === id)
+            return l;
+    return undefined;
+}
+/** Rebuilds `mesh.linkStart` / `mesh.linkItems`: per polygon the `link * 2 + end` records that start there. */
+export function rebuildLinkIndex(mesh) {
+    const start = new Int32Array(mesh.polyCount + 1);
+    let total = 0;
+    for (const l of mesh.links) {
+        if (l === null)
+            continue;
+        if (l.fromPoly >= 0 && l.toPoly >= 0) {
+            start[l.fromPoly + 1]++;
+            total++;
+            if (l.bidirectional) {
+                start[l.toPoly + 1]++;
+                total++;
+            }
+        }
+    }
+    for (let p = 0; p < mesh.polyCount; p++)
+        start[p + 1] += start[p];
+    const items = new Int32Array(Math.max(1, total));
+    const fill = new Int32Array(mesh.polyCount);
+    for (let i = 0; i < mesh.links.length; i++) {
+        const l = mesh.links[i];
+        if (l === null || l.fromPoly < 0 || l.toPoly < 0)
+            continue;
+        items[start[l.fromPoly] + fill[l.fromPoly]++] = i * 2;
+        if (l.bidirectional)
+            items[start[l.toPoly] + fill[l.toPoly]++] = i * 2 + 1;
+    }
+    mesh.linkStart = start;
+    mesh.linkItems = items;
+    mesh.version++;
+}

package/dist/nav/mesh/mesh-path.d.ts

@@ -0,0 +1,152 @@
+import type { FollowResult } from '../path.js';
+import type { NavMesh, NavPoint3 } from './navmesh.js';
+export interface NavPathLink {
+    /** The waypoint the link starts at; waypoint `index + 1` is where it lands. */
+    index: number;
+    /** The off-mesh link's id. */
+    id: number;
+}
+export interface NavPath3 {
+    /** Waypoints as world `x, y, z` triples; `length * 3` floats are valid. Grows in place as needed. */
+    points: Float32Array;
+    /** Waypoints in the path (0 when no path). */
+    length: number;
+    /** Index of the waypoint `followPath3` is heading for. */
+    cursor: number;
+    /** `mesh.version` when the path was found. */
+    version: number;
+    /** Off-mesh links the path takes, in order; `linkCount` entries are valid (records are reused). */
+    links: NavPathLink[];
+    linkCount: number;
+    /** The polygon corridor the path crosses, start to goal; `polyCount` entries are valid. */
+    polys: Int32Array;
+    polyCount: number;
+    /**
+     * The search's cost of the route (ws/nav-5): the priced length of its legs between portal
+     * midpoints (each × its polygon's `areaCost`) plus every link's cost, 0 when both ends share
+     * a polygon or there is no path. It is what `reachable(mesh, …)` budgets against, not the
+     * length of the pulled string (`pathDistance3`), which is never longer.
+     */
+    cost: number;
+}
+export interface FindMeshPathOptions extends AreaQueryOptions {
+    /** Give up (return false) after expanding this many polygons. Default: the whole mesh. */
+    maxExpand?: number;
+    /** How far `from` and `to` may be from the mesh to snap onto it. Default: any distance. */
+    snapRadius?: number;
+    /** False keeps the portal midpoints instead of pulling the string taut (for debugging). Default true. */
+    stringPull?: boolean;
+    /**
+     * Scales the straight-line heuristic (ws/nav-5). Default 1; 0 makes the search a Dijkstra,
+     * which settles every polygon at the same cost `reachable(mesh, …)` gives it (the heuristic
+     * can settle a polygon through a costlier portal when a nearer one points away from the goal).
+     */
+    heuristicWeight?: number;
+}
+/** A path with room for `capacity` waypoints (grows on demand). */
+export declare function createNavPath3(capacity?: number): NavPath3;
+/** Makes room for `count` corridor polygons (1.5× growth), keeping the data already there. */
+export declare function reservePolys3(path: NavPath3, count: number): void;
+/** Makes room for `count` waypoints (1.5× growth), keeping the floats already there. */
+export declare function reservePath3(path: NavPath3, count: number): void;
+/** Empties the path (`length` 0, `cursor` 0, no links, no corridor); the buffers stay. */
+export declare function clearPath3(path: NavPath3): void;
+/** Writes waypoint `i` into `out`. */
+export declare function pathPoint3(path: NavPath3, i: number, out: NavPoint3): NavPoint3;
+/** The sum of the segment lengths, world units. */
+export declare function pathDistance3(path: NavPath3): number;
+/** How a step into a polygon is priced and whether it is allowed: the area options every mesh query shares. */
+export interface AreaQueryOptions {
+    /**
+     * A cost multiplier per area byte (256 entries, see `createAreaCosts`): a leg across a
+     * polygon costs its length × `areaCost[area]`; `Infinity` excludes the area. Default: 1
+     * everywhere. Area 255 (obstacles) is always excluded.
+     */
+    areaCost?: Float32Array;
+    /** Per area byte (256 entries, see `createAreaMask`): 0 excludes the area. Default: all allowed. */
+    areaMask?: Uint8Array;
+}
+/** Whether a polygon of area `a` may be entered under the options. */
+export declare function areaAllowed(a: number, cost?: Float32Array, mask?: Uint8Array): boolean;
+export type MeshSearchState = 'idle' | 'running' | 'found' | 'failed';
+/**
+ * A resumable polygon A*: `begin` snaps the ends and seeds the open heap, `step(maxPops)`
+ * expands at most that many polygons and `finish` backtracks the corridor and string-pulls it
+ * into a path. `findMeshPath` runs one to the end; a path queue slices one across frames. Every
+ * array is allocated once per search (sized to the mesh) and reused.
+ */
+export declare class MeshSearch {
+    readonly mesh: NavMesh;
+    state: MeshSearchState;
+    /** The mesh version `begin` saw; a differing `mesh.version` means the search is stale. */
+    version: number;
+    private readonly g;
+    private readonly f;
+    private readonly parent;
+    /** How the polygon was entered: the parent's edge index, or `-(link * 2 + end) - 1` for a link. */
+    private readonly via;
+    /** Where the search stands inside each polygon (portal midpoints, link landings). */
+    private readonly px;
+    private readonly py;
+    private readonly pz;
+    private readonly seen;
+    private readonly closed;
+    private readonly heap;
+    private stamp;
+    /** The corridor, start to end, after backtracking. */
+    private readonly corridor;
+    private readonly corridorVia;
+    /** Funnel portals, `lx, ly, lz, rx, ry, rz` per step. */
+    private readonly portals;
+    private readonly start;
+    private readonly end;
+    /** The polygons the ends snapped to (-1 before `begin`). */
+    startPoly: number;
+    endPoly: number;
+    private expanded;
+    private maxExpand;
+    private pull;
+    private hw;
+    private areaCost;
+    private areaMask;
+    constructor(mesh: NavMesh);
+    /**
+     * Snaps `from` and `to` onto the mesh and seeds the search. False (state `'failed'`) when
+     * either end is off the mesh (beyond `snapRadius`) or the goal polygon's area is excluded.
+     */
+    begin(from: Readonly<NavPoint3>, to: Readonly<NavPoint3>, opts?: FindMeshPathOptions): boolean;
+    /** The funnel portal buffer (room for every polygon plus two), for `pullString`. */
+    portalsScratch(): Float64Array;
+    /** Pops up to `maxPops` polygons off the open heap; returns how many it popped. */
+    step(maxPops: number): number;
+    /**
+     * After `'found'`: backtracks the corridor into `out.polys` and string-pulls it (each stretch
+     * between links through its portals) into `out.points`. False, with `out` empty, unless the
+     * search found the goal.
+     */
+    finish(out: NavPath3): boolean;
+}
+/**
+ * Finds the shortest route over the mesh from `from` to `to` (both snapped to the nearest
+ * polygon) and writes its waypoints into `out`, the first being the snapped start and the last
+ * the snapped goal, and its polygon corridor into `out.polys`. Off-mesh links are taken when
+ * they are cheaper and listed in `out.links`. Steps are priced by `areaCost` and filtered by
+ * `areaMask`; area 255 (an obstacle) is never entered. Returns false, with `out` empty, when
+ * either end is off the mesh (beyond `snapRadius`), the goal is unreachable or excluded, or
+ * `maxExpand` ran out.
+ */
+export declare function findMeshPath(mesh: NavMesh, from: Readonly<NavPoint3>, to: Readonly<NavPoint3>, out: NavPath3, opts?: FindMeshPathOptions): boolean;
+/**
+ * String-pulls a corridor of `count` polygons (`polys[offset ..]`, each adjacent to the next)
+ * from `from` (inside the first) to `to` (inside the last) into `out`: the start, every
+ * corner, the target. A pair without a shared edge (an off-mesh link) is bridged through the
+ * next polygon's centre. Allocation-free after the mesh's first query; used by corridors.
+ */
+export declare function pullString(mesh: NavMesh, polys: Int32Array, offset: number, count: number, from: Readonly<NavPoint3>, to: Readonly<NavPoint3>, out: NavPath3): void;
+/**
+ * Heads for `path.points[path.cursor]` at `speed`: the cursor advances when `position` is within
+ * `arriveRadius` (measured in XZ) of its waypoint, and the last waypoint reached is `'arrived'`
+ * with a zero velocity. `outVelocity` is the desired velocity in 3D (world units per second);
+ * a walker usually keeps its own y and snaps it to `mesh.height(x, z)`.
+ */
+export declare function followPath3(path: NavPath3, position: Readonly<NavPoint3>, speed: number, arriveRadius: number, outVelocity: NavPoint3): FollowResult;