@woosh/meep-engine 2.138.20 → 2.140.0

package/src/engine/physics/narrowphase/compute_penetration.js

@@ -0,0 +1,396 @@
+import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
+import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
+import { mpr } from "../gjk/mpr.js";
+import { aabb_world_to_local } from "./decomposition/aabb_world_to_local.js";
+import { decompose_to_triangles } from "./decomposition/decompose_to_triangles.js";
+import { TRIANGLE_FLOAT_STRIDE } from "./decomposition/triangle_buffer_layout.js";
+import { PosedShape } from "./PosedShape.js";
+
+/**
+ * Module-scoped scratch — same single-thread re-entrancy assumption as
+ * the other narrowphase utilities. Safe because PhysicsSystem queries
+ * (and gameplay code calling this) run on the main thread.
+ */
+const posed_a = new PosedShape();
+const posed_b = new PosedShape();
+
+// MPR result buffer — direction is "A's interior into B", magnitude is
+// the depth. Same convention as EPA but MPR converges reliably on
+// smooth-vs-smooth supports where EPA hits its iteration cap and
+// returns a noisy closest-face approximation.
+const mpr_result = new Float64Array(3);
+
+/**
+ * Scratch buffers for the convex-vs-concave path (see
+ * {@link compute_penetration_concave}).
+ */
+const local_aabb = new Float64Array(6);
+const world_aabb = new Float64Array(6);
+const concave_query_aabb = new Float64Array(6);
+const scratch_v3 = new Float64Array(3);
+// Dedicated scratch for the per-triangle q · v · q* rotations below
+// (face normal + centroid). Distinct from `scratch_v3` (used by the
+// support-function call later in the same iteration) to keep the
+// data flow obvious.
+const scratch_rot = new Float64Array(3);
+
+/**
+ * Per-pair triangle decomposition cap. Same rationale as
+ * `narrowphase_step.MAX_TRIANGLES_PER_PAIR` and
+ * `overlap_shape.MAX_TRIANGLES_PER_PAIR`: the query AABB is already
+ * bounded by the convex shape's envelope, so a single pair typically
+ * yields tens of triangles. Excess triangles are dropped by the
+ * enumerator's bounds check.
+ * @type {number}
+ */
+const MAX_TRIANGLES_PER_PAIR = 1024;
+const triangle_buffer = new Float64Array(MAX_TRIANGLES_PER_PAIR * TRIANGLE_FLOAT_STRIDE);
+
+/**
+ * Penetration depths below this are treated as no contact. GJK can
+ * report tangent configurations as "overlap" — at exact tangent the
+ * Minkowski difference touches the origin and the algorithm can go
+ * either way; if it says overlap, EPA then returns a sub-micron depth
+ * that reflects numerical noise rather than a real penetration. The
+ * "0 means no overlap" contract is more useful when small-noise hits
+ * are filtered out at the source.
+ *
+ * 1e-4 m (100 µm) chosen to be well below any practical world-scale
+ * tolerance while still being larger than typical EPA convergence
+ * residuals at exact tangent. Smaller values would let near-tangent
+ * floating-point noise leak through as "tiny positive depth".
+ *
+ * @type {number}
+ */
+const CONTACT_EPSILON = 1e-4;
+
+/**
+ * Compute the penetration depth between two shapes at world poses,
+ * returning the depth and writing the separation direction.
+ *
+ * If the shapes overlap, the return value is the positive distance
+ * along `out_direction` you would have to translate `shape_a` to
+ * separate it from `shape_b`. `out_direction` is the unit vector
+ * pointing from `shape_b` toward `shape_a` — applying
+ * `out_direction * return_value` to `position_a` (or equivalently
+ * `-out_direction * return_value` to `position_b`) is the minimum
+ * translation that produces separation.
+ *
+ * If the shapes do not overlap (or EPA degenerates on a tangent
+ * contact), the return value is `0` and `out_direction` is left
+ * untouched. Callers should treat 0 as "no penetration".
+ *
+ * Sign convention matches the narrowphase's stored contact normal:
+ *   - `out_direction` ≡ "B → A" direction
+ *   - Negative of cast direction in shape_cast at the kiss point
+ *   - The outward normal of B's surface at the contact, pointing
+ *     toward A
+ *
+ * Built on the existing GJK + EPA + PosedShape primitives — same
+ * precision characteristics (essentially exact for sign-based supports
+ * like cubes; asymptotic on curved supports like spheres near tangent,
+ * where the polytope iteration cap leaves a small angular residual on
+ * the direction).
+ *
+ * ## Non-convex support
+ *
+ * Exactly **one** of the two shapes may be non-convex (heightmap,
+ * mesh). The non-convex shape is decomposed into triangles overlapping
+ * the convex shape's AABB (via the same machinery the narrowphase
+ * uses), and per-triangle GJK + EPA is run; the deepest contact's
+ * direction and depth are reported. Concave-vs-concave throws — the
+ * M×N triangle-pair cost is out of scope for this primitive (and is
+ * also refused by the narrowphase for dynamic pairs).
+ *
+ * ## Non-convex precision limits
+ *
+ * The concave path is a per-triangle half-space test (convex's deepest
+ * point along −face_normal, compared to the triangle's plane). This
+ * is exact for **heightmaps** — adjacent triangles cover the
+ * boundary cases, and the face normal IS the contact direction.
+ *
+ * For **closed meshes** the half-space test extrapolates each triangle
+ * as an infinite plane, which can over-report depth on side faces
+ * when the convex shape extends past a face's 2D extent. The
+ * deepest-wins aggregation then picks a "false-deepest" face whose
+ * direction may not be the geometrically optimal one. A closed-form
+ * triangle-vs-X solver per primitive shape would fix this; until
+ * then, the function reports *some* outward direction with positive
+ * depth, which still resolves penetration over multiple iterations.
+ *
+ * Bodies fully inside the concave solid (or below a heightmap
+ * surface) are correctly recovered: every face's deepest-inward
+ * support point lands on the inward side, so the half-space test
+ * fires, and the deepest face wins. The reported direction pushes
+ * the body outward through that face.
+ *
+ * @param {Float64Array|number[]} out_direction length ≥ 3; receives
+ *   the unit separation direction (B → A) on penetration
+ * @param {AbstractShape3D} shape_a  in shape_a's local frame; may be concave
+ * @param {{x:number,y:number,z:number}} position_a  world position of A
+ * @param {{x:number,y:number,z:number,w:number}} rotation_a  world rotation of A
+ * @param {AbstractShape3D} shape_b  in shape_b's local frame; may be concave
+ * @param {{x:number,y:number,z:number}} position_b  world position of B
+ * @param {{x:number,y:number,z:number,w:number}} rotation_b  world rotation of B
+ * @returns {number} penetration depth (positive) on overlap, 0 otherwise
+ * @throws {Error} if both shapes have `is_convex === false`
+ */
+export function compute_penetration(
+    out_direction,
+    shape_a, position_a, rotation_a,
+    shape_b, position_b, rotation_b
+) {
+    const isConcaveA = shape_a.is_convex === false;
+    const isConcaveB = shape_b.is_convex === false;
+
+    if (isConcaveA && isConcaveB) {
+        throw new Error("compute_penetration: at most one shape may be non-convex (concave-vs-concave triangle-pair cost is out of scope)");
+    }
+
+    if (isConcaveA || isConcaveB) {
+        return compute_penetration_concave(
+            out_direction, isConcaveA,
+            shape_a, position_a, rotation_a,
+            shape_b, position_b, rotation_b
+        );
+    }
+
+    return compute_penetration_convex(
+        out_direction,
+        shape_a, position_a, rotation_a,
+        shape_b, position_b, rotation_b
+    );
+}
+
+/**
+ * Convex-vs-convex implementation — single MPR call.
+ *
+ * MPR (Minkowski Portal Refinement) gives an overlap-or-not answer
+ * plus the MTV in one pass, with reliable convergence on smooth
+ * supports where the previous GJK + EPA path struggled (sphere-vs-
+ * sphere shallow overlap, sphere-vs-box near-tangent — the closest-
+ * face direction would noise out by 20-30° before EPA hit its
+ * iteration cap). MPR converges in 5-15 iterations on those same
+ * configurations.
+ * @private
+ */
+function compute_penetration_convex(
+    out_direction,
+    shape_a, position_a, rotation_a,
+    shape_b, position_b, rotation_b
+) {
+    posed_a.setup(shape_a, position_a, rotation_a);
+    posed_b.setup(shape_b, position_b, rotation_b);
+
+    if (!mpr(mpr_result, 0, posed_a, posed_b)) return 0;
+
+    let ex = mpr_result[0], ey = mpr_result[1], ez = mpr_result[2];
+    const depth = Math.sqrt(ex * ex + ey * ey + ez * ez);
+    if (!(depth > CONTACT_EPSILON) || !Number.isFinite(depth)) return 0;
+
+    // MTV direction sanity check: should point from A's centre toward
+    // B's centre. Same trick as in `narrowphase_step` — even MPR can
+    // settle on either side of the origin for symmetric configurations
+    // (axis-aligned cubes), so dot against the body-centre axis and
+    // flip if needed.
+    const ab_x = position_b.x - position_a.x;
+    const ab_y = position_b.y - position_a.y;
+    const ab_z = position_b.z - position_a.z;
+    if (ex * ab_x + ey * ab_y + ez * ab_z < 0) {
+        ex = -ex; ey = -ey; ez = -ez;
+    }
+
+    // MTV now points A → B. out_direction is B → A.
+    const inv = 1 / depth;
+    out_direction[0] = -ex * inv;
+    out_direction[1] = -ey * inv;
+    out_direction[2] = -ez * inv;
+
+    return depth;
+}
+
+/**
+ * Convex-vs-concave implementation — decompose, per-triangle half-space
+ * test, deepest-wins aggregation.
+ *
+ * Why the half-space test instead of per-triangle GJK + EPA:
+ *
+ * GJK + EPA on `Triangle3D` (a flat 2D shape) has a known degeneracy.
+ * `Triangle3D.support` along the triangle's face-normal axis returns
+ * the SAME vertex regardless of sign (all three vertices have equal
+ * projection along that axis). GJK can't converge from this degenerate
+ * support and returns false positives — sphere clearly above a flat
+ * surface gets reported as overlapping, with EPA producing a non-zero
+ * depth in some arbitrary direction.
+ *
+ * The half-space test is closed-form and exact for this case:
+ *
+ *   1. Compute the triangle's outward face normal in world frame
+ *      (winding gives outward-CCW per the enumerator's contract).
+ *   2. Query `convex.support(-face_normal)` — the deepest point of the
+ *      convex shape along the face-normal axis in the inward direction.
+ *   3. Project that point onto the face normal relative to the
+ *      triangle's centroid plane.
+ *   4. If the projection is positive, the convex shape is entirely on
+ *      the outward side — no penetration. Skip.
+ *   5. Otherwise the magnitude is the penetration depth, and the
+ *      face normal IS the contact direction.
+ *
+ * For continuous concave surfaces (heightmaps with adjacent triangles
+ * sharing edges) the half-space test gives exact results: any penetrating
+ * convex either crosses a triangle's plane within the triangle's 2D
+ * extent (correct depth reported) or hits an adjacent triangle.
+ *
+ * For closed meshes (each face is a separate triangle, edges are shared
+ * between facets at angles), the half-space test can over-report when a
+ * convex is outside the triangle's 2D extent but still on the inward
+ * side of its infinite plane. Deepest-wins aggregation makes this
+ * harmless in practice — the dominant face's depth wins, which is the
+ * geometrically meaningful answer for the kinematic-resolution use case.
+ *
+ * One-sided rejection is built into the test itself: if the convex's
+ * deepest inward point is still on the outward side, depth ≤ 0 → skip.
+ * Bodies in fully-invalid states (inside a closed mesh, below a
+ * heightmap surface) get rejected naturally and return 0.
+ *
+ * @private
+ */
+function compute_penetration_concave(
+    out_direction, isConcaveA,
+    shape_a, position_a, rotation_a,
+    shape_b, position_b, rotation_b
+) {
+    // Internally normalise: "concave" side is what we decompose;
+    // "convex" side is wrapped in PosedShape and queried via support.
+    const concave_shape = isConcaveA ? shape_a : shape_b;
+    const concave_pos   = isConcaveA ? position_a : position_b;
+    const concave_rot   = isConcaveA ? rotation_a : rotation_b;
+    const convex_shape  = isConcaveA ? shape_b : shape_a;
+    const convex_pos    = isConcaveA ? position_b : position_a;
+    const convex_rot    = isConcaveA ? rotation_b : rotation_a;
+
+    // ── 1. Convex shape's world AABB ───────────────────────────────
+    convex_shape.compute_bounding_box(local_aabb);
+    aabb3_transform_oriented(
+        world_aabb, 0,
+        local_aabb[0], local_aabb[1], local_aabb[2],
+        local_aabb[3], local_aabb[4], local_aabb[5],
+        convex_pos.x, convex_pos.y, convex_pos.z,
+        convex_rot.x, convex_rot.y, convex_rot.z, convex_rot.w
+    );
+
+    // ── 2. Project into concave's body-local frame ─────────────────
+    aabb_world_to_local(
+        concave_query_aabb, 0,
+        world_aabb,
+        concave_pos.x, concave_pos.y, concave_pos.z,
+        concave_rot.x, concave_rot.y, concave_rot.z, concave_rot.w
+    );
+
+    // ── 3. Decompose to triangles ──────────────────────────────────
+    const tri_count = decompose_to_triangles(
+        triangle_buffer, 0, concave_shape,
+        concave_query_aabb[0], concave_query_aabb[1], concave_query_aabb[2],
+        concave_query_aabb[3], concave_query_aabb[4], concave_query_aabb[5]
+    );
+    if (tri_count === 0) return 0;
+
+    // ── 4. Setup convex PosedShape (we'll call support on it per tri) ─
+    posed_b.setup(convex_shape, convex_pos, convex_rot);
+
+    const cqx = concave_rot.x;
+    const cqy = concave_rot.y;
+    const cqz = concave_rot.z;
+    const cqw = concave_rot.w;
+    const c_pos_x = concave_pos.x;
+    const c_pos_y = concave_pos.y;
+    const c_pos_z = concave_pos.z;
+
+    // ── 5. Per-triangle half-space test, deepest-wins ──────────────
+    let best_depth = 0;
+    let best_fnx_w = 0, best_fny_w = 0, best_fnz_w = 0;
+
+    for (let i = 0; i < tri_count; i++) {
+        const tri_offset = i * TRIANGLE_FLOAT_STRIDE;
+
+        const ax = triangle_buffer[tri_offset    ];
+        const ay = triangle_buffer[tri_offset + 1];
+        const az = triangle_buffer[tri_offset + 2];
+        const bx = triangle_buffer[tri_offset + 3];
+        const by = triangle_buffer[tri_offset + 4];
+        const bz = triangle_buffer[tri_offset + 5];
+        const cx_v = triangle_buffer[tri_offset + 6];
+        const cy_v = triangle_buffer[tri_offset + 7];
+        const cz_v = triangle_buffer[tri_offset + 8];
+
+        // Face normal in body-local: (B − A) × (C − A), then normalise.
+        const e1x_l = bx - ax, e1y_l = by - ay, e1z_l = bz - az;
+        const e2x_l = cx_v - ax, e2y_l = cy_v - ay, e2z_l = cz_v - az;
+        let fnx_l = e1y_l * e2z_l - e1z_l * e2y_l;
+        let fny_l = e1z_l * e2x_l - e1x_l * e2z_l;
+        let fnz_l = e1x_l * e2y_l - e1y_l * e2x_l;
+        const fn_mag = Math.sqrt(fnx_l * fnx_l + fny_l * fny_l + fnz_l * fnz_l);
+        if (fn_mag < 1e-12) continue;  // degenerate triangle
+        const fn_inv = 1 / fn_mag;
+        fnx_l *= fn_inv; fny_l *= fn_inv; fnz_l *= fn_inv;
+
+        // Rotate face normal to world via the concave body's quaternion.
+        v3_quat3_apply(scratch_rot, 0, fnx_l, fny_l, fnz_l, cqx, cqy, cqz, cqw);
+        const fnx_w = scratch_rot[0];
+        const fny_w = scratch_rot[1];
+        const fnz_w = scratch_rot[2];
+
+        // Centroid in body-local → world (one point on the triangle's plane).
+        const cent_lx = (ax + bx + cx_v) / 3;
+        const cent_ly = (ay + by + cy_v) / 3;
+        const cent_lz = (az + bz + cz_v) / 3;
+        v3_quat3_apply(scratch_rot, 0, cent_lx, cent_ly, cent_lz, cqx, cqy, cqz, cqw);
+        const cent_wx = scratch_rot[0] + c_pos_x;
+        const cent_wy = scratch_rot[1] + c_pos_y;
+        const cent_wz = scratch_rot[2] + c_pos_z;
+
+        // Deepest inward point of convex along -face_normal.
+        posed_b.support(scratch_v3, 0, -fnx_w, -fny_w, -fnz_w);
+
+        // Signed distance from that point to the triangle plane along
+        // the face normal: > 0 ⇒ convex is fully on outward side,
+        // ≤ 0 ⇒ convex extends |dist| into the solid through this face.
+        const signed_dist =
+              (scratch_v3[0] - cent_wx) * fnx_w
+            + (scratch_v3[1] - cent_wy) * fny_w
+            + (scratch_v3[2] - cent_wz) * fnz_w;
+
+        if (signed_dist >= 0) continue;
+
+        const depth = -signed_dist;
+        if (depth < CONTACT_EPSILON) continue;
+
+        if (depth > best_depth) {
+            best_depth = depth;
+            best_fnx_w = fnx_w;
+            best_fny_w = fny_w;
+            best_fnz_w = fnz_w;
+        }
+    }
+
+    if (best_depth === 0) return 0;
+
+    // ── 6. Write out_direction in the user's "B → A" convention ────
+    //
+    // The face normal points OUTWARD from the concave's solid.
+    //   - isConcaveA: original A = concave. "B → A" = convex → concave
+    //     = INTO the solid = −face_normal.
+    //   - isConcaveB: original A = convex. "B → A" = concave → convex
+    //     = AWAY from the solid = +face_normal.
+    if (isConcaveA) {
+        out_direction[0] = -best_fnx_w;
+        out_direction[1] = -best_fny_w;
+        out_direction[2] = -best_fnz_w;
+    } else {
+        out_direction[0] = best_fnx_w;
+        out_direction[1] = best_fny_w;
+        out_direction[2] = best_fnz_w;
+    }
+
+    return best_depth;
+}

