@driftengine/nav 4.0.0

package/dist/polymesh.js

@@ -0,0 +1,234 @@
+const NO_VERTEX = -1;
+export const NO_NEIGHBOUR = -1;
+export function polyVertexCount(mesh, poly) {
+    let count = 0;
+    for (let at = 0; at < mesh.maxVertsPerPoly; at += 1) {
+        if (mesh.polys[poly * mesh.maxVertsPerPoly + at] !== NO_VERTEX)
+            count += 1;
+    }
+    return count;
+}
+export function polyNeighbour(mesh, poly, edge) {
+    return mesh.neighbours[poly * mesh.maxVertsPerPoly + edge] ?? NO_NEIGHBOUR;
+}
+/** The shoelace area, which is positive for the winding this builds and zero for a degenerate. */
+export function polyArea(mesh, poly) {
+    const count = polyVertexCount(mesh, poly);
+    let twice = 0;
+    for (let at = 0; at < count; at += 1) {
+        const a = mesh.polys[poly * mesh.maxVertsPerPoly + at];
+        const b = mesh.polys[poly * mesh.maxVertsPerPoly + ((at + 1) % count)];
+        twice +=
+            mesh.vertices[a * 2] * mesh.vertices[b * 2 + 1] -
+                mesh.vertices[b * 2] * mesh.vertices[a * 2 + 1];
+    }
+    return Math.abs(twice) / 2;
+}
+export function polyIsConvex(mesh, poly) {
+    const count = polyVertexCount(mesh, poly);
+    if (count < 3)
+        return false;
+    const indices = [];
+    for (let at = 0; at < count; at += 1) {
+        indices.push(mesh.polys[poly * mesh.maxVertsPerPoly + at]);
+    }
+    return isConvexLoop(indices, mesh.vertices);
+}
+function cross(vertices, a, b, c) {
+    return ((vertices[b * 2] - vertices[a * 2]) *
+        (vertices[c * 2 + 1] - vertices[a * 2 + 1]) -
+        (vertices[b * 2 + 1] - vertices[a * 2 + 1]) *
+            (vertices[c * 2] - vertices[a * 2]));
+}
+/** Every turn the same way round, treating a straight run as no turn at all. */
+function isConvexLoop(loop, vertices) {
+    let sign = 0;
+    for (let at = 0; at < loop.length; at += 1) {
+        const a = loop[at];
+        const b = loop[(at + 1) % loop.length];
+        const c = loop[(at + 2) % loop.length];
+        const turn = Math.sign(cross(vertices, a, b, c));
+        if (turn === 0)
+            continue;
+        if (sign === 0)
+            sign = turn;
+        else if (turn !== sign)
+            return false;
+    }
+    return sign !== 0;
+}
+/** Whether `p` is inside or on triangle `a b c`, used to reject an ear that swallows a vertex. */
+function inTriangle(vertices, a, b, c, p) {
+    const d1 = cross(vertices, a, b, p);
+    const d2 = cross(vertices, b, c, p);
+    const d3 = cross(vertices, c, a, p);
+    const negative = d1 < 0 || d2 < 0 || d3 < 0;
+    const positive = d1 > 0 || d2 > 0 || d3 > 0;
+    return !(negative && positive);
+}
+/** Ear clipping. The loop is counter-clockwise by the time it gets here. */
+function triangulate(loop, vertices) {
+    const out = [];
+    const working = [...loop];
+    let guard = working.length * working.length + 8;
+    while (working.length > 3 && guard > 0) {
+        guard -= 1;
+        let clipped = false;
+        for (let at = 0; at < working.length; at += 1) {
+            const a = working[(at + working.length - 1) % working.length];
+            const b = working[at];
+            const c = working[(at + 1) % working.length];
+            if (cross(vertices, a, b, c) <= 0)
+                continue;
+            let swallows = false;
+            for (const other of working) {
+                if (other === a || other === b || other === c)
+                    continue;
+                if (inTriangle(vertices, a, b, c, other)) {
+                    swallows = true;
+                    break;
+                }
+            }
+            if (swallows)
+                continue;
+            out.push([a, b, c]);
+            working.splice(at, 1);
+            clipped = true;
+            break;
+        }
+        /* A loop with no ear at all is degenerate; stopping beats spinning inside a bake. */
+        if (!clipped)
+            break;
+    }
+    if (working.length === 3)
+        out.push([...working]);
+    return out;
+}
+/** Merge neighbours while the result stays convex and inside the vertex budget. */
+function mergeConvex(polys, vertices, maxVerts) {
+    const live = polys.map((poly) => [...poly]);
+    for (let changed = true; changed;) {
+        changed = false;
+        for (let a = 0; a < live.length && !changed; a += 1) {
+            for (let b = a + 1; b < live.length && !changed; b += 1) {
+                const merged = mergeIfConvex(live[a], live[b], vertices, maxVerts);
+                if (merged === null)
+                    continue;
+                live[a] = merged;
+                live.splice(b, 1);
+                changed = true;
+            }
+        }
+    }
+    return live;
+}
+/** The two polygons as one, or null where they do not share an edge or the result is not convex. */
+function mergeIfConvex(a, b, vertices, maxVerts) {
+    for (let i = 0; i < a.length; i += 1) {
+        const a0 = a[i];
+        const a1 = a[(i + 1) % a.length];
+        for (let j = 0; j < b.length; j += 1) {
+            const b0 = b[j];
+            const b1 = b[(j + 1) % b.length];
+            /* A shared edge runs the other way round in the neighbour, which is what makes them fit. */
+            if (a0 !== b1 || a1 !== b0)
+                continue;
+            const loop = [];
+            for (let k = 1; k < a.length; k += 1)
+                loop.push(a[(i + k) % a.length]);
+            for (let k = 1; k < b.length; k += 1)
+                loop.push(b[(j + k) % b.length]);
+            if (loop.length > maxVerts)
+                return null;
+            return isConvexLoop(loop, vertices) ? loop : null;
+        }
+    }
+    return null;
+}
+export function buildPolyMesh(contours, maxVertsPerPoly, placement) {
+    const maxVerts = Math.max(3, maxVertsPerPoly);
+    const vertexKeys = new Map();
+    const vertexList = [];
+    const polys = [];
+    const regions = [];
+    const intern = (x, z) => {
+        const key = `${x},${z}`;
+        const found = vertexKeys.get(key);
+        if (found !== undefined)
+            return found;
+        const index = vertexList.length / 2;
+        vertexList.push(x, z);
+        vertexKeys.set(key, index);
+        return index;
+    };
+    for (const contour of contours) {
+        const loop = [];
+        for (let at = 0; at < contour.points.length; at += 2) {
+            loop.push(intern(contour.points[at], contour.points[at + 1]));
+        }
+        if (loop.length < 3)
+            continue;
+        const vertices = Int32Array.from(vertexList);
+        /* Counter-clockwise, because ear clipping tests a positive turn and the walk may go either way. */
+        if (signedArea(loop, vertices) < 0)
+            loop.reverse();
+        const pieces = mergeConvex(triangulate(loop, vertices), vertices, maxVerts);
+        for (const piece of pieces) {
+            polys.push(piece);
+            regions.push(contour.region);
+        }
+    }
+    const vertices = Int32Array.from(vertexList);
+    const polyCount = polys.length;
+    const table = new Int32Array(polyCount * maxVerts).fill(NO_VERTEX);
+    const neighbours = new Int32Array(polyCount * maxVerts).fill(NO_NEIGHBOUR);
+    for (let poly = 0; poly < polyCount; poly += 1) {
+        const piece = polys[poly];
+        for (let at = 0; at < piece.length && at < maxVerts; at += 1) {
+            table[poly * maxVerts + at] = piece[at];
+        }
+    }
+    /*
+     * Both directions in one pass. An edge `a → b` in one polygon is `b → a` in its neighbour, so
+     * recording the pair the moment it is found makes the relation symmetric by construction rather
+     * than by a second loop somebody could forget.
+     */
+    const edgeOwner = new Map();
+    for (let poly = 0; poly < polyCount; poly += 1) {
+        const piece = polys[poly];
+        for (let at = 0; at < piece.length; at += 1) {
+            const from = piece[at];
+            const to = piece[(at + 1) % piece.length];
+            const reverse = edgeOwner.get(`${to},${from}`);
+            if (reverse === undefined) {
+                edgeOwner.set(`${from},${to}`, [poly, at]);
+                continue;
+            }
+            neighbours[poly * maxVerts + at] = reverse[0];
+            neighbours[reverse[0] * maxVerts + reverse[1]] = poly;
+        }
+    }
+    return {
+        vertices,
+        vertexCount: vertices.length / 2,
+        polys: table,
+        neighbours,
+        polyCount,
+        maxVertsPerPoly: maxVerts,
+        polyRegion: Int32Array.from(regions),
+        originX: placement.origin[0],
+        originZ: placement.origin[2],
+        cellSize: placement.cellSize,
+    };
+}
+function signedArea(loop, vertices) {
+    let twice = 0;
+    for (let at = 0; at < loop.length; at += 1) {
+        const a = loop[at];
+        const b = loop[(at + 1) % loop.length];
+        twice +=
+            vertices[a * 2] * vertices[b * 2 + 1] -
+                vertices[b * 2] * vertices[a * 2 + 1];
+    }
+    return twice / 2;
+}

