@woosh/meep-engine 2.163.3 → 2.163.5

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.163.3",
+  "version": "2.163.5",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_face_island_erode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_face_island_erode.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_face_island_erode.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;GAYG;AACH,uEAHW,MAAM,EAAE,kBACR,MAAM,QAqVhB"}
+{"version":3,"file":"bt_mesh_face_island_erode.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_face_island_erode.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;GAYG;AACH,uEAHW,MAAM,EAAE,kBACR,MAAM,QAgehB"}

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_face_island_erode.js

@@ -6,13 +6,34 @@ import {
 } from "../../../../line/line3_compute_segment_point_distance_eikonal.js";
 import { NULL_POINTER } from "../BinaryTopology.js";
 import { bt_face_get_incenter } from "../query/bt_face_get_incenter.js";
-import { bt_mesh_build_boundary_distance_field } from "../query/bt_mesh_build_boundary_distance_field.js";
 import { bt_mesh_cleanup_faceless_references } from "./bt_mesh_cleanup_faceless_references.js";
 import { bt_edge_split } from "./edge/bt_edge_split.js";
 import { bt_face_kill } from "./face/bt_face_kill.js";
 import { bt_mesh_face_poke } from "./face/bt_face_poke.js";
 import { bt_face_get_neighbour_faces } from "../query/bt_face_get_neighbour_faces.js";
 
+const _eb_a = new Float32Array(3);
+const _eb_b = new Float32Array(3);
+const _eb_p = new Float32Array(3);
+
+/**
+ * Squared straight-line distance from point p to segment a-b in 3D.
+ */
+function point_segment_distance_sq(px, py, pz, ax, ay, az, bx, by, bz) {
+    const abx = bx - ax, aby = by - ay, abz = bz - az;
+    const apx = px - ax, apy = py - ay, apz = pz - az;
+    const ab_len_sq = abx * abx + aby * aby + abz * abz;
+
+    let t = ab_len_sq > 0 ? (apx * abx + apy * aby + apz * abz) / ab_len_sq : 0;
+    if (t < 0) t = 0; else if (t > 1) t = 1;
+
+    const cx = ax + t * abx - px;
+    const cy = ay + t * aby - py;
+    const cz = az + t * abz - pz;
+
+    return cx * cx + cy * cy + cz * cz;
+}
+
 /**
  * Shrinks an island of faces by a given distance.
  * Conceptually, this moves the outline of the island inwards.
@@ -160,13 +181,152 @@ export function bt_mesh_face_island_erode(
         }
     }
 
-    // 3. Compute Geodesic Distance Field
+    // 3. Distance field: EXACT straight-line distance from each island vertex to the nearest boundary
+    // edge. Agent clearance is a Euclidean (line-of-sight) distance to the nearest wall, NOT a geodesic
+    // distance measured along the surface. The previous eikonal field was both semantically wrong and
+    // sensitive to the triangulation - it produced a lumpy, non-uniform inset (e.g. a 14x14 platform
+    // built from strips eroded by 0.45-0.65 instead of a uniform 0.4). Exact distance is uniform.
     /**
      * Vertex -> Distance from boundary
      * @type {Map<number, number>}
      */
     const vertex_boundary_distances = new Map();
