@driftengine/nav 4.7.0 → 4.7.2

package/README.md

@@ -2,7 +2,7 @@
 
 A navigation mesh: geometry in, convex walkable polygons out, and a straight line across them.
 
-**8,393 bytes gzipped**, measured by `scripts/size-gate.test.mjs` against
+**9,058 bytes gzipped**, measured by `scripts/size-gate.test.mjs` against
 `scripts/fixtures/size/nav-only.ts`. Optional — nothing in `@driftengine/core` imports it, so a game
 that does not path pays nothing.
 
@@ -36,6 +36,7 @@ const field = voxeliseWalkable(geometry, {
   maxSlope: 45,
   agentHeight: 2,
   agentRadius: 0.5,
+  maxStep: 1,
 });
 const regions = buildRegions(field, { minRegionSpans: 8, maxStep: 1 });
 const mesh = buildPolyMesh(buildContours(field, regions, 1.3), 6, field);
@@ -53,11 +54,28 @@ it has two components, and an agent that asks for the other side has to be told.
 - **Steering.** §6.5 of the design 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.
-- **Holes.** `buildContours` takes a region's outer loop and drops any inner one, so a room with a
-  free-standing pillar becomes a room and an agent walks through the pillar. There is a test that
-  pins that behaviour rather than a comment that hopes about it. The fix is a bridge edge joining
-  the inner loop to the outer; until it is built, leave a gap between a pillar and the floor so the
-  watershed splits around it.
-- **Optimal paths.** The funnel gives the shortest path through the corridor A* chose, and the
-  corridor comes from polygon centres. On the wall in `query.test.ts` that is 10.75 against an ideal
-  9.81 — about a tenth, from the region split putting a portal corner a cell below the wall's foot.
+- **A closed box's inside.** A column inside a box meets the floor, the box's bottom and its top,
+  and nothing there says the space between is solid short of trusting every mesh's winding. So the
+  floor a closed box encloses stays walkable: an island inside the box's walls that no route from
+  outside reaches, but `nearestPoly` can still snap a point beside the box onto it. A test pins it.
+- **More than one layer of polygons.** The voxel field keeps both floors under a bridge, and the
+  regions keep them apart, but a contour follows the lowest walkable span in each column, so where
+  two floors overlap only the lower one becomes polygons.
+
+## Walls, pillars and the shortest way round
+
+- **A wall is a solid.** A face too steep to stand on is clipped to every cell it crosses and
+  stands in that column as a solid, so a building on the ground blocks, and so does a wall with no
+  thickness and no top. Erosion judges a neighbour at the span's own height, so the agent keeps its
+  radius from a wall even when the wall's top is walkable, and from a ledge higher than `maxStep`.
+  Give the voxeliser the same `maxStep` as `buildRegions`: the polygons are flat, so two edges that
+  touch are a portal whatever their heights, and erosion is what keeps a floor and a ledge apart.
+- **A shared border is one line.** A room the watershed splits is several regions, and a portal is
+  where two polygons' edges overlap. The points where a border changes what it faces are held in
+  every outline through them, and each stretch between is simplified the same way from both sides,
+  so the regions meet edge to edge at any deviation.
+- **A pillar is a hole.** A region's inner loops are bridged into its outline, so a path goes round
+  a free-standing pillar and no polygon claims the ground under it.
+- **A path is the shortest way round.** The search runs over portals, the overlaps between
+  neighbouring polygons' edges, so the corridor it hands the funnel holds the shortest path: 9.81
+  on the wall in `query.test.ts`, where a search over polygon centres gives 10.75.

package/dist/contour.js