package/dist/portalGraph.d.ts

@@ -0,0 +1,36 @@
+import type { NavGraph } from '@driftengine/core';
+import { type PolyMesh } from './polymesh.ts';
+export interface PortalGraph {
+    /** Nodes: one per portal, then the start, then the goal. */
+    readonly graph: NavGraph;
+    readonly portalCount: number;
+    /** The two polygons each portal joins, near first: 2 per portal. */
+    readonly sides: Int32Array;
+    /**
+     * The portal's two vertices as **each** of its polygons stores them: 4 per portal, near's pair
+     * then far's.
+     *
+     * Both, rather than one pair flipped when the path crosses the other way. The funnel needs the
+     * left end and the right end *for the direction of travel*, and which vertex is which depends on
+     * the winding of the polygon being left — a mesh whose two polygons do not store a shared edge
+     * in opposite orders would silently get the funnel's two sides swapped, which is a legal path and
+     * a visibly worse one. Read at build time from both sides, so nothing assumes.
+     */
+    readonly ends: Int32Array;
+    /** Which portals a polygon has: `polyStart[p]` to `polyStart[p + 1]` into `polyPortals`. */
+    readonly polyStart: Uint32Array;
+    readonly polyPortals: Uint32Array;
+    readonly startNode: number;
+    readonly goalNode: number;
+    /** The edge slot each portal keeps for the goal, and the range the start node's slots occupy. */
+    readonly goalSlot: Uint32Array;
+    readonly startSlots: Uint32Array;
+    /** The polygon whose portals currently point at the goal, or −1. */
+    attachedGoal: number;
+}
+/** A portal's midpoint is its graph node's position, and the graph is in metres as a path is. */
+export declare function buildPortalGraph(mesh: PolyMesh): PortalGraph;
+/** Point the start node at the portals of the polygon holding it. */
+export declare function attachStart(portals: PortalGraph, poly: number, x: number, z: number): void;
+/** Point the portals of the goal's polygon at the goal node, and let the previous ones go. */
+export declare function attachGoal(portals: PortalGraph, poly: number, x: number, z: number): void;