-    bt_mesh_build_boundary_distance_field(vertex_boundary_distances, mesh, island_vertices, boundary_vertices);
+
+    // boundary edge segments, cached by compute_field for reuse in the deviation test below
+    let boundary_segments = [];
+
+    // (re)compute the exact distance field for the current island vertices/boundary
+    function compute_field() {
+        vertex_boundary_distances.clear();
+
+        boundary_segments = [];
+        for (const e of boundary_edges_set) {
+            const bv1 = mesh.edge_read_vertex1(e);
+            const bv2 = mesh.edge_read_vertex2(e);
+            mesh.vertex_read_coordinate(_eb_a, 0, bv1);
+            mesh.vertex_read_coordinate(_eb_b, 0, bv2);
+            boundary_segments.push(_eb_a[0], _eb_a[1], _eb_a[2], _eb_b[0], _eb_b[1], _eb_b[2]);
+        }
+
+        for (const v of island_vertices) {
+            mesh.vertex_read_coordinate(_eb_p, 0, v);
+            vertex_boundary_distances.set(v, dist_to_boundary(_eb_p[0], _eb_p[1], _eb_p[2]));
+        }
+    }
+
+    // exact straight-line distance from a point to the nearest boundary edge
+    function dist_to_boundary(px, py, pz) {
+        const seg = boundary_segments;
+        let best_sq = Infinity;
+        for (let i = 0; i < seg.length; i += 6) {
+            const d_sq = point_segment_distance_sq(
+                px, py, pz,
+                seg[i], seg[i + 1], seg[i + 2],
+                seg[i + 3], seg[i + 4], seg[i + 5]
+            );
+            if (d_sq < best_sq) best_sq = d_sq;
+        }
+        return best_sq === Infinity ? Infinity : Math.sqrt(best_sq);
+    }
+
+    compute_field();
+
+    // 3a. CUT-BAND REFINEMENT. The inset contour is reconstructed piecewise-linearly from the faces the
+    // erosion threshold passes through, so on a coarse/skewed triangulation the cut chord deviates from
+    // the true offset (a strip-built platform eroded unevenly, 0.4 on one side and 0.6 on another). For
+    // each straddling face, place the two cut points and test whether their midpoint really lies at the
+    // erode distance; only refine (split the longest edge) when the chord deviates. Already-accurate
+    // cuts (e.g. a plain quad's straight sides) are left coarse, so detail is added only where needed.
+    {
+        const fine = Math.max(erode_distance * 0.5, 0.1);
+        const fine_sq = fine * fine;
+        const tol = Math.max(erode_distance * 0.15, 0.04);
+        let rounds = 0;
+
+        const ca = new Float32Array(3), cb = new Float32Array(3), cc = new Float32Array(3);
+
+        while (rounds < 48) {
+            rounds++;
+
+            const targets = new Set();
+
+            for (let i = 0; i < island_faces.length; i++) {
+                const f = island_faces[i];
+                if (!mesh.faces.is_allocated(f)) continue;
+
+                const la = mesh.face_read_loop(f);
+                const lb = mesh.loop_read_next(la);
+                const lc = mesh.loop_read_next(lb);
+                const v1 = mesh.loop_read_vertex(la);
+                const v2 = mesh.loop_read_vertex(lb);
+                const v3 = mesh.loop_read_vertex(lc);
+
+                const d1 = vertex_boundary_distances.get(v1);
+                const d2 = vertex_boundary_distances.get(v2);
+                const d3 = vertex_boundary_distances.get(v3);
+
+                const dmin = Math.min(d1, d2, d3);
+                const dmax = Math.max(d1, d2, d3);
+
+                // does the erode threshold pass through this face?
+                if (!(dmin < erode_distance && dmax > erode_distance)) continue;
+
+                mesh.vertex_read_coordinate(ca, 0, v1);
+                mesh.vertex_read_coordinate(cb, 0, v2);
+                mesh.vertex_read_coordinate(cc, 0, v3);
+
+                const e_ab = (ca[0] - cb[0]) ** 2 + (ca[1] - cb[1]) ** 2 + (ca[2] - cb[2]) ** 2;
+                const e_bc = (cb[0] - cc[0]) ** 2 + (cb[1] - cc[1]) ** 2 + (cb[2] - cc[2]) ** 2;
+                const e_ca = (cc[0] - ca[0]) ** 2 + (cc[1] - ca[1]) ** 2 + (cc[2] - ca[2]) ** 2;
+                const longest = Math.max(e_ab, e_bc, e_ca);
+
+                if (longest <= fine_sq) continue;
+
+                // the two cut points where the threshold crosses this face's edges
+                let mx = 0, my = 0, mz = 0, crossings = 0;
+                // edge (v1,v2)
+                if ((d1 < erode_distance) !== (d2 < erode_distance)) {
+                    const t = (erode_distance - d1) / (d2 - d1);
+                    mx += ca[0] + t * (cb[0] - ca[0]); my += ca[1] + t * (cb[1] - ca[1]); mz += ca[2] + t * (cb[2] - ca[2]); crossings++;
+                }
+                // edge (v2,v3)
+                if ((d2 < erode_distance) !== (d3 < erode_distance)) {
+                    const t = (erode_distance - d2) / (d3 - d2);
+                    mx += cb[0] + t * (cc[0] - cb[0]); my += cb[1] + t * (cc[1] - cb[1]); mz += cb[2] + t * (cc[2] - cb[2]); crossings++;
+                }
+                // edge (v3,v1)
+                if ((d3 < erode_distance) !== (d1 < erode_distance)) {
+                    const t = (erode_distance - d3) / (d1 - d3);
+                    mx += cc[0] + t * (ca[0] - cc[0]); my += cc[1] + t * (ca[1] - cc[1]); mz += cc[2] + t * (ca[2] - cc[2]); crossings++;
+                }
+
+                if (crossings === 2) {
+                    mx *= 0.5; my *= 0.5; mz *= 0.5;
+                    const true_d = dist_to_boundary(mx, my, mz);
+                    if (Math.abs(true_d - erode_distance) <= tol) {
+                        // the straight cut here is already accurate - leave this face coarse
+                        continue;
+                    }
+                }
+
+                const sl = (longest === e_ab) ? la : (longest === e_bc) ? lb : lc;
+                targets.add(mesh.loop_read_edge(sl));
+            }
+
+            if (targets.size === 0) break;
+
+            for (const e of targets) {
+                if (mesh.edges.is_allocated(e)) bt_edge_split(mesh, e, 0.5);
+            }
+
+            island_faces = recompute_island_faces(faces);
+            ({ island_vertices, island_edges, boundary_vertices, boundary_edges_set } = collect_island_sets(island_faces));
+
+            compute_field();
+
+            if (mesh.faces.size > 200000) break;
+        }
+    }
     // ---------------------------------------------------------
     // 3.5. PEAK RESCUE PASS (The Fix)
     // Handle cases where a face is "submerged" by vertex values

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve T-junctions: where a vertex lies on the interior of a boundary edge (rather than at one of
+ * its endpoints), split that edge at the vertex so the two pieces can later be welded/fused into a
+ * shared edge.
+ *
+ * This is required for meshes assembled from independently-authored faces of differing sizes - e.g. an
+ * L-shaped or ring floor built from rectangles, where one rectangle's corner falls in the middle of a
+ * neighbour's edge. Without it those faces touch only at a single vertex, so edge-based neighbour
+ * queries (island detection, erosion, path-finding) treat them as DISCONNECTED.
+ *
+ * Call AFTER an initial vertex-merge/edge-fuse, then merge + fuse again so the new split vertices weld
+ * onto the T-junction vertices and the resulting duplicate edges fuse.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} [tolerance] max distance from a vertex to an edge for it to count as "on" the edge
+ * @returns {number} number of splits performed
+ */
+export function bt_mesh_resolve_t_junctions(mesh: BinaryTopology, tolerance?: number): number;
+//# sourceMappingURL=bt_mesh_resolve_t_junctions.d.ts.map

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_mesh_resolve_t_junctions.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AACH,8EAHW,MAAM,GACJ,MAAM,CAuElB"}

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.js

