@woosh/meep-engine 2.163.6 → 2.163.8

package/src/engine/navigation/mesh/PATHFINDING_PLAN.md

@@ -0,0 +1,185 @@
+# Navmesh shortest-path: goal-directed, early-terminating, edge-based Eikonal A*
+
+## Where we are
+
+`bt_mesh_face_find_path` returns the face **corridor** that
+`NavigationMesh.find_path` feeds to `funnel_string_pull`. The funnel produces the exact
+shortest path *inside* the corridor, so the corridor must **contain the true geodesic** or the final
+path is permanently too long.
+
+The original implementation ran A* on the face dual graph using **centroid-to-centroid distance**.
+That metric is shape-sensitive: across thin/sliver triangles the centroid path zig-zags so hard that a
+dense patch looks more expensive than detouring around large skirt triangles, so it routed *around*
+finely-tessellated regions (measured 1.2–1.55× the straight line). `bt_mesh_face_find_path.shortest_path.spec.js`
+locks this down (flat convex mesh ⇒ straight line is the true shortest path; every pair must be within
+1% of it).
+
+The current implementation fixes correctness with an **exact geodesic field**:
+
+1. `collect_island` — BFS the whole connected component from the start (reachability + vertex set).
+2. `bt_mesh_build_boundary_distance_field` — Fast Marching (Eikonal, Kimmel–Sethian) over **every**
+   island vertex, seeded at the goal face ⇒ true along-surface distance-to-goal at each vertex.
+3. `trace_corridor` — descend the field's in-plane gradient from the start (hugs the geodesic), with a
+   `search_corridor` best-first fallback for the cases the gradient can't follow cleanly (winding
+   around a hole).
+
+This is correct (all 92 navigation tests pass) but **per query it touches the entire connected
+component**: O(component) flood-fill + O(component · log) full Eikonal solve, regardless of how close
+start and goal are. On a large navmesh that is a real regression versus the old localized A*. The
+benchmark (`bt_mesh_face_find_path.bench.spec.js`, behind `.skip`) measures exactly this.
+
+## Target design
+
+A single **goal-directed, early-terminating** Eikonal search, with the corridor reconstructed from
+**edge/portal** parents rather than the fragile gradient trace.
+
+### Phase 1 — goal-directed, early-terminating fill (the big perf win, low risk)
+
+Replace `collect_island` + full `bt_mesh_build_boundary_distance_field` with one Fast Marching pass
+that is ordered as **A*** and stops as soon as it has resolved the start:
+
+- Seed the Eikonal wavefront at the **goal** face's three vertices (distance 0).
+- Order the heap by `f = g + h`, where `g` is the tentative geodesic distance-to-goal and
+  `h(v) = ‖v − start_centroid‖` (straight-line distance to the start). Euclidean `h` is **admissible
+  and consistent** for geodesic distance (geodesic ≥ Euclidean, and Euclidean obeys the triangle
+  inequality), so a popped vertex has its **final** `g` — exactly what the Eikonal update needs from
+  its inputs. The heuristic only changes *pop order*, pulling the front toward the start so we explore
+  the start↔goal "ellipse" instead of the whole component.
+- **Early termination:** stop once all three vertices of the **start** face have been popped (frozen).
+  Every vertex on the geodesic corridor has `g ≤ g(start)` and `f ≤ g(start)` (consistent `h` ⇒ on an
+  optimal path `f` is constant `= total`), so when the start is frozen the whole corridor is already
+  frozen. Reachability falls out for free: if the heap drains without freezing the start face, there is
+  no path ⇒ return 0 (drops the separate `collect_island` BFS entirely).
+
+Keep `trace_corridor` + `search_corridor` unchanged. Both only ever move *downhill* (toward smaller
+distance-to-goal), and the downhill region is exactly what the early-terminated fill computed, so they
+operate entirely within the resolved ellipse — including the around-a-hole geodesic, whose faces all
+satisfy `g ≤ g(start)` and are therefore frozen.
+
+**Causality / correctness note to honour:** the popped-is-final guarantee holds only if Eikonal
+updates use **frozen** inputs. Pure-`g` (and consistent `g + h`) ordering already makes
+*popped ⇒ final* because every update produces a value `≥` the popping vertex's `g` and the heap pops
+non-decreasing. The Dijkstra edge-relaxation fallback (for not-yet-fronted / obtuse cases) only ever
+supplies an upper bound that a later Eikonal update lowers *before* the vertex is popped, so it does
+not violate finality. This must be verified, not assumed, when the fill is split out from
+`bt_mesh_build_boundary_distance_field` (whose label-correcting full solve never relied on early-stop
+finality).
+
+### Phase 2 — exact any-angle (Polyanya), standalone
+
+The original sketch here was "swap the corridor extractor for a portal-based search." That was tried
+(descend the lowest-field portal, re-enter at its midpoint) and **did not move the ~2% around-obstacle
+gap** — see `_diag` runs: the corridor `touchesCornerL=true touchesCornerR=false`, i.e. it cuts one
+reflex corner on the descending side. The root cause is structural: the corner-*cutting* corridor is
+shorter by *every* corridor metric (centroid, portal-midpoint, field); only the funnel knows the
+corner-*touching* corridor yields a shorter final path. So no corridor-extraction swap can be exact —
+you must run the funnel *inside* the search.
+
+That is **Polyanya** (Cui/Harabor/Grastien, IJCAI 2017): A* over (root, interval-on-edge) search nodes.
+The cone from `root` through an interval is projected into the next triangle and clipped against its
+two far edges; visible pieces keep `root` (observable), pieces hidden behind a **reflex corner** at an
+interval endpoint turn there (the corner becomes the new root, non-observable). It returns the exact
+point path, turning only at obstacle corners — no corridor, no funnel post-pass.
+
+Built as a **standalone 2-D module** `navmesh_polyanya_find_path` (xy-plane; not yet wired into the
+3-D `NavigationMesh`). Two things were essential to get it correct *and* terminating:
+- **Reflex-corner restriction:** only boundary vertices whose incident-triangle angles sum to > 180°
+  are turning roots. Admitting flat/convex boundary vertices makes the search blow up combinatorially.
+- **Per-(edge, root) interval dedup:** a fixed root implies a fixed `g`, so the first node to cover a
+  stretch of an edge is optimal there; later nodes are clipped to the still-uncovered part. Without
+  this the wavefront re-floods every edge at the same `f` (the straight-line heuristic ignores
+  obstacles) and never terminates.
+
+## Sequencing
+
+1. **[done]** Land this plan + the benchmark (behind `.skip`) + the geodesic implementation. Baseline
+   (full-island `bt_mesh_build_boundary_distance_field`, ~100k-face mesh): **mean 2714 ms/search**,
+   ~0.4 searches/s. A large part of that was `insert_or_update`'s **O(n) linear-scan decrease-key**,
+   making the fill O(V²).
+2. **[done]** Phase 1. Self-contained goal-directed fill with **lazy-deletion** heap (kills the O(V²))
+   and early termination, replacing `collect_island` + the full solve. Same mesh: **mean 42.5 ms/search**
+   (p50 36, p99 126, min 0.17 for local queries), ~24 searches/s — **~64× faster**. `shortest_path.spec`
+   and all 92 navigation tests stay green; the gradient trace + graph-walk fallback are kept, with a
+   full-field re-solve as the backstop for under-resolved hole-winding corridors.
+3. **[done]** Phase 2. Standalone exact `navmesh_polyanya_find_path` (2-D). Validated by
+   `navmesh_polyanya_find_path.spec.js`: exact on analytic oracles (straight line, single hole,
+   U-barrier, asymmetric wall — all corner-hugging to 4 decimals) and, over 60 random pairs on a holed
+   mesh, never longer than the FMM+funnel path and never shorter than the straight line (strictly
+   shorter on detours). Benchmark on the same ~100k-face mesh: **mean 7.1 ms/search** (p50 3.3, p90 5.5,
+   p99 9.5), ~141 searches/s — faster *typical* than Phase 1 because most pairs have line-of-sight (avg
+   2.0 path points) and Polyanya short-circuits, where the FMM fills the whole ellipse regardless.
+   **Caveat:** a heavy tail (originally max ~6.2 s) on rare far pairs that force long, corner-rich
+   detours.
+
+   **Optimisation pass (done):** made the hot path allocation-light — `reserve` rewritten to flat,
+   in-place range arrays writing into a scratch buffer (no per-call uncovered/merged/`[lo,hi]` arrays,
+   no sort), and the string dedup key replaced by nested numeric-keyed Maps (the crossed edge is
+   uniquely `(from_face, neighbour)`). Same ~100k-face mesh: **mean 4.7 ms** (p50 2.0, p99 6.8), tail
+   **6.2 s → 3.35 s** (~33% faster mean, ~46% lower tail); `spec` stays green. The residual tail is now
+   dominated by node *count* (the Euclidean heuristic is weak on long forced detours), not per-node
+   cost.
+
+   **GC-free node storage (done):** search nodes moved out of per-node object literals into fixed
+   16-word records in a `BinaryElementPool` buffer, referenced by integer id, with the open list a
+   `Uint32Heap4` (id + f32 score) instead of an object heap. The buffer is driven by a monotonic
+   counter reset per query (nodes are never released mid-search and `is_allocated()` is never read), so
+   the pool's per-node occupancy bit and its O(capacity) `clear()` — itself a spike after a large query
+   — are bypassed; the buffer only ever grows (geometrically) and the cached `data_*` views are
+   re-read after a grow. This is a deliberate **latency**, not throughput, choice: it is a touch slower
+   on mean throughput (**~4.7 → ~6.0 ms**, p99 6.8 → 18.3 on the bench — object literals are cheap and
+   the typical query is tiny, avg ~2 points, so there was little GC to remove and the typed-array
+   bookkeeping costs more than it saves *in aggregate*), but pathfinding is a hot path and the point is
+   to emit **zero garbage** so it never triggers a GC pause that jitters the rest of the engine's frame.
+   Unpredictable pauses are worse than a predictable constant cost here. (Two earlier pool variants were
+   measured — `allocate()`/`clear()` was slower still; pool-as-buffer is the kept one.)
+
+   **3-D / intrinsic (done):** `navmesh_polyanya_find_path` takes 3-D start/goal and writes a 3-D point
+   path. It assumes **no global "up"** — the search follows the surface by UNFOLDING. Each node carries the
+   2-D positions of its entry edge in a frame accumulated along its own corridor; expanding flattens the
+   next triangle into that frame by placing the apex from its two 3-D edge lengths (an isometry of the
+   triangle), on the side fixed by the face winding. So frame distances are true geodesic distances and `g`
+   is **exact on a curved/folded surface**, not just a planar one. Corners are detected from the 3-D
+   incident-angle sum (also intrinsic). The goal has no fixed position across frames, so the A* heuristic is
+   the exact straight-3-D-chord shortest root→interval→goal (a lower bound on the geodesic, hence
+   admissible); a terminal's *exact* cost unfolds the goal into that node's frame (barycentric). Waypoints
+   lift back to 3-D from vertex ids — turning corners are mesh vertices (exact), start/goal are the given
+   points, a goal-edge bend is the exact point on that edge. Validated: flat oracles still exact; a
+   rigidly-rotated holed mesh reproduces the flat path R-for-R (rotation-invariance, no up passed); and a
+   developable curved strip's straight geodesic crosses every crease with **no spurious turn** (the
+   unfolding flattens several non-coplanar faces into one frame). `e1 = up × …` and any per-face/per-region
+   up decision are gone.
+
+   **Precision fix (with the 3-D work):** the rotation test surfaced a latent bug — the search's `1e-9`
+   tolerances assume exact coordinates, but vertices are stored **float32**, so once a mesh is *not*
+   axis-aligned its edge fractions carry ~`coord·2^-23` quantisation noise, far above `1e-9`. Coverage
+   intervals then fail to merge, the same edge stretches re-cover as slivers, and the wavefront floods
+   without converging. Fix: a parameter-space tolerance `PEPS = 1e-4` (edge fractions, interval coverage,
+   vertex snapping) sized to float32 precision, kept separate from the tight area-sign `EPS`. Never moves a
+   waypoint (corners are exact vertex positions). The old axis-aligned integer-grid tests never exposed this
+   because integers are exact in float32; the standing rotation test now jitters the lattice off the grid (a
+   perfectly integer lattice rotated exactly onto an axis is a measure-zero collinearity degeneracy that
+   does not occur on real navmeshes).
+
+   **Cost of going intrinsic (measured):** full ~100k-face bench, intrinsic — **mean 9.1 ms/search**
+   (p50 3.9, p90 14.2, p99 40.9, max 4.47 s), 100 % found, ~110 searches/s. Versus the previous
+   single-plane-projection build on the same mesh: object-heap **4.7 ms** (p50 2.0, p99 6.8) and GC-free
+   pool **~6.0 ms** (p99 18.3). So intrinsic is ~1.5–2× slower in the mean and markedly heavier in the
+   tail (p99 6.8 → 40.9). The whole gap is the **heuristic**: the straight-3-D-chord lower bound ignores
+   on-surface curvature, so it is weaker than the old in-plane touch distance and expands more nodes. The
+   per-node work (an extra unfold + a 3-D touch) is minor by comparison. This is the price of "follow face
+   normals" with no up assumption, and it buys exactness on curved surfaces.
+
+   Remaining levers: a tighter still-admissible heuristic (the biggest win — e.g. a 3-D touch distance
+   that accounts for the next face's tilt, or a cached lower-bound field), the paper's advanced interval
+   pruning, and wiring `navmesh_polyanya_find_path` into `NavigationMesh.find_path` as an alternative
+   backend (it now matches that contract — 3-D points in, 3-D points out, no up-vector — and just needs
+   BVH start/goal snapping).
+
+## Gates
+
+- **Correctness:** `bt_mesh_face_find_path.shortest_path.spec.js` (true shortest path on a flat convex
+  mesh) + the existing `bt_mesh_face_find_path.spec.js` + the `NavigationMesh` / `navmesh_*` suites
+  (holes, gaps, erosion — the fallback's job).
+- **Performance:** `bt_mesh_face_find_path.bench.spec.js` — random searches on a ~100k-face seeded
+  mesh for a fixed wall-clock budget; reports throughput and per-search timing percentiles. `.skip` by
+  default (not a quality gate); run on demand.

package/src/engine/navigation/mesh/bt_mesh_face_find_path.d.ts

@@ -2,6 +2,17 @@
  * Find a shortest path through topology faces.
  * If a path is found - the result will contain start and goal faces.
  *
+ * The corridor is steered by an exact-geodesic distance field rather than a face-graph metric. A
+ * goal-directed Fast Marching pass (exact Eikonal triangle update) solves the true along-surface
+ * distance-to-goal at each vertex, sweeping toward the start and stopping as soon as the start face is
+ * resolved. Because the field measures the real walked distance (not centroid-to-centroid hops), the
+ * corridor heads straight at the goal and crosses a finely tessellated patch instead of skirting around
+ * it. The corridor is then extracted by descending the field's gradient from the start (which hugs the
+ * geodesic, so the downstream funnel/string-pull recovers the exact shortest path); where the gradient
+ * is an unreliable guide -- winding around a hole -- a best-first graph walk on the same field takes
+ * over. A full (non-early-terminated) solve is used as a backstop for the rare case the bounded fill
+ * left the corridor under-resolved.
+ *
  * NOTE: if either start or goal faces are not part of the topology - an empty path will be produced.
  *
  * @param {number[]|Uint32Array} output path will be written here as a sequence of face IDs

package/src/engine/navigation/mesh/bt_mesh_face_find_path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_face_find_path.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/bt_mesh_face_find_path.js"],"names":[],"mappings":"AA2GA;;;;;;;;;;;;;;;GAeG;AACH,+CAVW,MAAM,EAAE,GAAC,WAAW,iBACpB,MAAM,gBACN,MAAM,8CAEN,MAAM,GAGJ,MAAM,CAsFlB"}
+{"version":3,"file":"bt_mesh_face_find_path.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/bt_mesh_face_find_path.js"],"names":[],"mappings":"AA0oBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,+CAVW,MAAM,EAAE,GAAC,WAAW,iBACpB,MAAM,gBACN,MAAM,8CAEN,MAAM,GAGJ,MAAM,CAuDlB"}