package/src/engine/physics/narrowphase/decomposition/aabb_world_to_local.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Transform a world-space AABB into a body's local frame.
+ *
+ * Given the body's world transform (pos, rot), computes
+ *   p_local = rot⁻¹ · (p_world − pos)
+ * for each of the world AABB's 8 corners, then writes the tight bbox
+ * over those 8 transformed corners.
+ *
+ * Used by the concave-shape narrowphase path: a concave collider's
+ * triangle enumerator wants its query AABB in the concave shape's
+ * body-local frame, so we project the other collider's *world* AABB
+ * through the concave body's inverse pose to get that.
+ *
+ * 8-corner brute force rather than Arvo's element-wise-abs trick:
+ *   - The world AABB we start from is *already* a loose envelope (it
+ *     came from oriented-rotate of the other shape's local AABB), so
+ *     applying Arvo a second time would compound the looseness. The
+ *     corner-by-corner pass produces the tightest projected AABB we
+ *     can derive from the world AABB without going back to the
+ *     untransformed local AABB.
+ *   - One-time-per-pair cost, not in the per-triangle hot loop.
+ *
+ * @param {Float64Array} out 6-float min/max in body-local frame
+ * @param {number} out_offset
+ * @param {Float64Array|number[]} world_aabb 6-float min/max in world frame
+ * @param {number} pos_x   body world position
+ * @param {number} pos_y
+ * @param {number} pos_z
+ * @param {number} rot_x   body world rotation (unit quaternion)
+ * @param {number} rot_y
+ * @param {number} rot_z
+ * @param {number} rot_w
+ */
+export function aabb_world_to_local(out: Float64Array, out_offset: number, world_aabb: Float64Array | number[], pos_x: number, pos_y: number, pos_z: number, rot_x: number, rot_y: number, rot_z: number, rot_w: number): void;
+//# sourceMappingURL=aabb_world_to_local.d.ts.map

package/src/engine/physics/narrowphase/decomposition/aabb_world_to_local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aabb_world_to_local.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/narrowphase/decomposition/aabb_world_to_local.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,yCAXW,YAAY,cACZ,MAAM,cACN,YAAY,GAAC,MAAM,EAAE,SACrB,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,QAwChB"}

package/src/engine/physics/narrowphase/decomposition/aabb_world_to_local.js

@@ -0,0 +1,80 @@
+import { v3_quat3_apply_inverse } from "../../../../core/geom/vec3/v3_quat3_apply_inverse.js";
+
+/**
+ * Scratch for the per-corner inverse-rotation output. 3 floats; allocation-free.
+ * @type {Float64Array}
+ */
+const scratch_local = new Float64Array(3);
+
+/**
+ * Transform a world-space AABB into a body's local frame.
+ *
+ * Given the body's world transform (pos, rot), computes
+ *   p_local = rot⁻¹ · (p_world − pos)
+ * for each of the world AABB's 8 corners, then writes the tight bbox
+ * over those 8 transformed corners.
+ *
+ * Used by the concave-shape narrowphase path: a concave collider's
+ * triangle enumerator wants its query AABB in the concave shape's
+ * body-local frame, so we project the other collider's *world* AABB
+ * through the concave body's inverse pose to get that.
+ *
+ * 8-corner brute force rather than Arvo's element-wise-abs trick:
+ *   - The world AABB we start from is *already* a loose envelope (it
+ *     came from oriented-rotate of the other shape's local AABB), so
+ *     applying Arvo a second time would compound the looseness. The
+ *     corner-by-corner pass produces the tightest projected AABB we
+ *     can derive from the world AABB without going back to the
+ *     untransformed local AABB.
+ *   - One-time-per-pair cost, not in the per-triangle hot loop.
+ *
+ * @param {Float64Array} out 6-float min/max in body-local frame
+ * @param {number} out_offset
+ * @param {Float64Array|number[]} world_aabb 6-float min/max in world frame
+ * @param {number} pos_x   body world position
+ * @param {number} pos_y
+ * @param {number} pos_z
+ * @param {number} rot_x   body world rotation (unit quaternion)
+ * @param {number} rot_y
+ * @param {number} rot_z
+ * @param {number} rot_w
+ */
+export function aabb_world_to_local(
+    out, out_offset,
+    world_aabb,
+    pos_x, pos_y, pos_z,
+    rot_x, rot_y, rot_z, rot_w
+) {
+    let min_x = Infinity, min_y = Infinity, min_z = Infinity;
+    let max_x = -Infinity, max_y = -Infinity, max_z = -Infinity;
+
+    for (let corner = 0; corner < 8; corner++) {
+        const wx = (corner & 1) !== 0 ? world_aabb[3] : world_aabb[0];
+        const wy = (corner & 2) !== 0 ? world_aabb[4] : world_aabb[1];
+        const wz = (corner & 4) !== 0 ? world_aabb[5] : world_aabb[2];
+
+        // Translate to body-centered, then inverse-rotate into local frame.
+        v3_quat3_apply_inverse(
+            scratch_local, 0,
+            wx - pos_x, wy - pos_y, wz - pos_z,
+            rot_x, rot_y, rot_z, rot_w
+        );
+        const lx = scratch_local[0];
+        const ly = scratch_local[1];
+        const lz = scratch_local[2];
+
+        if (lx < min_x) min_x = lx;
+        if (ly < min_y) min_y = ly;
+        if (lz < min_z) min_z = lz;
+        if (lx > max_x) max_x = lx;
+        if (ly > max_y) max_y = ly;
+        if (lz > max_z) max_z = lz;
+    }
+
+    out[out_offset    ] = min_x;
+    out[out_offset + 1] = min_y;
+    out[out_offset + 2] = min_z;
+    out[out_offset + 3] = max_x;
+    out[out_offset + 4] = max_y;
+    out[out_offset + 5] = max_z;
+}

package/src/engine/physics/narrowphase/decomposition/decompose_to_triangles.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Dispatch a non-convex shape to its triangle enumerator. Writes
+ * triangles into `output` at float-index `offset`, with the layout
+ * specified by {@link TRIANGLE_FLOAT_STRIDE} in `triangle_buffer_layout`.
+ *
+ * Explicit per-shape dispatch (no virtual `enumerate_triangles` method
+ * on AbstractShape3D) — adding support for a new concave shape kind is
+ * one line here plus a new enumerator file. The narrowphase calls this
+ * once per concave collider per contact pair; if performance ever
+ * becomes a worry, the entire function can be inlined into the
+ * call site without touching the enumerators.
+ *
+ * Throws if `shape` has no registered enumerator. The narrowphase
+ * gates this behind `shape.is_convex === false`, and every shape with
+ * `is_convex === false` is required to have an enumerator — there's
+ * no silent fallback to "empty triangle set" because that would
+ * masquerade the bug as a missed collision.
+ *
+ * @param {Float64Array} output
+ * @param {number} offset float-index into output
+ * @param {AbstractShape3D} shape (must have `is_convex === false`)
+ * @param {number} aabb_min_x query AABB in shape's body-local frame
+ * @param {number} aabb_min_y
+ * @param {number} aabb_min_z
+ * @param {number} aabb_max_x
+ * @param {number} aabb_max_y
+ * @param {number} aabb_max_z
+ * @returns {number} number of triangles written
+ */
+export function decompose_to_triangles(output: Float64Array, offset: number, shape: AbstractShape3D, aabb_min_x: number, aabb_min_y: number, aabb_min_z: number, aabb_max_x: number, aabb_max_y: number, aabb_max_z: number): number;
+//# sourceMappingURL=decompose_to_triangles.d.ts.map

package/src/engine/physics/narrowphase/decomposition/decompose_to_triangles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decompose_to_triangles.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/narrowphase/decomposition/decompose_to_triangles.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,+CAXW,YAAY,UACZ,MAAM,sCAEN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAwBlB"}

package/src/engine/physics/narrowphase/decomposition/decompose_to_triangles.js

@@ -0,0 +1,55 @@
+import { heightmap_enumerate_triangles } from "./heightmap_enumerate_triangles.js";
+import { mesh_enumerate_triangles } from "./mesh_enumerate_triangles.js";
+
+/**
+ * Dispatch a non-convex shape to its triangle enumerator. Writes
+ * triangles into `output` at float-index `offset`, with the layout
+ * specified by {@link TRIANGLE_FLOAT_STRIDE} in `triangle_buffer_layout`.
+ *
+ * Explicit per-shape dispatch (no virtual `enumerate_triangles` method
+ * on AbstractShape3D) — adding support for a new concave shape kind is
+ * one line here plus a new enumerator file. The narrowphase calls this
+ * once per concave collider per contact pair; if performance ever
+ * becomes a worry, the entire function can be inlined into the
+ * call site without touching the enumerators.
+ *
+ * Throws if `shape` has no registered enumerator. The narrowphase
+ * gates this behind `shape.is_convex === false`, and every shape with
+ * `is_convex === false` is required to have an enumerator — there's
+ * no silent fallback to "empty triangle set" because that would
+ * masquerade the bug as a missed collision.
+ *
+ * @param {Float64Array} output
+ * @param {number} offset float-index into output
+ * @param {AbstractShape3D} shape (must have `is_convex === false`)
+ * @param {number} aabb_min_x query AABB in shape's body-local frame
+ * @param {number} aabb_min_y
+ * @param {number} aabb_min_z
+ * @param {number} aabb_max_x
+ * @param {number} aabb_max_y
+ * @param {number} aabb_max_z
+ * @returns {number} number of triangles written
+ */
+export function decompose_to_triangles(
+    output, offset, shape,
+    aabb_min_x, aabb_min_y, aabb_min_z,
+    aabb_max_x, aabb_max_y, aabb_max_z
+) {
+    if (shape.isHeightMapShape3D === true) {
+        return heightmap_enumerate_triangles(
+            output, offset, shape,
+            aabb_min_x, aabb_min_y, aabb_min_z,
+            aabb_max_x, aabb_max_y, aabb_max_z
+        );
+    }
+
+    if (shape.isMeshShape3D === true) {
+        return mesh_enumerate_triangles(
+            output, offset, shape,
+            aabb_min_x, aabb_min_y, aabb_min_z,
+            aabb_max_x, aabb_max_y, aabb_max_z
+        );
+    }
+
+    throw new Error(`decompose_to_triangles: no enumerator registered for shape kind \`${shape.constructor.name}\``);
+}

package/src/engine/physics/narrowphase/decomposition/heightmap_enumerate_triangles.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Write the heightmap's triangles that may overlap the given body-local
+ * query AABB into `output`, starting at float-index `offset`.
+ *
+ * Each triangle occupies {@link TRIANGLE_FLOAT_STRIDE} consecutive floats:
+ *   [+0..+2]  vA.xyz   (body-local frame)
+ *   [+3..+5]  vB.xyz
+ *   [+6..+8]  vC.xyz
+ *   [+9]      feature_id   (stable across frames; warm-start key)
+ *
+ * The feature_id encodes `(cell_y * (W - 1) + cell_x) * 2 + tri_idx`
+ * where (cell_x, cell_y) is the grid cell and tri_idx ∈ {0, 1}. Two
+ * triangles per cell, lower-left-diagonal split (matches the existing
+ * {@link build_height_field_geometry} winding).
+ *
+ * The query AABB is filtered against the footprint *and* against the
+ * cell grid; triangles outside the query AABB along the height axis are
+ * NOT filtered out — that test is left to the per-triangle narrowphase
+ * (where the precise GJK distance is computed anyway). This keeps the
+ * enumerator branch-free over the height field and aligned with what
+ * Bullet's btHeightfieldTerrainShape does.
+ *
+ * The caller is responsible for ensuring
+ *   `output.length - offset >= cells_in_query * 2 * TRIANGLE_FLOAT_STRIDE`
+ * — sizing the scratch buffer for the *worst-case* query AABB is the
+ * right pattern (the broadphase already bounded the AABB to one body's
+ * world envelope, so the cell count is bounded by the footprint
+ * resolution).
+ *
+ * @param {Float64Array} output
+ * @param {number} offset float-index into output
+ * @param {HeightMapShape3D} shape
+ * @param {number} aabb_min_x  query AABB in shape's body-local frame
+ * @param {number} aabb_min_y
+ * @param {number} aabb_min_z
+ * @param {number} aabb_max_x
+ * @param {number} aabb_max_y
+ * @param {number} aabb_max_z
+ * @returns {number} number of triangles written
+ */
+export function heightmap_enumerate_triangles(output: Float64Array, offset: number, shape: HeightMapShape3D, aabb_min_x: number, aabb_min_y: number, aabb_min_z: number, aabb_max_x: number, aabb_max_y: number, aabb_max_z: number): number;
+//# sourceMappingURL=heightmap_enumerate_triangles.d.ts.map

package/src/engine/physics/narrowphase/decomposition/heightmap_enumerate_triangles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heightmap_enumerate_triangles.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/narrowphase/decomposition/heightmap_enumerate_triangles.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,sDAXW,YAAY,UACZ,MAAM,uCAEN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAmKlB"}