@@ -0,0 +1,95 @@
+import { NULL_POINTER } from "../BinaryTopology.js";
+import { bt_edge_split } from "./edge/bt_edge_split.js";
+
+const _a = new Float32Array(3);
+const _b = new Float32Array(3);
+const _p = new Float32Array(3);
+const _hit = new Float32Array(3);
+
+/**
+ * Resolve T-junctions: where a vertex lies on the interior of a boundary edge (rather than at one of
+ * its endpoints), split that edge at the vertex so the two pieces can later be welded/fused into a
+ * shared edge.
+ *
+ * This is required for meshes assembled from independently-authored faces of differing sizes - e.g. an
+ * L-shaped or ring floor built from rectangles, where one rectangle's corner falls in the middle of a
+ * neighbour's edge. Without it those faces touch only at a single vertex, so edge-based neighbour
+ * queries (island detection, erosion, path-finding) treat them as DISCONNECTED.
+ *
+ * Call AFTER an initial vertex-merge/edge-fuse, then merge + fuse again so the new split vertices weld
+ * onto the T-junction vertices and the resulting duplicate edges fuse.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} [tolerance] max distance from a vertex to an edge for it to count as "on" the edge
+ * @returns {number} number of splits performed
+ */
+export function bt_mesh_resolve_t_junctions(mesh, tolerance = 1e-4) {
+    const tol_sq = tolerance * tolerance;
+
+    let total = 0;
+    let rounds = 0;
+    let changed = true;
+
+    while (changed && rounds < 256) {
+        changed = false;
+        rounds++;
+
+        const edge_count = mesh.edges.size;
+
+        for (let e = 0; e < edge_count; e++) {
+            if (!mesh.edges.is_allocated(e)) continue;
+
+            // only boundary edges (a single radial loop) can carry a T-junction
+            const l = mesh.edge_read_loop(e);
+            if (l === NULL_POINTER) continue;
+            if (mesh.loop_read_radial_next(l) !== l) continue;
+
+            const v1 = mesh.edge_read_vertex1(e);
+            const v2 = mesh.edge_read_vertex2(e);
+
+            mesh.vertex_read_coordinate(_a, 0, v1);
+            mesh.vertex_read_coordinate(_b, 0, v2);
+
+            const abx = _b[0] - _a[0], aby = _b[1] - _a[1], abz = _b[2] - _a[2];
+            const ab_sq = abx * abx + aby * aby + abz * abz;
+            if (ab_sq <= tol_sq) continue;
+
+            const t_margin = tolerance / Math.sqrt(ab_sq);
+
+            let split_t = -1;
+            let split_v = -1;
+
+            const vertex_count = mesh.vertices.size;
+            for (let v = 0; v < vertex_count; v++) {
+                if (v === v1 || v === v2) continue;
+                if (!mesh.vertices.is_allocated(v)) continue;
+
+                mesh.vertex_read_coordinate(_p, 0, v);
+
+                const t = ((_p[0] - _a[0]) * abx + (_p[1] - _a[1]) * aby + (_p[2] - _a[2]) * abz) / ab_sq;
+                if (t <= t_margin || t >= 1 - t_margin) continue;
+
+                const cx = _a[0] + t * abx - _p[0];
+                const cy = _a[1] + t * aby - _p[1];
+                const cz = _a[2] + t * abz - _p[2];
+                if (cx * cx + cy * cy + cz * cz > tol_sq) continue;
+
+                split_t = t;
+                split_v = v;
+                break;
+            }
+
+            if (split_t >= 0) {
+                // snapshot the on-edge vertex coordinate, split, then snap the new vertex exactly onto it
+                mesh.vertex_read_coordinate(_hit, 0, split_v);
+                const nv = bt_edge_split(mesh, e, split_t);
+                mesh.vertex_write_coordinate(nv, _hit, 0);
+
+                total++;
+                changed = true;
+            }
+        }
+    }
+
+    return total;
+}

package/src/engine/navigation/mesh/build/bt_mesh_carve_height_clearance.d.ts

