@woosh/meep-engine 2.157.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.157.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/geom/3d/shape/PosedShape3D.d.ts

@@ -47,6 +47,23 @@ export class PosedShape3D extends AbstractShape3D {
         w: number;
     }): void;
     compute_bounding_box(result: any): void;
+    /**
+     * Signed distance from a WORLD-space point to the posed shape's boundary.
+     * Rigid poses preserve distances, so the local shape's SDF applies
+     * unchanged after re-framing the query point.
+     *
+     * @param {number[]|Float32Array|Float64Array} point  world-space, length 3
+     * @returns {number}
+     */
+    signed_distance_at_point(point: number[] | Float32Array | Float64Array): number;
+    /**
+     * Whether a WORLD-space point lies inside the posed shape.
+     *
+     * @param {number[]|Float32Array|Float64Array} point  world-space, length 3
+     * @returns {boolean}
+     */
+    contains_point(point: number[] | Float32Array | Float64Array): boolean;
+    #private;
 }
 import { AbstractShape3D } from "./AbstractShape3D.js";
 //# sourceMappingURL=PosedShape3D.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAKQ,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CACd;IAEjB,WAAW;IAAE,WAAW;IAAE,WAAW;IACrC,WAAW;IAAE,WAAW;IAAE,WAAW;IAAE,WAAW;IAGtD;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAM1D;IAgDD,wCASC;CACJ;gCA3G+B,sBAAsB"}
+{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAKQ,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CACd;IAEjB,WAAW;IAAE,WAAW;IAAE,WAAW;IACrC,WAAW;IAAE,WAAW;IAAE,WAAW;IAAE,WAAW;IAGtD;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAM1D;IAgDD,wCASC;IA4BD;;;;;;;OAOG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CAKlB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,OAAO,CAKnB;;CACJ;gCA7J+B,sBAAsB"}

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

@@ -106,4 +106,54 @@ export class PosedShape3D extends AbstractShape3D {
             this.qx, this.qy, this.qz, this.qw
         );
     }
+
+    /**
+     * Transform a world-space point into the body frame (inverse rigid pose:
+     * translate by −position, rotate by the conjugate quaternion) and write it
+     * into {@link scratch_local}. Shared by the point-query adapters below.
+     *
+     * @param {number[]|Float32Array|Float64Array} point  world-space, length 3
+     */
+    #world_point_to_local(point) {
+        const dx = point[0] - this.px;
+        const dy = point[1] - this.py;
+        const dz = point[2] - this.pz;
+
+        // v_local = q* · v · q — inline conjugate-quaternion rotation, the
+        // same literal expansion as in support().
+        const qx = this.qx, qy = this.qy, qz = this.qz, qw = this.qw;
+
+        const tx = qw * dx - qy * dz + qz * dy;
+        const ty = qw * dy - qz * dx + qx * dz;
+        const tz = qw * dz - qx * dy + qy * dx;
+        const tw = qx * dx + qy * dy + qz * dz;
+
+        scratch_local[0] = tx * qw + tw * qx + ty * qz - tz * qy;
+        scratch_local[1] = ty * qw + tw * qy + tz * qx - tx * qz;
+        scratch_local[2] = tz * qw + tw * qz + tx * qy - ty * qx;
+    }
+
+    /**
+     * Signed distance from a WORLD-space point to the posed shape's boundary.
+     * Rigid poses preserve distances, so the local shape's SDF applies
+     * unchanged after re-framing the query point.
+     *
+     * @param {number[]|Float32Array|Float64Array} point  world-space, length 3
+     * @returns {number}
+     */
+    signed_distance_at_point(point) {
+        this.#world_point_to_local(point);
+        return this.shape.signed_distance_at_point(scratch_local);
+    }
+
+    /**
+     * Whether a WORLD-space point lies inside the posed shape.
+     *
+     * @param {number[]|Float32Array|Float64Array} point  world-space, length 3
+     * @returns {boolean}
+     */
+    contains_point(point) {
+        this.#world_point_to_local(point);
+        return this.shape.contains_point(scratch_local);
+    }
 }

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));
 }

