@woosh/meep-engine 2.133.5 → 2.134.0

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

@@ -0,0 +1,21 @@
+/**
+ * Collapses an edge by merging its two vertices into one, relocating the surviving
+ * vertex to the supplied coordinate.
+ *
+ * All faces incident to the collapse edge are removed (they would become degenerate),
+ * while faces that only share one of the endpoints are retained and re-stitched onto
+ * the surviving vertex. The victim vertex is released.
+ *
+ * NOTE: Does not perform a weld pass, so collapses that share "link" vertices between
+ * the two endpoints will produce duplicate (parallel) edges. The topology remains
+ * self-consistent (disk and radial cycles are intact), but callers doing mesh
+ * simplification typically want to run a cleanup pass afterward.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} edge_id The edge to collapse
+ * @param {number[]|Float32Array} new_position New coordinate for the surviving vertex
+ * @param {number} [new_position_offset] Offset into `new_position`
+ * @returns {number} The surviving vertex ID
+ */
+export function bt_edge_collapse(mesh: BinaryTopology, edge_id: number, new_position: number[] | Float32Array, new_position_offset?: number): number;
+//# sourceMappingURL=bt_edge_collapse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bt_edge_collapse.d.ts","sourceRoot":"","sources":["../../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/edge/bt_edge_collapse.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;GAkBG;AACH,gEALW,MAAM,gBACN,MAAM,EAAE,GAAC,YAAY,wBACrB,MAAM,GACJ,MAAM,CA6BlB"}

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