@@ -1,17 +1,18 @@
 /**
- * Carve holes into a (welded, connected) walkable topology wherever an agent of the given height
- * would not fit under overhead geometry.
+ * Carve holes into a (welded) walkable topology wherever an agent of the given height+radius would not
+ * fit under overhead geometry. INTENDED TO RUN AFTER the agent-radius boundary erosion: the boundary is
+ * already handled, so this only removes the obstacle footprints (dilated by the agent radius).
  *
- * Operates on the topology rather than a triangle soup so that all subdivision is conformal:
- * {@link bt_edge_split} re-triangulates every face around a split edge, so neighbouring faces can
- * never disagree on a shared edge (no cracks / T-junctions). Refinement is adaptive - only faces whose
- * column actually contains an overhang are subdivided, and only down to `resolution` - so clear areas
- * stay coarse and the subdivision hugs the obstacle contour instead of tessellating whole triangles.
+ * All subdivision is conformal ({@link bt_edge_split} re-triangulates every face around a split edge),
+ * and culling whole faces ({@link bt_face_kill}) never cracks neighbours - so this cannot disconnect a
+ * passable region. Refinement is tight: faces straddling the (dilated) obstacle outline are refined to
+ * `resolution`; a still-large all-clear face whose column has overhead is refined down to a coarse
+ * guard so a small obstacle cannot hide unsampled; everything else stays coarse.
  *
  * @param {object} params
  * @param {BinaryTopology} params.mesh walkable topology to carve (modified in place)
  * @param {BinaryTopology} params.source original source mesh (walkable + overhead geometry)
- * @param {BVH} params.source_bvh BVH over `source` (leaves carry source face IDs)
+ * @param {BVH} params.source_bvh BVH over `source`
  * @param {number} params.agent_height
  * @param {number} params.agent_radius
  * @param {Vector3} params.up world up direction

package/src/engine/navigation/mesh/build/bt_mesh_carve_height_clearance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_carve_height_clearance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/bt_mesh_carve_height_clearance.js"],"names":[],"mappings":"AA2LA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAPkC,IAAI;IACJ,MAAM;IACjB,UAAU;IACP,YAAY,EAA3B,MAAM;IACS,YAAY,EAA3B,MAAM;IACU,EAAE;SAuH5B"}
+{"version":3,"file":"bt_mesh_carve_height_clearance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/bt_mesh_carve_height_clearance.js"],"names":[],"mappings":"AA2NA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAPkC,IAAI;IACJ,MAAM;IACjB,UAAU;IACP,YAAY,EAA3B,MAAM;IACS,YAAY,EAA3B,MAAM;IACU,EAAE;SAyH5B"}

package/src/engine/navigation/mesh/build/bt_mesh_carve_height_clearance.js

@@ -15,26 +15,10 @@ import {
     computeTriangleRayIntersectionBarycentric
 } from "../../../../core/geom/3d/triangle/computeTriangleRayIntersectionBarycentric.js";
 
-/**
- * Lift a ray origin off the surface so the upward clearance ray does not immediately re-hit the floor.
- * @type {number}
- */
+/** Lift a ray origin off the surface so the upward clearance ray does not re-hit the floor. */
 const SURFACE_EPSILON = 1e-4;
 
-/**
- * Horizontal inset applied to a face footprint before testing for overhead geometry. Prevents a
- * neighbour that merely *touches* a face along a shared edge (e.g. an adjacent platform at a slightly
- * different height) from being mistaken for an overhang. A real overhang overlaps the interior with
- * positive area and still registers.
- * @type {number}
- */
-const FOOTPRINT_INSET = 1e-2;
-
-/**
- * Safety cap on the number of faces the refinement is allowed to grow to, so a pathological input
- * cannot loop forever.
- * @type {number}
- */
+/** Safety cap on the face count during refinement. */
 const MAX_FACES = 200000;
 
 // reused scratch
@@ -50,11 +34,9 @@ const vc = new Float32Array(3);
 
 const overhead_hits = [];
 const query_aabb = new Float32Array(6);
+const scratch_normal = new Float32Array(3);
 
