@woosh/meep-engine 2.148.0 → 2.150.0

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

@@ -1,71 +1,174 @@
 import { assert } from "../../../../core/assert.js";
-import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { NULL_NODE } from "../../../../core/bvh2/bvh3/BVH.js";
+import {
+    bvh_query_leaves_ray_segment
+} from "../../../../core/bvh2/bvh3/query/bvh_query_leaves_ray_segment.js";
+import { NULL_POINTER } from "../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
 import { compute_triangle_area_3d } from "../../../../core/geom/3d/triangle/compute_triangle_area_3d.js";
-import { v3_compute_triangle_normal } from "../../../../core/geom/3d/triangle/v3_compute_triangle_normal.js";
+import {
+    computeTriangleRayIntersectionBarycentric
+} from "../../../../core/geom/3d/triangle/computeTriangleRayIntersectionBarycentric.js";
 import { clamp } from "../../../../core/math/clamp.js";
-import { roundFair } from "../../../../core/math/random/roundFair.js";
 
-function generate_hole_shapes_barycentric(
-    holes_positions,
-    hole_size,
-    ax, ay, az,
-    bx, by, bz,
-    cx, cy, cz,
-) {
-    throw new Error('Not implemented');
-}
+/**
+ * Upper bound on the per-edge subdivision factor, so a single huge triangle cannot explode into an
+ * unbounded number of sub-triangles. At this cap a triangle is sampled with up to K_MAX^2 points.
+ * @type {number}
+ */
+const K_MAX = 64;
+
+/**
+ * Small offset (in world units) used to lift a ray origin off the surface it sits on, so the upward
+ * clearance ray does not immediately re-intersect the floor it starts from.
+ * @type {number}
+ */
+const SURFACE_EPSILON = 1e-4;
+
+// reused scratch (build-time, but there's no reason to churn allocations per triangle)
+const ray_leaf_buffer = [];
+const intersection_result = new Float32Array(6);
+const tri_a = new Float32Array(3);
+const tri_b = new Float32Array(3);
+const tri_c = new Float32Array(3);
 
 /**
+ * True if there is no source geometry within `agent_height` directly above the point, measured along
+ * the world up direction. Casts a ray up from the point (nudged off the surface) and checks every
+ * source face whose AABB the ray crosses with a precise ray-triangle test.
  *
- * @param {number[]} output where to write new triangles
- * @param {number} output_offset
- * @param {number[][]} hole_shapes
- * @param {number} ax
- * @param {number} ay
- * @param {number} az
- * @param {number} bx
- * @param {number} by
- * @param {number} bz
- * @param {number} cx
- * @param {number} cy
- * @param {number} cz
- * @returns {number} new triangles added to the output
+ * @param {BVH} bvh source-geometry BVH (leaves carry source face IDs)
+ * @param {BinaryTopology} source source mesh, used to resolve face IDs to triangle vertices
+ * @param {number} px
+ * @param {number} py
+ * @param {number} pz
+ * @param {number} up_x normalized world up
+ * @param {number} up_y
+ * @param {number} up_z
+ * @param {number} agent_height
+ * @returns {boolean}
  */