package/dist/portalGraph.js

@@ -0,0 +1,285 @@
+/**
+ * The mesh as a graph over **portals**, which is what makes a path the shortest one.
+ *
+ * **A* over polygon centres optimises a quantity no agent walks.** A polygon path is a corridor and
+ * the funnel is optimal inside whatever corridor it is handed — so if the corridor is not the one
+ * holding the shortest path, the funnel cannot recover it. Measured on `query.test.ts`'s wall:
+ * **10.75 against an ideal 9.81**, for as long as the nodes were centroids.
+ *
+ * **And a cost on the edge between two polygons cannot fix it**, which is worth knowing before
+ * trying: what crossing a polygon costs depends on *which portal the path entered by*, and one
+ * number between two polygons cannot carry that. The midpoint-to-midpoint distance across a shared
+ * edge is zero, because it is one edge.
+ *
+ * **So the node is the portal.** An edge joins two portals of the same polygon and costs the
+ * distance between their midpoints, which is a distance something walks. The start and the goal are
+ * two more nodes, joined to the portals of the polygons holding them. What the search returns is
+ * then the portal sequence itself, so the funnel is handed its corridor directly rather than
+ * reconstructing it from a polygon path.
+ *
+ * **And a portal is where two polygons *overlap*, not where they share an edge — which is where the
+ * tenth actually went.** `buildPolyMesh` records a neighbour only for edges with the same two
+ * vertices, and two regions simplified independently do not agree about where a vertex goes: on the
+ * wall map, one polygon's edge from (6,3) to (6,4) is the middle of another's from (6,4) to (6,0),
+ * so the two are adjacent on the ground and strangers in the table. The path went the long way
+ * round because **the short corridor was not in the graph at all**, which is a different fault from
+ * the one the record had — see `docs/IMPROVEMENTS.md`, where the diagnosis was the search.
+ *
+ * Found by overlap in **exact integer arithmetic**: a mesh's vertices are cell indices, so two
+ * edges are on one line when their reduced directions and offsets are equal, and their overlap is
+ * an interval with endpoints drawn from their own four vertices. No tolerance is chosen, and none
+ * is needed.
+ *
+ * **What it gives up**: the corridor is optimal *between portal midpoints*, which is still not
+ * exactly the continuous shortest path — a route that should cross a portal near one end pays for
+ * the midpoint. On the maps here that is under a thousandth; what would make it wrong is a mesh
+ * with very long portals, where the fix is to keep the funnel and search over portal *intervals*.
+ *
+ * **Nothing here allocates per query.** The graph is built once; the start and the goal are written
+ * into edge slots reserved for them at build time, which is why `attachStart` and `attachGoal` take
+ * a graph and write to it rather than returning one.
+ */
+import { buildNavGraph } from '@driftengine/core';
+import { polyNeighbour, polyVertexCount } from './polymesh.js';
+function gcd(a, b) {
+    let x = Math.abs(a);
+    let y = Math.abs(b);
+    while (y !== 0) {
+        const held = y;
+        y = x % y;
+        x = held;
+    }
+    return x === 0 ? 1 : x;
+}
+/**
+ * Every pair of polygon edges that lie on one line and overlap in more than a point.
+ *
+ * **Bucketed by the line itself**, so this is one pass over the edges and a small comparison inside
+ * each bucket rather than every edge against every other. The line's key is its direction reduced
+ * by the greatest common divisor, signed one way, and its offset — all integers, because a mesh's
+ * vertices are cell indices, so two edges are on one line exactly or not at all.
+ */
+function overlappingEdges(mesh) {
+    const lines = new Map();
+    for (let poly = 0; poly < mesh.polyCount; poly += 1) {
+        const verts = polyVertexCount(mesh, poly);
+        for (let edge = 0; edge < verts; edge += 1) {
+            const from = mesh.polys[poly * mesh.maxVertsPerPoly + edge];
+            const to = mesh.polys[poly * mesh.maxVertsPerPoly + ((edge + 1) % verts)];
+            const ax = mesh.vertices[from * 2];
+            const az = mesh.vertices[from * 2 + 1];
+            const dx = mesh.vertices[to * 2] - ax;
+            const dz = mesh.vertices[to * 2 + 1] - az;
+            if (dx === 0 && dz === 0)
+                continue;
+            const divisor = gcd(dx, dz);
+            let ux = dx / divisor;
+            let uz = dz / divisor;
+            /* One sign per line, so an edge and its reverse land in the same bucket. */
+            if (ux < 0 || (ux === 0 && uz < 0)) {
+                ux = -ux;
+                uz = -uz;
+            }
+            /* The cross of the direction with a point on it: constant along the line, so it names it. */
+            const offset = ux * az - uz * ax;
+            const key = `${ux},${uz},${offset}`;
+            /* Along the line, measured on whichever axis the direction actually moves in. */
+            const along = (vertex) => ux !== 0
+                ? mesh.vertices[vertex * 2]
+                : mesh.vertices[vertex * 2 + 1];
+            const side = { poly, from, to, fromAt: along(from), toAt: along(to) };
+            const held = lines.get(key);
+            if (held === undefined)
+                lines.set(key, [side]);
+            else
+                held.push(side);
+        }
+    }
+    const out = [];
+    for (const sides of lines.values()) {
+        for (let i = 0; i < sides.length; i += 1) {
+            for (let j = i + 1; j < sides.length; j += 1) {
+                const a = sides[i];
+                const b = sides[j];
+                if (a.poly === b.poly)
+                    continue;
+                const low = Math.max(Math.min(a.fromAt, a.toAt), Math.min(b.fromAt, b.toAt));
+                const high = Math.min(Math.max(a.fromAt, a.toAt), Math.max(b.fromAt, b.toAt));
+                /* Touching at a point is not a way through, and a zero-length portal breaks the funnel. */
+                if (!(high > low))
+                    continue;
+                const atLow = (side) => (side.fromAt === low ? side.from : side.to);
+                const atHigh = (side) => (side.fromAt === high ? side.from : side.to);
+                const lowVertex = a.fromAt === low || a.toAt === low ? atLow(a) : atLow(b);
+                const highVertex = a.fromAt === high || a.toAt === high ? atHigh(a) : atHigh(b);
+                /*
+                 * Each side names the overlap in **its own** direction of travel: the funnel wants a left
+                 * end and a right end for the polygon being left, and swapping them is a legal path that
+                 * bulges away from every corner instead of hugging it.
+                 */
+                const forward = (side) => side.toAt > side.fromAt;
+                out.push({
+                    near: a.poly,
+                    far: b.poly,
+                    nearFrom: forward(a) ? lowVertex : highVertex,
+                    nearTo: forward(a) ? highVertex : lowVertex,
+                    farFrom: forward(b) ? lowVertex : highVertex,
+                    farTo: forward(b) ? highVertex : lowVertex,
+                });
+            }
+        }
+    }
+    return out;
+}
+/** A portal's midpoint is its graph node's position, and the graph is in metres as a path is. */
+export function buildPortalGraph(mesh) {
+    const slots = mesh.maxVertsPerPoly;
+    const found = overlappingEdges(mesh);
+    const portalCount = found.length;
+    const startNode = portalCount;
+    const goalNode = portalCount + 1;
+    const positions = new Float32Array((portalCount + 2) * 3);
+    const sides = new Int32Array(portalCount * 2);
+    const ends = new Int32Array(portalCount * 4);
+    const degree = new Uint32Array(mesh.polyCount);
+    for (let at = 0; at < portalCount; at += 1) {
+        const portal = found[at];
+        sides[at * 2] = portal.near;
+        sides[at * 2 + 1] = portal.far;
+        ends[at * 4] = portal.nearFrom;
+        ends[at * 4 + 1] = portal.nearTo;
+        ends[at * 4 + 2] = portal.farFrom;
+        ends[at * 4 + 3] = portal.farTo;
+        positions[at * 3] = midpoint(mesh, portal.nearFrom, portal.nearTo, 0);
+        positions[at * 3 + 2] = midpoint(mesh, portal.nearFrom, portal.nearTo, 1);
+        degree[portal.near] = degree[portal.near] + 1;
+        degree[portal.far] = degree[portal.far] + 1;
+    }
+    /* Which portals each polygon has, as a CSR the attach step walks. */
+    const polyStart = new Uint32Array(mesh.polyCount + 1);
+    for (let poly = 0; poly < mesh.polyCount; poly += 1) {
+        polyStart[poly + 1] = polyStart[poly] + degree[poly];
+    }
+    const cursor = Uint32Array.from(polyStart.subarray(0, mesh.polyCount));
+    const polyPortals = new Uint32Array(polyStart[mesh.polyCount]);
+    for (let portal = 0; portal < portalCount; portal += 1) {
+        for (let side = 0; side < 2; side += 1) {
+            const poly = sides[portal * 2 + side];
+            polyPortals[cursor[poly]] = portal;
+            cursor[poly] = cursor[poly] + 1;
+        }
+    }
+    /*
+     * An edge between every two portals of one polygon, both ways. `buildNavGraph` costs an edge at
+     * the distance between its ends, which here is midpoint to midpoint — a distance something
+     * walks, and the straight line A*'s heuristic needs it never to undercut.
+     */
+    const edges = [];
+    for (let poly = 0; poly < mesh.polyCount; poly += 1) {
+        const from = polyStart[poly];
+        const to = polyStart[poly + 1];
+        for (let i = from; i < to; i += 1) {
+            for (let j = from; j < to; j += 1) {
+                if (i !== j) {
+                    edges.push({ from: polyPortals[i], to: polyPortals[j] });
+                }
+            }
+        }
+    }
+    /*
+     * **A slot per portal for the goal, and `maxVertsPerPoly` for the start**, written as self-loops
+     * and rewritten per query. A self-loop is inert in a search with no negative costs — reaching a
+     * node from itself can never improve what it already cost to get there — so a slot nobody is
+     * using is a slot that does nothing, rather than a route with a large number on it that a
+     * "no path" query would return as a path.
+     */
+    for (let portal = 0; portal < portalCount; portal += 1)
+        edges.push({ from: portal, to: portal });
+    for (let slot = 0; slot < slots; slot += 1)
+        edges.push({ from: startNode, to: startNode });
+    const graph = buildNavGraph(positions, edges);
+    const goalSlot = new Uint32Array(portalCount);
+    for (let portal = 0; portal < portalCount; portal += 1) {
+        goalSlot[portal] = selfLoopOf(graph, portal);
+    }
+    const startSlots = new Uint32Array(slots);
+    for (let slot = 0; slot < slots; slot += 1) {
+        startSlots[slot] = graph.edgeStart[startNode] + slot;
+    }
+    return {
+        graph,
+        portalCount,
+        sides,
+        ends,
+        polyStart,
+        polyPortals,
+        startNode,
+        goalNode,
+        goalSlot,
+        startSlots,
+        attachedGoal: -1,
+    };
+}
+/**
+ * Where the reserved slot landed, found rather than computed.
+ *
+ * `buildNavGraph` groups edges by their `from`, and the order inside a group is the order they were
+ * given in — so the reserved one is last. Searching for it instead costs one pass at build time and
+ * keeps this file from depending on that.
+ */
+function selfLoopOf(graph, node) {
+    for (let edge = graph.edgeStart[node]; edge < graph.edgeStart[node + 1]; edge += 1) {
+        if (graph.edgeTarget[edge] === node)
+            return edge;
+    }
+    throw new Error(`nav: node ${node} has no reserved slot`);
+}
+function midpoint(mesh, a, b, axis) {
+    const origin = axis === 0 ? mesh.originX : mesh.originZ;
+    const first = mesh.vertices[a * 2 + axis];
+    const second = mesh.vertices[b * 2 + axis];
+    return origin + ((first + second) / 2) * mesh.cellSize;
+}
+/** Point the start node at the portals of the polygon holding it. */
+export function attachStart(portals, poly, x, z) {
+    const { graph, startNode } = portals;
+    graph.positions[startNode * 3] = x;
+    graph.positions[startNode * 3 + 1] = 0;
+    graph.positions[startNode * 3 + 2] = z;
+    const from = portals.polyStart[poly];
+    const to = portals.polyStart[poly + 1];
+    for (let slot = 0; slot < portals.startSlots.length; slot += 1) {
+        const edge = portals.startSlots[slot];
+        const held = from + slot < to ? portals.polyPortals[from + slot] : -1;
+        graph.edgeTarget[edge] = held < 0 ? startNode : held;
+        graph.edgeCost[edge] = held < 0 ? 0 : reach(graph, held, x, z);
+    }
+}
+/** Point the portals of the goal's polygon at the goal node, and let the previous ones go. */
+export function attachGoal(portals, poly, x, z) {
+    const { graph, goalNode } = portals;
+    graph.positions[goalNode * 3] = x;
+    graph.positions[goalNode * 3 + 1] = 0;
+    graph.positions[goalNode * 3 + 2] = z;
+    const previous = portals.attachedGoal;
+    if (previous >= 0) {
+        for (let at = portals.polyStart[previous]; at < portals.polyStart[previous + 1]; at += 1) {
+            const portal = portals.polyPortals[at];
+            const edge = portals.goalSlot[portal];
+            graph.edgeTarget[edge] = portal;
+            graph.edgeCost[edge] = 0;
+        }
+    }
+    for (let at = portals.polyStart[poly]; at < portals.polyStart[poly + 1]; at += 1) {
+        const portal = portals.polyPortals[at];
+        const edge = portals.goalSlot[portal];
+        graph.edgeTarget[edge] = goalNode;
+        graph.edgeCost[edge] = reach(graph, portal, x, z);
+    }
+    portals.attachedGoal = poly;
+}
+function reach(graph, portal, x, z) {
+    const dx = graph.positions[portal * 3] - x;
+    const dz = graph.positions[portal * 3 + 2] - z;
+    return Math.sqrt(dx * dx + dz * dz);
+}