package/src/engine/graphics/ecs/trail2d/Trail2D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Trail2D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail2d/Trail2D.js"],"names":[],"mappings":";AAoBA;IAsKI,oCAMC;IA1KD;;;OAGG;IACH,QAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,QAFU,OAAO,GAAC,IAAI,CAER;IAEd;;;OAGG;IACH,UAFU,mBAAmB,CAEQ;IAErC;;;OAGG;IACH,cAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,cAAsB;IAEtB,gBAQC;IAMD,4BAEC;IAND,yBAEC;IAMD;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,SACnB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,OAAO,CAInB;IAED;;;OAGG;IACH,qBAFW,MAAM,QAehB;IADG,kHAAgB;IAGpB;;OAEG;IACH,cAeC;IAUD;;;;;;;;;;;aAcC;IAGD;;;;;;;;;;;;;;;MAQC;IAED;;;OAGG;IACH,cAFW,OAAO,WASjB;IAED;;;;;;;OAOG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CA2CnB;CAEJ;;;;;;sBA3RqB,iCAAiC;oBACnC,kCAAkC;wBAI9B,0BAA0B;oCACd,sCAAsC;0BAPhD,yCAAyC;6BAStC,mBAAmB;kCADd,wBAAwB"}
+{"version":3,"file":"Trail2D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail2d/Trail2D.js"],"names":[],"mappings":";AAoBA;IA6KI,oCAMC;IAjLD;;;OAGG;IACH,QAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,QAFU,OAAO,GAAC,IAAI,CAER;IAEd;;;OAGG;IACH,UAFU,mBAAmB,CAEQ;IAErC;;;OAGG;IACH,cAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,cAAsB;IAEtB,gBAQC;IAMD,4BAEC;IAND,yBAEC;IAMD;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,SACnB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,OAAO,CAInB;IAED;;;OAGG;IACH,qBAFW,MAAM,QAehB;IADG,kHAAgB;IAGpB;;OAEG;IACH,cAsBC;IAUD;;;;;;;;;;;aAcC;IAGD;;;;;;;;;;;;;;;MAQC;IAED;;;OAGG;IACH,cAFW,OAAO,WASjB;IAED;;;;;;;OAOG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CAyDnB;CAEJ;;;;;;sBAhTqB,iCAAiC;oBACnC,kCAAkC;wBAI9B,0BAA0B;oCACd,sCAAsC;0BAPhD,yCAAyC;6BAStC,mBAAmB;kCADd,wBAAwB"}

package/src/engine/graphics/ecs/trail2d/Trail2D.js

@@ -182,6 +182,13 @@ class Trail2D {
             ribbon.setPointAlpha(i, 0);
         }
 