-function triangle_punch_holes(
+function point_has_clearance(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;
+    const origin_z = pz + up_z * SURFACE_EPSILON;
+
+    const leaf_count = bvh_query_leaves_ray_segment(
+        bvh, bvh.root,
+        ray_leaf_buffer, 0,
+        origin_x, origin_y, origin_z,
+        up_x, up_y, up_z,
+        0, agent_height
+    );
+
+    for (let i = 0; i < leaf_count; i++) {
+        const node = ray_leaf_buffer[i];
+        const face_id = bvh.node_get_user_data(node);
+
+        const loop_a = source.face_read_loop(face_id);
+
+        if (loop_a === NULL_POINTER) {
+            continue;
+        }
+
+        const loop_b = source.loop_read_next(loop_a);
+        const loop_c = source.loop_read_next(loop_b);
+
+        source.vertex_read_coordinate(tri_a, 0, source.loop_read_vertex(loop_a));
+        source.vertex_read_coordinate(tri_b, 0, source.loop_read_vertex(loop_b));
+        source.vertex_read_coordinate(tri_c, 0, source.loop_read_vertex(loop_c));
+
+        const hit = computeTriangleRayIntersectionBarycentric(
+            intersection_result,
+            origin_x, origin_y, origin_z,
+            up_x, up_y, up_z,
+            tri_a[0], tri_a[1], tri_a[2],
+            tri_b[0], tri_b[1], tri_b[2],
+            tri_c[0], tri_c[1], tri_c[2]
+        );
+
+        if (!hit) {
+            continue;
+        }
+
+        const t = intersection_result[0];
+
+        if (t > 0 && t <= agent_height) {
+            // an overhead obstruction sits within the agent's height
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Append a triangle (9 floats) to `output`.
+ */
+function emit_triangle(
     output,
-    output_offset,
-    hole_shapes,
     ax, ay, az,
     bx, by, bz,
-    cx, cy, cz,
+    cx, cy, cz
 ) {
-    throw new Error('Not implemented');
+    output.push(ax, ay, az, bx, by, bz, cx, cy, cz);
 }
 
 /**
+ * Knock holes in the walkable triangle soup wherever an agent of the given height would not fit under
+ * overhead geometry.
  *
- * @param {BVH} bvh
+ * Approach: subdivide each candidate triangle to a resolution tied to the agent's footprint, cast an
+ * upward clearance ray from each sub-triangle centroid against the source geometry, and keep only the
+ * sub-triangles that have clearance. Fully-clear triangles are emitted unchanged (no subdivision), so
+ * the common case adds no triangles; fully-blocked triangles are dropped; partially-blocked triangles
+ * are replaced by their clear sub-triangles. Accuracy is bounded by the sampling resolution.
+ *
+ * The `triangles` array is rewritten in place with the surviving triangles.
+ *
+ * @param {BVH} bvh source-geometry BVH (leaves carry source face IDs)
+ * @param {BinaryTopology} source source mesh, used to resolve face IDs to triangle vertices
  * @param {number} agent_height
  * @param {number} agent_radius
- * @param {number} triangle_count
- * @param {number[]} triangles
- * @param {function():number} random
+ * @param {number} triangle_count number of triangles currently in `triangles`
+ * @param {number[]} triangles flat XYZ soup, 9 floats per triangle
+ * @param {Vector3} up world up direction
  * @returns {number} new triangle count
  */
 export function enforce_agent_height_clearance({
                                                    bvh,
+                                                   source,
                                                    agent_height,
                                                    agent_radius,
                                                    triangle_count,
                                                    triangles,
-                                                   random
+                                                   up,
                                                }) {
-    console.warn('enforce_agent_height_clearance() is not implemented');
 
-    return triangle_count;
+    assert.defined(bvh, 'bvh');
+    assert.defined(source, 'source');
+    assert.greaterThan(agent_height, 0, 'agent_height');
+
+    if (bvh.root === NULL_NODE) {
+        // no source geometry to obstruct anything
+        return triangle_count;
+    }
+
+    // normalize up so ray-intersection distances are world distances
+    let up_x = up.x;
+    let up_y = up.y;
+    let up_z = up.z;
+
+    const up_length = Math.sqrt(up_x * up_x + up_y * up_y + up_z * up_z);
+
+    assert.greaterThan(up_length, 0, 'up vector length');
+
+    up_x /= up_length;
+    up_y /= up_length;
+    up_z /= up_length;
 
     /**
-     * Spatial resolution for performing clearance checks
+     * Resolution at which clearance is sampled. Tied to the agent footprint so the sampling grid is
+     * fine enough to resolve gaps the agent could (or could not) fit through.
      * @type {number}
      */
     const sampling_resolution = Math.min(
@@ -73,132 +176,144 @@ export function enforce_agent_height_clearance({
         Math.max(agent_radius / 2, 0.001)
     );
 
-    assert.notNaN(sampling_resolution, 'sampling_resolution');
     assert.isFinite(sampling_resolution, 'sampling_resolution');
+    assert.greaterThan(sampling_resolution, 0, 'sampling_resolution');
 
-    const sample_area = sampling_resolution * sampling_resolution;
-
-    const triangle_normal = new Float32Array(3);
-    const ray = new Ray3();
-    ray.tMax = agent_height;
-
-    let current_triangle_count = triangle_count;
-
-    for (let i = 0; i < current_triangle_count; i++) {
-        const triangle_address = i * 9;
+    /**
+     * Surviving triangles. Built separately because the count can grow (subdivision), then copied back.
+     * @type {number[]}
+     */
+    const output = [];
 
-        const ax = triangles[triangle_address];
-        const ay = triangles[triangle_address + 1];
-        const az = triangles[triangle_address + 2];
+    for (let i = 0; i < triangle_count; i++) {
+        const address = i * 9;
 
-        const bx = triangles[triangle_address + 3];
-        const by = triangles[triangle_address + 4];
-        const bz = triangles[triangle_address + 5];
+        const ax = triangles[address];
+        const ay = triangles[address + 1];
+        const az = triangles[address + 2];
 
-        const cx = triangles[triangle_address + 6];
-        const cy = triangles[triangle_address + 7];
-        const cz = triangles[triangle_address + 8];
+        const bx = triangles[address + 3];
+        const by = triangles[address + 4];
+        const bz = triangles[address + 5];
 
-        // TODO we can accelerate this by performing a clipping volume query first instead
-        //      majority of the triangles are expected to fully pass clearance, and a single clipping volume test will be able to give us "Not obstructed" answer.
+        const cx = triangles[address + 6];
+        const cy = triangles[address + 7];
+        const cz = triangles[address + 8];
 
-        const triangle_area = compute_triangle_area_3d(
-            ax, ay, az,
-            bx, by, bz,
-            cx, cy, cz
-        );
+        const area = compute_triangle_area_3d(ax, ay, az, bx, by, bz, cx, cy, cz);
 
-        if (triangle_area === 0) {
-            // a degenerate triangle, should not happen but no point in sampling
+        if (area === 0) {
+            // degenerate, nothing meaningful to sample - keep as-is
+            emit_triangle(output, ax, ay, az, bx, by, bz, cx, cy, cz);
             continue;
         }
 
-        // construct normal
-        v3_compute_triangle_normal(
-            triangle_normal, 0,
-            ax, ay, az,
-            bx, by, bz,
-            cx, cy, cz
-        );
-
-        const sample_count_desired = triangle_area / sample_area;
-        const sample_count_rounded = roundFair(sample_count_desired, random);
-
-        // Guard against degenerate cases
-        const SAMPLE_COUNT_MAX = 32000;
-
-        const sample_count = clamp(sample_count_rounded, 1, SAMPLE_COUNT_MAX);
-
-        // perform sampling
-        const normal_x = triangle_normal[0];
-        const normal_y = triangle_normal[1];
-        const normal_z = triangle_normal[2];
-
-        ray.setDirection(normal_x, normal_y, normal_z);
-
-        // construct edges for sampling
-        const e0x = bx - ax;
-        const e0y = by - ay;
-        const e0z = bz - az;
-
-        const e1x = cx - bx;
-        const e1y = cy - by;
-        const e1z = cz - bz;
-
-        /**
-         * Barycentric coordinates of where the holes are
-         * @type {number[]}
-         */
-        const holes = [];
-
-        for (let j = 0; j < sample_count; j++) {
-
-            // perform initial sample
-            const r0 = random();
-            const r1 = random() * (1 - r0);
-
-            const x = ax + r0 * e0x + r1 * e1x;
-            const y = ay + r0 * e0y + r1 * e1y;
-            const z = az + r0 * e0z + r1 * e1z;
-
-            ray.setOrigin(x, y, z);
-
-            // tiny offset to avoid self-occlusion
-            ray.shiftForward(1e-7);
-
-            // TODO actual raycast
-
-            // if we got a hit - create a hole triangle, if no hit - continue
-            holes.push(r0, r1);
+        // edges, used both to size the subdivision and to place sub-triangle vertices
+        const e0x = bx - ax, e0y = by - ay, e0z = bz - az; // a -> b
+        const e1x = cx - ax, e1y = cy - ay, e1z = cz - az; // a -> c
+
+        const len_ab = Math.sqrt(e0x * e0x + e0y * e0y + e0z * e0z);
+        const len_ac = Math.sqrt(e1x * e1x + e1y * e1y + e1z * e1z);
+        const dbcx = cx - bx, dbcy = cy - by, dbcz = cz - bz;
+        const len_bc = Math.sqrt(dbcx * dbcx + dbcy * dbcy + dbcz * dbcz);
+
+        const longest_edge = Math.max(len_ab, len_ac, len_bc);
+
+        const k = clamp(Math.ceil(longest_edge / sampling_resolution), 1, K_MAX);
+
+        const inv_k = 1 / k;
+
+        // Sub-triangle vertices are P(i,j) = a + (i/k)*(b-a) + (j/k)*(c-a), for i+j <= k.
+        // Walk the k^2 sub-triangles (k*(k+... )/...) testing each centroid for clearance.
+        let any_blocked = false;
+        let any_clear = false;
+
+        // reuse a per-triangle scratch list of clear sub-triangles only when we actually subdivide
+        const clear_subtriangles = [];
+
+        for (let row = 0; row < k; row++) {
+            for (let col = 0; col < k - row; col++) {
+                // "upward" sub-triangle: P(col,row), P(col+1,row), P(col,row+1)
+                emit_subtriangle_if_clear(
+                    bvh, source, agent_height, up_x, up_y, up_z,
+                    ax, ay, az, e0x, e0y, e0z, e1x, e1y, e1z, inv_k,
+                    col, row, col + 1, row, col, row + 1,
+                    clear_subtriangles
+                ) ? (any_clear = true) : (any_blocked = true);
+
+                // "downward" sub-triangle: P(col+1,row), P(col+1,row+1), P(col,row+1)
+                if (col < k - row - 1) {
+                    emit_subtriangle_if_clear(
+                        bvh, source, agent_height, up_x, up_y, up_z,
+                        ax, ay, az, e0x, e0y, e0z, e1x, e1y, e1z, inv_k,
+                        col + 1, row, col + 1, row + 1, col, row + 1,
+                        clear_subtriangles
+                    ) ? (any_clear = true) : (any_blocked = true);
+                }
+            }
         }
 
-        if (holes.length === 0) {
-            // clearance OK
-            continue;
+        if (!any_blocked) {
+            // fully clear - keep the original triangle, no subdivision, no bloat
+            emit_triangle(output, ax, ay, az, bx, by, bz, cx, cy, cz);
+        } else if (any_clear) {
+            // partially blocked - replace with the surviving sub-triangles
+            for (let s = 0; s < clear_subtriangles.length; s++) {
+                output.push(clear_subtriangles[s]);
+            }
         }
+        // else fully blocked - drop the triangle entirely
+    }
 
-        const hole_shapes = generate_hole_shapes_barycentric(
-            holes,
-            sampling_resolution,
-            ax, ay, az,
-            bx, by, bz,
-            cx, cy, cz
-        );
+    // rewrite the soup in place with the survivors
+    for (let i = 0; i < output.length; i++) {
+        triangles[i] = output[i];
+    }
+    triangles.length = output.length;
 
-        const added_triangle_count = triangle_punch_holes(
-            triangles,
-            triangle_count,
-            hole_shapes,
-            ax, ay, az,
-            bx, by, bz,
-            cx, cy, cz
-        );
+    return (output.length / 9) | 0;
+}
 
-        triangle_count += added_triangle_count;
+/**
+ * Build sub-triangle vertices P(i,j) = a + (i/k)*e0 + (j/k)*e1, test its centroid for clearance, and
+ * push its 9 coordinates into `out` when clear. Returns whether it was clear.
+ */
+function emit_subtriangle_if_clear(
+    bvh, source, agent_height, up_x, up_y, up_z,
+    ax, ay, az, e0x, e0y, e0z, e1x, e1y, e1z, inv_k,
+    i0, j0, i1, j1, i2, j2,
+    out
+) {
+    const s0 = i0 * inv_k, t0 = j0 * inv_k;
+    const s1 = i1 * inv_k, t1 = j1 * inv_k;
+    const s2 = i2 * inv_k, t2 = j2 * inv_k;
+
+    const p0x = ax + s0 * e0x + t0 * e1x;
+    const p0y = ay + s0 * e0y + t0 * e1y;
+    const p0z = az + s0 * e0z + t0 * e1z;
+
+    const p1x = ax + s1 * e0x + t1 * e1x;
+    const p1y = ay + s1 * e0y + t1 * e1y;
+    const p1z = az + s1 * e0z + t1 * e1z;
+
+    const p2x = ax + s2 * e0x + t2 * e1x;
+    const p2y = ay + s2 * e0y + t2 * e1y;
+    const p2z = az + s2 * e0z + t2 * e1z;
+
+    const centroid_x = (p0x + p1x + p2x) / 3;
+    const centroid_y = (p0y + p1y + p2y) / 3;
+    const centroid_z = (p0z + p1z + p2z) / 3;
+
+    const clear = point_has_clearance(
+        bvh, source,
+        centroid_x, centroid_y, centroid_z,
+        up_x, up_y, up_z,
+        agent_height
+    );
 
-        // TODO remove the original triangle, cut out the holes and add new triangles back
+    if (clear) {
+        out.push(p0x, p0y, p0z, p1x, p1y, p1z, p2x, p2y, p2z);
     }
 
-    //
-    return current_triangle_count;
-}
+    return clear;
+}

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":"AAsCA;;;;;;;;;;GAUG;AACH,wKATW,cAAc,QA2JxB;+BAjM8B,mEAAmE"}
+{"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,QAoLxB;+BA/N8B,mEAAmE"}

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

@@ -4,6 +4,9 @@ import { BinaryTopology } from "../../../../core/geom/3d/topology/struct/binary/
 import {
     bt_mesh_cleanup_faceless_references
 } from "../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_cleanup_faceless_references.js";
+import {
+    bt_mesh_compact
+} from "../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_compact.js";
 import {
     bt_mesh_compute_face_normals
 } from "../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_compute_face_normals.js";
@@ -25,12 +28,14 @@ import {
     bt_merge_verts_by_distance
 } from "../../../../core/geom/3d/topology/struct/binary/io/vertex/bt_merge_verts_by_distance.js";
 import { bt_face_is_degenerate } from "../../../../core/geom/3d/topology/struct/binary/query/bt_face_is_degenerate.js";
+import {
+    bt_mesh_bridge_islands
+} from "../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_bridge_islands.js";
 import {
     bt_mesh_compute_face_islands
 } from "../../../../core/geom/3d/topology/struct/binary/query/bt_mesh_compute_face_islands.js";
 import { v3_angle_between } from "../../../../core/geom/vec3/v3_angle_between.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
-import { seededRandom } from "../../../../core/math/random/seededRandom.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 { enforce_agent_height_clearance } from "./enforce_agent_height_clearance.js";
@@ -67,7 +72,12 @@ export function navmesh_build_topology({
     assert.greaterThanOrEqual(agent_max_step_height, 0, 'agent_max_step_height');
     assert.greaterThanOrEqual(agent_max_step_distance, 0, 'agent_max_step_distance');
 
-    const random = seededRandom();
+    // The walkable-angle filter below reads each source face's normal. Compute them defensively rather
+    // than relying on an undocumented "caller already populated normals" precondition - normals are
+    // derived data, so this is idempotent. NOTE: a single face normal cannot distinguish a correctly
+    // wound floor from a flipped one (or a ceiling), so the source is still required to have consistent
+    // outward winding; that remains an input contract we cannot recover from here.
+    bt_mesh_compute_face_normals(source);
 
     const source_bvh = new BVH();
 
@@ -135,11 +145,12 @@ export function navmesh_build_topology({
 
         triangle_count = enforce_agent_height_clearance({
             bvh: source_bvh,
+            source: source,
             agent_height: agent_height,
             agent_radius: agent_radius,
             triangle_count: triangle_count,
             triangles: raw_triangles,
-            random: random
+            up: up,
         });
 
     }
@@ -186,6 +197,25 @@ export function navmesh_build_topology({
         // remove dangling references
         bt_mesh_cleanup_faceless_references(mesh);
 
+        // 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);
+
+        // 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.
+        if (agent_max_step_height > 0 || agent_max_step_distance > 0) {
+            bt_mesh_bridge_islands(mesh, {
+                max_step_height: agent_max_step_height,
+                max_step_distance: agent_max_step_distance,
+                up,
+            });
+
+            // bridging rebuilds via vertex-merge / edge-fuse, which can leave holes; re-densify
+            bt_mesh_compact(mesh);
+        }
+
         // face normals are consumed by navigation queries (string-pulling portal normals), populate them now
         bt_mesh_compute_face_normals(mesh);
 

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

@@ -8,8 +8,11 @@
  * @param {number} x
  * @param {number} y
  * @param {number} z
+ * @param {Float32Array|number[]} out_point the closest point ON the winning face's surface (the snapped
+ *        contact point) is written here when a face is found. Required, must not be null.
+ * @param {number} [out_point_offset=0] offset into `out_point` to write the snapped XYZ triple
  * @param {number} [max_distance=Infinity] optional cutoff, only faces within this distance are considered
  * @returns {number} face ID of the nearest face, or {@link NULL_POINTER} if no face was found within the cutoff
  */
-export function bvh_query_nearest_face(bvh: BVH, mesh: BinaryTopology, x: number, y: number, z: number, max_distance?: number): number;
+export function bvh_query_nearest_face(bvh: BVH, mesh: BinaryTopology, x: number, y: number, z: number, out_point: Float32Array | number[], out_point_offset?: number, max_distance?: number): number;
 //# sourceMappingURL=bvh_query_nearest_face.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"bvh_query_nearest_face.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/bvh_query_nearest_face.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;GAYG;AACH,0EANW,MAAM,KACN,MAAM,KACN,MAAM,iBACN,MAAM,GACJ,MAAM,CA+FlB"}
+{"version":3,"file":"bvh_query_nearest_face.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/bvh_query_nearest_face.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;GAeG;AACH,0EATW,MAAM,KACN,MAAM,KACN,MAAM,aACN,YAAY,GAAC,MAAM,EAAE,qBAErB,MAAM,iBACN,MAAM,GACJ,MAAM,CA+HlB"}