@woosh/meep-engine 2.148.0 → 2.150.0

package/src/engine/navigation/mesh/bt_mesh_face_find_path.js

@@ -8,19 +8,24 @@ import {
 const open = new Uint32Heap();
 
 /**
- *
  * @type {Set<number>}
  */
 const closed = new Set();
 
 /**
- *
+ * Least known traversal cost (sum of centroid-to-centroid distances) from start to each face.
  * @type {Map<number, number>}
  */
 const g_score = new Map();
 
 /**
- * Note that we limit the supported number of neighbors, a reasonable meshes will fit this criteria
+ * Reconstruction parent pointers: face -> the face we reached it from on the best path.
+ * @type {Map<number, number>}
+ */
+const came_from = new Map();
+
+/**
+ * Note that we limit the supported number of neighbors, a reasonable mesh will fit this criteria
  * @type {Uint32Array}
  */
 const neighbors = new Uint32Array(256);
@@ -28,96 +33,80 @@ const neighbors = new Uint32Array(256);
 const scratch_array_f32 = new Float32Array(6);
 
 /**
+ * Straight-line distance between the centroids of two faces.
+ *
+ * This is used both as the step cost (between adjacent faces) and as the heuristic (from a face to
+ * the goal). Because, by the triangle inequality, the straight-line distance from any face to the
+ * goal is never greater than the summed centroid-to-centroid distance of an actual face path between
+ * them, the heuristic is admissible AND consistent. A* therefore returns a shortest-distance corridor
+ * (under the centroid metric) rather than a fewest-faces one.
  *
  * @param {number} a
  * @param {number} b
  * @param {BinaryTopology} topology
  * @returns {number}
  */
-function heuristic(a, b, topology) {
-    // compare centroid distances
+function face_centroid_distance(a, b, topology) {
     bt_face_get_centroid(scratch_array_f32, 0, topology, a);
     bt_face_get_centroid(scratch_array_f32, 3, topology, b);
 
-    // delta
     const dx = scratch_array_f32[0] - scratch_array_f32[3];
     const dy = scratch_array_f32[1] - scratch_array_f32[4];
     const dz = scratch_array_f32[2] - scratch_array_f32[5];
 
-    // distance
-    return dx * dx + dy * dy + dz * dz;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
 }
 
 /**
+ * Walk parent pointers from goal back to start, writing the face sequence into `output` in
+ * START -> GOAL order. Never writes more than `max_path_length` entries: if the corridor is longer
+ * than that it does not fit the caller's buffer and 0 is returned (no partial/garbage result is used).
  *
  * @param {number[]|Uint32Array} output
- * @param {number} goal
- * @param {Map<number, number>} g_score
- * @param {BinaryTopology} topology
- * @returns {number}
+ * @param {number} start_face
+ * @param {number} goal_face
+ * @param {Map<number, number>} came_from
+ * @param {number} max_path_length
+ * @returns {number} number of faces written, or 0 if the corridor exceeds `max_path_length`
  */
-function construct_path(output, goal, g_score, topology) {
-
-    let current = goal;
-    let path_length = 0;
+function construct_path(output, start_face, goal_face, came_from, max_path_length) {
+    let length = 0;
+    let current = goal_face;
 
-    // 1. Walk back via lowest g-score path until we get to 0 (start)
+    // walk back to the start, writing in reverse (goal -> start)
     while (true) {
-        output[path_length++] = current;
-
-        const current_g = g_score.get(current);
-
-        // If we reached the start node (g_score === 0), we're done traversing
-        if (current_g === 0) {
-            break;
+        if (length >= max_path_length) {
+            // corridor does not fit the output buffer; refuse rather than writing out of bounds
+            return 0;
         }
 
-        const neighbor_count = bt_face_get_neighbour_faces(neighbors, 0, topology, current);
+        output[length] = current;
+        length++;
 
-        let best_neighbor = -1;
-        let lowest_g = Infinity;
-
-        // Find the neighbor with the lowest g_score
-        for (let i = 0; i < neighbor_count; i++) {
-            const neighbor = neighbors[i];
-
-            if (g_score.has(neighbor)) {
-                const g = g_score.get(neighbor);
-
-                if (g < lowest_g) {
-                    lowest_g = g;
-                    best_neighbor = neighbor;
-                }
-
-            }
-        }
-
-        // Safeguard: Break if no valid neighbor is found or if we aren't strictly descending.
-        // (Since your traversal_cost is currently 1.0, lowest_g should be current_g - 1.0)
-        if (best_neighbor === -1 || lowest_g >= current_g) {
+        if (current === start_face) {
             break;
         }
 
-        current = best_neighbor;
+        current = came_from.get(current);
     }
 
-    // 2. Reverse the path in-place to get START -> GOAL order
-    const half_length = Math.floor(path_length / 2);
+    // reverse in place to get START -> GOAL order
+    const half_length = length >> 1;
 
     for (let i = 0; i < half_length; i++) {
-        const mirror_i = path_length - 1 - i;
+        const mirror_i = length - 1 - i;
         const temp = output[i];
 
         output[i] = output[mirror_i];
         output[mirror_i] = temp;
     }
 
-    return path_length;
+    return length;
 }
 
 
 /**
- * Find a path through topology faces.
+ * Find a shortest path through topology faces.
  * If a path is found - the result will contain start and goal faces.
  *
  * NOTE: if either start or goal faces are not part of the topology - an empty path will be produced.
@@ -126,13 +115,18 @@ function construct_path(output, goal, g_score, topology) {
  * @param {number} start_face_id
  * @param {number} goal_face_id
  * @param {BinaryTopology} topology
- * @returns {number} number of faces that make up the path. This will be 0 if no path is found.
+ * @param {number} [max_path_length=Infinity] cap on the number of faces written to `output`. If the
+ *        shortest corridor is longer than this it does not fit the buffer and 0 is returned. Pass the
+ *        capacity of `output` to guarantee no out-of-bounds writes.
+ * @returns {number} number of faces that make up the path. This will be 0 if no path is found (or the
+ *        path does not fit `max_path_length`).
  */
 export function bt_mesh_face_find_path(
     output,
     start_face_id,
     goal_face_id,
     topology,
+    max_path_length = Infinity,
 ) {
     assert.isArrayLike(output, 'output');
     assert.isNonNegativeInteger(start_face_id, 'start_face_id');
@@ -141,35 +135,35 @@ export function bt_mesh_face_find_path(
     assert.defined(topology, 'topology');
     assert.equal(topology.isBinaryTopology, true, 'topology.isBinaryTopology !== true');
 
-    // TODO we can switch traversal to edges instead, that way we can get much better distance heuristics
-    //      we don't know where exactly we're going to cross through the triangle, but we know we're going to cross the edge at least, which narrows the domain
-
     open.clear();
     closed.clear();
     g_score.clear();
+    came_from.clear();
 
     g_score.set(start_face_id, 0);
 
-    open.insert(start_face_id, heuristic(start_face_id, goal_face_id, topology));
+    open.insert(start_face_id, face_centroid_distance(start_face_id, goal_face_id, topology));
 
     while (!open.is_empty()) {
 
         const current_node = open.pop_min();
 
-        // Lazy-push: a node may be in the heap multiple times if its g-score was improved after an earlier
-        // push. The lowest-score entry is popped first; later popped duplicates land on an already-closed
-        // node and must be skipped.
+        // Lazy deletion: a face may sit in the heap multiple times if its g-score improved after an
+        // earlier push. The lowest-f entry is popped first; later popped duplicates land on an
+        // already-closed face and must be skipped.
         if (closed.has(current_node)) {
             continue;
         }
 
         if (current_node === goal_face_id) {
             // Reached the goal
-            return construct_path(output, goal_face_id, g_score, topology);
+            return construct_path(output, start_face_id, goal_face_id, came_from, max_path_length);
         }
 
         closed.add(current_node);
 
+        const current_g_score = g_score.get(current_node);
+
         const neighbor_count = bt_face_get_neighbour_faces(neighbors, 0, topology, current_node);
 
         for (let i = 0; i < neighbor_count; i++) {
@@ -181,26 +175,26 @@ export function bt_mesh_face_find_path(
                 continue;
             }
 
-            // TODO compute correct traversal cost based on triangle size
-            const traversal_cost = 1.0;
-
-            const current_g_score = g_score.get(current_node);
+            // step cost is the real geometric distance between adjacent face centroids, so the
+            // search minimises corridor length rather than the number of triangles crossed
+            const traversal_cost = face_centroid_distance(current_node, neighbor, topology);
 
             const cost_so_far = current_g_score + traversal_cost;
 
             if (!g_score.has(neighbor) || cost_so_far < g_score.get(neighbor)) {
-                // better path
+                // better path to this neighbour
 
                 g_score.set(neighbor, cost_so_far);
+                came_from.set(neighbor, current_node);
 
-                const remaining_heuristic = heuristic(neighbor, goal_face_id, topology);
+                const remaining_heuristic = face_centroid_distance(neighbor, goal_face_id, topology);
 
-                const refined_heuristic = cost_so_far + remaining_heuristic;
+                const f_score = cost_so_far + remaining_heuristic;
 
-                // Lazy push: always insert. If neighbor was already on the open list, the older (worse-score)
-                // entry will be skipped when popped (see closed-check at the top of the loop). This avoids
-                // an O(n) find_index_by_id scan per relaxation.
-                open.insert(neighbor, refined_heuristic);
+                // Lazy push: always insert. If neighbor was already on the open list, the older
+                // (worse-f) entry will be skipped when popped (see closed-check at the top of the
+                // loop). This avoids an O(n) find_index_by_id scan per relaxation.
+                open.insert(neighbor, f_score);
 
             }
 
@@ -210,4 +204,4 @@ export function bt_mesh_face_find_path(
 
     // No result found
     return 0;
-}
+}

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

@@ -1,12 +1,23 @@
 /**
+ * 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, agent_height, agent_radius, triangle_count, triangles, random }: BVH): number;
+export function enforce_agent_height_clearance({ bvh, source, agent_height, agent_radius, triangle_count, triangles, up, }: BVH): number;
 //# sourceMappingURL=enforce_agent_height_clearance.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"enforce_agent_height_clearance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/enforce_agent_height_clearance.js"],"names":[],"mappings":"AA4CA;;;;;;;;;GASG;AACH,6HAFa,MAAM,CAuJlB"}
+{"version":3,"file":"enforce_agent_height_clearance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/enforce_agent_height_clearance.js"],"names":[],"mappings":"AAmHA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,kIAFa,MAAM,CA4IlB"}