+        // Ages/alphas alone don't erase the trail: point POSITIONS still
+        // trace the old path, and alpha is interpolated per-quad — the first
+        // live head vertex written after this would form a visible gradient
+        // quad back to the stale geometry (worst case: a screen-wide streak
+        // after a teleport). Defer a geometry reset to the next updateHead(),
+        // which is the first code to know the post-clear position.
+        this.setFlag(Trail2DFlags.Reseed);
     }
 
     static fromJSON(json) {
@@ -245,6 +252,20 @@ class Trail2D {
 
         const maxAge = this.maxAge;
 
+        if (this.getFlag(Trail2DFlags.Reseed)) {
+            // post-clear() re-seed: collapse every point onto the new head
+            // position (mirrors Trail2DSystem.__build_trail's seeding).
+            // setPointPosition keeps the PREVIOUS/NEXT extrusion attributes
+            // consistent, so the screen-space normals are sane on the first
+            // live frame too.
+            const n = ribbon.getCount();
+            for (let i = 0; i < n; i++) {
+                ribbon.setPointPosition(i, x, y, z);
+            }
+            this.timeSinceLastUpdate = 0;
+            this.clearFlag(Trail2DFlags.Reseed);
+        }
+
         const refitTimeDelta = maxAge / ribbon.getCount();
 
         let head_index = ribbon.getHeadIndex();

package/src/engine/graphics/ecs/trail2d/Trail2DFlags.d.ts

@@ -4,5 +4,6 @@ export namespace Trail2DFlags {
     let Aging: number;
     let Built: number;
     let BoundsNeedUpdate: number;
+    let Reseed: number;
 }
 //# sourceMappingURL=Trail2DFlags.d.ts.map

package/src/engine/graphics/ecs/trail2d/Trail2DFlags.js

@@ -6,5 +6,13 @@ export const Trail2DFlags = {
     Spawning: 1,
     Aging: 2,
     Built: 4,
-    BoundsNeedUpdate: 8
+    BoundsNeedUpdate: 8,
+
+    /**
+     * Set by Trail2D.clear(); consumed by the next updateHead(), which
+     * collapses the whole ribbon onto the new head position before resuming.
+     * Guarantees no quad can bridge post-clear geometry to pre-clear history
+     * (e.g. a screen-wide streak after teleporting the entity).
+     */
+    Reseed: 16
 };

package/src/engine/physics/fluid/FluidField.d.ts

@@ -1,8 +1,16 @@
 /**
- * Cell-centered 3D Eulerian grid for the fluid simulator.
+ * 3D Eulerian grid for the fluid simulator — MAC (marker-and-cell) staggered
+ * layout: pressure, solids and scalars live at cell centers; each velocity
+ * component lives on the cell FACES normal to it (Harlow & Welch 1965).
  *
- * Holds three velocity components (x, y, z), an optional per-cell `solid` mask, and any
- * number of user-defined passive scalar attributes that get transported by the flow.
+ * Staggering makes the discrete divergence and pressure gradient exact
+ * adjoints, so projection drives divergence to actual zero (no collocated
+ * operator-mismatch floor, no projection-invisible checkerboard modes) and
+ * solid boundaries pin the exact normal face velocity (true no-penetration).
+ *
+ * Holds three face-centered velocity components, a per-cell `solid` mask, and any
+ * number of user-defined cell-centered passive scalar attributes transported by
+ * the flow.
  *
  * Holds only state whose value carries information across step boundaries. The
  * simulator's transient working memory (per-step velocity snapshots, divergence,
@@ -20,16 +28,24 @@
  */
 export class FluidField {
     /**
-     * Velocity X component, length = cell count. Cell-centered, indexed by
-     * `z * res_x * res_y + y * res_x + x`.
+     * Velocity X component on x-faces. Length `(res_x+1) * res_y * res_z`,
+     * indexed by `z * (res_x+1) * res_y + y * (res_x+1) + x` with
+     * `x ∈ [0, res_x]`. Face `(x, y, z)` sits between cells `(x−1, y, z)` and
+     * `(x, y, z)` — at grid-space position `(x − 0.5, y, z)` in the
+     * cell-center coordinate frame.
      * @type {Float32Array|null}
      */
     velocity_x: Float32Array | null;
     /**
+     * Velocity Y component on y-faces. Length `res_x * (res_y+1) * res_z`,
+     * indexed by `z * res_x * (res_y+1) + y * res_x + x` with `y ∈ [0, res_y]`.
      * @type {Float32Array|null}
      */
     velocity_y: Float32Array | null;
     /**
+     * Velocity Z component on z-faces. Length `res_x * res_y * (res_z+1)`,
+     * indexed by `z * res_x * res_y + y * res_x + x` with `z ∈ [0, res_z]`
+     * (the face slice size equals the cell slice size).
      * @type {Float32Array|null}
      */
     velocity_z: Float32Array | null;
@@ -72,6 +88,25 @@ export class FluidField {
      * @type {Uint8Array|null}
      */
     solid_neighbour_mask: Uint8Array | null;
+    /**
+     * Per-face "pinned" mask for x-faces: `1` where either adjacent cell is
+     * solid — the face's normal velocity is a boundary condition (0 for
+     * static solids), not a degree of freedom. Same length and indexing as
+     * {@link velocity_x}. Baked by {@link recomputeSolidNeighbourMask} via
+     * {@link v3_mac_compute_face_solid}; domain-edge faces stay 0 (open).
+     * @type {Uint8Array|null}
+     */
+    face_solid_x: Uint8Array | null;
+    /**
+     * y-face pinned mask — see {@link face_solid_x}.
+     * @type {Uint8Array|null}
+     */
+    face_solid_y: Uint8Array | null;
+    /**
+     * z-face pinned mask — see {@link face_solid_x}.
+     * @type {Uint8Array|null}
+     */
+    face_solid_z: Uint8Array | null;
     /**
      * Per-cell pressure-Laplacian diagonal, baked alongside
      * {@link solid_neighbour_mask} by the same kernel pass:
@@ -196,7 +231,11 @@ export class FluidField {
      */
     cellIndex(x: number, y: number, z: number): number;
     /**
-     * Set the velocity at an integer grid cell.
+     * Set the velocity of an integer grid cell: each component is written to
+     * BOTH faces of the cell along its axis, so sampling at the cell centre
+     * reads back exactly `(vx, vy, vz)`. Adjacent cells share faces — the
+     * later write wins on a shared face, exactly like overlapping
+     * cell-centered writes used to.
      * @param {number} x
      * @param {number} y
      * @param {number} z
@@ -206,7 +245,9 @@ export class FluidField {
      */
     setVelocityAt(x: number, y: number, z: number, vx: number, vy: number, vz: number): void;
     /**
-     * Add to the velocity at an integer grid cell (impulse).
+     * Add to the velocity of an integer grid cell (impulse). Deposits each
+     * component onto BOTH faces of the cell along its axis; the centre-sampled
+     * velocity increases by exactly `(dvx, dvy, dvz)`.
      * @param {number} x
      * @param {number} y
      * @param {number} z
@@ -239,8 +280,11 @@ export class FluidField {
      */
     isSolidAt(x: number, y: number, z: number): boolean;
     /**
-     * Sample velocity at a fractional grid position (positions outside the grid are
-     * clamped). Writes into `out` and returns it.
+     * Sample velocity at a fractional grid position in CELL-CENTER coordinates
+     * (positions outside the grid are clamped). Each component is trilinearly
+     * interpolated on its own staggered face lattice — x-face `i` sits at
+     * `x = i − 0.5`, so the component is sampled at `x + 0.5` in face-index
+     * space, and likewise per axis. Writes into `out` and returns it.
      * @param {Float32Array|number[]} out  Length-3 destination.
      * @param {number} x
      * @param {number} y

package/src/engine/physics/fluid/FluidField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidField.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidField.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAQI;;;;OAIG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;OAEG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;OAEG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;;;OAMG;IACH,OAFU,UAAU,GAAC,IAAI,CAEZ;IAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,sBAFU,UAAU,GAAC,IAAI,CAEG;IAE5B;;;;;;;;;;;;;;;;OAgBG;IACH,eAFU,UAAU,GAAC,IAAI,CAEJ;IAErB;;;;;;;;;;;;;OAaG;IACH,UAFU,YAAY,kBAAc,IAAI,CAExB;IAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,yBAFU,OAAO,CAEe;IAShC;;;;;;OAMG;IACH,qBAJW,MAAM,SACN,MAAM,SACN,MAAM,QAWhB;IAED;;;OAGG;IACH,iBAHY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAKnC;IAED;;;OAGG;IACH,aAHY,MAAM,CAKjB;IAED;;;;;;;;;OASG;IACH,gBAHW,MAAM,GACL,MAAM,CAejB;IAED;;;OAGG;IACH,kBAHW,MAAM,GACL,MAAM,CAIjB;IAED;;;;OAIG;IACH,oBAJW,MAAM,GACL,YAAY,GAAC,IAAI,CAM5B;IAED;;OAEG;IACH,uBAFY;QAAE,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE,CAIjD;IAED;;;OAGG;IACH,cAoBC;IAED;;;;;;OAMG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAajB;IAED;;;;;;;;OAQG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAOhB;IAED;;;;;;;;OAQG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,kCANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,SACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,cALW,MAAM,KACN,MAAM,KACN,MAAM,YACN,OAAO,QAIjB;IAED;;;;;OAKG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,OAAO,CAIlB;IAED;;;;;;;;OAQG;IACH,oBANW,YAAY,GAAC,MAAM,EAAE,KACrB,MAAM,KACN,MAAM,KACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAUhC;IAED;;;;;;;OAOG;IACH,mBANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAMjB;IAED;;;;;;;;;;OAUG;IACH,cAHW,UAAU,GACT,OAAO,CAqDlB;IAED;;;;;;;;;;;OAWG;IACH,QAFY,MAAM,CAajB;IAED;;;;;;;;;;OAUG;IACH,oCAUC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,eAJW,MAAM,WACN,MAAM,WACN,MAAM,QAuChB;IAED;;;;OAIG;IACH,cASC;;CACJ"}
+{"version":3,"file":"FluidField.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidField.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAQI;;;;;;;OAOG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;OAIG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;;OAKG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;;;OAMG;IACH,OAFU,UAAU,GAAC,IAAI,CAEZ;IAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,sBAFU,UAAU,GAAC,IAAI,CAEG;IAE5B;;;;;;;OAOG;IACH,cAFU,UAAU,GAAC,IAAI,CAEL;IAEpB;;;OAGG;IACH,cAFU,UAAU,GAAC,IAAI,CAEL;IAEpB;;;OAGG;IACH,cAFU,UAAU,GAAC,IAAI,CAEL;IAEpB;;;;;;;;;;;;;;;;OAgBG;IACH,eAFU,UAAU,GAAC,IAAI,CAEJ;IAErB;;;;;;;;;;;;;OAaG;IACH,UAFU,YAAY,kBAAc,IAAI,CAExB;IAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,yBAFU,OAAO,CAEe;IAShC;;;;;;OAMG;IACH,qBAJW,MAAM,SACN,MAAM,SACN,MAAM,QAWhB;IAED;;;OAGG;IACH,iBAHY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAKnC;IAED;;;OAGG;IACH,aAHY,MAAM,CAKjB;IAED;;;;;;;;;OASG;IACH,gBAHW,MAAM,GACL,MAAM,CAejB;IAED;;;OAGG;IACH,kBAHW,MAAM,GACL,MAAM,CAIjB;IAED;;;;OAIG;IACH,oBAJW,MAAM,GACL,YAAY,GAAC,IAAI,CAM5B;IAED;;OAEG;IACH,uBAFY;QAAE,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE,CAIjD;IAED;;;OAGG;IACH,cA6BC;IAED;;;;;;OAMG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAajB;IAED;;;;;;;;;;;;OAYG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAgBhB;IAED;;;;;;;;;;OAUG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,QAgBhB;IAED;;;;;;OAMG;IACH,kCANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,SACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,cALW,MAAM,KACN,MAAM,KACN,MAAM,YACN,OAAO,QAIjB;IAED;;;;;OAKG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,OAAO,CAIlB;IAED;;;;;;;;;;;OAWG;IACH,oBANW,YAAY,GAAC,MAAM,EAAE,KACrB,MAAM,KACN,MAAM,KACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAUhC;IAED;;;;;;;OAOG;IACH,mBANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAMjB;IAED;;;;;;;;;;OAUG;IACH,cAHW,UAAU,GACT,OAAO,CAqDlB;IAED;;;;;;;;;;;OAWG;IACH,QAFY,MAAM,CAajB;IAED;;;;;;;;;;OAUG;IACH,oCAgBC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,eAJW,MAAM,WACN,MAAM,WACN,MAAM,QA0ChB;IAED;;;;OAIG;IACH,cASC;;CACJ"}