@driftengine/nav 4.0.0

package/dist/contour.js

@@ -0,0 +1,516 @@
+const SPAN_STRIDE = 3;
+/** The four sides of a cell, as the directed edge each contributes when its neighbour is absent. */
+const SIDES = [
+    /* dx, dz, from x, from z, to x, to z — all in cell-corner units, relative to the cell. */
+    [-1, 0, 0, 1, 0, 0],
+    [1, 0, 1, 0, 1, 1],
+    [0, -1, 0, 0, 1, 0],
+    [0, 1, 1, 1, 0, 1],
+];
+/** Which region a column's first walkable span belongs to, or `-1`. */
+function regionAtColumn(field, regions, x, z) {
+    if (x < 0 || z < 0 || x >= field.width || z >= field.depth)
+        return -1;
+    const column = x + z * field.width;
+    const from = field.columnStart[column] / SPAN_STRIDE;
+    const to = field.columnStart[column + 1] / SPAN_STRIDE;
+    for (let at = from; at < to; at += 1) {
+        if (field.spans[at * SPAN_STRIDE + 2] === 1)
+            return regions.regionOf[at];
+    }
+    return -1;
+}
+/**
+ * One closed loop per region, holes bridged into it, simplified.
+ *
+ * **This took the longest loop and dropped the rest until 2026-09-16, and the limitation was worse
+ * than it was written down as.** It was stated as losing a pillar — an agent walking through a
+ * column in the middle of a room. What it actually did was *claim ground*: a ring's outer loop is
+ * the room's whole perimeter, so simplifying it gives a rectangle covering the pillar and whatever
+ * else the watershed carved out of the middle. Measured on
+ * `['..........', '....##....', '....##....', '..........']`, the ring's polygon came out as the
+ * entire ten-by-four map, area 40 where the region is 32 — a navigation mesh asserting that a wall
+ * and a neighbouring region are both walkable by the same agent.
+ *
+ * **Holes are bridged rather than emitted separately.** A hole as its own contour would become its
+ * own walkable polygon, which is the same defect pointing the other way. A bridge joins the inner
+ * loop to the outer along a segment traversed once each way, so the pair becomes **one closed loop
+ * with a zero-width slit** — weakly simple rather than simple, which is what ear clipping wants and
+ * what `segmentsCross` tolerates, since it requires a *strict* crossing and the two bridge edges
+ * are coincident.
+ */
+export function buildContours(field, regions, maxDeviation) {
+    const out = [];
+    for (let region = 0; region < regions.count; region += 1) {
+        const edges = [];
+        for (let z = 0; z < field.depth; z += 1) {
+            for (let x = 0; x < field.width; x += 1) {
+                if (regionAtColumn(field, regions, x, z) !== region)
+                    continue;
+                for (const [dx, dz, fx, fz, tx, tz] of SIDES) {
+                    if (regionAtColumn(field, regions, x + dx, z + dz) === region)
+                        continue;
+                    edges.push({ fx: x + fx, fz: z + fz, tx: x + tx, tz: z + tz, used: false });
+                }
+            }
+        }
+        if (edges.length === 0)
+            continue;
+        const loops = chainLoops(edges);
+        if (loops.length === 0)
+            continue;
+        /*
+         * **Bridge first, then simplify with the bridge vertices held fixed**, and both halves of that
+         * were arrived at by getting them wrong.
+         *
+         * Simplifying the bridged loop *freely* destroys the slit: Douglas–Peucker has no idea the two
+         * traversals of a bridge have to stay coincident, so it moves them independently and what was
+         * weakly simple becomes genuinely self-overlapping. Ear clipping then produces a mesh that does
+         * not cover its own contour — 67.5 against 82 on one of 150 random blobs, and 89 against 88 on
+         * another.
+         *
+         * Simplifying each loop *before* bridging fixes that and breaks something else: a hole and the
+         * boundary containing it then move independently, by up to the deviation each, so a hole can
+         * poke through its own container and the contour crosses itself with no bridge involved.
+         *
+         * What works is holding the bridge's vertices — two endpoints, each appearing twice — and
+         * simplifying the chains between them. A bridge has no interior vertices, so fixing its ends
+         * fixes it exactly.
+         */
+        const bridged = bridgeHoles(loops);
+        const raw = Int32Array.from(bridged.loop);
+        out.push({ region, points: simplify(raw, maxDeviation, bridged.anchors), raw });
+    }
+    return out;
+}
+/**
+ * Follow the directed edges into closed loops.
+ *
+ * **A vertex may have two outgoing edges, and the first version of this kept one of them.** Where a
+ * region pinches — a one-cell isthmus, or a ring closing on itself — the boundary passes through
+ * one corner twice, so a map from vertex to edge silently drops half the loop. Over 23,636 contours
+ * from random blobs that produced 46 self-intersecting results, every one of which the guard in
+ * `simplify` could not fix because the *raw* boundary was already wrong.
+ *
+ * The fix is to keep every edge. **Which of two edges is taken at a fork does not matter**, and a
+ * sharpest-turn rule was written, measured and removed: every vertex has as many edges in as out,
+ * so any choice decomposes the boundary into closed walks along cell edges, and a closed walk along
+ * cell edges cannot cross itself whichever walk it is. Across 106,000 contours at six fill
+ * densities the rule changed nothing, so it is not here.
+ *
+ * What the choice *does* decide is how a pinched boundary splits between two loops, and this takes
+ * the longest — the same heuristic, and the same limitation, as a region with a hole.
+ */
+function chainLoops(edges) {
+    const outgoing = new Map();
+    for (const edge of edges) {
+        const key = `${edge.fx},${edge.fz}`;
+        const list = outgoing.get(key);
+        if (list === undefined)
+            outgoing.set(key, [edge]);
+        else
+            list.push(edge);
+    }
+    const loops = [];
+    /* Sorted, so a region with two loops always yields them in the same order. */
+    for (const start of [...outgoing.keys()].sort()) {
+        for (;;) {
+            const first = (outgoing.get(start) ?? []).find((edge) => !edge.used);
+            if (first === undefined)
+                break;
+            const loop = [];
+            let edge = first;
+            while (edge !== undefined && !edge.used) {
+                edge.used = true;
+                loop.push(edge.tx, edge.tz);
+                edge = (outgoing.get(`${edge.tx},${edge.tz}`) ?? []).find((next) => !next.used);
+            }
+            if (loop.length >= 6)
+                loops.push(loop);
+        }
+    }
+    return loops;
+}
+/** Twice the signed area of a closed loop, which is the sign of its winding and the size of it. */
+function twiceSignedArea(loop) {
+    let total = 0;
+    const count = loop.length / 2;
+    for (let at = 0; at < count; at += 1) {
+        const next = (at + 1) % count;
+        total +=
+            loop[at * 2] * loop[next * 2 + 1] -
+                loop[next * 2] * loop[at * 2 + 1];
+    }
+    return total;
+}
+/** Whether every loop visits each vertex once and no two loops share one. */
+function loopsAreDisjointAndSimple(loops) {
+    const all = new Set();
+    for (const loop of loops) {
+        const mine = new Set();
+        for (let at = 0; at < loop.length / 2; at += 1) {
+            const key = `${loop[at * 2]},${loop[at * 2 + 1]}`;
+            if (mine.has(key) || all.has(key))
+                return false;
+            mine.add(key);
+        }
+        for (const key of mine)
+            all.add(key);
+    }
+    return true;
+}
+/**
+ * One loop out of several, with every hole cut into the outer one by a bridge.
+ *
+ * **The outer loop is the one with the largest area, not the most points.** A hole traced round a
+ * long thin slot can carry more vertices than the boundary containing it, and picking by length
+ * then makes the hole the region — the old heuristic failing in the one direction nobody looks.
+ *
+ * **Each hole is wound against the outer before it is spliced**, because that is what subtracts it.
+ * A hole wound the same way *adds* its area, and every test about which corners are on the boundary
+ * passes either way: the loop visits the same points, and only the shoelace sum can tell.
+ *
+ * **The bridge is the closest pair that nothing gets in the way of.** Every pair of vertices is
+ * tried in order of distance and the first whose segment crosses no edge — of the outer loop, of
+ * this hole, or of any hole still to be cut — is taken. That is quadratic in a region's boundary
+ * and this is a bake: `buildContours` runs when a level is built, never in a tick, and the
+ * alternative is the ray-casting construction whose correctness argument is three pages long.
+ *
+ * **A pinched boundary already visits a corner twice, and a bridge into one cannot be told from
+ * the pinch.** `chainLoops` records the case: where a region narrows to a one-cell isthmus the walk
+ * along cell edges passes through the same corner twice, so the loop is not simple before anything
+ * is spliced into it. Bridging such a loop produces a vertex visited three times, which
+ * `segmentsCross` tolerates — three edges meeting at a point never strictly cross — and which ear
+ * clipping resolves by covering part of the region twice. Measured on a 12x12 blob whose region 7
+ * is pinched *and* holed: a mesh of 83 against a contour of 82, a navigation mesh claiming ground
+ * that is not walkable, which is the defect this whole change exists to remove. So a region whose
+ * loops are not individually simple, or which share a vertex, keeps exactly what it had before —
+ * the outer loop alone. **The limitation is now the narrow one it was always described as**, a
+ * pillar in a room that also pinches, rather than every pillar in every room.
+ */
+function bridgeHoles(loops) {
+    if (loops.length === 1)
+        return { loop: [...loops[0]], anchors: [] };
+    const areas = loops.map(twiceSignedArea);
+    let outerAt = 0;
+    for (let at = 1; at < loops.length; at += 1) {
+        if (Math.abs(areas[at]) > Math.abs(areas[outerAt]))
+            outerAt = at;
+    }
+    if (!loopsAreDisjointAndSimple(loops)) {
+        return { loop: [...loops[outerAt]], anchors: [] };
+    }
+    const outerSign = Math.sign(areas[outerAt]);
+    let merged = [...loops[outerAt]];
+    const holes = [];
+    for (let at = 0; at < loops.length; at += 1) {
+        if (at === outerAt)
+            continue;
+        const hole = [...loops[at]];
+        if (Math.sign(areas[at]) === outerSign)
+            reverseLoop(hole);
+        holes.push(hole);
+    }
+    /* Deterministic order, so two builds of one level produce the same mesh. */
+    holes.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    let anchors = [];
+    /* The coordinates every bridge placed so far lands on. See `spliceHole` for why they are barred. */
+    const taken = new Set();
+    for (let at = 0; at < holes.length; at += 1) {
+        const spliced = spliceHole(merged, holes[at], holes.slice(at + 1), taken);
+        /* Anchors recorded earlier sit before the splice, or shift by the hole's length after it. */
+        const grew = holes[at].length / 2 + 1;
+        anchors = [
+            ...anchors.map((index) => (index <= spliced.insertedAfter ? index : index + grew)),
+            ...spliced.anchors,
+        ];
+        merged = spliced.loop;
+    }
+    anchors.sort((a, b) => a - b);
+    return { loop: merged, anchors };
+}
+/** A loop the other way round, in place. */
+function reverseLoop(loop) {
+    const count = loop.length / 2;
+    for (let at = 0; at < Math.floor(count / 2); at += 1) {
+        const other = count - 1 - at;
+        const x = loop[at * 2];
+        const z = loop[at * 2 + 1];
+        loop[at * 2] = loop[other * 2];
+        loop[at * 2 + 1] = loop[other * 2 + 1];
+        loop[other * 2] = x;
+        loop[other * 2 + 1] = z;
+    }
+}
+/** Cut one hole into a loop along the shortest segment that crosses nothing. */
+function spliceHole(outer, hole, pending, taken) {
+    const outerCount = outer.length / 2;
+    const holeCount = hole.length / 2;
+    const pairs = [];
+    for (let o = 0; o < outerCount; o += 1) {
+        for (let h = 0; h < holeCount; h += 1) {
+            const dx = outer[o * 2] - hole[h * 2];
+            const dz = outer[o * 2 + 1] - hole[h * 2 + 1];
+            pairs.push({ outerAt: o, holeAt: h, distance: dx * dx + dz * dz });
+        }
+    }
+    /* Ties broken by index, so the choice does not depend on the sort's stability. */
+    pairs.sort((a, b) => a.distance - b.distance || a.outerAt - b.outerAt || a.holeAt - b.holeAt);
+    for (const pair of pairs) {
+        const ax = outer[pair.outerAt * 2];
+        const az = outer[pair.outerAt * 2 + 1];
+        const bx = hole[pair.holeAt * 2];
+        const bz = hole[pair.holeAt * 2 + 1];
+        if (ax === bx && az === bz)
+            continue;
+        /*
+         * **No two bridges may land on the same vertex**, and **no bridge may cross an edge.** Sharing a
+         * vertex gives a loop that visits it three times, which is a tangle rather than a slit — two
+         * bridges meeting at a point never *strictly* cross, so `segmentsCross` allows it and ear
+         * clipping resolves it by covering part of the region twice. A bridge across an edge gives a
+         * polygon that is not even weakly simple.
+         *
+         * **Neither guard has been reached by a test, and both are kept.** The disjoint-and-simple
+         * check above turns away the shapes that produced tangles, and across 150 random blobs, three
+         * hand-drawn pillar rooms and a spiral corridor, every hole's closest vertex pair was already
+         * clear and unclaimed. They are guards against a case the check above has not been *proved* to
+         * exclude, which is a different thing from one it has — a hole tucked inside a concavity has a
+         * blocked closest pair by construction, and nothing here says a region cannot have one.
+         * Perturbing either changes no test; that is recorded rather than papered over.
+         */
+        if (taken.has(`${ax},${az}`) || taken.has(`${bx},${bz}`))
+            continue;
+        if (bridgeBlocked(ax, az, bx, bz, outer, hole, pending))
+            continue;
+        taken.add(`${ax},${az}`);
+        taken.add(`${bx},${bz}`);
+        const out = [];
+        for (let at = 0; at <= pair.outerAt; at += 1) {
+            out.push(outer[at * 2], outer[at * 2 + 1]);
+        }
+        for (let step = 0; step <= holeCount; step += 1) {
+            const at = (pair.holeAt + step) % holeCount;
+            out.push(hole[at * 2], hole[at * 2 + 1]);
+        }
+        for (let at = pair.outerAt; at < outerCount; at += 1) {
+            out.push(outer[at * 2], outer[at * 2 + 1]);
+        }
+        /*
+         * The four vertices the bridge is made of: the outer vertex either side of the slit, and the
+         * hole vertex at each end of the loop round the hole. Holding these is what keeps the two
+         * traversals of the bridge exactly on top of each other through simplification.
+         */
+        const holeStart = pair.outerAt + 1;
+        return {
+            loop: out,
+            anchors: [pair.outerAt, holeStart, holeStart + holeCount, holeStart + holeCount + 1],
+            insertedAfter: pair.outerAt,
+        };
+    }
+    /*
+     * **Nothing could be joined, so the hole is left out rather than joined wrongly.** A bridge that
+     * crossed an edge would produce a polygon that is not even weakly simple, which is worse than the
+     * limitation this replaces.
+     */
+    return { loop: [...outer], anchors: [], insertedAfter: outerCount - 1 };
+}
+/** Whether a proposed bridge strictly crosses any edge of any loop it has to pass. */
+function bridgeBlocked(ax, az, bx, bz, outer, hole, pending) {
+    for (const loop of [outer, hole, ...pending]) {
+        const count = loop.length / 2;
+        for (let at = 0; at < count; at += 1) {
+            const next = (at + 1) % count;
+            if (segmentsCross(ax, az, bx, bz, loop[at * 2], loop[at * 2 + 1], loop[next * 2], loop[next * 2 + 1])) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/** Perpendicular distance from `p` to the segment `a`–`b`, or to `a` where the segment is a point. */
+function distanceToSegment(px, pz, ax, az, bx, bz) {
+    const dx = bx - ax;
+    const dz = bz - az;
+    const lengthSq = dx * dx + dz * dz;
+    // determinism: build-time — contour simplification is a bake, never a tick
+    if (lengthSq === 0)
+        return Math.hypot(px - ax, pz - az);
+    let t = ((px - ax) * dx + (pz - az) * dz) / lengthSq;
+    t = Math.max(0, Math.min(1, t));
+    // determinism: build-time — contour simplification is a bake, never a tick
+    return Math.hypot(px - (ax + t * dx), pz - (az + t * dz));
+}
+/** The furthest any raw point sits from the simplified loop. What the deviation bound means. */
+export function maxDeviationOf(raw, simplified) {
+    const count = simplified.length / 2;
+    if (count < 2)
+        return Infinity;
+    let worst = 0;
+    for (let at = 0; at < raw.length; at += 2) {
+        let best = Infinity;
+        for (let seg = 0; seg < count; seg += 1) {
+            const next = (seg + 1) % count;
+            best = Math.min(best, distanceToSegment(raw[at], raw[at + 1], simplified[seg * 2], simplified[seg * 2 + 1], simplified[next * 2], simplified[next * 2 + 1]));
+        }
+        worst = Math.max(worst, best);
+    }
+    return worst;
+}
+/**
+ * Whether any two non-adjacent segments of a closed loop cross.
+ *
+ * Adjacent segments share an endpoint by construction and are skipped; everything else is a proper
+ * crossing test, so a loop that merely touches itself at a vertex is not reported — that is a
+ * pinch rather than a crossing, and a polygon built from it is still walkable.
+ */
+export function contourSelfIntersects(points) {
+    const count = points.length / 2;
+    if (count < 4)
+        return false;
+    for (let a = 0; a < count; a += 1) {
+        const a2 = (a + 1) % count;
+        for (let b = a + 1; b < count; b += 1) {
+            const b2 = (b + 1) % count;
+            if (a === b || a2 === b || b2 === a)
+                continue;
+            if (segmentsCross(points[a * 2], points[a * 2 + 1], points[a2 * 2], points[a2 * 2 + 1], points[b * 2], points[b * 2 + 1], points[b2 * 2], points[b2 * 2 + 1])) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function side(ax, az, bx, bz, px, pz) {
+    return Math.sign((bx - ax) * (pz - az) - (bz - az) * (px - ax));
+}
+function segmentsCross(ax, az, bx, bz, cx, cz, dx, dz) {
+    const d1 = side(ax, az, bx, bz, cx, cz);
+    const d2 = side(ax, az, bx, bz, dx, dz);
+    const d3 = side(cx, cz, dx, dz, ax, az);
+    const d4 = side(cx, cz, dx, dz, bx, bz);
+    return d1 !== d2 && d3 !== d4 && d1 !== 0 && d2 !== 0 && d3 !== 0 && d4 !== 0;
+}
+/**
+ * Douglas–Peucker around a closed loop, halving the deviation until the result is simple.
+ *
+ * The raw boundary is a walk along cell edges and cannot cross itself, so the loop terminates at
+ * something valid however hostile the shape. The halving is the honest version of "this usually
+ * works": it costs a few extra passes on a shape that needs them and nothing at all on one that
+ * does not.
+ */
+function simplify(raw, maxDeviation, anchors = []) {
+    for (let deviation = maxDeviation; deviation > 1e-4; deviation /= 2) {
+        const candidate = simplifyOnce(raw, deviation, anchors);
+        if (!contourSelfIntersects(candidate))
+            return candidate;
+    }
+    return raw;
+}
+function simplifyOnce(raw, maxDeviation, anchors) {
+    const count = raw.length / 2;
+    if (count < 4)
+        return raw;
+    const keep = new Uint8Array(count);
+    const bridged = anchors.length >= 2;
+    let fixed;
+    if (bridged) {
+        /*
+         * **A bridged loop's anchors are the bridge, and they are not negotiable.** Every chain between
+         * two of them is an ordinary open polyline Douglas–Peucker may do as it likes with; the anchors
+         * are what keep the two traversals of each bridge coincident, which is the whole of what makes
+         * the polygon weakly simple rather than self-overlapping.
+         */
+        fixed = [...anchors].sort((a, b) => a - b);
+    }
+    else {
+        /* Two anchors, so the loop becomes two open chains: the first point and the one furthest. */
+        let far = 0;
+        let farDistance = -1;
+        for (let at = 1; at < count; at += 1) {
+            // determinism: build-time — contour simplification is a bake, never a tick
+            const d = Math.hypot(raw[at * 2] - raw[0], raw[at * 2 + 1] - raw[1]);
+            if (d > farDistance) {
+                farDistance = d;
+                far = at;
+            }
+        }
+        fixed = [0, far];
+    }
+    for (const at of fixed)
+        keep[at] = 1;
+    for (let at = 0; at < fixed.length; at += 1) {
+        const from = fixed[at];
+        const to = at + 1 < fixed.length ? fixed[at + 1] : count;
+        chain(raw, from, to, maxDeviation, keep);
+    }
+    /*
+     * **Only a *bridge* anchor is protected from the collinear pass, never the arbitrary pair.** The
+     * two anchors of an unbridged loop are wherever the trace happened to start and whatever was
+     * furthest from it, so one is routinely a point in the middle of a straight edge — and
+     * `dropCollinear` exists precisely to remove that, which is what keeps an L six-cornered.
+     */
+    const out = [];
+    const protectedOut = [];
+    for (let at = 0; at < count; at += 1) {
+        if (keep[at] !== 1)
+            continue;
+        if (bridged && fixed.includes(at))
+            protectedOut.push(out.length / 2);
+        out.push(raw[at * 2], raw[at * 2 + 1]);
+    }
+    return dropCollinear(Int32Array.from(out), protectedOut);
+}
+/**
+ * Remove any point that lies on the line between its neighbours.
+ *
+ * **The anchors are arbitrary and one of them is always kept**, so without this a loop that happens
+ * to start halfway along an edge carries a seventh point through a six-cornered shape — a vertex
+ * that is not a corner, in a mesh whose polygons are built from these. Removing a collinear point
+ * cannot affect the deviation bound, because a point on the line between its neighbours is at
+ * distance zero from the segment that replaces it.
+ */
+function dropCollinear(points, protect = []) {
+    const count = points.length / 2;
+    if (count < 4)
+        return points;
+    const out = [];
+    for (let at = 0; at < count; at += 1) {
+        /* A bridge endpoint is collinear with its neighbours as often as not, and removing one opens
+           the slit into the rest of the polygon. */
+        if (protect.includes(at)) {
+            out.push(points[at * 2], points[at * 2 + 1]);
+            continue;
+        }
+        const prev = (at + count - 1) % count;
+        const next = (at + 1) % count;
+        const cross = (points[at * 2] - points[prev * 2]) *
+            (points[next * 2 + 1] - points[prev * 2 + 1]) -
+            (points[at * 2 + 1] - points[prev * 2 + 1]) *
+                (points[next * 2] - points[prev * 2]);
+        if (cross === 0)
+            continue;
+        out.push(points[at * 2], points[at * 2 + 1]);
+    }
+    return out.length >= 6 ? Int32Array.from(out) : points;
+}
+/** Mark the points of `raw[from..to]` that have to stay. `to` may be one past the end, meaning wrap. */
+function chain(raw, from, to, maxDeviation, keep) {
+    const count = raw.length / 2;
+    const endIndex = to % count;
+    if (to - from < 2)
+        return;
+    let worst = -1;
+    let worstAt = -1;
+    for (let at = from + 1; at < to; at += 1) {
+        const d = distanceToSegment(raw[at * 2], raw[at * 2 + 1], raw[from * 2], raw[from * 2 + 1], raw[endIndex * 2], raw[endIndex * 2 + 1]);
+        if (d > worst) {
+            worst = d;
+            worstAt = at;
+        }
+    }
+    if (worst <= maxDeviation || worstAt < 0)
+        return;
+    keep[worstAt] = 1;
+    chain(raw, from, worstAt, maxDeviation, keep);
+    chain(raw, worstAt, to, maxDeviation, keep);
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * `@driftengine/nav` — a navigation mesh.
+ *
+ * **This reverses a refusal, and the refused module named its own trigger.**
+ * `core/src/nav/navGraph.ts` says it is a graph rather than a mesh, that this is a decision rather
+ * than a first step, and that *"if a world's walkable space genuinely is a region, this is the
+ * wrong structure and a mesh is the row that is still open."* A streamed open world is that world.
+ *
+ * **The graph is not replaced.** It stays right for the case it was built for — roads, corridors,
+ * rails, docking lanes — which is what consumers kept arriving with, and a mesh would have asked
+ * them to throw that away. Two structures, two shapes of world, one search: the query here builds a
+ * `NavGraph` over polygons and hands it to core's `NavSearch`, so there is one A* in this
+ * repository and not two.
+ *
+ * **Steering is still refused.** §6.5 reverses the refusal of a navigation *mesh*, which is a
+ * function from geometry to a graph. What an agent does with a path stays a game's decision, and
+ * `ai/src/entities/context.ts`'s refusal is upheld on exactly that line.
+ */
+export { columnAt, spanCount, spanFloor, spanWalkable, voxeliseWalkable } from './voxelise.ts';
+export type { NavGeometry, VoxelField, VoxeliseSettings } from './voxelise.ts';
+export { buildRegions, regionOfSpan, regionsLinked, spanIndexAt } from './regions.ts';
+export type { RegionField, RegionSettings } from './regions.ts';
+export { buildContours, contourSelfIntersects, maxDeviationOf } from './contour.ts';
+export type { Contour } from './contour.ts';
+export { NO_NEIGHBOUR, buildPolyMesh, polyArea, polyIsConvex, polyNeighbour, polyVertexCount, } from './polymesh.ts';
+export type { NavPlacement, PolyMesh } from './polymesh.ts';
+export { NavMeshQuery, nearestPoly } from './query.ts';
+export { attachGoal, attachStart, buildPortalGraph } from './portalGraph.ts';
+export type { PortalGraph } from './portalGraph.ts';

package/dist/index.js

@@ -0,0 +1,31 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * `@driftengine/nav` — a navigation mesh.
+ *
+ * **This reverses a refusal, and the refused module named its own trigger.**
+ * `core/src/nav/navGraph.ts` says it is a graph rather than a mesh, that this is a decision rather
+ * than a first step, and that *"if a world's walkable space genuinely is a region, this is the
+ * wrong structure and a mesh is the row that is still open."* A streamed open world is that world.
+ *
+ * **The graph is not replaced.** It stays right for the case it was built for — roads, corridors,
+ * rails, docking lanes — which is what consumers kept arriving with, and a mesh would have asked
+ * them to throw that away. Two structures, two shapes of world, one search: the query here builds a
+ * `NavGraph` over polygons and hands it to core's `NavSearch`, so there is one A* in this
+ * repository and not two.
+ *
+ * **Steering is still refused.** §6.5 reverses the refusal of a navigation *mesh*, which is a
+ * function from geometry to a graph. What an agent does with a path stays a game's decision, and
+ * `ai/src/entities/context.ts`'s refusal is upheld on exactly that line.
+ */
+export { columnAt, spanCount, spanFloor, spanWalkable, voxeliseWalkable } from './voxelise.js';
+export { buildRegions, regionOfSpan, regionsLinked, spanIndexAt } from './regions.js';
+export { buildContours, contourSelfIntersects, maxDeviationOf } from './contour.js';
+export { NO_NEIGHBOUR, buildPolyMesh, polyArea, polyIsConvex, polyNeighbour, polyVertexCount, } from './polymesh.js';
+export { NavMeshQuery, nearestPoly } from './query.js';
+/*
+ * **The graph is over portals, not polygons**, which is what makes a path the shortest one rather
+ * than one about a tenth longer. `portalGraph.ts` carries the argument and the measurement that
+ * opened it; `buildPolyGraph` is gone, because a node per polygon optimises a quantity no agent
+ * walks and there is no reason to keep a second graph that does.
+ */
+export { attachGoal, attachStart, buildPortalGraph } from './portalGraph.js';

package/dist/polymesh.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Contours to convex polygons that tile the region and border each other both ways.
+ *
+ * **Convex, because the funnel algorithm is what makes a path a straight line** and it walks a
+ * corridor of convex cells. A concave polygon has an interior point the straight line between two
+ * of its own vertices leaves, so the funnel would produce a path through a wall.
+ *
+ * **Adjacency is built from shared edges in both directions at once**, because a one-directional
+ * build breaks silently: what it produces is a mesh where a path from A to B exists and the same
+ * path from B to A does not, which reads as a pathfinding bug and is a mesh-building one.
+ *
+ * Ear clipping first, then merge neighbours while the result stays convex. Triangles are convex by
+ * definition, so the merge can only ever improve the mesh and never make it invalid — which is why
+ * it can be a plain greedy pass with no backtracking.
+ */
+import type { Contour } from './contour.ts';
+export declare const NO_NEIGHBOUR = -1;
+/**
+ * Where a mesh stands in the world: a vertex at cell `(i, j)` is at `originX + i * cellSize`,
+ * `originZ + j * cellSize`. A `VoxelField` is one, which is what `buildPolyMesh` is meant to be
+ * handed.
+ */
+export interface NavPlacement {
+    /** x, y, z of the field's corner; y is not used, since a polygon mesh has none. */
+    readonly origin: ArrayLike<number>;
+    readonly cellSize: number;
+}
+export interface PolyMesh {
+    /** x,z per vertex, in cell units. `originX`, `originZ` and `cellSize` turn them into metres. */
+    readonly vertices: Int32Array;
+    readonly vertexCount: number;
+    /** `maxVertsPerPoly` slots per polygon, padded with `-1`. */
+    readonly polys: Int32Array;
+    /** The polygon across each edge, or `-1`. Same layout as `polys`: edge `i` leaves vertex `i`. */
+    readonly neighbours: Int32Array;
+    readonly polyCount: number;
+    readonly maxVertsPerPoly: number;
+    /** Which region each polygon came from. */
+    readonly polyRegion: Int32Array;
+    /**
+     * **Where the mesh stands, kept with it.** The field it was built from knew and the mesh used to
+     * drop it, so a query given positions in metres compared them with cell indices and answered in
+     * a mixture of the two — invisible to every test that built its field at the origin with one-unit
+     * cells, where the two are the same number.
+     */
+    readonly originX: number;
+    readonly originZ: number;
+    readonly cellSize: number;
+}
+export declare function polyVertexCount(mesh: PolyMesh, poly: number): number;
+export declare function polyNeighbour(mesh: PolyMesh, poly: number, edge: number): number;
+/** The shoelace area, which is positive for the winding this builds and zero for a degenerate. */
+export declare function polyArea(mesh: PolyMesh, poly: number): number;
+export declare function polyIsConvex(mesh: PolyMesh, poly: number): boolean;
+export declare function buildPolyMesh(contours: readonly Contour[], maxVertsPerPoly: number, placement: NavPlacement): PolyMesh;