@woosh/meep-engine 2.138.20 → 2.140.0

package/src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Subtract the pressure gradient from a velocity field in-place, making the velocity
+ * (approximately) divergence-free:
+ *
+ *     v(c) -= 0.5 * ( p(x+1) - p(x-1), p(y+1) - p(y-1), p(z+1) - p(z-1) )
+ *
+ * Pairs with {@link v3_grid_solve_pressure}. After this, divergence will be
+ * close to zero in the bulk; residual divergence at boundaries / under-converged solves
+ * is normal.
+ *
+ * Boundary cells use one-sided differences. Solid cells have their velocity zeroed
+ * (no-slip), and neighbour gradients across a solid face reflect the cell's own
+ * pressure (consistent with the Neumann condition used in the solve), which keeps the
+ * flow tangent to the boundary.
+ *
+ * Which neighbours count as fluid is read straight from `neighbour_mask`, the same
+ * pre-baked per-cell bitmask {@link v3_grid_solve_pressure} consumes (populated by
+ * {@link FluidField.recomputeSolidNeighbourMask}). A set bit means "that neighbour is
+ * fluid (in-bounds AND non-solid)", so a clear bit reflects the cell's own pressure —
+ * folding the boundary check and the solid-neighbour check into one register-resident
+ * bit-test per face. Encoding:
+ *
+ *     bit 0 (= 1)  : -x neighbour is fluid
+ *     bit 1 (= 2)  : +x neighbour is fluid
+ *     bit 2 (= 4)  : -y neighbour is fluid
+ *     bit 3 (= 8)  : +y neighbour is fluid
+ *     bit 4 (= 16) : -z neighbour is fluid
+ *     bit 5 (= 32) : +z neighbour is fluid
+ *
+ * Unlike the solve, the mask can't drive the self-cell branch: both a solid cell and
+ * an isolated fluid cell (no fluid neighbours) encode as `mask = 0`, yet they need
+ * opposite handling — the solid must be zeroed for no-slip, while the isolated fluid's
+ * gradient already nets to zero (every face reflects its own pressure) and must be
+ * left alone. `solid` is what tells them apart, so it stays.
+ *
+ * @param {Float32Array} vel_x          Mutated in place.
+ * @param {Float32Array} vel_y          Mutated in place.
+ * @param {Float32Array} vel_z          Mutated in place.
+ * @param {Float32Array} pressure       From {@link v3_grid_solve_pressure}.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Uint8Array} solid            Required (zero-filled for a wall-free domain).
+ * @param {Uint8Array} neighbour_mask   Length ≥ res_x*res_y*res_z. Same buffer the
+ *     pressure solve uses; MUST be recomputed whenever `solid` changes.
+ */
+export function v3_grid_subtract_pressure_gradient(vel_x: Float32Array, vel_y: Float32Array, vel_z: Float32Array, pressure: Float32Array, res_x: number, res_y: number, res_z: number, solid: Uint8Array, neighbour_mask: Uint8Array): void;
+//# sourceMappingURL=v3_grid_subtract_pressure_gradient.d.ts.map

package/src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_subtract_pressure_gradient.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,0DAXW,YAAY,SACZ,YAAY,SACZ,YAAY,YACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,SACN,UAAU,kBACV,UAAU,QA8CpB"}

package/src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.js

