@woosh/meep-engine 2.139.0 → 2.141.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.139.0",
+  "version": "2.141.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.d.ts

@@ -1,9 +1,9 @@
 /**
  *
- * @param {number[]} result
+ * @param {number[]|Uint32Array} result
  * @param {number} result_offset
  * @param {BVH} bvh
- * @param {number[]|Float32Array|AABB3} aabb
+ * @param {number[]|Float32Array|Float64Array|AABB3} aabb
  */
-export function bvh_query_user_data_overlaps_aabb(result: number[], result_offset: number, bvh: BVH, aabb: number[] | Float32Array | AABB3): number;
+export function bvh_query_user_data_overlaps_aabb(result: number[] | Uint32Array, result_offset: number, bvh: BVH, aabb: number[] | Float32Array | Float64Array | AABB3): number;
 //# sourceMappingURL=bvh_query_user_data_overlaps_aabb.d.ts.map

package/src/core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bvh_query_user_data_overlaps_aabb.d.ts","sourceRoot":"","sources":["../../../../../../src/core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH,0DALW,MAAM,EAAE,iBACR,MAAM,kBAEN,MAAM,EAAE,GAAC,YAAY,QAAM,UAoErC"}
+{"version":3,"file":"bvh_query_user_data_overlaps_aabb.d.ts","sourceRoot":"","sources":["../../../../../../src/core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH,0DALW,MAAM,EAAE,GAAC,WAAW,iBACpB,MAAM,kBAEN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,QAAM,UAoElD"}

package/src/core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js

@@ -9,10 +9,10 @@ const scratch_aabb = new Float32Array(6);
 
 /**
  *
- * @param {number[]} result
+ * @param {number[]|Uint32Array} result
  * @param {number} result_offset
  * @param {BVH} bvh
- * @param {number[]|Float32Array|AABB3} aabb
+ * @param {number[]|Float32Array|Float64Array|AABB3} aabb
  */
 export function bvh_query_user_data_overlaps_aabb(
     result,
@@ -48,7 +48,7 @@ export function bvh_query_user_data_overlaps_aabb(
         // test node against the ray
         bvh.node_get_aabb(node, scratch_aabb);
 
-       const intersection_exists = aabb3_intersects_aabb3(
+        const intersection_exists = aabb3_intersects_aabb3(
             scratch_aabb[0], scratch_aabb[1], scratch_aabb[2],
             scratch_aabb[3], scratch_aabb[4], scratch_aabb[5],
             aabb[0], aabb[1], aabb[2],
@@ -66,7 +66,7 @@ export function bvh_query_user_data_overlaps_aabb(
             // leaf node
             result[result_cursor++] = bvh.node_get_user_data(node);
 
-        }  else {
+        } else {
             // read in-order
             const child1 = bvh.node_get_child1(node);
             const child2 = bvh.node_get_child2(node);

package/src/{engine/physics/broadphase/aabb_transform_oriented.d.ts → core/geom/3d/aabb/aabb3_transform_oriented.d.ts}

@@ -26,5 +26,5 @@
  * @param {number} qz  quaternion z
  * @param {number} qw  quaternion w
  */
-export function aabb_transform_oriented(result: number[] | Float32Array | Float64Array, result_offset: number, lx0: number, ly0: number, lz0: number, lx1: number, ly1: number, lz1: number, px: number, py: number, pz: number, qx: number, qy: number, qz: number, qw: number): void;
-//# sourceMappingURL=aabb_transform_oriented.d.ts.map
+export function aabb3_transform_oriented(result: number[] | Float32Array | Float64Array, result_offset: number, lx0: number, ly0: number, lz0: number, lx1: number, ly1: number, lz1: number, px: number, py: number, pz: number, qx: number, qy: number, qz: number, qw: number): void;
+//# sourceMappingURL=aabb3_transform_oriented.d.ts.map

package/src/core/geom/3d/aabb/aabb3_transform_oriented.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aabb3_transform_oriented.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/aabb/aabb3_transform_oriented.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,iDAhBW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAkEhB"}

package/src/{engine/physics/broadphase/aabb_transform_oriented.js → core/geom/3d/aabb/aabb3_transform_oriented.js}

@@ -26,7 +26,7 @@
  * @param {number} qz  quaternion z
  * @param {number} qw  quaternion w
  */
-export function aabb_transform_oriented(
+export function aabb3_transform_oriented(
     result, result_offset,
     lx0, ly0, lz0, lx1, ly1, lz1,
     px, py, pz,

package/src/core/geom/3d/quaternion/quat3_multiply.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hamilton product of two unit quaternions: `out = a ⊗ b`.
+ *
+ * Composition order is the usual rotation convention: the product `a ⊗ b`
+ * applies `b` first, then `a` (i.e. `(a⊗b)·v·(a⊗b)* == a·(b·v·b*)·a*`). So to
+ * rotate a vector by `q1` and then by `q2`, compose `q2 ⊗ q1`.
+ *
+ * Sign convention: `(x, y, z, w)` — `w` last, matching {@link Quaternion} and
+ * the rest of the `core/geom/3d/quaternion/` family.
+ *
+ * `out` may alias neither `a` nor `b` component-wise (the result is computed
+ * from all eight inputs before any write, so passing the same backing array
+ * via different offsets is safe only if the ranges don't overlap).
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
+ * @param {number} ax @param {number} ay @param {number} az @param {number} aw
+ * @param {number} bx @param {number} by @param {number} bz @param {number} bw
+ */
+export function quat3_multiply(out: number[] | Float32Array | Float64Array, out_offset: number, ax: number, ay: number, az: number, aw: number, bx: number, by: number, bz: number, bw: number): void;
+//# sourceMappingURL=quat3_multiply.d.ts.map

package/src/core/geom/3d/quaternion/quat3_multiply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quat3_multiply.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/quat3_multiply.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,oCALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,MACN,MAAM,MAAa,MAAM,MAAa,MAAM,MAAa,MAAM,MAC/D,MAAM,MAAa,MAAM,MAAa,MAAM,MAAa,MAAM,QAOzE"}

package/src/core/geom/3d/quaternion/quat3_multiply.js

@@ -0,0 +1,25 @@
+/**
+ * Hamilton product of two unit quaternions: `out = a ⊗ b`.
+ *
+ * Composition order is the usual rotation convention: the product `a ⊗ b`
+ * applies `b` first, then `a` (i.e. `(a⊗b)·v·(a⊗b)* == a·(b·v·b*)·a*`). So to
+ * rotate a vector by `q1` and then by `q2`, compose `q2 ⊗ q1`.
+ *
+ * Sign convention: `(x, y, z, w)` — `w` last, matching {@link Quaternion} and
+ * the rest of the `core/geom/3d/quaternion/` family.
+ *
+ * `out` may alias neither `a` nor `b` component-wise (the result is computed
+ * from all eight inputs before any write, so passing the same backing array
+ * via different offsets is safe only if the ranges don't overlap).
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
+ * @param {number} ax @param {number} ay @param {number} az @param {number} aw
+ * @param {number} bx @param {number} by @param {number} bz @param {number} bw
+ */
+export function quat3_multiply(out, out_offset, ax, ay, az, aw, bx, by, bz, bw) {
+    out[out_offset]     = aw * bx + ax * bw + ay * bz - az * by;
+    out[out_offset + 1] = aw * by - ax * bz + ay * bw + az * bx;
+    out[out_offset + 2] = aw * bz + ax * by - ay * bx + az * bw;
+    out[out_offset + 3] = aw * bw - ax * bx - ay * by - az * bz;
+}

package/src/core/geom/3d/quaternion/quat3_to_matrix3.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Convert a unit quaternion to a 3×3 matrix laid out as
+ * "rows-are-world-coords-of-the-local-axes".
+ *
+ * Writes 9 floats starting at `out[out_offset]`:
+ *
+ *   row 0 (offsets 0..2) — image of body-local +X in world space
+ *   row 1 (offsets 3..5) — image of body-local +Y in world space
+ *   row 2 (offsets 6..8) — image of body-local +Z in world space
+ *
+ * This is the **transpose** of the standard linear-algebra rotation
+ * matrix `R(q)` (which is "columns-are-world-coords-of-local-axes" or
+ * equivalently rows-are-local-coords-of-world-axes). The layout here
+ * matches the existing `quat_to_axes` helpers in
+ * `box_box_manifold.js` / `box_triangle_contact.js` — for SAT
+ * projection a row dot product against a candidate axis directly
+ * yields "extent of the box's local axis i along that direction":
+ *
+ *   project_onto(v) = out[off+0..2] · v        // ← local-X extent
+ *
+ * Computing M(q) once and reusing across many vectors is cheaper
+ * than calling {@link v3_quat3_apply} per vector when the same
+ * orientation rotates ≥ 4 vectors (box-vs-box SAT projects 8
+ * corners; box-vs-triangle clips an incident face). For one-shot
+ * rotation use {@link v3_quat3_apply} directly.
+ *
+ * To rotate a world-space vector `v` into the local frame via the
+ * matrix form, the standard `R · v` (rotate local → world) requires
+ * a **column-major** read of this storage:
+ *
+ *   (R · v)[i] = out[off + 0 + i] * v[0]
+ *              + out[off + 3 + i] * v[1]
+ *              + out[off + 6 + i] * v[2]
+ *
+ * — equivalent to {@link v3_quat3_apply}(v, q).
+ *
+ * Sign convention: `(qx, qy, qz, qw)` — `w` last, matching
+ * {@link Quaternion} and the rest of the `core/geom/3d/quaternion/`
+ * family.
+ *
+ * Formula (yields R^T of the standard linear-algebra rotation matrix):
+ *   out[0]=1-2(yy+zz)   out[1]=2(xy+wz)     out[2]=2(xz-wy)
+ *   out[3]=2(xy-wz)     out[4]=1-2(xx+zz)   out[5]=2(yz+wx)
+ *   out[6]=2(xz+wy)     out[7]=2(yz-wx)     out[8]=1-2(xx+yy)
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 9 floats
+ * @param {number} qx unit quaternion x
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw unit quaternion w (last)
+ */
+export function quat3_to_matrix3(out: number[] | Float32Array | Float64Array, out_offset: number, qx: number, qy: number, qz: number, qw: number): void;
+//# sourceMappingURL=quat3_to_matrix3.d.ts.map

package/src/core/geom/3d/quaternion/quat3_to_matrix3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quat3_to_matrix3.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/quat3_to_matrix3.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,sCAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAkBhB"}

package/src/core/geom/3d/quaternion/quat3_to_matrix3.js

@@ -0,0 +1,69 @@
+/**
+ * Convert a unit quaternion to a 3×3 matrix laid out as
+ * "rows-are-world-coords-of-the-local-axes".
+ *
+ * Writes 9 floats starting at `out[out_offset]`:
+ *
+ *   row 0 (offsets 0..2) — image of body-local +X in world space
+ *   row 1 (offsets 3..5) — image of body-local +Y in world space
+ *   row 2 (offsets 6..8) — image of body-local +Z in world space
+ *
+ * This is the **transpose** of the standard linear-algebra rotation
+ * matrix `R(q)` (which is "columns-are-world-coords-of-local-axes" or
+ * equivalently rows-are-local-coords-of-world-axes). The layout here
+ * matches the existing `quat_to_axes` helpers in
+ * `box_box_manifold.js` / `box_triangle_contact.js` — for SAT
+ * projection a row dot product against a candidate axis directly
+ * yields "extent of the box's local axis i along that direction":
+ *
+ *   project_onto(v) = out[off+0..2] · v        // ← local-X extent
+ *
+ * Computing M(q) once and reusing across many vectors is cheaper
+ * than calling {@link v3_quat3_apply} per vector when the same
+ * orientation rotates ≥ 4 vectors (box-vs-box SAT projects 8
+ * corners; box-vs-triangle clips an incident face). For one-shot
+ * rotation use {@link v3_quat3_apply} directly.
+ *
+ * To rotate a world-space vector `v` into the local frame via the
+ * matrix form, the standard `R · v` (rotate local → world) requires
+ * a **column-major** read of this storage:
+ *
+ *   (R · v)[i] = out[off + 0 + i] * v[0]
+ *              + out[off + 3 + i] * v[1]
+ *              + out[off + 6 + i] * v[2]
+ *
+ * — equivalent to {@link v3_quat3_apply}(v, q).
+ *
+ * Sign convention: `(qx, qy, qz, qw)` — `w` last, matching
+ * {@link Quaternion} and the rest of the `core/geom/3d/quaternion/`
+ * family.
+ *
+ * Formula (yields R^T of the standard linear-algebra rotation matrix):
+ *   out[0]=1-2(yy+zz)   out[1]=2(xy+wz)     out[2]=2(xz-wy)
+ *   out[3]=2(xy-wz)     out[4]=1-2(xx+zz)   out[5]=2(yz+wx)
+ *   out[6]=2(xz+wy)     out[7]=2(yz-wx)     out[8]=1-2(xx+yy)
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 9 floats
+ * @param {number} qx unit quaternion x
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw unit quaternion w (last)
+ */
+export function quat3_to_matrix3(out, out_offset, qx, qy, qz, qw) {
+    const xx = qx * qx, yy = qy * qy, zz = qz * qz;
+    const xy = qx * qy, xz = qx * qz, yz = qy * qz;
+    const wx = qw * qx, wy = qw * qy, wz = qw * qz;
+
+    out[out_offset]     = 1 - 2 * (yy + zz);
+    out[out_offset + 1] = 2 * (xy + wz);
+    out[out_offset + 2] = 2 * (xz - wy);
+
+    out[out_offset + 3] = 2 * (xy - wz);
+    out[out_offset + 4] = 1 - 2 * (xx + zz);
+    out[out_offset + 5] = 2 * (yz + wx);
+
+    out[out_offset + 6] = 2 * (xz + wy);
+    out[out_offset + 7] = 2 * (yz - wx);
+    out[out_offset + 8] = 1 - 2 * (xx + yy);
+}

package/src/core/geom/3d/shape/AbstractShape3D.d.ts

@@ -51,14 +51,14 @@ export class AbstractShape3D {
     /**
      * Support function, given a direction vector, return point on the shape that's furthest in that direction
      * Assumes direction is a unit vector
-     * @param {number[]|Float32Array} result
+     * @param {number[]|Float32Array|Float64Array} result
      * @param {number} result_offset
      * @param {number} direction_x
      * @param {number} direction_y
      * @param {number} direction_z
      * @returns {void}
      */
-    support(result: number[] | Float32Array, result_offset: number, direction_x: number, direction_y: number, direction_z: number): void;
+    support(result: number[] | Float32Array | Float64Array, result_offset: number, direction_x: number, direction_y: number, direction_z: number): void;
     /**
      * @template {AbstractShape3D} T
      * @param {T} other
@@ -70,5 +70,27 @@ export class AbstractShape3D {
      * @returns {number}
      */
     hash(): number;
+    /**
+     * Whether this shape is convex.
+     *
+     * Convex shapes can be fed directly into GJK/EPA via their {@link support}
+     * function — the Minkowski difference of two convex sets is itself convex,
+     * which is the precondition GJK relies on. Non-convex shapes (heightmaps,
+     * arbitrary meshes, unions of convex shapes) violate that precondition: the
+     * support operator is still definable as `argmax (p · d)`, but feeding it to
+     * GJK will produce false negatives where the algorithm walks into a
+     * concavity and reports "no overlap" between intersecting bodies.
+     *
+     * The narrowphase reads this flag to gate Minkowski-based pair dispatch.
+     * When `false`, a dedicated path is required (grid traversal for heightmaps,
+     * per-triangle GJK for meshes, per-child decomposition for unions).
+     *
+     * Default is `true` — convex is the common case across primitives. Each
+     * non-convex subclass overrides this on its own prototype.
+     *
+     * @readonly
+     * @type {boolean}
+     */
+    readonly is_convex: boolean;
 }
 //# sourceMappingURL=AbstractShape3D.d.ts.map

package/src/core/geom/3d/shape/AbstractShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/AbstractShape3D.js"],"names":[],"mappings":"AAAA;IACI;;;;OAIG;IACH,gCAHW,MAAM,EAAE,GACN,MAAM,CAIlB;IAED;;;;;OAKG;IACH,0CAJW,MAAM,EAAE,SACR,MAAM,EAAE,GACN,MAAM,CAIlB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,EAAE,aACR,MAAM,EAAE,GACN,IAAI,CAIhB;IAED;;;;;;OAMG;IACH,sCALW,MAAM,EAAE,iBACR,MAAM,qBAEJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,sBAHW,MAAM,EAAE,GACN,OAAO,CAInB;IAED;;;OAGG;IACH,qBAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,6BAHW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,GAAC,YAAY,GAClD,IAAI,CAIhB;IAED;;;;;;;;;OASG;IACH,gBAPW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,6CAFa,OAAO,CAInB;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;CACJ"}
+{"version":3,"file":"AbstractShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/AbstractShape3D.js"],"names":[],"mappings":"AAAA;IACI;;;;OAIG;IACH,gCAHW,MAAM,EAAE,GACN,MAAM,CAIlB;IAED;;;;;OAKG;IACH,0CAJW,MAAM,EAAE,SACR,MAAM,EAAE,GACN,MAAM,CAIlB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,EAAE,aACR,MAAM,EAAE,GACN,IAAI,CAIhB;IAED;;;;;;OAMG;IACH,sCALW,MAAM,EAAE,iBACR,MAAM,qBAEJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,sBAHW,MAAM,EAAE,GACN,OAAO,CAInB;IAED;;;OAGG;IACH,qBAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,6BAHW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,GAAC,YAAY,GAClD,IAAI,CAIhB;IAED;;;;;;;;;OASG;IACH,gBAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,6CAFa,OAAO,CAInB;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAGL;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,oBAFU,OAAO,CAEkB;CAvBlC"}

package/src/core/geom/3d/shape/AbstractShape3D.js

@@ -75,7 +75,7 @@ export class AbstractShape3D {
     /**
      * Support function, given a direction vector, return point on the shape that's furthest in that direction
      * Assumes direction is a unit vector
-     * @param {number[]|Float32Array} result
+     * @param {number[]|Float32Array|Float64Array} result
      * @param {number} result_offset
      * @param {number} direction_x
      * @param {number} direction_y
@@ -103,3 +103,26 @@ export class AbstractShape3D {
         return 0;
     }
 }
+
+/**
+ * Whether this shape is convex.
+ *
+ * Convex shapes can be fed directly into GJK/EPA via their {@link support}
+ * function — the Minkowski difference of two convex sets is itself convex,
+ * which is the precondition GJK relies on. Non-convex shapes (heightmaps,
+ * arbitrary meshes, unions of convex shapes) violate that precondition: the
+ * support operator is still definable as `argmax (p · d)`, but feeding it to
+ * GJK will produce false negatives where the algorithm walks into a
+ * concavity and reports "no overlap" between intersecting bodies.
+ *
+ * The narrowphase reads this flag to gate Minkowski-based pair dispatch.
+ * When `false`, a dedicated path is required (grid traversal for heightmaps,
+ * per-triangle GJK for meshes, per-child decomposition for unions).
+ *
+ * Default is `true` — convex is the common case across primitives. Each
+ * non-convex subclass overrides this on its own prototype.
+ *
+ * @readonly
+ * @type {boolean}
+ */
+AbstractShape3D.prototype.is_convex = true;

package/src/core/geom/3d/shape/HeightMapShape3D.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Heightmap shape, intended primarily for terrain.
+ *
+ * The shape is a closed solid bounded below by the plane perpendicular to
+ * {@link orientation} (the "floor") and above by a height-field surface
+ * defined by a {@link Sampler2D}. Heights are sampled with Catmull-Rom
+ * filtering ({@link Sampler2D#sampleChannelCatmullRomUV}), matching what
+ * the terrain system uses for geometry construction.
+ *
+ * Local frame layout:
+ *   - The orientation vector defines the local "up" axis (unit).
+ *   - An orthonormal basis (u, v, n=orientation) is built from it.
+ *   - Footprint extends along the basis-u axis over [-size.x/2, +size.x/2]
+ *     and along the basis-v axis over [-size.z/2, +size.z/2].
+ *   - The surface height (along orientation) at heightmap-UV (u01, v01) is
+ *     `sampler.sampleChannelCatmullRomUV(u01, v01, 0)`.
+ *   - The solid volume occupies `h ∈ [0, sampledHeight(u01, v01)]` along the
+ *     orientation axis, with `0` being the floor at body-local origin.
+ *   - `size.y` is the maximum height value of the heightfield (used for the
+ *     bounding box). Sampler values are NOT clamped to it.
+ *
+ * NON-CONVEX. {@link support} throws — GJK/EPA cannot be run against a
+ * heightmap directly. The physics narrowphase must dispatch a dedicated
+ * grid-traversal path when one of the colliders is a heightmap.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class HeightMapShape3D extends AbstractShape3D {
+    /**
+     * Convenience constructor.
+     * @param {Sampler2D} sampler
+     * @param {number} size_x footprint extent along basis-u
+     * @param {number} size_y maximum heightmap height (along orientation)
+     * @param {number} size_z footprint extent along basis-v
+     * @param {Vector3} [orientation] defaults to +Y
+     * @returns {HeightMapShape3D}
+     */
+    static from(sampler: Sampler2D, size_x: number, size_y: number, size_z: number, orientation?: Vector3): HeightMapShape3D;
+    /**
+     * Unit vector defining the local "up" axis (the direction the
+     * heightmap's surface faces). Default is +Y.
+     * @readonly
+     * @type {Vector3}
+     */
+    readonly orientation: Vector3;
+    /**
+     * Bounding-box extents in the heightmap-local (u, height, v) frame.
+     *   size.x — footprint extent along basis-u (perpendicular to orientation)
+     *   size.y — maximum heightmap height (extent along orientation)
+     *   size.z — footprint extent along basis-v (perpendicular to orientation)
+     * @readonly
+     * @type {Vector3}
+     */
+    readonly size: Vector3;
+    /**
+     * Sampler holding height values. Float32 backing recommended so the
+     * Terrain system's height texture plugs in directly. Single-channel
+     * sampler is the common case; only channel 0 is read.
+     * @type {Sampler2D | null}
+     */
+    sampler: Sampler2D | null;
+    /**
+     * Cached orthonormal basis [u_x,u_y,u_z, v_x,v_y,v_z, n_x,n_y,n_z]
+     * built from {@link orientation}. Updated lazily by {@link _ensure_basis}.
+     * @private
+     * @type {Float64Array}
+     */
+    private _basis;
+    _basis_orientation_x: number;
+    _basis_orientation_y: number;
+    _basis_orientation_z: number;
+    /**
+     * Recompute the orthonormal basis (u, v, n) if {@link orientation} changed.
+     *
+     * Construction chosen so that the default orientation +Y produces the
+     * intuitive mapping `u = +X, v = +Z, n = +Y` — i.e. size.x runs along
+     * body X, size.z along body Z. We project body +X onto the plane
+     * perpendicular to n (the orientation), with a fall-back to projecting
+     * body +Z when n is too close to colinear with +X.
+     * @private
+     */
+    private _ensure_basis;
+    /**
+     * Sample the surface height at heightmap UV coordinates.
+     * Uses Catmull-Rom filtering to match the terrain system's geometry construction.
+     * @param {number} u01 horizontal UV, in [0, 1]
+     * @param {number} v01 vertical UV, in [0, 1]
+     * @returns {number} height along orientation axis
+     */
+    sample_height_at_uv(u01: number, v01: number): number;
+    /**
+     * Project a body-local position to the surface and sample the height there.
+     * The returned height is in the orientation-axis direction.
+     * Positions outside the footprint sample the clamped UV (sampler clamps).
+     * @param {number} px body-local x
+     * @param {number} py body-local y
+     * @param {number} pz body-local z
+     * @returns {number}
+     */
+    sample_height_at_position(px: number, py: number, pz: number): number;
+    compute_bounding_box(result: any): void;
+    contains_point(point: any): boolean;
+    /**
+     * Approximate signed distance: difference between the point's height
+     * (along orientation) and the surface height sampled at the point's
+     * footprint UV. POSITIVE = above surface, NEGATIVE = below.
+     *
+     * Locally correct when the surface is flat; biased when the surface
+     * has significant slope. Sufficient for cling/raycast queries that
+     * walk down to the surface.
+     */
+    signed_distance_at_point(point: any): number;
+    /**
+     * Project a reference point onto the surface along the orientation axis.
+     * The footprint UV is clamped, so points outside the footprint produce
+     * the nearest edge-of-footprint surface sample (approximate).
+     */
+    nearest_point_on_surface(result: any, reference: any): void;
+    /**
+     * Heightmaps are non-convex; GJK/EPA cannot work against them directly.
+     * The physics narrowphase must dispatch a grid-traversal path that
+     * decomposes the heightmap into per-cell triangle pairs and tests each
+     * against the other shape (analogous to Bullet's btHeightfieldTerrainShape
+     * × btConcaveShape interface).
+     *
+     * This throws rather than returning a degenerate result so the call
+     * site is forced to handle heightmaps explicitly.
+     */
+    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
+    /**
+     * @param {HeightMapShape3D} other
+     * @returns {boolean}
+     */
+    equals(other: HeightMapShape3D): boolean;
+    /**
+     * Fast type-check marker, matching the pattern on every other concrete
+     * AbstractShape3D subclass. The physics narrowphase reads this to dispatch
+     * the heightmap-vs-X grid-traversal path.
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isHeightMapShape3D: boolean;
+}
+import { AbstractShape3D } from "./AbstractShape3D.js";
+import { Vector3 } from "../../Vector3.js";
+//# sourceMappingURL=HeightMapShape3D.d.ts.map

package/src/core/geom/3d/shape/HeightMapShape3D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeightMapShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/HeightMapShape3D.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IA4CI;;;;;;;;OAQG;IACH,wCANW,MAAM,UACN,MAAM,UACN,MAAM,gBACN,OAAO,GACL,gBAAgB,CAmB5B;IAlEG;;;;;OAKG;IACH,sBAFU,OAAO,CAEsB;IAEvC;;;;;;;OAOG;IACH,eAFU,OAAO,CAEe;IAEhC;;;;;OAKG;IACH,SAFU,YAAY,IAAI,CAEP;IAEnB;;;;;OAKG;IACH,eAAiC;IAGjC,6BAA+B;IAC/B,6BAA+B;IAC/B,6BAA+B;IA+BnC;;;;;;;;;OASG;IACH,sBA+CC;IAED;;;;;;OAMG;IACH,yBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,8BALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAelB;IAED,wCA8BC;IAED,oCA2BC;IAED;;;;;;;;OAQG;IACH,6CAmBC;IAED;;;;OAIG;IACH,4DA2BC;IAED;;;;;;;;;OASG;IACH,qGAEC;IAED,kFAiBC;IA6CD;;;OAGG;IACH,cAHW,gBAAgB,GACd,OAAO,CAgBnB;IAcL;;;;;;OAMG;IACH,6BAFU,OAAO,CAE4B;CAT5C;gCA3a+B,sBAAsB;wBAD9B,kBAAkB"}