@@ -40,7 +40,7 @@ function regionAtColumn(field, regions, x, z) {
  * are coincident.
  */
 export function buildContours(field, regions, maxDeviation) {
-    const out = [];
+    const traced = [];
     for (let region = 0; region < regions.count; region += 1) {
         const edges = [];
         for (let z = 0; z < field.depth; z += 1) {
@@ -78,10 +78,67 @@ export function buildContours(field, regions, maxDeviation) {
          * fixes it exactly.
          */
         const bridged = bridgeHoles(loops);
-        const raw = Int32Array.from(bridged.loop);
-        out.push({ region, points: simplify(raw, maxDeviation, bridged.anchors), raw });
+        traced.push({ region, raw: Int32Array.from(bridged.loop), bridges: bridged.anchors });
+    }
+    /*
+     * **A border two regions share has to come out of simplification the same from both sides.** A
+     * portal is where two polygons' edges overlap, and each region's outline was simplified on its
+     * own: a jagged border between two regions came out as two different lines, which overlap
+     * nowhere, and a room the watershed had split was islands with no route between them. On a 16 by
+     * 10 room with a pillar, simplified to 1.3, there were two regions and no path across.
+     *
+     * So the points where a border changes what it faces are held in every loop that passes through
+     * them, which makes each stretch between two held points one border with the same two ends from
+     * both sides; a bridge's ends are held everywhere for the same reason, since the region on the
+     * far side of a hole meets them too. Each stretch is simplified in one canonical direction, so
+     * both sides take the same points. And the halving that keeps a loop from crossing itself is
+     * applied to every region together, because a shared stretch simplified at two deviations is two
+     * lines again. One awkward region makes every outline finer, which costs vertices and nothing
+     * else.
+     */
+    const bridgeEnds = new Set();
+    for (const { raw, bridges } of traced) {
+        for (const at of bridges)
+            bridgeEnds.add(`${raw[at * 2]},${raw[at * 2 + 1]}`);
     }
-    return out;
+    const held = traced.map(({ raw }) => {
+        const indices = [];
+        for (let at = 0; at < raw.length / 2; at += 1) {
+            const x = raw[at * 2];
+            const z = raw[at * 2 + 1];
+            if (bridgeEnds.has(`${x},${z}`) || isJunction(field, regions, x, z))
+                indices.push(at);
+        }
+        return indices;
+    });
+    for (let deviation = maxDeviation; deviation > 1e-4; deviation /= 2) {
+        const simplified = traced.map(({ raw }, at) => simplifyOnce(raw, deviation, held[at] ?? []));
+        if (simplified.some(contourSelfIntersects))
+            continue;
+        return traced.map(({ region, raw }, at) => ({
+            region,
+            points: simplified[at],
+            raw,
+        }));
+    }
+    return traced.map(({ region, raw }) => ({ region, points: raw, raw }));
+}
+/**
+ * Whether three or more different things meet at a cell corner: regions, or regions and nothing.
+ *
+ * Where a region's boundary stops facing one thing and starts facing another, the corner has the
+ * region and both of those around it, and that is the only way three can meet. So this is exactly
+ * the set of points where some loop through the corner changes what it borders, decided from the
+ * field alone, which is what lets every loop through it agree.
+ */
+function isJunction(field, regions, x, z) {
+    const around = [
+        regionAtColumn(field, regions, x - 1, z - 1),
+        regionAtColumn(field, regions, x, z - 1),
+        regionAtColumn(field, regions, x - 1, z),
+        regionAtColumn(field, regions, x, z),
+    ];
+    return new Set(around).size >= 3;
 }
 /**
  * Follow the directed edges into closed loops.
@@ -391,36 +448,27 @@ function segmentsCross(ax, az, bx, bz, cx, cz, dx, dz) {
     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.
+ * Douglas–Peucker around a closed loop, holding `held` and simplifying the stretches between.
  *
- * 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.
+ * `buildContours` halves the deviation until no loop crosses itself. The raw boundary is a walk
+ * along cell edges and cannot cross itself, so that terminates at something valid however hostile
+ * the shape: it costs a few extra passes on a shape that needs them and nothing 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) {
+function simplifyOnce(raw, maxDeviation, held) {
     const count = raw.length / 2;
     if (count < 4)
         return raw;
     const keep = new Uint8Array(count);
-    const bridged = anchors.length >= 2;
     let fixed;
-    if (bridged) {
+    if (held.length > 0) {
         /*
-         * **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.
+         * **Held points are a bridge or a change of neighbour, and they are not negotiable.** Every
+         * stretch between two of them is an open polyline Douglas–Peucker may do as it likes with; the
+         * held points are what keep the two traversals of each bridge coincident, and each shared
+         * border the same from both of its regions.
          */
-        fixed = [...anchors].sort((a, b) => a - b);
+        fixed = [...held];
     }
     else {
         /* Two anchors, so the loop becomes two open chains: the first point and the one furthest. */
@@ -440,12 +488,12 @@ function simplifyOnce(raw, maxDeviation, anchors) {
         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);
+        const to = at + 1 < fixed.length ? fixed[at + 1] : fixed[0] + count;
+        stretch(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
+     * **Only a *held* point is protected from the collinear pass, never the arbitrary pair.** The two
+     * anchors of a loop with nothing held 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.
      */
@@ -454,7 +502,7 @@ function simplifyOnce(raw, maxDeviation, anchors) {
     for (let at = 0; at < count; at += 1) {
         if (keep[at] !== 1)
             continue;
-        if (bridged && fixed.includes(at))
+        if (held.length > 0 && fixed.includes(at))
             protectedOut.push(out.length / 2);
         out.push(raw[at * 2], raw[at * 2 + 1]);
     }
@@ -493,16 +541,50 @@ function dropCollinear(points, protect = []) {
     }
     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) {
+/**
+ * Mark the points of `raw` from `from` to `to` that have to stay. `to` may pass the end, which
+ * wraps; `to` equal to `from` plus the loop's length is the whole loop from one held point.
+ *
+ * **Walked in one canonical direction, whichever way the loop runs**, so a border two regions
+ * share, which each traces the other way round, keeps the same points from both sides: the
+ * stretch runs from its lesser end to its greater, comparing x then z, and a stretch that starts
+ * and ends at one point runs toward the lesser of its two neighbours.
+ */
+function stretch(raw, from, to, maxDeviation, keep) {
     const count = raw.length / 2;
-    const endIndex = to % count;
     if (to - from < 2)
         return;
+    const order = [];
+    for (let at = from; at <= to; at += 1)
+        order.push(at % count);
+    const last = order.length - 1;
+    const first = order[0];
+    const end = order[last];
+    const sameEnds = raw[first * 2] === raw[end * 2] && raw[first * 2 + 1] === raw[end * 2 + 1];
+    const backwards = sameEnds
+        ? lesser(raw, order[last - 1], order[1])
+        : lesser(raw, end, first);
+    if (backwards)
+        order.reverse();
+    douglasPeucker(raw, order, 0, last, maxDeviation, keep);
+}
+/** Whether point `a` comes before point `b`, by x and then by z. */
+function lesser(raw, a, b) {
+    const ax = raw[a * 2];
+    const bx = raw[b * 2];
+    return ax < bx || (ax === bx && raw[a * 2 + 1] < raw[b * 2 + 1]);
+}
+/** Keep the furthest point of `order` between `lo` and `hi` while it is further than the bound. */
+function douglasPeucker(raw, order, lo, hi, maxDeviation, keep) {
+    if (hi - lo < 2)
+        return;
+    const a = order[lo];
+    const b = order[hi];
     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]);
+    for (let at = lo + 1; at < hi; at += 1) {
+        const point = order[at];
+        const d = distanceToSegment(raw[point * 2], raw[point * 2 + 1], raw[a * 2], raw[a * 2 + 1], raw[b * 2], raw[b * 2 + 1]);
         if (d > worst) {
             worst = d;
             worstAt = at;
@@ -510,7 +592,7 @@ function chain(raw, from, to, maxDeviation, keep) {
     }
     if (worst <= maxDeviation || worstAt < 0)
         return;
-    keep[worstAt] = 1;
-    chain(raw, from, worstAt, maxDeviation, keep);
-    chain(raw, worstAt, to, maxDeviation, keep);
+    keep[order[worstAt]] = 1;
+    douglasPeucker(raw, order, lo, worstAt, maxDeviation, keep);
+    douglasPeucker(raw, order, worstAt, hi, maxDeviation, keep);
 }

package/dist/voxelise.d.ts

@@ -34,6 +34,16 @@ export interface VoxeliseSettings {
     readonly agentHeight: number;
     /** How far from an edge an agent's centre must stay. */
     readonly agentRadius: number;
+    /**
+     * How many cells of height an agent can step across, the number `buildRegions` takes; 1 when
+     * absent. A neighbour further above or below than this is an edge, and erosion keeps the agent's
+     * radius from it.
+     *
+     * **Here as well as there because the polygons are flat.** Two regions whose edges touch are
+     * joined by a portal whatever their heights, so a floor and a ledge above it must be kept apart
+     * by erosion, or a route goes over the ledge.
+     */
+    readonly maxStep?: number;
 }
 /**
  * Walkable surfaces as spans, in columns on a horizontal grid.

package/dist/voxelise.js

@@ -59,6 +59,10 @@ export function spanWalkable(field, x, z, at) {
         return false;
     return field.spans[base + 2] === 1;
 }
+/** Scratch for clipping a triangle to one cell: four planes leave at most seven vertices. */
+const CLIP_IN = new Float64Array(8 * 3);
+const CLIP_OUT = new Float64Array(8 * 3);
+const HEIGHTS = new Float64Array(2);
 /**
  * Rasterise, then decide.
  *
@@ -116,18 +120,89 @@ export function voxeliseWalkable(geometry, settings) {
         const hiZ = Math.min(depth - 1, Math.floor((Math.max(az, bz, cz) - minZ) / settings.cellSize));
         for (let gz = loZ; gz <= hiZ; gz += 1) {
             for (let gx = loX; gx <= hiX; gx += 1) {
-                const px = minX + (gx + 0.5) * settings.cellSize;
-                const pz = minZ + (gz + 0.5) * settings.cellSize;
-                const height = heightAt(ax, ay, az, bx, by, bz, cx, cy, cz, px, pz);
-                if (height === null)
+                if (walkable) {
+                    const px = minX + (gx + 0.5) * settings.cellSize;
+                    const pz = minZ + (gz + 0.5) * settings.cellSize;
+                    const height = heightAt(ax, ay, az, bx, by, bz, cx, cy, cz, px, pz);
+                    if (height === null)
+                        continue;
+                    const floor = Math.floor((height - minY) / settings.cellHeight);
+                    columns[gx + gz * width]?.push({ bottom: floor, top: floor, walkable });
                     continue;
-                const floor = Math.floor((height - minY) / settings.cellHeight);
-                columns[gx + gz * width]?.push({ floor, walkable });
+                }
+                /*
+                 * **A face too steep to stand on is a solid, over every cell it crosses.** Sampled at the
+                 * cell's centre like a floor, a wall is never met at all: it is vertical, so it covers no
+                 * area seen from above, and a building on the ground read as a roof over open floor that a
+                 * route went straight through. So the face is clipped to the cell's square, and the heights
+                 * it spans there stand in the column as one solid, whose top is not walkable.
+                 */
+                const x0 = minX + gx * settings.cellSize;
+                const z0 = minZ + gz * settings.cellSize;
+                CLIP_IN.set([ax, ay, az, bx, by, bz, cx, cy, cz]);
+                if (!clipToCell(x0, x0 + settings.cellSize, z0, z0 + settings.cellSize, HEIGHTS)) {
+                    continue;
+                }
+                columns[gx + gz * width]?.push({
+                    bottom: Math.floor((HEIGHTS[0] - minY) / settings.cellHeight),
+                    top: Math.floor((HEIGHTS[1] - minY) / settings.cellHeight),
+                    walkable: false,
+                });
             }
         }
     }
     return pack(columns, width, depth, origin, settings);
 }
+/**
+ * The lowest and highest heights of the triangle in `CLIP_IN` within one cell's square, written to
+ * `out`; false where the triangle misses the cell.
+ *
+ * Sutherland–Hodgman against the square's four sides. Inclusive, so a wall lying exactly on a cell
+ * boundary still lands in the cell the bounding box chose for it.
+ */
+function clipToCell(x0, x1, z0, z1, out) {
+    let count = 3;
+    count = clipSide(CLIP_IN, count, CLIP_OUT, 0, x0, 1);
+    count = clipSide(CLIP_OUT, count, CLIP_IN, 0, x1, -1);
+    count = clipSide(CLIP_IN, count, CLIP_OUT, 2, z0, 1);
+    count = clipSide(CLIP_OUT, count, CLIP_IN, 2, z1, -1);
+    if (count === 0)
+        return false;
+    let low = Infinity;
+    let high = -Infinity;
+    for (let at = 0; at < count; at += 1) {
+        const y = CLIP_IN[at * 3 + 1];
+        low = Math.min(low, y);
+        high = Math.max(high, y);
+    }
+    out[0] = low;
+    out[1] = high;
+    return true;
+}
+/** Keep the part of a polygon on one side of `axis = bound`: above it for `side` 1, below for -1. */
+function clipSide(from, count, to, axis, bound, side) {
+    let written = 0;
+    for (let at = 0; at < count; at += 1) {
+        const next = (at + 1) % count;
+        const here = (from[at * 3 + axis] - bound) * side;
+        const there = (from[next * 3 + axis] - bound) * side;
+        if (here >= 0) {
+            to[written * 3] = from[at * 3];
+            to[written * 3 + 1] = from[at * 3 + 1];
+            to[written * 3 + 2] = from[at * 3 + 2];
+            written += 1;
+        }
+        if (here >= 0 !== there >= 0) {
+            const t = here / (here - there);
+            for (let k = 0; k < 3; k += 1) {
+                const a = from[at * 3 + k];
+                to[written * 3 + k] = a + (from[next * 3 + k] - a) * t;
+            }
+            written += 1;
+        }
+    }
+    return written;
+}
 /**
  * The triangle's height at (px, pz), or null where the point is outside it.
  *
@@ -157,20 +232,34 @@ function pack(columns, width, depth, origin, settings) {
     const headroom = Math.ceil(settings.agentHeight / settings.cellHeight);
     const merged = [];
     for (const samples of columns) {
-        samples.sort((a, b) => a.floor - b.floor || Number(a.walkable) - Number(b.walkable));
+        samples.sort((a, b) => a.bottom - b.bottom || a.top - b.top || Number(a.walkable) - Number(b.walkable));
         const spans = [];
+        /* Where each span's solid starts, which is the ceiling of the span below it. */
+        const bottoms = [];
         for (const sample of samples) {
             const last = spans.length - SPAN_STRIDE;
-            /* Samples within one cell of each other are one surface, not two. */
-            if (last >= 0 && sample.floor - spans[last] <= 1) {
-                spans[last + 2] = spans[last + 2] | (sample.walkable ? 1 : 0);
+            const top = spans[last];
+            /*
+             * A sample starting within one cell of a span's top is part of that solid, not a new one.
+             * The span stands on the highest top, and is walkable if anything ending within a cell of
+             * that top is: a wall rising past a floor takes the floor over, and a floor's two triangles
+             * at one height agree.
+             */
+            if (last >= 0 && sample.bottom - top <= 1) {
+                const flag = sample.walkable ? 1 : 0;
+                if (sample.top > top + 1)
+                    spans[last + 2] = flag;
+                else if (sample.top >= top - 1)
+                    spans[last + 2] = spans[last + 2] | flag;
+                spans[last] = Math.max(top, sample.top);
                 continue;
             }
-            spans.push(sample.floor, Number.MAX_SAFE_INTEGER, sample.walkable ? 1 : 0);
+            spans.push(sample.top, Number.MAX_SAFE_INTEGER, sample.walkable ? 1 : 0);
+            bottoms.push(sample.bottom);
         }
-        /* A span's ceiling is the next span's floor. The topmost has open sky. */
-        for (let at = 0; at + SPAN_STRIDE < spans.length; at += SPAN_STRIDE) {
-            spans[at + 1] = spans[at + SPAN_STRIDE];
+        /* A span's ceiling is where the next solid starts. The topmost has open sky. */
+        for (let at = 0, next = 1; at + SPAN_STRIDE < spans.length; at += SPAN_STRIDE, next += 1) {
+            spans[at + 1] = bottoms[next];
             if (spans[at + 1] - spans[at] < headroom)
                 spans[at + 2] = 0;
         }
@@ -209,28 +298,43 @@ function pack(columns, width, depth, origin, settings) {
  * doing it as that many single-cell passes keeps the whole thing integer arithmetic with no
  * distance to round. **Copied per pass**, because eroding in place erodes into what the same pass
  * just cleared and eats the mesh from its edges inward.
+ *
+ * **A neighbour is judged at this span's height, not anywhere in its column.** Asked whether a
+ * neighbouring column had any walkable span at all, a wall answered yes, with the roof on top of
+ * it, and the floor beside the wall kept no margin. A neighbour counts as open when it has a
+ * walkable span within `maxStep` of this one, a step the agent can take. Further than that is a
+ * wall, a ledge or a drop, and the agent keeps its radius from it.
  */
 function erode(columns, width, depth, settings) {
     const steps = Math.ceil(settings.agentRadius / settings.cellSize);
+    const reach = settings.maxStep ?? 1;
     for (let pass = 0; pass < steps; pass += 1) {
         const before = columns.map((column) => [...column]);
-        const open = (gx, gz) => {
+        const open = (gx, gz, floor) => {
             if (gx < 0 || gz < 0 || gx >= width || gz >= depth)
                 return false;
             const column = before[gx + gz * width];
             for (let at = 0; at < column.length; at += SPAN_STRIDE) {
-                if (column[at + 2] === 1)
+                if (column[at + 2] === 1 && Math.abs(column[at] - floor) <= reach)
                     return true;
             }
             return false;
         };
         for (let gz = 0; gz < depth; gz += 1) {
             for (let gx = 0; gx < width; gx += 1) {
-                if (open(gx - 1, gz) && open(gx + 1, gz) && open(gx, gz - 1) && open(gx, gz + 1))
-                    continue;
                 const column = columns[gx + gz * width];
-                for (let at = 0; at < column.length; at += SPAN_STRIDE)
+                for (let at = 0; at < column.length; at += SPAN_STRIDE) {
+                    if (column[at + 2] !== 1)
+                        continue;
+                    const floor = column[at];
+                    if (open(gx - 1, gz, floor) &&
+                        open(gx + 1, gz, floor) &&
+                        open(gx, gz - 1, floor) &&
+                        open(gx, gz + 1, floor)) {
+                        continue;
+                    }
                     column[at + 2] = 0;
+                }
             }
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/nav",
-  "version": "4.7.0",
+  "version": "4.7.2",
   "description": "A navigation mesh: geometry to walkable convex polygons, and a straight line across them",
   "license": "Apache-2.0",
   "type": "module",
@@ -53,6 +53,6 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/nav"
   },
   "dependencies": {
-    "@driftengine/core": "4.7.0"
+    "@driftengine/core": "4.7.2"
   }
 }

package/src/contour.ts

@@ -69,7 +69,7 @@ export function buildContours(
   regions: RegionField,
   maxDeviation: number,
 ): Contour[] {
-  const out: Contour[] = [];
+  const traced: { region: number; raw: Int32Array; bridges: number[] }[] = [];
   for (let region = 0; region < regions.count; region += 1) {
     const edges: Edge[] = [];
     for (let z = 0; z < field.depth; z += 1) {
@@ -105,10 +105,67 @@ export function buildContours(
      * fixes it exactly.
      */
     const bridged = bridgeHoles(loops);
-    const raw = Int32Array.from(bridged.loop);
-    out.push({ region, points: simplify(raw, maxDeviation, bridged.anchors), raw });
+    traced.push({ region, raw: Int32Array.from(bridged.loop), bridges: bridged.anchors });
   }
-  return out;
+
+  /*
+   * **A border two regions share has to come out of simplification the same from both sides.** A
+   * portal is where two polygons' edges overlap, and each region's outline was simplified on its
+   * own: a jagged border between two regions came out as two different lines, which overlap
+   * nowhere, and a room the watershed had split was islands with no route between them. On a 16 by
+   * 10 room with a pillar, simplified to 1.3, there were two regions and no path across.
+   *
+   * So the points where a border changes what it faces are held in every loop that passes through
+   * them, which makes each stretch between two held points one border with the same two ends from
+   * both sides; a bridge's ends are held everywhere for the same reason, since the region on the
+   * far side of a hole meets them too. Each stretch is simplified in one canonical direction, so
+   * both sides take the same points. And the halving that keeps a loop from crossing itself is
+   * applied to every region together, because a shared stretch simplified at two deviations is two
+   * lines again. One awkward region makes every outline finer, which costs vertices and nothing
+   * else.
+   */
+  const bridgeEnds = new Set<string>();
+  for (const { raw, bridges } of traced) {
+    for (const at of bridges) bridgeEnds.add(`${raw[at * 2]},${raw[at * 2 + 1]}`);
+  }
+  const held = traced.map(({ raw }) => {
+    const indices: number[] = [];
+    for (let at = 0; at < raw.length / 2; at += 1) {
+      const x = raw[at * 2] as number;
+      const z = raw[at * 2 + 1] as number;
+      if (bridgeEnds.has(`${x},${z}`) || isJunction(field, regions, x, z)) indices.push(at);
+    }
+    return indices;
+  });
+
+  for (let deviation = maxDeviation; deviation > 1e-4; deviation /= 2) {
+    const simplified = traced.map(({ raw }, at) => simplifyOnce(raw, deviation, held[at] ?? []));
+    if (simplified.some(contourSelfIntersects)) continue;
+    return traced.map(({ region, raw }, at) => ({
+      region,
+      points: simplified[at] as Int32Array,
+      raw,
+    }));
+  }
+  return traced.map(({ region, raw }) => ({ region, points: raw, raw }));
+}
+
+/**
+ * Whether three or more different things meet at a cell corner: regions, or regions and nothing.
+ *
+ * Where a region's boundary stops facing one thing and starts facing another, the corner has the
+ * region and both of those around it, and that is the only way three can meet. So this is exactly
+ * the set of points where some loop through the corner changes what it borders, decided from the
+ * field alone, which is what lets every loop through it agree.
+ */
+function isJunction(field: VoxelField, regions: RegionField, x: number, z: number): boolean {
+  const around = [
+    regionAtColumn(field, regions, x - 1, z - 1),
+    regionAtColumn(field, regions, x, z - 1),
+    regionAtColumn(field, regions, x - 1, z),
+    regionAtColumn(field, regions, x, z),
+  ];
+  return new Set(around).size >= 3;
 }
 
 /** One side of one cell, pointing so the region stays on the same hand throughout. */
@@ -495,44 +552,27 @@ function segmentsCross(
 }
 
 /**
- * Douglas–Peucker around a closed loop, halving the deviation until the result is simple.
+ * Douglas–Peucker around a closed loop, holding `held` and simplifying the stretches between.
  *
- * 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.
+ * `buildContours` halves the deviation until no loop crosses itself. The raw boundary is a walk
+ * along cell edges and cannot cross itself, so that terminates at something valid however hostile
+ * the shape: it costs a few extra passes on a shape that needs them and nothing on one that does
+ * not.
  */
-function simplify(
-  raw: Int32Array,
-  maxDeviation: number,
-  anchors: readonly number[] = [],
-): Int32Array {
-  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: Int32Array,
-  maxDeviation: number,
-  anchors: readonly number[],
-): Int32Array {
+function simplifyOnce(raw: Int32Array, maxDeviation: number, held: readonly number[]): Int32Array {
   const count = raw.length / 2;
   if (count < 4) return raw;
 
   const keep = new Uint8Array(count);
-  const bridged = anchors.length >= 2;
   let fixed: number[];
-  if (bridged) {
+  if (held.length > 0) {
     /*
-     * **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.
+     * **Held points are a bridge or a change of neighbour, and they are not negotiable.** Every
+     * stretch between two of them is an open polyline Douglas–Peucker may do as it likes with; the
+     * held points are what keep the two traversals of each bridge coincident, and each shared
+     * border the same from both of its regions.
      */
-    fixed = [...anchors].sort((a, b) => a - b);
+    fixed = [...held];
   } else {
     /* Two anchors, so the loop becomes two open chains: the first point and the one furthest. */
     let far = 0;
@@ -554,13 +594,13 @@ function simplifyOnce(
   for (const at of fixed) keep[at] = 1;
   for (let at = 0; at < fixed.length; at += 1) {
     const from = fixed[at] as number;
-    const to = at + 1 < fixed.length ? (fixed[at + 1] as number) : count;
-    chain(raw, from, to, maxDeviation, keep);
+    const to = at + 1 < fixed.length ? (fixed[at + 1] as number) : (fixed[0] as number) + count;
+    stretch(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
+   * **Only a *held* point is protected from the collinear pass, never the arbitrary pair.** The two
+   * anchors of a loop with nothing held 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.
    */
@@ -568,7 +608,7 @@ function simplifyOnce(
   const protectedOut: number[] = [];
   for (let at = 0; at < count; at += 1) {
     if (keep[at] !== 1) continue;
-    if (bridged && fixed.includes(at)) protectedOut.push(out.length / 2);
+    if (held.length > 0 && fixed.includes(at)) protectedOut.push(out.length / 2);
     out.push(raw[at * 2] as number, raw[at * 2 + 1] as number);
   }
   return dropCollinear(Int32Array.from(out), protectedOut);
@@ -607,8 +647,16 @@ function dropCollinear(points: Int32Array, protect: readonly number[] = []): Int
   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(
+/**
+ * Mark the points of `raw` from `from` to `to` that have to stay. `to` may pass the end, which
+ * wraps; `to` equal to `from` plus the loop's length is the whole loop from one held point.
+ *
+ * **Walked in one canonical direction, whichever way the loop runs**, so a border two regions
+ * share, which each traces the other way round, keeps the same points from both sides: the
+ * stretch runs from its lesser end to its greater, comparing x then z, and a stretch that starts
+ * and ends at one point runs toward the lesser of its two neighbours.
+ */
+function stretch(
   raw: Int32Array,
   from: number,
   to: number,
@@ -616,19 +664,50 @@ function chain(
   keep: Uint8Array,
 ): void {
   const count = raw.length / 2;
-  const endIndex = to % count;
   if (to - from < 2) return;
+  const order: number[] = [];
+  for (let at = from; at <= to; at += 1) order.push(at % count);
+  const last = order.length - 1;
+  const first = order[0] as number;
+  const end = order[last] as number;
+  const sameEnds = raw[first * 2] === raw[end * 2] && raw[first * 2 + 1] === raw[end * 2 + 1];
+  const backwards = sameEnds
+    ? lesser(raw, order[last - 1] as number, order[1] as number)
+    : lesser(raw, end, first);
+  if (backwards) order.reverse();
+  douglasPeucker(raw, order, 0, last, maxDeviation, keep);
+}
+
+/** Whether point `a` comes before point `b`, by x and then by z. */
+function lesser(raw: Int32Array, a: number, b: number): boolean {
+  const ax = raw[a * 2] as number;
+  const bx = raw[b * 2] as number;
+  return ax < bx || (ax === bx && (raw[a * 2 + 1] as number) < (raw[b * 2 + 1] as number));
+}
 
+/** Keep the furthest point of `order` between `lo` and `hi` while it is further than the bound. */
+function douglasPeucker(
+  raw: Int32Array,
+  order: readonly number[],
+  lo: number,
+  hi: number,
+  maxDeviation: number,
+  keep: Uint8Array,
+): void {
+  if (hi - lo < 2) return;
+  const a = order[lo] as number;
+  const b = order[hi] as number;
   let worst = -1;
   let worstAt = -1;
-  for (let at = from + 1; at < to; at += 1) {
+  for (let at = lo + 1; at < hi; at += 1) {
+    const point = order[at] as number;
     const d = distanceToSegment(
-      raw[at * 2] as number,
-      raw[at * 2 + 1] as number,
-      raw[from * 2] as number,
-      raw[from * 2 + 1] as number,
-      raw[endIndex * 2] as number,
-      raw[endIndex * 2 + 1] as number,
+      raw[point * 2] as number,
+      raw[point * 2 + 1] as number,
+      raw[a * 2] as number,
+      raw[a * 2 + 1] as number,
+      raw[b * 2] as number,
+      raw[b * 2 + 1] as number,
     );
     if (d > worst) {
       worst = d;
@@ -636,7 +715,7 @@ function chain(
     }
   }
   if (worst <= maxDeviation || worstAt < 0) return;
-  keep[worstAt] = 1;
-  chain(raw, from, worstAt, maxDeviation, keep);
-  chain(raw, worstAt, to, maxDeviation, keep);
+  keep[order[worstAt] as number] = 1;
+  douglasPeucker(raw, order, lo, worstAt, maxDeviation, keep);
+  douglasPeucker(raw, order, worstAt, hi, maxDeviation, keep);
 }

package/src/voxelise.ts

@@ -36,6 +36,16 @@ export interface VoxeliseSettings {
   readonly agentHeight: number;
   /** How far from an edge an agent's centre must stay. */
   readonly agentRadius: number;
+  /**
+   * How many cells of height an agent can step across, the number `buildRegions` takes; 1 when
+   * absent. A neighbour further above or below than this is an edge, and erosion keeps the agent's
+   * radius from it.
+   *
+   * **Here as well as there because the polygons are flat.** Two regions whose edges touch are
+   * joined by a portal whatever their heights, so a floor and a ledge above it must be kept apart
+   * by erosion, or a route goes over the ledge.
+   */
+  readonly maxStep?: number;
 }
 
 /** Words per span: floor cell, ceiling cell, walkable. */
@@ -103,12 +113,21 @@ export function spanWalkable(field: VoxelField, x: number, z: number, at: number
   return field.spans[base + 2] === 1;
 }
 
-/** One rasterised sample before the columns are packed. */
+/**
+ * One rasterised sample before the columns are packed: a solid from `bottom` to `top`, in cells,
+ * and whether its top can be stood on. A floor is a solid of no height.
+ */
 interface Sample {
-  floor: number;
+  bottom: number;
+  top: number;
   walkable: boolean;
 }
 
+/** Scratch for clipping a triangle to one cell: four planes leave at most seven vertices. */
+const CLIP_IN = new Float64Array(8 * 3);
+const CLIP_OUT = new Float64Array(8 * 3);
+const HEIGHTS = new Float64Array(2);
+
 /**
  * Rasterise, then decide.
  *
@@ -172,12 +191,33 @@ export function voxeliseWalkable(geometry: NavGeometry, settings: VoxeliseSettin
 
     for (let gz = loZ; gz <= hiZ; gz += 1) {
       for (let gx = loX; gx <= hiX; gx += 1) {
-        const px = minX + (gx + 0.5) * settings.cellSize;
-        const pz = minZ + (gz + 0.5) * settings.cellSize;
-        const height = heightAt(ax, ay, az, bx, by, bz, cx, cy, cz, px, pz);
-        if (height === null) continue;
-        const floor = Math.floor((height - minY) / settings.cellHeight);
-        columns[gx + gz * width]?.push({ floor, walkable });
+        if (walkable) {
+          const px = minX + (gx + 0.5) * settings.cellSize;
+          const pz = minZ + (gz + 0.5) * settings.cellSize;
+          const height = heightAt(ax, ay, az, bx, by, bz, cx, cy, cz, px, pz);
+          if (height === null) continue;
+          const floor = Math.floor((height - minY) / settings.cellHeight);
+          columns[gx + gz * width]?.push({ bottom: floor, top: floor, walkable });
+          continue;
+        }
+        /*
+         * **A face too steep to stand on is a solid, over every cell it crosses.** Sampled at the
+         * cell's centre like a floor, a wall is never met at all: it is vertical, so it covers no
+         * area seen from above, and a building on the ground read as a roof over open floor that a
+         * route went straight through. So the face is clipped to the cell's square, and the heights
+         * it spans there stand in the column as one solid, whose top is not walkable.
+         */
+        const x0 = minX + gx * settings.cellSize;
+        const z0 = minZ + gz * settings.cellSize;
+        CLIP_IN.set([ax, ay, az, bx, by, bz, cx, cy, cz]);
+        if (!clipToCell(x0, x0 + settings.cellSize, z0, z0 + settings.cellSize, HEIGHTS)) {
+          continue;
+        }
+        columns[gx + gz * width]?.push({
+          bottom: Math.floor(((HEIGHTS[0] as number) - minY) / settings.cellHeight),
+          top: Math.floor(((HEIGHTS[1] as number) - minY) / settings.cellHeight),
+          walkable: false,
+        });
       }
     }
   }
@@ -185,6 +225,64 @@ export function voxeliseWalkable(geometry: NavGeometry, settings: VoxeliseSettin
   return pack(columns, width, depth, origin, settings);
 }
 
+/**
+ * The lowest and highest heights of the triangle in `CLIP_IN` within one cell's square, written to
+ * `out`; false where the triangle misses the cell.
+ *
+ * Sutherland–Hodgman against the square's four sides. Inclusive, so a wall lying exactly on a cell
+ * boundary still lands in the cell the bounding box chose for it.
+ */
+function clipToCell(x0: number, x1: number, z0: number, z1: number, out: Float64Array): boolean {
+  let count = 3;
+  count = clipSide(CLIP_IN, count, CLIP_OUT, 0, x0, 1);
+  count = clipSide(CLIP_OUT, count, CLIP_IN, 0, x1, -1);
+  count = clipSide(CLIP_IN, count, CLIP_OUT, 2, z0, 1);
+  count = clipSide(CLIP_OUT, count, CLIP_IN, 2, z1, -1);
+  if (count === 0) return false;
+  let low = Infinity;
+  let high = -Infinity;
+  for (let at = 0; at < count; at += 1) {
+    const y = CLIP_IN[at * 3 + 1] as number;
+    low = Math.min(low, y);
+    high = Math.max(high, y);
+  }
+  out[0] = low;
+  out[1] = high;
+  return true;
+}
+
+/** Keep the part of a polygon on one side of `axis = bound`: above it for `side` 1, below for -1. */
+function clipSide(
+  from: Float64Array,
+  count: number,
+  to: Float64Array,
+  axis: number,
+  bound: number,
+  side: number,
+): number {
+  let written = 0;
+  for (let at = 0; at < count; at += 1) {
+    const next = (at + 1) % count;
+    const here = ((from[at * 3 + axis] as number) - bound) * side;
+    const there = ((from[next * 3 + axis] as number) - bound) * side;
+    if (here >= 0) {
+      to[written * 3] = from[at * 3] as number;
+      to[written * 3 + 1] = from[at * 3 + 1] as number;
+      to[written * 3 + 2] = from[at * 3 + 2] as number;
+      written += 1;
+    }
+    if (here >= 0 !== there >= 0) {
+      const t = here / (here - there);
+      for (let k = 0; k < 3; k += 1) {
+        const a = from[at * 3 + k] as number;
+        to[written * 3 + k] = a + ((from[next * 3 + k] as number) - a) * t;
+      }
+      written += 1;
+    }
+  }
+  return written;
+}
+
 /**
  * The triangle's height at (px, pz), or null where the point is outside it.
  *
@@ -232,20 +330,34 @@ function pack(
   const merged: number[][] = [];
 
   for (const samples of columns) {
-    samples.sort((a, b) => a.floor - b.floor || Number(a.walkable) - Number(b.walkable));
+    samples.sort(
+      (a, b) => a.bottom - b.bottom || a.top - b.top || Number(a.walkable) - Number(b.walkable),
+    );
     const spans: number[] = [];
+    /* Where each span's solid starts, which is the ceiling of the span below it. */
+    const bottoms: number[] = [];
     for (const sample of samples) {
       const last = spans.length - SPAN_STRIDE;
-      /* Samples within one cell of each other are one surface, not two. */
-      if (last >= 0 && sample.floor - (spans[last] as number) <= 1) {
-        spans[last + 2] = (spans[last + 2] as number) | (sample.walkable ? 1 : 0);
+      const top = spans[last] as number;
+      /*
+       * A sample starting within one cell of a span's top is part of that solid, not a new one.
+       * The span stands on the highest top, and is walkable if anything ending within a cell of
+       * that top is: a wall rising past a floor takes the floor over, and a floor's two triangles
+       * at one height agree.
+       */
+      if (last >= 0 && sample.bottom - top <= 1) {
+        const flag = sample.walkable ? 1 : 0;
+        if (sample.top > top + 1) spans[last + 2] = flag;
+        else if (sample.top >= top - 1) spans[last + 2] = (spans[last + 2] as number) | flag;
+        spans[last] = Math.max(top, sample.top);
         continue;
       }
-      spans.push(sample.floor, Number.MAX_SAFE_INTEGER, sample.walkable ? 1 : 0);
+      spans.push(sample.top, Number.MAX_SAFE_INTEGER, sample.walkable ? 1 : 0);
+      bottoms.push(sample.bottom);
     }
-    /* A span's ceiling is the next span's floor. The topmost has open sky. */
-    for (let at = 0; at + SPAN_STRIDE < spans.length; at += SPAN_STRIDE) {
-      spans[at + 1] = spans[at + SPAN_STRIDE] as number;
+    /* A span's ceiling is where the next solid starts. The topmost has open sky. */
+    for (let at = 0, next = 1; at + SPAN_STRIDE < spans.length; at += SPAN_STRIDE, next += 1) {
+      spans[at + 1] = bottoms[next] as number;
       if ((spans[at + 1] as number) - (spans[at] as number) < headroom) spans[at + 2] = 0;
     }
     merged.push(spans);
@@ -288,6 +400,12 @@ function pack(
  * doing it as that many single-cell passes keeps the whole thing integer arithmetic with no
  * distance to round. **Copied per pass**, because eroding in place erodes into what the same pass
  * just cleared and eats the mesh from its edges inward.
+ *
+ * **A neighbour is judged at this span's height, not anywhere in its column.** Asked whether a
+ * neighbouring column had any walkable span at all, a wall answered yes, with the roof on top of
+ * it, and the floor beside the wall kept no margin. A neighbour counts as open when it has a
+ * walkable span within `maxStep` of this one, a step the agent can take. Further than that is a
+ * wall, a ledge or a drop, and the agent keeps its radius from it.
  */
 function erode(
   columns: number[][],
@@ -296,22 +414,34 @@ function erode(
   settings: VoxeliseSettings,
 ): void {
   const steps = Math.ceil(settings.agentRadius / settings.cellSize);
+  const reach = settings.maxStep ?? 1;
   for (let pass = 0; pass < steps; pass += 1) {
     const before = columns.map((column) => [...column]);
-    const open = (gx: number, gz: number): boolean => {
+    const open = (gx: number, gz: number, floor: number): boolean => {
       if (gx < 0 || gz < 0 || gx >= width || gz >= depth) return false;
       const column = before[gx + gz * width] as number[];
       for (let at = 0; at < column.length; at += SPAN_STRIDE) {
-        if (column[at + 2] === 1) return true;
+        if (column[at + 2] === 1 && Math.abs((column[at] as number) - floor) <= reach) return true;
       }
       return false;
     };
 
     for (let gz = 0; gz < depth; gz += 1) {
       for (let gx = 0; gx < width; gx += 1) {
-        if (open(gx - 1, gz) && open(gx + 1, gz) && open(gx, gz - 1) && open(gx, gz + 1)) continue;
         const column = columns[gx + gz * width] as number[];
-        for (let at = 0; at < column.length; at += SPAN_STRIDE) column[at + 2] = 0;
+        for (let at = 0; at < column.length; at += SPAN_STRIDE) {
+          if (column[at + 2] !== 1) continue;
+          const floor = column[at] as number;
+          if (
+            open(gx - 1, gz, floor) &&
+            open(gx + 1, gz, floor) &&
+            open(gx, gz - 1, floor) &&
+            open(gx, gz + 1, floor)
+          ) {
+            continue;
+          }
+          column[at + 2] = 0;
+        }
       }
     }
   }