@woosh/meep-engine 2.158.0 → 2.159.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.158.0",
+  "version": "2.159.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/binary/BitSet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BitSet.d.ts","sourceRoot":"","sources":["../../../../src/core/binary/BitSet.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;GAcG;AACH;IAslBI;;;;OAIG;IACH,oBAHW,MAAM,GACJ,MAAM,CAQlB;IA/lBD;;;OAGG;IACH,+BAFW,MAAM,EAgChB;IA3BG;;;;OAIG;IACH,iBAAiB;IAEjB;;;;;OAKG;IACH,mBAA4C;IAE5C;;;;OAIG;IACH,sBAA0D;IAE1D;;;OAGG;IACH,gBAFU,MAAM,CAE2B;IAG/C;;;;OAIG;IACH,iBAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,mBAFW,MAAM,QAOhB;IACD;;;;;;OAMG;IACH,uBAJW,MAAM,GAEJ,IAAI,CAUhB;IAED;;;;OAIG;IACH,QAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAsBC;IAED;;;OAGG;IACH,uBAMC;IAED;;;;;OAKG;IACH,oBAyBC;IAED;;;;OAIG;IACH,2BAHW,MAAM,GACJ,MAAM,CAuClB;IAED;;;;OAIG;IACH,uBAHW,MAAM,GACJ,MAAM,CAuDlB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,MAAM,CAkDlB;IAED;;;;;OAKG;IACH,eAJW,MAAM,SACN,OAAO,GACL,IAAI,CAmChB;IAED;;;OAGG;IACH,iBAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,sBAHW,MAAM,aACN,MAAM,QAWhB;IAED;;;;OAIG;IACH,wBAHW,MAAM,aACN,MAAM,QAShB;IAED;;;;OAIG;IACH,qBAFa,OAAO,CAkBnB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,OAAO,CAUnB;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,OAAO,CAUnB;IAED;;;;;OAKG;IACH,sBAJW,MAAM,eACN,MAAM,aACN,MAAM,QAShB;IAED;;;;;OAKG;IACH,qBAJW,MAAM,eACN,MAAM,aACN,MAAM,QAShB;IAED;;;;;OAKG;IACH,gBAJW,MAAM,eACN,MAAM,aACN,MAAM,QAQhB;IAED;;OAEG;IACH,cAgBC;IAED;;;;OAIG;IACH,eAFa,MAAM,CA+BlB;IAED;;;OAGG;IACH,YAFW,MAAM,QAoChB;CAcJ"}
+{"version":3,"file":"BitSet.d.ts","sourceRoot":"","sources":["../../../../src/core/binary/BitSet.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;GAcG;AACH;IA2lBI;;;;OAIG;IACH,oBAHW,MAAM,GACJ,MAAM,CAQlB;IApmBD;;;OAGG;IACH,+BAFW,MAAM,EAgChB;IA3BG;;;;OAIG;IACH,iBAAiB;IAEjB;;;;;OAKG;IACH,mBAA4C;IAE5C;;;;OAIG;IACH,sBAA0D;IAE1D;;;OAGG;IACH,gBAFU,MAAM,CAE2B;IAG/C;;;;OAIG;IACH,iBAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,mBAFW,MAAM,QAOhB;IACD;;;;;;OAMG;IACH,uBAJW,MAAM,GAEJ,IAAI,CAUhB;IAED;;;;OAIG;IACH,QAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAsBC;IAED;;;OAGG;IACH,uBAMC;IAED;;;;;OAKG;IACH,oBAyBC;IAED;;;;OAIG;IACH,2BAHW,MAAM,GACJ,MAAM,CAuClB;IAED;;;;OAIG;IACH,uBAHW,MAAM,GACJ,MAAM,CAuDlB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,MAAM,CAuDlB;IAED;;;;;OAKG;IACH,eAJW,MAAM,SACN,OAAO,GACL,IAAI,CAmChB;IAED;;;OAGG;IACH,iBAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,sBAHW,MAAM,aACN,MAAM,QAWhB;IAED;;;;OAIG;IACH,wBAHW,MAAM,aACN,MAAM,QAShB;IAED;;;;OAIG;IACH,qBAFa,OAAO,CAkBnB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,OAAO,CAUnB;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,OAAO,CAUnB;IAED;;;;;OAKG;IACH,sBAJW,MAAM,eACN,MAAM,aACN,MAAM,QAShB;IAED;;;;;OAKG;IACH,qBAJW,MAAM,eACN,MAAM,aACN,MAAM,QAShB;IAED;;;;;OAKG;IACH,gBAJW,MAAM,eACN,MAAM,aACN,MAAM,QAQhB;IAED;;OAEG;IACH,cAgBC;IAED;;;;OAIG;IACH,eAFa,MAAM,CA+BlB;IAED;;;OAGG;IACH,YAFW,MAAM,QAoChB;CAcJ"}

package/src/core/binary/BitSet.js

@@ -368,7 +368,12 @@ export class BitSet {
 
         }
 
-        return set_length;
+        // Bits at or beyond __length are implicitly clear. When from_index
+        // is word-aligned and lies at or beyond __length, both the masked
+        // first-word branch and the scan loop are skipped — returning
+        // set_length alone would violate the "first clear bit >= from_index"
+        // contract by returning a value smaller than from_index.
+        return Math.max(set_length, from_index);
     }
 
     /**

package/src/core/binary/float_to_uint8.d.ts

@@ -1,7 +1,10 @@
 /**
+ * Quantize a [0, 1] float to a byte. Out-of-range input saturates: every caller is a
+ * color/channel packer, where wrapping would turn 1.004 into 0 (near-white to black) and
+ * negatives into arbitrary mid-range values.
  *
  * @param {number} v
- * @returns {number}
+ * @returns {number} integer in [0, 255]
  */
 export function float_to_uint8(v: number): number;
 //# sourceMappingURL=float_to_uint8.d.ts.map