@@ -0,0 +1,92 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Subtract the pressure gradient from a velocity field in-place, making the velocity
+ * (approximately) divergence-free:
+ *
+ *     v(c) -= 0.5 * ( p(x+1) - p(x-1), p(y+1) - p(y-1), p(z+1) - p(z-1) )
+ *
+ * Pairs with {@link v3_grid_solve_pressure}. After this, divergence will be
+ * close to zero in the bulk; residual divergence at boundaries / under-converged solves
+ * is normal.
+ *
+ * Boundary cells use one-sided differences. Solid cells have their velocity zeroed
+ * (no-slip), and neighbour gradients across a solid face reflect the cell's own
+ * pressure (consistent with the Neumann condition used in the solve), which keeps the
+ * flow tangent to the boundary.
+ *
+ * Which neighbours count as fluid is read straight from `neighbour_mask`, the same
+ * pre-baked per-cell bitmask {@link v3_grid_solve_pressure} consumes (populated by
+ * {@link FluidField.recomputeSolidNeighbourMask}). A set bit means "that neighbour is
+ * fluid (in-bounds AND non-solid)", so a clear bit reflects the cell's own pressure —
+ * folding the boundary check and the solid-neighbour check into one register-resident
+ * bit-test per face. Encoding:
+ *
+ *     bit 0 (= 1)  : -x neighbour is fluid
+ *     bit 1 (= 2)  : +x neighbour is fluid
+ *     bit 2 (= 4)  : -y neighbour is fluid
+ *     bit 3 (= 8)  : +y neighbour is fluid
+ *     bit 4 (= 16) : -z neighbour is fluid
+ *     bit 5 (= 32) : +z neighbour is fluid
+ *
+ * Unlike the solve, the mask can't drive the self-cell branch: both a solid cell and
+ * an isolated fluid cell (no fluid neighbours) encode as `mask = 0`, yet they need
+ * opposite handling — the solid must be zeroed for no-slip, while the isolated fluid's
+ * gradient already nets to zero (every face reflects its own pressure) and must be
+ * left alone. `solid` is what tells them apart, so it stays.
+ *
+ * @param {Float32Array} vel_x          Mutated in place.
+ * @param {Float32Array} vel_y          Mutated in place.
+ * @param {Float32Array} vel_z          Mutated in place.
+ * @param {Float32Array} pressure       From {@link v3_grid_solve_pressure}.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Uint8Array} solid            Required (zero-filled for a wall-free domain).
+ * @param {Uint8Array} neighbour_mask   Length ≥ res_x*res_y*res_z. Same buffer the
+ *     pressure solve uses; MUST be recomputed whenever `solid` changes.
+ */
+export function v3_grid_subtract_pressure_gradient(vel_x, vel_y, vel_z, pressure, res_x, res_y, res_z, solid, neighbour_mask) {
+    const cell_count = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(vel_x.length, cell_count, "vel_x covers grid");
+    assert.greaterThanOrEqual(vel_y.length, cell_count, "vel_y covers grid");
+    assert.greaterThanOrEqual(vel_z.length, cell_count, "vel_z covers grid");
+    assert.greaterThanOrEqual(pressure.length, cell_count, "pressure covers grid");
+    assert.greaterThanOrEqual(neighbour_mask.length, cell_count, "neighbour_mask covers grid");
+
+    const slice_size = res_x * res_y;
+
+    for (let z = 0; z < res_z; z++) {
+        const z_off = z * slice_size;
+
+        for (let y = 0; y < res_y; y++) {
+            const y_off = y * res_x;
+
+            for (let x = 0; x < res_x; x++) {
+                const c = z_off + y_off + x;
+
+                if (solid[c] !== 0) {
+                    vel_x[c] = 0;
+                    vel_y[c] = 0;
+                    vel_z[c] = 0;
+                    continue;
+                }
+
+                // A clear bit means the neighbour is out-of-bounds or solid; reflect
+                // the cell's own pressure so that face contributes 0 to the gradient,
+                // consistent with ∂p/∂n = 0 at the wall.
+                const mask = neighbour_mask[c];
+                const p_xm = (mask & 1)  ? pressure[c - 1]          : pressure[c];
+                const p_xp = (mask & 2)  ? pressure[c + 1]          : pressure[c];
+                const p_ym = (mask & 4)  ? pressure[c - res_x]      : pressure[c];
+                const p_yp = (mask & 8)  ? pressure[c + res_x]      : pressure[c];
+                const p_zm = (mask & 16) ? pressure[c - slice_size] : pressure[c];
+                const p_zp = (mask & 32) ? pressure[c + slice_size] : pressure[c];
+
+                vel_x[c] -= 0.5 * (p_xp - p_xm);
+                vel_y[c] -= 0.5 * (p_yp - p_ym);
+                vel_z[c] -= 0.5 * (p_zp - p_zm);
+            }
+        }
+    }
+}

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

@@ -1,13 +1,13 @@
 /**
  * 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
  */
-export function expanding_polytope_algorithm(result: number[], result_offset: number, a: number[], b: number[], c: number[], d: number[], coll1: AbstractShape3D, coll2: AbstractShape3D): void;
+export function expanding_polytope_algorithm(result: number[] | Float64Array, result_offset: number, a: number[] | Float64Array, b: number[] | Float64Array, c: number[] | Float64Array, d: number[] | Float64Array, coll1: AbstractShape3D, coll2: AbstractShape3D): void;
 //# sourceMappingURL=expanding_polytope_algorithm.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"expanding_polytope_algorithm.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/gjk/expanding_polytope_algorithm.js"],"names":[],"mappings":"AAgEA;;;;;;;;;;GAUG;AACH,qDATW,MAAM,EAAE,iBACR,MAAM,KACN,MAAM,EAAE,KACR,MAAM,EAAE,KACR,MAAM,EAAE,KACR,MAAM,EAAE,wDAgQlB"}
+{"version":3,"file":"expanding_polytope_algorithm.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/gjk/expanding_polytope_algorithm.js"],"names":[],"mappings":"AAqGA;;;;;;;;;;GAUG;AACH,qDATW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,KACN,MAAM,EAAE,GAAC,YAAY,KACrB,MAAM,EAAE,GAAC,YAAY,KACrB,MAAM,EAAE,GAAC,YAAY,KACrB,MAAM,EAAE,GAAC,YAAY,wDAuQ/B"}

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;
@@ -238,12 +278,12 @@ export function expanding_polytope_algorithm(
                 }
 
                 if (!found_edge) { //add current edge to list
-                    // assert(num_loose_edges<EPA_MAX_NUM_LOOSE_EDGES);
-
-                    assert.lessThan(num_loose_edges, EPA_MAX_NUM_LOOSE_EDGES);
-
                     if (num_loose_edges >= EPA_MAX_NUM_LOOSE_EDGES) {
-                        // this should not happen, but if it does it is best to be "kind of right" than to fail completely
+                        // Polytope degenerated (typically smooth-surface
+                        // pairs the dispatch should be special-casing — this
+                        // is the safety net). Bail out and return the
+                        // closest-face result accumulated so far instead of
+                        // crashing the simulation step.
                         break;
                     }
 
@@ -271,12 +311,10 @@ export function expanding_polytope_algorithm(
 
         //Reconstruct polytope with p added
         for (let i = 0; i < num_loose_edges; i++) {
-            // assert(num_faces<EPA_MAX_NUM_FACES);
-
-            assert.lessThan(num_faces, EPA_MAX_NUM_FACES);
-
             if (num_faces >= EPA_MAX_NUM_FACES) {
-                // should never happen
+                // Polytope hit the face cap before converging. Same
+                // degenerate-surface story as the loose-edge overflow above.
+                // Bail out and let the caller use the best face found so far.
                 break;
             }
 
@@ -313,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"}