@@ -0,0 +1,52 @@
+import { assert } from "../../../../../../../assert.js";
+import { bt_vert_kill } from "../vertex/bt_vert_kill.js";
+import { bt_vertex_replace } from "../vertex/bt_vertex_replace.js";
+import { bt_edge_kill } from "./bt_edge_kill.js";
+
+/**
+ * Collapses an edge by merging its two vertices into one, relocating the surviving
+ * vertex to the supplied coordinate.
+ *
+ * All faces incident to the collapse edge are removed (they would become degenerate),
+ * while faces that only share one of the endpoints are retained and re-stitched onto
+ * the surviving vertex. The victim vertex is released.
+ *
+ * NOTE: Does not perform a weld pass, so collapses that share "link" vertices between
+ * the two endpoints will produce duplicate (parallel) edges. The topology remains
+ * self-consistent (disk and radial cycles are intact), but callers doing mesh
+ * simplification typically want to run a cleanup pass afterward.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} edge_id The edge to collapse
+ * @param {number[]|Float32Array} new_position New coordinate for the surviving vertex
+ * @param {number} [new_position_offset] Offset into `new_position`
+ * @returns {number} The surviving vertex ID
+ */
+export function bt_edge_collapse(
+    mesh,
+    edge_id,
+    new_position,
+    new_position_offset = 0
+) {
+    assert.defined(mesh, 'mesh');
+    assert.notNull(mesh, 'mesh');
+    assert.isNonNegativeInteger(edge_id, 'edge_id');
+    assert.defined(new_position, 'new_position');
+
+    const v_survivor = mesh.edge_read_vertex1(edge_id);
+    const v_victim = mesh.edge_read_vertex2(edge_id);
+
+    // 1. Kill adjacent faces and remove the collapse edge itself.
+    bt_edge_kill(mesh, edge_id);
+
+    // 2. Re-point every remaining edge/loop from the victim onto the survivor.
+    bt_vertex_replace(mesh, v_victim, v_survivor);
+
+    // 3. Release the now-disconnected victim vertex.
+    bt_vert_kill(mesh, v_victim);
+
+    // 4. Move the survivor to the requested position.
+    mesh.vertex_write_coordinate(v_survivor, new_position, new_position_offset);
+
+    return v_survivor;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Kill every edge that shares both endpoints with `keep_edge`, leaving `keep_edge`
+ * itself alive. Useful as a pre-pass before {@link bt_edge_collapse} so that
+ * {@link bt_vertex_replace} cannot produce a self-loop edge when a direct parallel
+ * exists.
+ *
+ * Adjacent faces of each killed parallel are removed as part of bt_edge_kill; the
+ * return value reports how many were taken down so callers doing face-count
+ * bookkeeping don't have to rescan.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} keep_edge Edge ID to preserve; its other-parallels are killed.
+ * @returns {number} Number of faces killed as a side effect.
+ */
+export function bt_edge_kill_parallels(mesh: BinaryTopology, keep_edge: number): number;
+//# sourceMappingURL=bt_edge_kill_parallels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bt_edge_kill_parallels.d.ts","sourceRoot":"","sources":["../../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/edge/bt_edge_kill_parallels.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,wEAHW,MAAM,GACJ,MAAM,CAyElB"}

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

@@ -0,0 +1,90 @@
+import { assert } from "../../../../../../../assert.js";
+import { NULL_POINTER } from "../../BinaryTopology.js";
+import { bt_edge_kill } from "./bt_edge_kill.js";
+
+/**
+ * Kill every edge that shares both endpoints with `keep_edge`, leaving `keep_edge`
+ * itself alive. Useful as a pre-pass before {@link bt_edge_collapse} so that
+ * {@link bt_vertex_replace} cannot produce a self-loop edge when a direct parallel
+ * exists.
+ *
+ * Adjacent faces of each killed parallel are removed as part of bt_edge_kill; the
+ * return value reports how many were taken down so callers doing face-count
+ * bookkeeping don't have to rescan.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} keep_edge Edge ID to preserve; its other-parallels are killed.
+ * @returns {number} Number of faces killed as a side effect.
+ */
+export function bt_edge_kill_parallels(mesh, keep_edge) {
+    assert.defined(mesh, 'mesh');
+    assert.notNull(mesh, 'mesh');
+    assert.isNonNegativeInteger(keep_edge, 'keep_edge');
+
+    const a = mesh.edge_read_vertex1(keep_edge);
+    const b = mesh.edge_read_vertex2(keep_edge);
+
+    const start_e = mesh.vertex_read_edge(b);
+
+    if (start_e === NULL_POINTER) {
+        return 0;
+    }
+
+    // Collect parallels while walking b's disk cycle. We snapshot into an array
+    // so that subsequent bt_edge_kill calls (which mutate the disk cycle) can't
+    // invalidate the traversal.
+    const victims = [];
+    let curr_e = start_e;
+
+    do {
+        let next_e;
+        if (mesh.edge_read_vertex1(curr_e) === b) {
+            next_e = mesh.edge_read_v1_disk_next(curr_e);
+        } else {
+            next_e = mesh.edge_read_v2_disk_next(curr_e);
+        }
+
+        if (curr_e !== keep_edge) {
+            const v1 = mesh.edge_read_vertex1(curr_e);
+            const v2 = mesh.edge_read_vertex2(curr_e);
+
+            if ((v1 === a && v2 === b) || (v1 === b && v2 === a)) {
+                victims.push(curr_e);
+            }
+        }
+
+        curr_e = next_e;
+    } while (curr_e !== start_e && curr_e !== NULL_POINTER);
+
+    const edge_pool = mesh.edges;
+    const face_pool = mesh.faces;
+
+    let faces_killed = 0;
+
+    for (let i = 0; i < victims.length; i++) {
+        const e = victims[i];
+
+        if (!edge_pool.is_allocated(e)) {
+            continue;
+        }
+
+        // Count still-allocated faces in this edge's radial loop cycle before
+        // bt_edge_kill drops them. Orphan loops (face already dead) are skipped.
+        const l0 = mesh.edge_read_loop(e);
+
+        if (l0 !== NULL_POINTER) {
+            let l = l0;
+            do {
+                const f = mesh.loop_read_face(l);
+                if (f !== NULL_POINTER && face_pool.is_allocated(f)) {
+                    faces_killed++;
+                }
+                l = mesh.loop_read_radial_next(l);
+            } while (l !== l0 && l !== NULL_POINTER);
+        }
+
+        bt_edge_kill(mesh, e);
+    }
+
+    return faces_killed;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Walk the mesh and fuse any pair of edges that share the same endpoint pair into a single edge.
+ *
+ * When two edges connect the same vertices, all loops on the victim are moved into the master's
+ * radial cycle, the victim is removed from both endpoint disk cycles, and the victim edge is
+ * deallocated. This restores the topology invariant that a vertex pair is represented by at most
+ * one edge — which is what loop/face neighbour queries rely on.
+ *
+ * Degenerate edges (v1 === v2) are left alone; callers that want those removed should run a
+ * dedicated pass.
+ *
+ * Typically used after {@link bt_merge_verts_by_distance}, which re-points vertex references but
+ * can leave behind multiple edges sharing the same endpoint pair.
+ *
+ * @param {BinaryTopology} mesh
+ * @returns {number} number of edges fused away
+ */
+export function bt_mesh_fuse_duplicate_edges(mesh: BinaryTopology): number;
+//# sourceMappingURL=bt_mesh_fuse_duplicate_edges.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bt_mesh_fuse_duplicate_edges.d.ts","sourceRoot":"","sources":["../../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/edge/bt_mesh_fuse_duplicate_edges.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;GAgBG;AACH,oEAFa,MAAM,CA6DlB"}

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

@@ -0,0 +1,83 @@
+import { NULL_POINTER } from "../../BinaryTopology.js";
+import { bt_disk_edge_remove } from "../bt_disk_edge_remove.js";
+import { bt_radial_loop_add } from "../bt_radial_loop_add.js";
+import { bt_radial_loop_remove } from "../bt_radial_loop_remove.js";
+import { bt_kill_only_edge } from "./bt_kill_only_edge.js";
+
+/**
+ * Walk the mesh and fuse any pair of edges that share the same endpoint pair into a single edge.
+ *
+ * When two edges connect the same vertices, all loops on the victim are moved into the master's
+ * radial cycle, the victim is removed from both endpoint disk cycles, and the victim edge is
+ * deallocated. This restores the topology invariant that a vertex pair is represented by at most
+ * one edge — which is what loop/face neighbour queries rely on.
+ *
+ * Degenerate edges (v1 === v2) are left alone; callers that want those removed should run a
+ * dedicated pass.
+ *
+ * Typically used after {@link bt_merge_verts_by_distance}, which re-points vertex references but
+ * can leave behind multiple edges sharing the same endpoint pair.
+ *
+ * @param {BinaryTopology} mesh
+ * @returns {number} number of edges fused away
+ */
+export function bt_mesh_fuse_duplicate_edges(mesh) {
+    const edges = mesh.edges;
+    const edge_count = edges.size;
+
+    let removed_count = 0;
+
+    for (let master = 0; master < edge_count; master++) {
+        if (edges.is_allocated(master) === false) {
+            continue;
+        }
+
+        const master_v1 = mesh.edge_read_vertex1(master);
+        const master_v2 = mesh.edge_read_vertex2(master);
+
+        if (master_v1 === master_v2) {
+            // degenerate edge; skip
+            continue;
+        }
+
+        // walk master_v1's disk cycle, fusing any edge that also connects to master_v2
+        let curr = mesh.edge_read_v1_disk_next(master);
+
+        while (curr !== master) {
+
+            const curr_v1 = mesh.edge_read_vertex1(curr);
+            const curr_v2 = mesh.edge_read_vertex2(curr);
+
+            const curr_on_v1 = curr_v1 === master_v1;
+
+            // capture next before we potentially splice curr out of the disk cycle
+            const next = curr_on_v1
+                ? mesh.edge_read_v1_disk_next(curr)
+                : mesh.edge_read_v2_disk_next(curr);
+
+            const other_endpoint = curr_on_v1 ? curr_v2 : curr_v1;
+
+            if (other_endpoint === master_v2) {
+
+                // move every loop on curr into master's radial cycle
+                let l = mesh.edge_read_loop(curr);
+                while (l !== NULL_POINTER) {
+                    bt_radial_loop_remove(mesh, l, curr);
+                    bt_radial_loop_add(mesh, l, master);
+                    l = mesh.edge_read_loop(curr);
+                }
+
+                bt_disk_edge_remove(mesh, curr, master_v1);
+                bt_disk_edge_remove(mesh, curr, master_v2);
+
+                bt_kill_only_edge(mesh, curr);
+
+                removed_count++;
+            }
+
+            curr = next;
+        }
+    }
+
+    return removed_count;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Localized counterpart to {@link bt_mesh_fuse_duplicate_edges} that inspects only
+ * `v`'s disk cycle. Any two edges in that cycle sharing the same other endpoint
+ * are fused: loops move from the victim to the master, the victim is untangled
+ * from both endpoint disk cycles, and its memory is released.
+ *
+ * If transferring a loop would leave the master edge with two loops on the same
+ * face (i.e. the face has collapsed to a degenerate two-edge polygon), that face
+ * is killed as well.
+ *
+ * Self-loops on `v` are left alone; the caller should handle them separately.
+ *
+ * Typical use: after an iterative edit that may have produced link-vertex
+ * duplicates around `v`, run this to restore the one-edge-per-vertex-pair
+ * invariant without the cost of a whole-mesh pass.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} v
+ * @returns {number} Number of faces killed as a side effect.
+ */
+export function bt_vert_fuse_duplicate_edges(mesh: BinaryTopology, v: number): number;
+//# sourceMappingURL=bt_vert_fuse_duplicate_edges.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bt_vert_fuse_duplicate_edges.d.ts","sourceRoot":"","sources":["../../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/vertex/bt_vert_fuse_duplicate_edges.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,sEAHW,MAAM,GACJ,MAAM,CAyHlB"}

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

@@ -0,0 +1,148 @@
+import { assert } from "../../../../../../../assert.js";
+import { NULL_POINTER } from "../../BinaryTopology.js";
+import { bt_disk_edge_remove } from "../bt_disk_edge_remove.js";
+import { bt_loop_kill } from "../bt_loop_kill.js";
+import { bt_radial_loop_add } from "../bt_radial_loop_add.js";
+import { bt_radial_loop_remove } from "../bt_radial_loop_remove.js";
+import { bt_kill_only_edge } from "../edge/bt_kill_only_edge.js";
+
+/**
+ * Localized counterpart to {@link bt_mesh_fuse_duplicate_edges} that inspects only
+ * `v`'s disk cycle. Any two edges in that cycle sharing the same other endpoint
+ * are fused: loops move from the victim to the master, the victim is untangled
+ * from both endpoint disk cycles, and its memory is released.
+ *
+ * If transferring a loop would leave the master edge with two loops on the same
+ * face (i.e. the face has collapsed to a degenerate two-edge polygon), that face
+ * is killed as well.
+ *
+ * Self-loops on `v` are left alone; the caller should handle them separately.
+ *
+ * Typical use: after an iterative edit that may have produced link-vertex
+ * duplicates around `v`, run this to restore the one-edge-per-vertex-pair
+ * invariant without the cost of a whole-mesh pass.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} v
+ * @returns {number} Number of faces killed as a side effect.
+ */
+export function bt_vert_fuse_duplicate_edges(mesh, v) {
+    assert.defined(mesh, 'mesh');
+    assert.notNull(mesh, 'mesh');
+    assert.isNonNegativeInteger(v, 'v');
+
+    const edge_pool = mesh.edges;
+
+    const start_e = mesh.vertex_read_edge(v);
+
+    if (start_e === NULL_POINTER) {
+        return 0;
+    }
+
+    // Snapshot v's disk cycle up front so that later fusion operations, which
+    // mutate that cycle, don't invalidate our traversal cursor.
+    const edges_in_disk = [];
+    let curr_e = start_e;
+
+    do {
+        edges_in_disk.push(curr_e);
+
+        if (mesh.edge_read_vertex1(curr_e) === v) {
+            curr_e = mesh.edge_read_v1_disk_next(curr_e);
+        } else {
+            curr_e = mesh.edge_read_v2_disk_next(curr_e);
+        }
+    } while (curr_e !== start_e && curr_e !== NULL_POINTER);
+
+    // Group edges by other endpoint to detect duplicates in a single pass.
+    const master_by_other = new Map();
+    const fusion_masters = [];
+    const fusion_victims = [];
+    const fusion_others = [];
+
+    for (let i = 0; i < edges_in_disk.length; i++) {
+        const e = edges_in_disk[i];
+
+        if (!edge_pool.is_allocated(e)) {
+            continue;
+        }
+
+        const v1 = mesh.edge_read_vertex1(e);
+        const v2 = mesh.edge_read_vertex2(e);
+        const other = v1 === v ? v2 : v1;
+
+        if (other === v) {
+            // Self-loop; not our concern here.
+            continue;
+        }
+
+        if (master_by_other.has(other)) {
+            fusion_masters.push(master_by_other.get(other));
+            fusion_victims.push(e);
+            fusion_others.push(other);
+        } else {
+            master_by_other.set(other, e);
+        }
+    }
+
+    const face_pool = mesh.faces;
+
+    let faces_killed = 0;
+
+    for (let i = 0; i < fusion_masters.length; i++) {
+        const master = fusion_masters[i];
+        const victim = fusion_victims[i];
+        const other = fusion_others[i];
+
+        if (!edge_pool.is_allocated(victim) || !edge_pool.is_allocated(master)) {
+            continue;
+        }
+
+        let l = mesh.edge_read_loop(victim);
+
+        while (l !== NULL_POINTER) {
+            bt_radial_loop_remove(mesh, l, victim);
+
+            const face = mesh.loop_read_face(l);
+            let collapse_face = false;
+
+            if (face !== NULL_POINTER && face_pool.is_allocated(face)) {
+                // If master already has a loop on the same face, transferring
+                // this loop would give that face two coincident edges -- a
+                // degenerate polygon that has to die.
+                let mast_l = mesh.edge_read_loop(master);
+                if (mast_l !== NULL_POINTER) {
+                    const mast_start = mast_l;
+                    do {
+                        if (mesh.loop_read_face(mast_l) === face) {
+                            collapse_face = true;
+                            break;
+                        }
+                        mast_l = mesh.loop_read_radial_next(mast_l);
+                    } while (mast_l !== mast_start && mast_l !== NULL_POINTER);
+                }
+            }
+
+            bt_radial_loop_add(mesh, l, master);
+
+            if (collapse_face) {
+                const face_to_kill = face;
+                let fl = mesh.face_read_loop(face_to_kill);
+                while (fl !== NULL_POINTER) {
+                    bt_loop_kill(mesh, fl);
+                    fl = mesh.face_read_loop(face_to_kill);
+                }
+                face_pool.release(face_to_kill);
+                faces_killed++;
+            }
+
+            l = mesh.edge_read_loop(victim);
+        }
+
+        bt_disk_edge_remove(mesh, victim, v);
+        bt_disk_edge_remove(mesh, victim, other);
+        bt_kill_only_edge(mesh, victim);
+    }
+
+    return faces_killed;
+}

package/src/core/geom/3d/topology/struct/binary/query/bt_face_get_incenter.js

@@ -64,11 +64,11 @@ export function bt_face_get_incenter(
 
     do {
         const vertex_id = mesh.loop_read_vertex(current_loop_id);
-        mesh.vertex_read_coordinate(scratch_coord, 0, vertex_id);
+        mesh.vertex_read_coordinate(scratch_coords, 0, vertex_id);
 
-        sum_x += scratch_coord[0];
-        sum_y += scratch_coord[1];
-        sum_z += scratch_coord[2];
+        sum_x += scratch_coords[0];
+        sum_y += scratch_coords[1];
+        sum_z += scratch_coords[2];
 
         vertex_count++;
         current_loop_id = mesh.loop_read_next(current_loop_id);

package/src/core/geom/3d/topology/struct/binary/query/bt_faces_shared_loop.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Find the loop in `face_a` whose edge is shared with `face_b`.
+ *
+ * The returned loop belongs to `face_a` and its edge is also used by a loop in `face_b`.
+ * Combined with {@link BinaryTopology#loop_read_vertex} and {@link BinaryTopology#loop_read_next},
+ * this is enough to read the two vertices of the shared edge in `face_a`'s winding order,
+ * which is useful for constructing directed portals.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} face_a
+ * @param {number} face_b
+ * @returns {number} loop ID in `face_a` that shares an edge with `face_b`, or {@link NULL_POINTER} if no shared edge exists
+ */
+export function bt_faces_shared_loop(mesh: BinaryTopology, face_a: number, face_b: number): number;
+//# sourceMappingURL=bt_faces_shared_loop.d.ts.map

package/src/core/geom/3d/topology/struct/binary/query/bt_faces_shared_loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_faces_shared_loop.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/query/bt_faces_shared_loop.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,mEAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAiClB"}

package/src/core/geom/3d/topology/struct/binary/query/bt_faces_shared_loop.js

@@ -0,0 +1,48 @@
+import { assert } from "../../../../../../assert.js";
+import { NULL_POINTER } from "../BinaryTopology.js";
+
+/**
+ * Find the loop in `face_a` whose edge is shared with `face_b`.
+ *
+ * The returned loop belongs to `face_a` and its edge is also used by a loop in `face_b`.
+ * Combined with {@link BinaryTopology#loop_read_vertex} and {@link BinaryTopology#loop_read_next},
+ * this is enough to read the two vertices of the shared edge in `face_a`'s winding order,
+ * which is useful for constructing directed portals.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} face_a
+ * @param {number} face_b
+ * @returns {number} loop ID in `face_a` that shares an edge with `face_b`, or {@link NULL_POINTER} if no shared edge exists
+ */
+export function bt_faces_shared_loop(mesh, face_a, face_b) {
+    assert.defined(mesh, "mesh");
+    assert.notNull(mesh, "mesh");
+    assert.equal(mesh.isBinaryTopology, true, "mesh.isBinaryTopology !== true");
+    assert.isNonNegativeInteger(face_a, "face_a");
+    assert.isNonNegativeInteger(face_b, "face_b");
+
+    const start_loop = mesh.face_read_loop(face_a);
+
+    if (start_loop === NULL_POINTER) {
+        return NULL_POINTER;
+    }
+
+    let current_loop = start_loop;
+
+    do {
+        // walk the radial cycle around the edge of this loop
+        let radial_loop = mesh.loop_read_radial_next(current_loop);
+
+        while (radial_loop !== current_loop) {
+            if (mesh.loop_read_face(radial_loop) === face_b) {
+                return current_loop;
+            }
+
+            radial_loop = mesh.loop_read_radial_next(radial_loop);
+        }
+
+        current_loop = mesh.loop_read_next(current_loop);
+    } while (current_loop !== start_loop);
+
+    return NULL_POINTER;
+}

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

@@ -10,20 +10,22 @@ export class NavigationMesh {
      * @param {BinaryTopology} source
      * @param {number} [agent_radius]
      * @param {number} [agent_height]
-     * @param {number} [agent_max_climb] In radians, how steep of an angle can the agent go up by
+     * @param {number} [agent_max_climb_angle] In radians, how steep of an angle can the agent go up by
      * @param {Vector3} [up] Defines world's "UP" direction, this is what the agent will respect for climbing constraint
      */
-    build({ source, agent_radius, agent_height, agent_max_climb, up, }: BinaryTopology): void;
+    build({ source, agent_radius, agent_height, agent_max_climb_angle, up, }: BinaryTopology): void;
     /**
+     * Compute a walkable path between the two points.
+     * The result is a sequence of 3d points written into `output`. First point matches start, last point matches goal (snapped onto the mesh).
      *
-     * @param {Float32Array} output
+     * @param {Float32Array} output packed XYZ triples
      * @param {number} start_x
      * @param {number} start_y
      * @param {number} start_z
      * @param {number} goal_x
      * @param {number} goal_y
      * @param {number} goal_z
-     * @returns {number}
+     * @returns {number} number of 3d points written to `output` (0 if no path was found)
      */
     find_path(output: Float32Array, start_x: number, start_y: number, start_z: number, goal_x: number, goal_y: number, goal_z: number): number;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"NavigationMesh.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/NavigationMesh.js"],"names":[],"mappings":"AAmCA;IAEI,yBAAgC;IAEhC;;;OAGG;IACH,KAFU,GAAG,CAEG;IAEhB;;;;;;;OAOG;IACH,oEANW,cAAc,QAwBxB;IAGD;;;;;;;;;;OAUG;IACH,kBATW,YAAY,WACZ,MAAM,WACN,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAwGlB;CAEJ;+BA3L4C,gEAAgE;oBAFzF,gCAAgC"}
+{"version":3,"file":"NavigationMesh.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/NavigationMesh.js"],"names":[],"mappings":"AAgCA;IAEI,yBAAgC;IAEhC;;;OAGG;IACH,KAFU,GAAG,CAEG;IAEhB;;;;;;;OAOG;IACH,0EANW,cAAc,QAwBxB;IAGD;;;;;;;;;;;;OAYG;IACH,kBATW,YAAY,WACZ,MAAM,WACN,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CA+HlB;CAEJ;+BAlN4C,gEAAgE;oBADzF,gCAAgC"}