@driftengine/nav 4.0.0

package/src/polymesh.ts

@@ -0,0 +1,301 @@
+/**
+ * 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';
+
+const NO_VERTEX = -1;
+export 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 function polyVertexCount(mesh: PolyMesh, poly: number): number {
+  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: PolyMesh, poly: number, edge: number): number {
+  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: PolyMesh, poly: number): number {
+  const count = polyVertexCount(mesh, poly);
+  let twice = 0;
+  for (let at = 0; at < count; at += 1) {
+    const a = mesh.polys[poly * mesh.maxVertsPerPoly + at] as number;
+    const b = mesh.polys[poly * mesh.maxVertsPerPoly + ((at + 1) % count)] as number;
+    twice +=
+      (mesh.vertices[a * 2] as number) * (mesh.vertices[b * 2 + 1] as number) -
+      (mesh.vertices[b * 2] as number) * (mesh.vertices[a * 2 + 1] as number);
+  }
+  return Math.abs(twice) / 2;
+}
+
+export function polyIsConvex(mesh: PolyMesh, poly: number): boolean {
+  const count = polyVertexCount(mesh, poly);
+  if (count < 3) return false;
+  const indices: number[] = [];
+  for (let at = 0; at < count; at += 1) {
+    indices.push(mesh.polys[poly * mesh.maxVertsPerPoly + at] as number);
+  }
+  return isConvexLoop(indices, mesh.vertices);
+}
+
+function cross(vertices: Int32Array, a: number, b: number, c: number): number {
+  return (
+    ((vertices[b * 2] as number) - (vertices[a * 2] as number)) *
+      ((vertices[c * 2 + 1] as number) - (vertices[a * 2 + 1] as number)) -
+    ((vertices[b * 2 + 1] as number) - (vertices[a * 2 + 1] as number)) *
+      ((vertices[c * 2] as number) - (vertices[a * 2] as number))
+  );
+}
+
+/** Every turn the same way round, treating a straight run as no turn at all. */
+function isConvexLoop(loop: readonly number[], vertices: Int32Array): boolean {
+  let sign = 0;
+  for (let at = 0; at < loop.length; at += 1) {
+    const a = loop[at] as number;
+    const b = loop[(at + 1) % loop.length] as number;
+    const c = loop[(at + 2) % loop.length] as number;
+    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: Int32Array, a: number, b: number, c: number, p: number): boolean {
+  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: number[], vertices: Int32Array): number[][] {
+  const out: number[][] = [];
+  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] as number;
+      const b = working[at] as number;
+      const c = working[(at + 1) % working.length] as number;
+      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: number[][], vertices: Int32Array, maxVerts: number): number[][] {
+  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] as number[], live[b] as number[], 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: readonly number[],
+  b: readonly number[],
+  vertices: Int32Array,
+  maxVerts: number,
+): number[] | null {
+  for (let i = 0; i < a.length; i += 1) {
+    const a0 = a[i] as number;
+    const a1 = a[(i + 1) % a.length] as number;
+    for (let j = 0; j < b.length; j += 1) {
+      const b0 = b[j] as number;
+      const b1 = b[(j + 1) % b.length] as number;
+      /* 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: number[] = [];
+      for (let k = 1; k < a.length; k += 1) loop.push(a[(i + k) % a.length] as number);
+      for (let k = 1; k < b.length; k += 1) loop.push(b[(j + k) % b.length] as number);
+      if (loop.length > maxVerts) return null;
+      return isConvexLoop(loop, vertices) ? loop : null;
+    }
+  }
+  return null;
+}
+
+export function buildPolyMesh(
+  contours: readonly Contour[],
+  maxVertsPerPoly: number,
+  placement: NavPlacement,
+): PolyMesh {
+  const maxVerts = Math.max(3, maxVertsPerPoly);
+  const vertexKeys = new Map<string, number>();
+  const vertexList: number[] = [];
+  const polys: number[][] = [];
+  const regions: number[] = [];
+
+  const intern = (x: number, z: number): number => {
+    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: number[] = [];
+    for (let at = 0; at < contour.points.length; at += 2) {
+      loop.push(intern(contour.points[at] as number, contour.points[at + 1] as number));
+    }
+    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] as number[];
+    for (let at = 0; at < piece.length && at < maxVerts; at += 1) {
+      table[poly * maxVerts + at] = piece[at] as number;
+    }
+  }
+
+  /*
+   * 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<string, [number, number]>();
+  for (let poly = 0; poly < polyCount; poly += 1) {
+    const piece = polys[poly] as number[];
+    for (let at = 0; at < piece.length; at += 1) {
+      const from = piece[at] as number;
+      const to = piece[(at + 1) % piece.length] as number;
+      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] as number,
+    originZ: placement.origin[2] as number,
+    cellSize: placement.cellSize,
+  };
+}
+
+function signedArea(loop: readonly number[], vertices: Int32Array): number {
+  let twice = 0;
+  for (let at = 0; at < loop.length; at += 1) {
+    const a = loop[at] as number;
+    const b = loop[(at + 1) % loop.length] as number;
+    twice +=
+      (vertices[a * 2] as number) * (vertices[b * 2 + 1] as number) -
+      (vertices[b * 2] as number) * (vertices[a * 2 + 1] as number);
+  }
+  return twice / 2;
+}

package/src/portalGraph.ts

@@ -0,0 +1,359 @@
+/**
+ * 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 type { NavEdge, NavGraph } from '@driftengine/core';
+
+import { polyNeighbour, polyVertexCount, 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;
+}
+
+/** One portal: the two polygons, and the overlap's two ends as each of them stores its direction. */
+interface Portal {
+  readonly near: number;
+  readonly far: number;
+  readonly nearFrom: number;
+  readonly nearTo: number;
+  readonly farFrom: number;
+  readonly farTo: number;
+}
+
+interface Side {
+  readonly poly: number;
+  /** The edge's own two vertices, in the order its polygon stores them. */
+  readonly from: number;
+  readonly to: number;
+  /** Where each end sits along the line, as an exact integer. */
+  readonly fromAt: number;
+  readonly toAt: number;
+}
+
+function gcd(a: number, b: number): number {
+  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: PolyMesh): Portal[] {
+  const lines = new Map<string, Side[]>();
+  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] as number;
+      const to = mesh.polys[poly * mesh.maxVertsPerPoly + ((edge + 1) % verts)] as number;
+      const ax = mesh.vertices[from * 2] as number;
+      const az = mesh.vertices[from * 2 + 1] as number;
+      const dx = (mesh.vertices[to * 2] as number) - ax;
+      const dz = (mesh.vertices[to * 2 + 1] as number) - 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: number): number =>
+        ux !== 0
+          ? (mesh.vertices[vertex * 2] as number)
+          : (mesh.vertices[vertex * 2 + 1] as number);
+      const side: 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: Portal[] = [];
+  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] as Side;
+        const b = sides[j] as Side;
+        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): number => (side.fromAt === low ? side.from : side.to);
+        const atHigh = (side: Side): number => (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): boolean => 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: PolyMesh): PortalGraph {
+  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] as Portal;
+    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] as number) + 1;
+    degree[portal.far] = (degree[portal.far] as number) + 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] as number) + (degree[poly] as number);
+  }
+  const cursor = Uint32Array.from(polyStart.subarray(0, mesh.polyCount));
+  const polyPortals = new Uint32Array(polyStart[mesh.polyCount] as number);
+  for (let portal = 0; portal < portalCount; portal += 1) {
+    for (let side = 0; side < 2; side += 1) {
+      const poly = sides[portal * 2 + side] as number;
+      polyPortals[cursor[poly] as number] = portal;
+      cursor[poly] = (cursor[poly] as number) + 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: NavEdge[] = [];
+  for (let poly = 0; poly < mesh.polyCount; poly += 1) {
+    const from = polyStart[poly] as number;
+    const to = polyStart[poly + 1] as number;
+    for (let i = from; i < to; i += 1) {
+      for (let j = from; j < to; j += 1) {
+        if (i !== j) {
+          edges.push({ from: polyPortals[i] as number, to: polyPortals[j] as number });
+        }
+      }
+    }
+  }
+
+  /*
+   * **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] as number) + 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: NavGraph, node: number): number {
+  for (
+    let edge = graph.edgeStart[node] as number;
+    edge < (graph.edgeStart[node + 1] as number);
+    edge += 1
+  ) {
+    if ((graph.edgeTarget[edge] as number) === node) return edge;
+  }
+  throw new Error(`nav: node ${node} has no reserved slot`);
+}
+
+function midpoint(mesh: PolyMesh, a: number, b: number, axis: number): number {
+  const origin = axis === 0 ? mesh.originX : mesh.originZ;
+  const first = mesh.vertices[a * 2 + axis] as number;
+  const second = mesh.vertices[b * 2 + axis] as number;
+  return origin + ((first + second) / 2) * mesh.cellSize;
+}
+
+/** Point the start node at the portals of the polygon holding it. */
+export function attachStart(portals: PortalGraph, poly: number, x: number, z: number): void {
+  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] as number;
+  const to = portals.polyStart[poly + 1] as number;
+  for (let slot = 0; slot < portals.startSlots.length; slot += 1) {
+    const edge = portals.startSlots[slot] as number;
+    const held = from + slot < to ? (portals.polyPortals[from + slot] as number) : -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: PortalGraph, poly: number, x: number, z: number): void {
+  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] as number;
+      at < (portals.polyStart[previous + 1] as number);
+      at += 1
+    ) {
+      const portal = portals.polyPortals[at] as number;
+      const edge = portals.goalSlot[portal] as number;
+      graph.edgeTarget[edge] = portal;
+      graph.edgeCost[edge] = 0;
+    }
+  }
+  for (
+    let at = portals.polyStart[poly] as number;
+    at < (portals.polyStart[poly + 1] as number);
+    at += 1
+  ) {
+    const portal = portals.polyPortals[at] as number;
+    const edge = portals.goalSlot[portal] as number;
+    graph.edgeTarget[edge] = goalNode;
+    graph.edgeCost[edge] = reach(graph, portal, x, z);
+  }
+  portals.attachedGoal = poly;
+}
+
+function reach(graph: NavGraph, portal: number, x: number, z: number): number {
+  const dx = (graph.positions[portal * 3] as number) - x;
+  const dz = (graph.positions[portal * 3 + 2] as number) - z;
+  return Math.sqrt(dx * dx + dz * dz);
+}