package/dist/query.d.ts

@@ -0,0 +1,59 @@
+import { type PolyMesh } from './polymesh.ts';
+import { type PortalGraph } from './portalGraph.ts';
+/**
+ * The polygon a point is in, or the nearest within `extent`. `-1` beyond it. The point and the
+ * extent are in metres, which the mesh's placement turns into its cells.
+ *
+ * **`-1` rather than the nearest whatever the distance**, because an agent asked to walk to a
+ * place that is not on the mesh has to be told. Snapping across the map produces a path to
+ * somewhere nobody asked for, which is worse than no path at all.
+ */
+export declare function nearestPoly(mesh: PolyMesh, x: number, z: number, extent: number): number;
+/**
+ * A query, holding everything a search needs so that running one allocates nothing.
+ *
+ * One per agent, or one shared by a caller that queries serially. The scratch is sized by the mesh
+ * because a polygon path cannot be longer than the mesh has polygons.
+ */
+export declare class NavMeshQuery {
+    readonly mesh: PolyMesh;
+    readonly portals: PortalGraph;
+    private readonly search;
+    /** The nodes a search returns: the start, the portals it crosses, then the goal. */
+    private readonly nodePath;
+    /** Portal ends, two points per portal: left x, left z, right x, right z. */
+    private readonly corridor;
+    private readonly centre;
+    constructor(mesh: PolyMesh);
+    /**
+     * The polygons from `from` to `to`, written into `out`. Zero where there is no route.
+     *
+     * Asked between the two polygons' centres, because a polygon is a region and a search over
+     * portals needs a point. What comes back is the corridor a path between those two points would
+     * be funnelled through, which is what a caller asking this question wants.
+     */
+    findPolyPath(from: number, to: number, out: Uint32Array): number;
+    /**
+     * A path from one point to another, as world positions in `out`, x and z per step.
+     *
+     * Returns how many points were written, or zero for no route — which is a real answer, not an
+     * error: a mesh with two components is a world with a gap in it, and an agent that asks for the
+     * other side has to be told rather than thrown at inside a frame.
+     */
+    findPath(fromX: number, fromZ: number, toX: number, toZ: number, extent: number, out: Float64Array): number;
+    /** The search itself: how many portals the path crosses, or −1 for no route. */
+    private search_;
+    /**
+     * The portals the path crosses, as the funnel wants them: a left end and a right end **for the
+     * direction of travel**, in metres.
+     *
+     * Swapping the two is a legal path and a visibly worse one — the funnel tightens the wrong way
+     * and bulges away from every corner instead of hugging it. Measured on three maps rather than
+     * reasoned about, because the convention depends on the winding, on which way `z` runs and on the
+     * order `buildPolyMesh` emits an edge in: 10.75 against 18.30 on a wall, 8.75 against 12.65 on a
+     * corner, 8.60 against 24.70 on a zigzag.
+     */
+    private fillCorridor;
+    /** The polygons a portal path passes through, which is the corridor named the other way. */
+    private walkPolygons;
+}