-/**
- * True if there is no source geometry within `agent_height` directly above the point along `up`.
- * (Mirrors the clearance ray-cast used by the old soup-based pass.)
- */
+/** True if nothing in `source` sits directly above the point within `agent_height` (exact ray test). */
 function point_has_clearance(source_bvh, source, px, py, pz, up_x, up_y, up_z, agent_height) {
     const origin_x = px + up_x * SURFACE_EPSILON;
     const origin_y = py + up_y * SURFACE_EPSILON;
@@ -73,9 +55,15 @@ function point_has_clearance(source_bvh, source, px, py, pz, up_x, up_y, up_z, a
         const face_id = source_bvh.node_get_user_data(node);
 
         const loop_a = source.face_read_loop(face_id);
-        if (loop_a === NULL_POINTER) {
+        if (loop_a === NULL_POINTER) continue;
+
+        // Only DOWNWARD-facing geometry (a ceiling / overhang underside) can obstruct head clearance.
+        // Up-facing walkable floors above (a higher tier, a step the agent climbs) must NOT block.
+        source.face_read_normal(scratch_normal, 0, face_id);
+        if (scratch_normal[0] * up_x + scratch_normal[1] * up_y + scratch_normal[2] * up_z >= -1e-3) {
             continue;
         }
+
         const loop_b = source.loop_read_next(loop_a);
         const loop_c = source.loop_read_next(loop_b);
 
@@ -91,62 +79,92 @@ function point_has_clearance(source_bvh, source, px, py, pz, up_x, up_y, up_z, a
             tri_b[0], tri_b[1], tri_b[2],
             tri_c[0], tri_c[1], tri_c[2]
         );
-        if (!hit) {
-            continue;
-        }
+        if (!hit) continue;
 
         const t = intersection_result[0];
-        if (t > 0 && t <= agent_height) {
-            // overhead obstruction within the agent's height
-            return false;
-        }
+        if (t > 0 && t <= agent_height) return false;
     }
 
     return true;
 }
 
 /**
- * Read the three vertices of a triangular face into va/vb/vc and return its loops.
+ * True if any source geometry sits above the point within `agent_height`, anywhere inside a horizontal
+ * disc of radius `r` (approximated by an axis-aligned box). Used to dilate the obstacle footprint by
+ * the agent radius - the agent's body cannot occupy a spot whose `r`-neighbourhood is overhung.
  */
-function read_face_triangle(mesh, face_id) {
-    const la = mesh.face_read_loop(face_id);
-    const lb = mesh.loop_read_next(la);
-    const lc = mesh.loop_read_next(lb);
+function overhead_within_radius(source_bvh, source, px, py, pz, up_x, up_y, up_z, agent_height, r) {
+    const p_along_up = px * up_x + py * up_y + pz * up_z;
 
-    mesh.vertex_read_coordinate(va, 0, mesh.loop_read_vertex(la));
-    mesh.vertex_read_coordinate(vb, 0, mesh.loop_read_vertex(lb));
-    mesh.vertex_read_coordinate(vc, 0, mesh.loop_read_vertex(lc));
+    // expand on the axes perpendicular to up by r, then sweep up by agent_height
+    const ex = r * (1 - Math.abs(up_x));
+    const ey = r * (1 - Math.abs(up_y));
+    const ez = r * (1 - Math.abs(up_z));
 
-    return { la, lb, lc };
+    let min_x = px - ex, min_y = py - ey, min_z = pz - ez;
+    let max_x = px + ex, max_y = py + ey, max_z = pz + ez;
+
+    const dx = up_x * agent_height, dy = up_y * agent_height, dz = up_z * agent_height;
+    if (dx > 0) max_x += dx; else min_x += dx;
+    if (dy > 0) max_y += dy; else min_y += dy;
+    if (dz > 0) max_z += dz; else min_z += dz;
+
+    query_aabb[0] = min_x; query_aabb[1] = min_y; query_aabb[2] = min_z;
+    query_aabb[3] = max_x; query_aabb[4] = max_y; query_aabb[5] = max_z;
+
+    const count = bvh_query_user_data_overlaps_aabb(overhead_hits, 0, source_bvh, query_aabb);
+
+    for (let i = 0; i < count; i++) {
+        const fid = overhead_hits[i];
+        const la = source.face_read_loop(fid);
+        if (la === NULL_POINTER) continue;
+
+        // only downward-facing geometry counts as an overhang (see point_has_clearance)
+        source.face_read_normal(scratch_normal, 0, fid);
+        if (scratch_normal[0] * up_x + scratch_normal[1] * up_y + scratch_normal[2] * up_z >= -1e-3) {
+            continue;
+        }
+
+        const lb = source.loop_read_next(la);
+        const lc = source.loop_read_next(lb);
+
+        source.vertex_read_coordinate(tri_a, 0, source.loop_read_vertex(la));
+        source.vertex_read_coordinate(tri_b, 0, source.loop_read_vertex(lb));
+        source.vertex_read_coordinate(tri_c, 0, source.loop_read_vertex(lc));
+
+        const cand_min_along_up = Math.min(
+            tri_a[0] * up_x + tri_a[1] * up_y + tri_a[2] * up_z,
+            tri_b[0] * up_x + tri_b[1] * up_y + tri_b[2] * up_z,
+            tri_c[0] * up_x + tri_c[1] * up_y + tri_c[2] * up_z
+        );
+
+        if (cand_min_along_up > p_along_up + 1e-3 && cand_min_along_up <= p_along_up + agent_height + 1e-3) {
+            return true;
+        }
+    }
+
+    return false;
 }
 
 /**
- * Does the upward column (height `agent_height` along `up`) over this face's footprint contain any
- * source geometry that sits *above* the face? Uses a loose axis-aligned box (conservative), inset
- * horizontally so edge-touching neighbours do not count. May report true for a face whose triangle
- * does not actually pass under the overhang, which only costs a little extra refinement, never a
- * wrong cull.
+ * Does the column over this face's footprint (inflated horizontally by `pad`) contain any DOWNWARD-
+ * facing geometry above it within `agent_height`? Footprint-wide (not just the centroid), so an
+ * obstacle sitting anywhere under a large face is detected and the face is refined toward it.
  */
-function column_has_overhead(source_bvh, source, face_max_along_up, up_x, up_y, up_z, agent_height) {
-    let min_x = Math.min(va[0], vb[0], vc[0]);
-    let min_y = Math.min(va[1], vb[1], vc[1]);
-    let min_z = Math.min(va[2], vb[2], vc[2]);
-    let max_x = Math.max(va[0], vb[0], vc[0]);
-    let max_y = Math.max(va[1], vb[1], vc[1]);
-    let max_z = Math.max(va[2], vb[2], vc[2]);
-
-    // inset the footprint on the axes perpendicular to up (so touching-only neighbours are excluded)
-    const ex = FOOTPRINT_INSET * (1 - Math.abs(up_x));
-    const ey = FOOTPRINT_INSET * (1 - Math.abs(up_y));
-    const ez = FOOTPRINT_INSET * (1 - Math.abs(up_z));
-    min_x += ex; max_x -= ex;
-    min_y += ey; max_y -= ey;
-    min_z += ez; max_z -= ez;
-    if (min_x > max_x) { const m = (min_x + max_x) * 0.5; min_x = m; max_x = m; }
-    if (min_y > max_y) { const m = (min_y + max_y) * 0.5; min_y = m; max_y = m; }
-    if (min_z > max_z) { const m = (min_z + max_z) * 0.5; min_z = m; max_z = m; }
-
-    // sweep the box by agent_height along the up direction
+function footprint_has_overhead(source_bvh, source, up_x, up_y, up_z, agent_height, pad) {
+    const face_max_along_up = Math.max(
+        va[0] * up_x + va[1] * up_y + va[2] * up_z,
+        vb[0] * up_x + vb[1] * up_y + vb[2] * up_z,
+        vc[0] * up_x + vc[1] * up_y + vc[2] * up_z
+    );
+
+    let min_x = Math.min(va[0], vb[0], vc[0]) - pad;
+    let min_y = Math.min(va[1], vb[1], vc[1]) - pad;
+    let min_z = Math.min(va[2], vb[2], vc[2]) - pad;
+    let max_x = Math.max(va[0], vb[0], vc[0]) + pad;
+    let max_y = Math.max(va[1], vb[1], vc[1]) + pad;
+    let max_z = Math.max(va[2], vb[2], vc[2]) + pad;
+
     const dx = up_x * agent_height, dy = up_y * agent_height, dz = up_z * agent_height;
     if (dx > 0) max_x += dx; else min_x += dx;
     if (dy > 0) max_y += dy; else min_y += dy;
@@ -159,24 +177,26 @@ function column_has_overhead(source_bvh, source, face_max_along_up, up_x, up_y,
 
     for (let i = 0; i < count; i++) {
         const fid = overhead_hits[i];
-
         const la = source.face_read_loop(fid);
         if (la === NULL_POINTER) continue;
+
+        source.face_read_normal(scratch_normal, 0, fid);
+        if (scratch_normal[0] * up_x + scratch_normal[1] * up_y + scratch_normal[2] * up_z >= -1e-3) {
+            continue;
+        }
+
         const lb = source.loop_read_next(la);
         const lc = source.loop_read_next(lb);
-
         source.vertex_read_coordinate(tri_a, 0, source.loop_read_vertex(la));
         source.vertex_read_coordinate(tri_b, 0, source.loop_read_vertex(lb));
         source.vertex_read_coordinate(tri_c, 0, source.loop_read_vertex(lc));
 
-        // lowest extent of the candidate along up
         const cand_min_along_up = Math.min(
             tri_a[0] * up_x + tri_a[1] * up_y + tri_a[2] * up_z,
             tri_b[0] * up_x + tri_b[1] * up_y + tri_b[2] * up_z,
             tri_c[0] * up_x + tri_c[1] * up_y + tri_c[2] * up_z
         );
 
-        // strictly above the face (the face's own/coplanar floor reads <= face_max_along_up)
         if (cand_min_along_up > face_max_along_up + 1e-3) {
             return true;
         }
@@ -185,20 +205,33 @@ function column_has_overhead(source_bvh, source, face_max_along_up, up_x, up_y,
     return false;
 }
 
+function read_face_triangle(mesh, face_id) {
+    const la = mesh.face_read_loop(face_id);
+    const lb = mesh.loop_read_next(la);
+    const lc = mesh.loop_read_next(lb);
+
+    mesh.vertex_read_coordinate(va, 0, mesh.loop_read_vertex(la));
+    mesh.vertex_read_coordinate(vb, 0, mesh.loop_read_vertex(lb));
+    mesh.vertex_read_coordinate(vc, 0, mesh.loop_read_vertex(lc));
+
+    return { la, lb, lc };
+}
+
 /**
- * Carve holes into a (welded, connected) walkable topology wherever an agent of the given height
- * would not fit under overhead geometry.
+ * Carve holes into a (welded) walkable topology wherever an agent of the given height+radius would not
+ * fit under overhead geometry. INTENDED TO RUN AFTER the agent-radius boundary erosion: the boundary is
+ * already handled, so this only removes the obstacle footprints (dilated by the agent radius).
  *
- * Operates on the topology rather than a triangle soup so that all subdivision is conformal:
- * {@link bt_edge_split} re-triangulates every face around a split edge, so neighbouring faces can
- * never disagree on a shared edge (no cracks / T-junctions). Refinement is adaptive - only faces whose
- * column actually contains an overhang are subdivided, and only down to `resolution` - so clear areas
- * stay coarse and the subdivision hugs the obstacle contour instead of tessellating whole triangles.
+ * All subdivision is conformal ({@link bt_edge_split} re-triangulates every face around a split edge),
+ * and culling whole faces ({@link bt_face_kill}) never cracks neighbours - so this cannot disconnect a
+ * passable region. Refinement is tight: faces straddling the (dilated) obstacle outline are refined to
+ * `resolution`; a still-large all-clear face whose column has overhead is refined down to a coarse
+ * guard so a small obstacle cannot hide unsampled; everything else stays coarse.
  *
  * @param {object} params
  * @param {BinaryTopology} params.mesh walkable topology to carve (modified in place)
  * @param {BinaryTopology} params.source original source mesh (walkable + overhead geometry)
- * @param {BVH} params.source_bvh BVH over `source` (leaves carry source face IDs)
+ * @param {BVH} params.source_bvh BVH over `source`
  * @param {number} params.agent_height
  * @param {number} params.agent_radius
  * @param {Vector3} params.up world up direction
@@ -212,28 +245,30 @@ export function bt_mesh_carve_height_clearance({
                                                    up,
                                                }) {
 
-    if (agent_height <= 0 || source_bvh.root === NULL_NODE) {
-        // nothing overhead can obstruct anything
-        return;
-    }
+    if (agent_height <= 0 || source_bvh.root === NULL_NODE) return;
 
-    // normalize up
     let up_x = up.x, up_y = up.y, up_z = up.z;
     const up_len = Math.sqrt(up_x * up_x + up_y * up_y + up_z * up_z);
-    if (up_len === 0) {
-        return;
-    }
+    if (up_len === 0) return;
     up_x /= up_len; up_y /= up_len; up_z /= up_len;
 
-    // Contour resolution: how finely the obstacle outline is resolved. Tied to the agent footprint;
-    // floored so a tiny radius cannot trigger runaway refinement.
-    const resolution = Math.max(agent_radius > 0 ? agent_radius : agent_height / 4, 0.25);
+    const r = Math.max(agent_radius, 0);
+    const resolution = Math.max(agent_radius > 0 ? agent_radius : agent_height / 4, 0.3);
     const res_sq = resolution * resolution;
 
-    // ---- Phase 1: adaptive, conformal refinement around overhangs ----
-    // Repeated fixed-point passes: split the longest edge of any face that (a) is still larger than
-    // the contour resolution and (b) has overhead geometry in its column. Splitting is conformal, so
-    // the mesh stays crack-free throughout.
+    // The agent fits at p iff nothing overhangs directly above it AND nothing overhangs within its body
+    // radius. (For r == 0 this is just the exact overhead ray.)
+    function agent_fits(px, py, pz) {
+        if (!point_has_clearance(source_bvh, source, px, py, pz, up_x, up_y, up_z, agent_height)) {
+            return false;
+        }
+        if (r > 0 && overhead_within_radius(source_bvh, source, px, py, pz, up_x, up_y, up_z, agent_height, r)) {
+            return false;
+        }
+        return true;
+    }
+
+    // ---- Phase 1: tight, conformal refinement around the (dilated) obstacle outline ----
     let changed = true;
     let guard = 0;
 
@@ -244,53 +279,58 @@ export function bt_mesh_carve_height_clearance({
         const face_count = mesh.faces.size;
 
         for (let f = 0; f < face_count; f++) {
-            if (!mesh.faces.is_allocated(f)) {
-                continue;
-            }
+            if (!mesh.faces.is_allocated(f)) continue;
 
             read_face_triangle(mesh, f);
 
-            // longest edge (by squared length); read_face_triangle puts va/vb/vc in loop order
-            // la=(a,b), lb=(b,c), lc=(c,a)
             const ab = (va[0] - vb[0]) ** 2 + (va[1] - vb[1]) ** 2 + (va[2] - vb[2]) ** 2;
             const bc = (vb[0] - vc[0]) ** 2 + (vb[1] - vc[1]) ** 2 + (vb[2] - vc[2]) ** 2;
             const ca = (vc[0] - va[0]) ** 2 + (vc[1] - va[1]) ** 2 + (vc[2] - va[2]) ** 2;
-
             const longest_sq = Math.max(ab, bc, ca);
 
-            if (longest_sq <= res_sq) {
-                // small enough to resolve the contour
-                continue;
+            if (longest_sq <= res_sq) continue;
+
+            const mab_x = (va[0] + vb[0]) * 0.5, mab_y = (va[1] + vb[1]) * 0.5, mab_z = (va[2] + vb[2]) * 0.5;
+            const mbc_x = (vb[0] + vc[0]) * 0.5, mbc_y = (vb[1] + vc[1]) * 0.5, mbc_z = (vb[2] + vc[2]) * 0.5;
+            const mca_x = (vc[0] + va[0]) * 0.5, mca_y = (vc[1] + va[1]) * 0.5, mca_z = (vc[2] + va[2]) * 0.5;
+            const cx = (va[0] + vb[0] + vc[0]) / 3, cy = (va[1] + vb[1] + vc[1]) / 3, cz = (va[2] + vb[2] + vc[2]) / 3;
+
+            const samples = [
+                va[0], va[1], va[2], vb[0], vb[1], vb[2], vc[0], vc[1], vc[2],
+                mab_x, mab_y, mab_z, mbc_x, mbc_y, mbc_z, mca_x, mca_y, mca_z,
+                cx, cy, cz,
+            ];
+            let n_clear = 0, n_block = 0;
+            for (let s = 0; s < samples.length; s += 3) {
+                if (agent_fits(samples[s], samples[s + 1], samples[s + 2])) n_clear++; else n_block++;
             }
 
-            const face_max_along_up = Math.max(
-                va[0] * up_x + va[1] * up_y + va[2] * up_z,
-                vb[0] * up_x + vb[1] * up_y + vb[2] * up_z,
-                vc[0] * up_x + vc[1] * up_y + vc[2] * up_z
-            );
-
-            if (!column_has_overhead(source_bvh, source, face_max_along_up, up_x, up_y, up_z, agent_height)) {
-                // fully clear column - keep this face coarse
-                continue;
+            let refine = false;
+            if (n_block > 0 && n_clear > 0) {
+                refine = true;   // (dilated) outline crosses this face -> hug it at `resolution`
+            } else if (n_block === 0) {
+                // all clear by sampling, but a small obstacle can hide entirely between the samples of a
+                // coarse face. If any downward-facing overhang sits under the face footprint, keep
+                // refining down to the contour resolution so even sub-sample obstacles get caught.
+                if (footprint_has_overhead(source_bvh, source, up_x, up_y, up_z, agent_height, r)) {
+                    refine = true;
+                }
             }
+            // n_clear === 0 (fully blocked): leave it for the cull phase
+
+            if (!refine) continue;
 
             const { la, lb, lc } = read_face_triangle(mesh, f);
             let split_loop;
-            if (longest_sq === ab) {
-                split_loop = la;
-            } else if (longest_sq === bc) {
-                split_loop = lb;
-            } else {
-                split_loop = lc;
-            }
+            if (longest_sq === ab) split_loop = la;
+            else if (longest_sq === bc) split_loop = lb;
+            else split_loop = lc;
 
             bt_edge_split(mesh, mesh.loop_read_edge(split_loop), 0.5);
             changed = true;
         }
 
-        if (mesh.faces.size > MAX_FACES) {
-            break;
-        }
+        if (mesh.faces.size > MAX_FACES) break;
     }
 
     // ---- Phase 2: cull blocked faces (whole-face, conformal) ----
@@ -298,19 +338,14 @@ export function bt_mesh_carve_height_clearance({
     const face_count = mesh.faces.size;
 
     for (let f = 0; f < face_count; f++) {
-        if (!mesh.faces.is_allocated(f)) {
-            continue;
-        }
+        if (!mesh.faces.is_allocated(f)) continue;
 
         read_face_triangle(mesh, f);
-
         const cx = (va[0] + vb[0] + vc[0]) / 3;
         const cy = (va[1] + vb[1] + vc[1]) / 3;
         const cz = (va[2] + vb[2] + vc[2]) / 3;
 
-        if (!point_has_clearance(source_bvh, source, cx, cy, cz, up_x, up_y, up_z, agent_height)) {
-            faces_to_kill.push(f);
-        }
+        if (!agent_fits(cx, cy, cz)) faces_to_kill.push(f);
     }
 
     for (let i = 0; i < faces_to_kill.length; i++) {

package/src/engine/navigation/mesh/build/navmesh_build_topology.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navmesh_build_topology.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/navmesh_build_topology.js"],"names":[],"mappings":"AA2CA;;;;;;;;;;GAUG;AACH,wKATW,cAAc,QAiLxB;+BA5N8B,mEAAmE"}
+{"version":3,"file":"navmesh_build_topology.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/navmesh_build_topology.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;GAUG;AACH,wKATW,cAAc,QAyLxB;+BAvO8B,mEAAmE"}

package/src/engine/navigation/mesh/build/navmesh_build_topology.js

@@ -39,6 +39,9 @@ import Vector3 from "../../../../core/geom/Vector3.js";
 import { bvh_build_from_bt_mesh } from "../bvh_build_from_bt_mesh.js";
 import { bvh_build_from_unindexed_triangles } from "./bvh_build_from_unindexed_triangles.js";
 import { bt_mesh_carve_height_clearance } from "./bt_mesh_carve_height_clearance.js";
+import {
+    bt_mesh_resolve_t_junctions
+} from "../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.js";
 
 
 /**
@@ -164,41 +167,49 @@ export function navmesh_build_topology({
         // which is what the loop-based neighbour queries rely on
         bt_mesh_fuse_duplicate_edges(mesh);
 
-        // Carve holes wherever an agent of the given height would not fit under overhead geometry.
-        // Done on the welded topology (rather than the raw soup) so the subdivision is conformal -
-        // bt_edge_split re-triangulates every face around a shared edge, so neighbours can never crack
-        // apart - and adaptive, hugging each obstacle's contour instead of tessellating whole triangles.
+        // Resolve T-junctions: when faces of differing sizes abut (an L-shaped or ring floor built from
+        // rectangles, a small tile against a big one), one face's corner can land in the middle of
+        // another's edge. Those faces touch at a single vertex only, so edge-based neighbour queries
+        // treat them as disconnected. Split such edges at the stray vertex, then re-weld/fuse so the
+        // pieces share a real edge.
+        if (bt_mesh_resolve_t_junctions(mesh, 1e-4) > 0) {
+            bt_merge_verts_by_distance(mesh, 1e-6);
+            bt_mesh_fuse_duplicate_edges(mesh);
+        }
+
+        // --- Carve obstacle footprints first (no radius dilation here) ---
+        // Cull the floor directly under any overhang, opening a hole at each obstacle footprint. The
+        // agent-radius dilation is handled by the erosion below, which treats these holes as boundaries
+        // and insets them (and the outer edge) by exactly agent_radius - giving both a uniform inset and
+        // a smooth, consistent outline around obstacles from a single, robust pass.
         if (agent_height > 0) {
             bt_mesh_carve_height_clearance({
                 mesh,
                 source,
                 source_bvh,
                 agent_height,
-                agent_radius,
+                agent_radius: 0,
                 up,
             });
-        }
-
-        const islands = bt_mesh_compute_face_islands(mesh);
 
-        // enabled us to modify islands independently
-        bt_mesh_face_decouple_islands(mesh, islands);
-
-        // shrink islands to agent_radius
-        for (const island of islands) {
-            bt_mesh_face_island_erode(mesh, island, agent_radius);
+            bt_mesh_compact(mesh);
         }
 
-        // TODO attempt to reduce mesh complexity by re-triangulating flat areas or running a very constrained decimation
+        // --- Then erode every boundary (outer edge + obstacle holes) by the agent radius ---
+        // The erosion uses an exact Euclidean distance field with cut-band refinement, so it stays
+        // accurate and connected even on the hole-punched mesh the carve produces.
+        {
+            const islands = bt_mesh_compute_face_islands(mesh);
+
+            bt_mesh_face_decouple_islands(mesh, islands);
 
-        // remove dangling references
-        bt_mesh_cleanup_faceless_references(mesh);
+            for (const island of islands) {
+                bt_mesh_face_island_erode(mesh, island, agent_radius);
+            }
 
-        // Island erosion (above) kills faces via the pool's free-list, leaving holes in the ID space.
-        // `faces.size` is a high-water mark, not a live count, so consumers that iterate `0..faces.size`
-        // (e.g. bvh_build_from_bt_mesh) would touch freed slots. Compact so every consumer sees a dense,
-        // hole-free topology - this is the single invariant downstream code relies on.
-        bt_mesh_compact(mesh);
+            bt_mesh_cleanup_faceless_references(mesh);
+            bt_mesh_compact(mesh);
+        }
 
         // bridge across small steps / gaps so stair-separated or slightly-broken tiers are reachable.
         // Opt-in: with both step params 0 (the default) the topology is left untouched.