@woosh/meep-engine 2.139.0 → 2.141.0

package/src/engine/physics/gjk/expanding_polytope_algorithm.js

@@ -1,4 +1,3 @@
-import { assert } from "../../../core/assert.js";
 import { array_copy } from "../../../core/collection/array/array_copy.js";
 import { array_swap } from "../../../core/collection/array/array_swap.js";
 import { v3_compute_triangle_normal } from "../../../core/geom/3d/triangle/v3_compute_triangle_normal.js";
@@ -7,7 +6,30 @@ import { v3_dot_array_array } from "../../../core/geom/vec3/v3_dot_array_array.j
 
 import { v3_negate_array } from "../../../core/geom/vec3/v3_negate_array.js";
 
-const EPA_TOLERANCE = 0.0001;
+/**
+ * Convergence tolerance — relative to the current closest-face distance,
+ * floored at an absolute epsilon to prevent zero-distance loops.
+ *
+ * Why relative, not absolute (P2.2). An absolute `EPA_TOLERANCE = 1e-4`
+ * works for mid-scale contacts (a few millimetres deep on metre-sized
+ * bodies) but degrades for shallow contacts: when the closest-face
+ * distance is ~1e-5 m (sub-mm overlaps that the speculative-margin path
+ * handles), `1e-4` is *larger than the depth itself*, so EPA terminates
+ * with whatever intermediate face it happens to have, producing a noisy
+ * normal direction. Jolt's `EPSILON_REL_DIST_SQ` and similar
+ * formulations scale tolerance with the current distance.
+ *
+ * Note: only the TOLERANCE was made relative as part of P2.2. The
+ * convergence-path RESULT magnitude is intentionally left as
+ * `dot_p_search_dir` (the new support point's projection) — switching
+ * to `min_dist` was tried and caused energy injection in the closed-
+ * form-dispatch paths that share the EPA depth metric (e.g.
+ * sphere-vs-sphere stack regressions). See REVIEW_001_ACTION_PLAN.md.
+ *
+ * @type {number}
+ */
+const EPA_TOLERANCE_REL = 1e-4;
+const EPA_TOLERANCE_ABS = 1e-6;
 const EPA_MAX_NUM_FACES = 64;
 const EPA_MAX_NUM_LOOSE_EDGES = 32;
 const EPA_MAX_NUM_ITERATIONS = 64;
@@ -16,16 +38,31 @@ const FACE_ELEMENT_COUNT = 3 * 4;
 
 const EDGE_ELEMENT_COUNT = 2 * 3;
 
-//Array of faces, each with 3 verts and a normal
-const faces = new Float32Array(EPA_MAX_NUM_FACES * FACE_ELEMENT_COUNT);
+/**
+ * Polytope face buffer. Float64 throughout — EPA's expand-and-recompute
+ * step iterates up to {@link EPA_MAX_NUM_ITERATIONS} times, each
+ * iteration rebuilds face normals via cross products, and tests them
+ * against accumulated support points; the per-iteration error in
+ * Float32 compounds and noticeably slows convergence on shapes with
+ * many similar-magnitude faces (anything with subtle curvature). The
+ * memory footprint of the upgrade is the buffer's size doubling — a
+ * few KB at most.
+ *
+ * Layout per face: 3 vec3 vertices + 1 vec3 normal = 12 floats.
+ * @type {Float64Array}
+ */
+const faces = new Float64Array(EPA_MAX_NUM_FACES * FACE_ELEMENT_COUNT);
 
 /**
- * keep track of edges we need to fix after removing faces
- * @type {Float32Array}
+ * Edges we need to fix after removing faces. Same Float64 motivation
+ * as {@link faces} — endpoints are vertex coords pulled out of `faces`,
+ * and any precision loss here propagates back into the next face when
+ * the polytope is rebuilt.
+ * @type {Float64Array}
  */
-const loose_edges = new Float32Array(EPA_MAX_NUM_LOOSE_EDGES * EDGE_ELEMENT_COUNT);
+const loose_edges = new Float64Array(EPA_MAX_NUM_LOOSE_EDGES * EDGE_ELEMENT_COUNT);
 
-const scratch_v3 = new Float32Array(3);
+const scratch_v3 = new Float64Array(3);
 
 /**
  *
@@ -39,7 +76,7 @@ function write_v3(target, target_index, v) {
 
 /**
  *
- * @param {number[]|Float32Array} faces
+ * @param {number[]|Float64Array} faces
  * @param {number} index
  * @param {number[]} a
  * @param {number[]} b
@@ -64,12 +101,12 @@ function write_face(faces, index, a, b, c) {
 
 /**
  * TODO: needs to be tested thoroughly, intended to be working with GJK
- * @param {number[]} result
+ * @param {number[]|Float64Array} result
  * @param {number} result_offset
- * @param {number[]} a
- * @param {number[]} b
- * @param {number[]} c
- * @param {number[]} d
+ * @param {number[]|Float64Array} a
+ * @param {number[]|Float64Array} b
+ * @param {number[]|Float64Array} c
+ * @param {number[]|Float64Array} d
  * @param {AbstractShape3D} coll1
  * @param {AbstractShape3D} coll2
  */