package/src/core/binary/float_to_uint8.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"float_to_uint8.d.ts","sourceRoot":"","sources":["../../../../src/core/binary/float_to_uint8.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,kCAHW,MAAM,GACJ,MAAM,CAIlB"}
+{"version":3,"file":"float_to_uint8.d.ts","sourceRoot":"","sources":["../../../../src/core/binary/float_to_uint8.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,kCAHW,MAAM,GACJ,MAAM,CAMlB"}

package/src/core/binary/float_to_uint8.js

@@ -1,8 +1,13 @@
 /**
+ * Quantize a [0, 1] float to a byte. Out-of-range input saturates: every caller is a
+ * color/channel packer, where wrapping would turn 1.004 into 0 (near-white to black) and
+ * negatives into arbitrary mid-range values.
  *
  * @param {number} v
- * @returns {number}
+ * @returns {number} integer in [0, 255]
  */
 export function float_to_uint8(v) {
-    return Math.round(v * 255);
+    const whole = Math.round(v * 255);
+    // clamp to 0-255; masking with & 0xFF would wrap, not clamp
+    return whole < 0 ? 0 : (whole > 255 ? 255 : whole);
 }

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

@@ -1,10 +1,20 @@
 /**
+ * Tightens the relaxed planes of a frustum against the contents of a BVH: each relaxed
+ * plane is moved to the tightest position that still contains every leaf AABB surviving
+ * the fixed planes.
+ *
+ * Both input and output planes use the engine's inward `dot(normal, p) + offset >= 0`
+ * convention (see {@link v3_distance_above_plane}); fixed planes are copied through
+ * unchanged.
+ *
  * @param {number[]} result
  * @param {number} result_offset
  * @param {number} plane_mask if bit is set to 0, that plane is not allowed to move
  * @param {BVH} bvh
  * @param {number[]|ArrayLike<number>|Float32Array} frustum
- * @returns {boolean} true iff planes were updated, false otherwise. If false is returned - result is not written
+ * @returns {boolean} true iff every relaxed plane was tightened against geometry. False
+ * when the BVH is empty or when no leaf intersects the fixed planes — a relaxed plane
+ * would otherwise carry its infinite sentinel. If false is returned - result is not written
  */
 export function compute_tight_near_far_clipping_planes(result: number[], result_offset: number, plane_mask: number, bvh: BVH, frustum: number[] | ArrayLike<number> | Float32Array): boolean;
 //# sourceMappingURL=compute_tight_near_far_clipping_planes.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"compute_tight_near_far_clipping_planes.d.ts","sourceRoot":"","sources":["../../../../../../src/core/bvh2/bvh3/query/compute_tight_near_far_clipping_planes.js"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH,+DAPW,MAAM,EAAE,iBACR,MAAM,cACN,MAAM,qBAEN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,GACrC,OAAO,CA4MnB"}
+{"version":3,"file":"compute_tight_near_far_clipping_planes.d.ts","sourceRoot":"","sources":["../../../../../../src/core/bvh2/bvh3/query/compute_tight_near_far_clipping_planes.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;GAiBG;AACH,+DATW,MAAM,EAAE,iBACR,MAAM,cACN,MAAM,qBAEN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,GACrC,OAAO,CA2NnB"}

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

@@ -11,12 +11,22 @@ const scratch_aabb = [];
 const scratch_frustum = new Float32Array(24);
 
 /**
+ * Tightens the relaxed planes of a frustum against the contents of a BVH: each relaxed
+ * plane is moved to the tightest position that still contains every leaf AABB surviving
+ * the fixed planes.
+ *
+ * Both input and output planes use the engine's inward `dot(normal, p) + offset >= 0`
+ * convention (see {@link v3_distance_above_plane}); fixed planes are copied through
+ * unchanged.
+ *
  * @param {number[]} result
  * @param {number} result_offset
  * @param {number} plane_mask if bit is set to 0, that plane is not allowed to move
  * @param {BVH} bvh
  * @param {number[]|ArrayLike<number>|Float32Array} frustum
- * @returns {boolean} true iff planes were updated, false otherwise. If false is returned - result is not written
+ * @returns {boolean} true iff every relaxed plane was tightened against geometry. False
+ * when the BVH is empty or when no leaf intersects the fixed planes — a relaxed plane
+ * would otherwise carry its infinite sentinel. If false is returned - result is not written
  */
 export function compute_tight_near_far_clipping_planes(
     result,
@@ -28,13 +38,17 @@ export function compute_tight_near_far_clipping_planes(
     assert.isNonNegativeInteger(result_offset, 'result_offset');
     assert.isNonNegativeInteger(plane_mask, 'plane_mask');
 
+    const relaxed_mask = plane_mask & 0b111111;
+
     // initialize result
     array_copy(frustum, 0, scratch_frustum, 0, 24);
 
-    // set output planes to infinity so we can slowly bring them in
+    // Relaxed planes start infinitely tight ("no geometry seen yet") and are pushed out by
+    // leaves. In the dot+offset convention the tight containing offset is the running
+    // maximum of -dot(normal, nearest_corner), so the sentinel is -Infinity.
     for (let i = 0; i < 6; i++) {
-        if (((plane_mask >> i) & 1) === 1) {
-            scratch_frustum[i * 4 + 3] = Infinity;
+        if (((relaxed_mask >> i) & 1) === 1) {
+            scratch_frustum[i * 4 + 3] = -Infinity;
         }
     }
 
@@ -52,7 +66,8 @@ export function compute_tight_near_far_clipping_planes(
 
     stack[stack_top] = root;
 
-    let result_cursor = result_offset;
+    // relaxed planes that have been tightened against at least one leaf
+    let updated_mask = 0;
 
     // 0 is the nearest point along the normal and 1 is the furthest
     let x0,
@@ -71,7 +86,6 @@ export function compute_tight_near_far_clipping_planes(
          */
         const node = stack[stack.pointer];
 
-        // test node against the ray
         bvh.node_get_aabb(node, scratch_aabb);
 
         const _x0 = scratch_aabb[0];
@@ -122,15 +136,15 @@ export function compute_tight_near_far_clipping_planes(
                 z1 = _z0;
             }
 
-            if (((plane_mask >> plane_index) & 1) === 1) {
-                // plane is not fixed, we're done here
-
+            if (((relaxed_mask >> plane_index) & 1) === 1) {
+                // relaxed plane: this node can push it out iff the node's nearest corner
+                // lies outside the current plane
                 const distance_above_plane = v3_distance_above_plane(
                     x0, y0, z0,
-                    plane_normal_x, plane_normal_y, plane_normal_z, 0
+                    plane_normal_x, plane_normal_y, plane_normal_z, plane_offset
                 );
 
-                if (distance_above_plane < plane_offset) {
+                if (distance_above_plane < 0) {
                     collision_mask |= (1 << plane_index);
                 }
 
@@ -203,19 +217,28 @@ export function compute_tight_near_far_clipping_planes(
                         z0 = _z1;
                     }
 
-                    // move plane
-                    scratch_frustum[plane_address + 3] = v3_distance_above_plane(
+                    // move the plane out to contain this leaf: offset = -dot(n, nearest
+                    // corner) puts the corner exactly on the plane (dot + offset == 0).
+                    // Only ever reached when the corner is outside the current plane
+                    // (collision_mask gate), so the offset grows monotonically.
+                    scratch_frustum[plane_address + 3] = -v3_distance_above_plane(
                         x0, y0, z0,
                         plane_normal_x, plane_normal_y, plane_normal_z, 0
                     );
 
+                    updated_mask |= (1 << i);
+
                 }
             }
 
         }
     }
 
-    // TODO check if results are still at infinity
+    if ((updated_mask & relaxed_mask) !== relaxed_mask) {
+        // some relaxed plane was never constrained by geometry (nothing intersects the
+        // fixed planes) — it still carries the -Infinity sentinel and must not leak out
+        return false;
+    }
 
     array_copy(scratch_frustum, 0, result, result_offset, 24);
 

package/src/core/math/gaussian.d.ts

@@ -1,9 +1,10 @@
 /**
- * This is not the standard gaussian.
- * It lacks the normalization factor, standard gaussian would be weighted by `1 / √(2π * variance)`
- * @param {number} sigma Standard deviation. Distance from mean. Represents the "width" of the Gaussian-like curve.  Note: The parameter is named `sigma`, but its placement in the formula means it scales inversely to the usual effect of sigma.
- * @param {number} v Variance. Represents the "height" or "amplitude" of the curve, but at a distance from the mean.  Larger variance values result in larger function values further away from the mean (0).
- * @returns {number} Ranges from 0 to 1 (exclusive of 0)
+ * Un-normalized gaussian: `exp(−distance² / (2·sigma²))`.
+ * This is not the standard gaussian — it lacks the normalization factor;
+ * the standard gaussian would be weighted by `1 / √(2π·sigma²)`.
+ * @param {number} sigma Standard deviation. Controls the "width" of the bell curve: larger sigma → wider curve, slower falloff with distance.
+ * @param {number} distance Distance from the mean (the point at which to evaluate the curve). At 0 the result is 1; it decays toward 0 as |distance| grows.
+ * @returns {number} Ranges from 0 to 1 (exclusive of 0, inclusive of 1 at distance 0)
  */
-export function gaussian(sigma: number, v: number): number;
+export function gaussian(sigma: number, distance: number): number;
 //# sourceMappingURL=gaussian.d.ts.map

package/src/core/math/gaussian.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gaussian.d.ts","sourceRoot":"","sources":["../../../../src/core/math/gaussian.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,gCAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAOlB"}
+{"version":3,"file":"gaussian.d.ts","sourceRoot":"","sources":["../../../../src/core/math/gaussian.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,gCAJW,MAAM,YACN,MAAM,GACJ,MAAM,CAOlB"}

package/src/core/math/gaussian.js

@@ -1,13 +1,14 @@
 /**
- * This is not the standard gaussian.
- * It lacks the normalization factor, standard gaussian would be weighted by `1 / √(2π * variance)`
- * @param {number} sigma Standard deviation. Distance from mean. Represents the "width" of the Gaussian-like curve.  Note: The parameter is named `sigma`, but its placement in the formula means it scales inversely to the usual effect of sigma.
- * @param {number} v Variance. Represents the "height" or "amplitude" of the curve, but at a distance from the mean.  Larger variance values result in larger function values further away from the mean (0).
- * @returns {number} Ranges from 0 to 1 (exclusive of 0)
+ * Un-normalized gaussian: `exp(−distance² / (2·sigma²))`.
+ * This is not the standard gaussian — it lacks the normalization factor;
+ * the standard gaussian would be weighted by `1 / √(2π·sigma²)`.
+ * @param {number} sigma Standard deviation. Controls the "width" of the bell curve: larger sigma → wider curve, slower falloff with distance.
+ * @param {number} distance Distance from the mean (the point at which to evaluate the curve). At 0 the result is 1; it decays toward 0 as |distance| grows.
+ * @returns {number} Ranges from 0 to 1 (exclusive of 0, inclusive of 1 at distance 0)
  */
-export function gaussian(sigma, v) {
-    const v2 = v * v;
+export function gaussian(sigma, distance) {
+    const d2 = distance * distance;
     const sigma2 = sigma * sigma;
 
-    return Math.exp(- v2 / (2 * sigma2));
+    return Math.exp(- d2 / (2 * sigma2));
 }