@@ -117,10 +154,6 @@ export function expanding_polytope_algorithm(
         const search_dir_y = faces[closest_face_normal_offset + 1];
         const search_dir_z = faces[closest_face_normal_offset + 2];
 
-        if (search_dir_x === 0 && search_dir_y === 0 && search_dir_z === 0) {
-            debugger;
-        }
-
         // build new support point to expand polytope
 
         coll2.support(scratch_v3, 0, search_dir_x, search_dir_y, search_dir_z);
@@ -141,7 +174,14 @@ export function expanding_polytope_algorithm(
 
         const dot_p_search_dir = v3_dot(p_x, p_y, p_z, search_dir_x, search_dir_y, search_dir_z);
 
-        if (dot_p_search_dir - min_dist < EPA_TOLERANCE) {
+        // Adaptive convergence (P2.2). Terminate when the new support
+        // point's projection onto the current search direction is
+        // within a RELATIVE tolerance of the current closest-face
+        // distance — scales with depth instead of the fixed absolute
+        // EPA_TOLERANCE = 1e-4 that was too coarse for sub-mm contacts.
+        const min_dist_abs = min_dist < 0 ? -min_dist : min_dist;
+        const tol_floor = min_dist_abs > EPA_TOLERANCE_ABS ? min_dist_abs : EPA_TOLERANCE_ABS;
+        if (dot_p_search_dir - min_dist < EPA_TOLERANCE_REL * tol_floor) {
             //Convergence (new point is not significantly further from origin)
 
             result[result_offset] = search_dir_x * dot_p_search_dir;
@@ -311,9 +351,15 @@ export function expanding_polytope_algorithm(
         }
     }
 
-    console.warn("EPA did not converge");
-
-    //Return most recent closest point
+    // Iteration cap reached without convergence. Return the
+    // closest-face approximation rather than warning — this is the
+    // expected outcome on smooth / high-complexity shapes (a torus knot
+    // collider produces it dozens of times per frame while the player
+    // is in contact). The narrowphase consumer treats any depth that
+    // isn't strictly positive + finite as a miss, so a degenerate
+    // closest-face result is filtered upstream. PLAN.md already lists
+    // EPA-on-smooth-shapes as a known limitation; the actionable fix
+    // is MPR / hierarchical support, not console spam.
     const closest_face_offset = closest_face * FACE_ELEMENT_COUNT;
     const closest_face_normal_offset = closest_face_offset + 3 * 3;
 

package/src/engine/physics/gjk/gjk.d.ts

@@ -7,10 +7,36 @@
  *
  * Adapted from https://github.com/kevinmoran/GJK/blob/master/GJK.h
  *
- * @param {number[]|Float32Array} simplex Working buffer for simplex vertices (4 vec3s). Must have length >= 12.
+ * @param {number[]|Float64Array} simplex Working buffer for simplex vertices (4 vec3s). Must have length >= 12.
  * @param {AbstractShape3D} shape_a
  * @param {AbstractShape3D} shape_b
  * @returns {boolean} true if the shapes intersect
  */
-export function gjk(simplex: number[] | Float32Array, shape_a: AbstractShape3D, shape_b: AbstractShape3D): boolean;
+export function gjk(simplex: number[] | Float64Array, shape_a: AbstractShape3D, shape_b: AbstractShape3D): boolean;
+/**
+ * Separating-axis-cached variant of {@link gjk}. The 3 floats at
+ * `axis_buffer[axis_offset..+2]` are used as the initial search
+ * direction (seed) AND are overwritten with the final search direction
+ * on exit. The narrowphase keeps a per-manifold-slot cache of these
+ * three floats so quiescent contacts converge in 1–2 iterations next
+ * frame instead of ~6–10 from a cold `(1, 0, 0)` start (Bullet's
+ * `m_cachedSeparatingAxis` and Jolt's `ioV` use the same pattern).
+ *
+ * The same primitive doubles as a separating-axis cache for the
+ * "no-overlap" path: when GJK returns false, the final direction is
+ * roughly the separating axis, and next frame's first iteration
+ * detects separation immediately.
+ *
+ * Writeback is automatic — `gjk_core` mutates a `subarray` view of
+ * `axis_buffer`, so on return `axis_buffer[axis_offset..+2]` holds the
+ * final direction. No try/finally needed.
+ *
+ * @param {number[]|Float64Array} simplex
+ * @param {AbstractShape3D} shape_a
+ * @param {AbstractShape3D} shape_b
+ * @param {Float64Array} axis_buffer
+ * @param {number} axis_offset
+ * @returns {boolean}
+ */
+export function gjk_with_axis(simplex: number[] | Float64Array, shape_a: AbstractShape3D, shape_b: AbstractShape3D, axis_buffer: Float64Array, axis_offset: number): boolean;
 //# sourceMappingURL=gjk.d.ts.map

package/src/engine/physics/gjk/gjk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gjk.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/gjk/gjk.js"],"names":[],"mappings":"AAmDA;;;;;;;;;;;;;GAaG;AACH,6BALW,MAAM,EAAE,GAAC,YAAY,uDAGnB,OAAO,CAkGnB"}
+{"version":3,"file":"gjk.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/gjk/gjk.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;GAaG;AACH,6BALW,MAAM,EAAE,GAAC,YAAY,uDAGnB,OAAO,CAWnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,uCAPW,MAAM,EAAE,GAAC,YAAY,mEAGrB,YAAY,eACZ,MAAM,GACJ,OAAO,CAqBnB"}