@woosh/meep-engine 2.169.0 → 2.169.2

package/src/engine/physics/constraint/solve_constraints.js

@@ -1,3 +1,4 @@
+import { apply_impulse_to_body } from "../solver/apply_impulse_to_body.js";
 import { quat3_multiply } from "../../../core/geom/3d/quaternion/quat3_multiply.js";
 import { quat3_to_matrix3 } from "../../../core/geom/3d/quaternion/quat3_to_matrix3.js";
 import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
@@ -21,7 +22,7 @@ import {
 } from "../body/SolverBodyState.js";
 import { JOINT_WORLD } from "../ecs/Joint.js";
 import { SleepState } from "../ecs/SleepState.js";
-import { world_inverse_inertia_apply_raw } from "../inertia/world_inverse_inertia.js";
+import { angular_effective_mass_raw, world_inverse_inertia_apply_raw } from "../inertia/world_inverse_inertia.js";
 import { DofMode } from "./DofMode.js";
 
 /**
@@ -190,17 +191,18 @@ function apply_angular_impulse(ss, base, ax, ay, az, lambda, sign) {
  */
 function axis_effective_mass(ss, base, invM, rx, ry, rz, dx, dy, dz) {
     if (invM === 0) return 0;
-    let k = invM;
     const iix = ss[base + SBS_INV_I_X], iiy = ss[base + SBS_INV_I_Y], iiz = ss[base + SBS_INV_I_Z];
-    if (iix !== 0 || iiy !== 0 || iiz !== 0) {
-        const cx = ry * dz - rz * dy;
-        const cy = rz * dx - rx * dz;
-        const cz = rx * dy - ry * dx;
-        world_inverse_inertia_apply_raw(scratch_inertia, 0, iix, iiy, iiz,
-            ss[base + SBS_QX], ss[base + SBS_QY], ss[base + SBS_QZ], ss[base + SBS_QW], cx, cy, cz);
-        k += cx * scratch_inertia[0] + cy * scratch_inertia[1] + cz * scratch_inertia[2];
+    if (iix === 0 && iiy === 0 && iiz === 0) {
+        // no rotational response, so the lever arm contributes nothing
+        return invM;
     }
-    return k;
+    return invM + angular_effective_mass_raw(
+        iix, iiy, iiz,
+        ss[base + SBS_QX], ss[base + SBS_QY], ss[base + SBS_QZ], ss[base + SBS_QW],
+        rx, ry, rz,
+        dx, dy, dz,
+        scratch_inertia
+    );
 }
 
 /**
@@ -232,38 +234,6 @@ function relative_anchor_velocity(out, ss, baseA, rAx, rAy, rAz, baseB, rBx, rBy
 /** Destination for {@link relative_anchor_velocity}. */
 const scratch_rv = new Float64Array(3);
 
-/**
- * Apply impulse `P` at body-relative offset `r`: Δv = P·invM, Δω = Iw⁻¹·(r×P).
- * Reads / writes the body's {@link SolverBodyState} span.
- *
- * @param {Float64Array} ss solver-body-state data array
- * @param {number} base `body_index * SBS_STRIDE`
- * @param {number} invM
- * @param {number} rx
- * @param {number} ry
- * @param {number} rz
- * @param {number} Px
- * @param {number} Py
- * @param {number} Pz
- * @param {number} sign +1 / −1
- */
-function apply_impulse(ss, base, invM, rx, ry, rz, Px, Py, Pz, sign) {
-    if (invM === 0) return;
-    const sPx = sign * Px, sPy = sign * Py, sPz = sign * Pz;
-    ss[base + SBS_LV_X] += sPx * invM;
-    ss[base + SBS_LV_Y] += sPy * invM;
-    ss[base + SBS_LV_Z] += sPz * invM;
-
-    const tx = ry * sPz - rz * sPy;
-    const ty = rz * sPx - rx * sPz;
-    const tz = rx * sPy - ry * sPx;
-    world_inverse_inertia_apply_raw(scratch_inertia, 0,
-        ss[base + SBS_INV_I_X], ss[base + SBS_INV_I_Y], ss[base + SBS_INV_I_Z],
-        ss[base + SBS_QX], ss[base + SBS_QY], ss[base + SBS_QZ], ss[base + SBS_QW], tx, ty, tz);
-    ss[base + SBS_AV_X] += scratch_inertia[0];
-    ss[base + SBS_AV_Y] += scratch_inertia[1];
-    ss[base + SBS_AV_Z] += scratch_inertia[2];
-}
 
 /**
  * Clamp the SPOOK position bias to ±{@link MAX_JOINT_BIAS}.
@@ -779,8 +749,8 @@ export function solve_joints(joints, system, dt_sub, iters, reverse) {
                 Px += w * fa[3 * k]; Py += w * fa[3 * k + 1]; Pz += w * fa[3 * k + 2];
             }
             if (Px !== 0 || Py !== 0 || Pz !== 0) {
-                apply_impulse(ss, baseA, invMA, rAx, rAy, rAz, Px, Py, Pz, +1);
-                if (!to_world) apply_impulse(ss, baseB, invMB, rBx, rBy, rBz, Px, Py, Pz, -1);
+                apply_impulse_to_body(ss, baseA, invMA, rAx, rAy, rAz, Px, Py, Pz, +1, scratch_inertia);
+                if (!to_world) apply_impulse_to_body(ss, baseB, invMB, rBx, rBy, rBz, Px, Py, Pz, -1, scratch_inertia);
             }
             let Lx = 0, Ly = 0, Lz = 0;
             for (let k = 0; k < 3; k++) {
@@ -820,8 +790,8 @@ export function solve_joints(joints, system, dt_sub, iters, reverse) {
                 const Py = d0 * a0y + d1 * a1y + d2 * a2y;
                 const Pz = d0 * a0z + d1 * a1z + d2 * a2z;
                 if (Px !== 0 || Py !== 0 || Pz !== 0) {
-                    apply_impulse(ss, baseA, invMA, rAx, rAy, rAz, Px, Py, Pz, +1);
-                    if (!to_world) apply_impulse(ss, baseB, invMB, rBx, rBy, rBz, Px, Py, Pz, -1);
+                    apply_impulse_to_body(ss, baseA, invMA, rAx, rAy, rAz, Px, Py, Pz, +1, scratch_inertia);
+                    if (!to_world) apply_impulse_to_body(ss, baseB, invMB, rBx, rBy, rBz, Px, Py, Pz, -1, scratch_inertia);
                 }
             } else {
                 for (let k = 0; k < 3; k++) {
@@ -837,8 +807,8 @@ export function solve_joints(joints, system, dt_sub, iters, reverse) {
                     imp[k] = nv;
                     const d = nv - old;
                     if (d !== 0) {
-                        apply_impulse(ss, baseA, invMA, rAx, rAy, rAz, d * ax, d * ay, d * az, +1);
-                        if (!to_world) apply_impulse(ss, baseB, invMB, rBx, rBy, rBz, d * ax, d * ay, d * az, -1);
+                        apply_impulse_to_body(ss, baseA, invMA, rAx, rAy, rAz, d * ax, d * ay, d * az, +1, scratch_inertia);
+                        if (!to_world) apply_impulse_to_body(ss, baseB, invMB, rBx, rBy, rBz, d * ax, d * ay, d * az, -1, scratch_inertia);
                     }
                 }
             }

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#169@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#189@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#169@#clear_field"(fluid: FluidComponent): void;
+    static "__#189@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#169@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#189@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,14 +100,10 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#169@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#189@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];
-    /**
-     * @param {number} time_delta_seconds
-     */
-    fixedUpdate(time_delta_seconds: number): void;
     #private;
 }
 import { System } from "../../../ecs/System.js";

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidObstacleSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidObstacleSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH;IA+GI;;OAEG;IACH,sCAFW,cAAc,QAIxB;IAED;;OAEG;IACH,oCAFW,cAAc,QAOxB;IAED;;;;;;;;;;OAUG;IACH,iCANW,cAAc,SACd,YAAY,QACZ,YAAY,aACZ,MAAM,SACN,YAAY,QAiDtB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,4CATW,cAAc,SACd,YAAY,QACZ,YAAY,aACZ,MAAM,SACN,YAAY,OACZ,MAAM,OACN,MAAM,OACN,MAAM,QAqEhB;;IAhRD,uCAA+B;IAE/B,2QAOE;IAoBF;;OAEG;IACH,gCAFW,MAAM,QA6EhB;;CAsKJ;uBAxVsB,wBAAwB;8BAKjB,oBAAoB;0BAJxB,qCAAqC;4CAFnB,uDAAuD;0BAIzE,wBAAwB;yBADzB,uBAAuB;+BAEjB,qBAAqB;6BAPvB,gDAAgD"}
+{"version":3,"file":"FluidObstacleSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidObstacleSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH;IA+GI;;OAEG;IACH,sCAFW,cAAc,QAIxB;IAED;;OAEG;IACH,oCAFW,cAAc,QAOxB;IAED;;;;;;;;;;OAUG;IACH,iCANW,cAAc,SACd,YAAY,QACZ,YAAY,aACZ,MAAM,SACN,YAAY,QAiDtB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,4CATW,cAAc,SACd,YAAY,QACZ,YAAY,aACZ,MAAM,SACN,YAAY,OACZ,MAAM,OACN,MAAM,OACN,MAAM,QAqEhB;;IAhRD,uCAA+B;IAE/B,2QAOE;;CAwQL;uBAxVsB,wBAAwB;8BAKjB,oBAAoB;0BAJxB,qCAAqC;4CAFnB,uDAAuD;0BAIzE,wBAAwB;yBADzB,uBAAuB;+BAEjB,qBAAqB;6BAPvB,gDAAgD"}

package/src/engine/physics/fluid/ecs/FluidSystem.d.ts

@@ -38,7 +38,7 @@ export class FluidSystem extends System<any> {
      * @param {FluidEffectorsComponent} effectors_component
      * @param {Transform} transform
      */
-    static "__#168@#sync_effectors_from_transform"(effectors_component: FluidEffectorsComponent, transform: Transform): void;
+    static "__#188@#sync_effectors_from_transform"(effectors_component: FluidEffectorsComponent, transform: Transform): void;
     /**
      * Visitor for the (FluidComponent, Transform) traversal — keeps the field's
      * grid origin locked to a cell-aligned position near the transform.
@@ -61,7 +61,7 @@ export class FluidSystem extends System<any> {
      * @param {FluidComponent} component
      * @param {Transform} transform
      */
-    static "__#168@#reanchor_field"(component: FluidComponent, transform: Transform): void;
+    static "__#188@#reanchor_field"(component: FluidComponent, transform: Transform): void;
     /**
      * Write the world-to-grid affine for a FluidComponent into `out`. Axis-aligned,
      * uniform-scale, so the matrix is sparse:
@@ -76,7 +76,7 @@ export class FluidSystem extends System<any> {
      * @param {Float32Array} out  length-16
      * @param {FluidComponent} component
      */
-    static "__#168@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
+    static "__#188@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
     constructor();
     dependencies: (typeof FluidComponent)[];
     /**
@@ -96,10 +96,6 @@ export class FluidSystem extends System<any> {
      * @type {FluidSimulator}
      */
     simulator: FluidSimulator;
-    /**
-     * @param {number} time_delta_seconds
-     */
-    fixedUpdate(time_delta_seconds: number): void;
     #private;
 }
 import { System } from "../../../ecs/System.js";

package/src/engine/physics/fluid/ecs/FluidSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IA+GI;;;;;OAKG;IACH,oEAHW,uBAAuB,aACvB,SAAS,QAOnB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,2CAHW,cAAc,aACd,SAAS,QA4DnB;IAED;;;;;;;;;;;;;OAaG;IACH,0CAHW,YAAY,aACZ,cAAc,QAexB;;IAvOD,wCAAgC;IAEhC;;;;;;;;OAQG;IACH,sLAME;IAEF;;;;;OAKG;IACH,WAFU,cAAc,CAES;IA4BjC;;OAEG;IACH,gCAFW,MAAM,QAqDhB;;CA6HJ;uBAjRsB,wBAAwB;+BAEhB,qBAAqB;0BAD1B,qCAAqC;4CAFnB,uDAAuD;wCAI3D,8BAA8B;+BACvC,sBAAsB"}
+{"version":3,"file":"FluidSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IA+GI;;;;;OAKG;IACH,oEAHW,uBAAuB,aACvB,SAAS,QAOnB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,2CAHW,cAAc,aACd,SAAS,QA4DnB;IAED;;;;;;;;;;;;;OAaG;IACH,0CAHW,YAAY,aACZ,cAAc,QAexB;;IAvOD,wCAAgC;IAEhC;;;;;;;;OAQG;IACH,sLAME;IAEF;;;;;OAKG;IACH,WAFU,cAAc,CAES;;CA+MpC;uBAjRsB,wBAAwB;+BAEhB,qBAAqB;0BAD1B,qCAAqC;4CAFnB,uDAAuD;wCAI3D,8BAA8B;+BACvC,sBAAsB"}

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_advect_maccormack_scalar.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_maccormack_scalar.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,yDAbW,YAAY,UACZ,YAAY,mBACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA8FpB"}
+{"version":3,"file":"v3_grid_advect_maccormack_scalar.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_maccormack_scalar.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,yDAbW,YAAY,UACZ,YAAY,mBACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA8FpB"}

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

@@ -2,6 +2,13 @@ import { assert } from "../../../../core/assert.js";
 import { clamp } from "../../../../core/math/clamp.js";
 import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
 
+/*
+ * COLLOCATED VARIANT. FluidSimulator transports through the MAC (staggered-grid) kernels in the sibling
+ * v3_mac_* files; this collocated family is exported public surface and is not used by the simulator. The
+ * two families implement the same algorithms against different grid layouts, so a fix to one does not
+ * reach the other -- check both.
+ */
+
 /**
  * Unconditionally stable MacCormack advection of a scalar field — second-order
  * accurate in space and time, at roughly twice the cost of plain

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_advect_maccormack_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_maccormack_velocity.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,4DAbW,YAAY,EAAE,WACd,YAAY,EAAE,aACd,YAAY,aACZ,YAAY,aACZ,YAAY,mBACZ,YAAY,EAAE,SAEd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QAgHpB"}
+{"version":3,"file":"v3_grid_advect_maccormack_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_maccormack_velocity.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,4DAbW,YAAY,EAAE,WACd,YAAY,EAAE,aACd,YAAY,aACZ,YAAY,aACZ,YAAY,mBACZ,YAAY,EAAE,SAEd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QAgHpB"}

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

@@ -1,7 +1,15 @@
+import { v3_grid_limit8_at_indices } from "./v3_grid_limit8_at_indices.js";
 import { assert } from "../../../../core/assert.js";
 import { clamp } from "../../../../core/math/clamp.js";
 import { scs3d_sample_linear3 } from "../../../graphics/texture/3d/scs3d_sample_linear3.js";
 
+/*
+ * COLLOCATED VARIANT. FluidSimulator transports through the MAC (staggered-grid) kernels in the sibling
+ * v3_mac_* files; this collocated family is exported public surface and is not used by the simulator. The
+ * two families implement the same algorithms against different grid layouts, so a fix to one does not
+ * reach the other -- check both.
+ */
+
 /**
  * Unconditionally stable MacCormack advection of a 3-component velocity field
  * along a separate carrier field — the velocity counterpart of
@@ -141,29 +149,14 @@ export function v3_grid_advect_maccormack_velocity(outputs, sources, carrier_x,
                 const c011 = z1_off + y1_off + x0;
                 const c111 = z1_off + y1_off + x1;
 
-                out_x[c] = limit8(corr_x, src_x, c000, c100, c010, c110, c001, c101, c011, c111);
-                out_y[c] = limit8(corr_y, src_y, c000, c100, c010, c110, c001, c101, c011, c111);
-                out_z[c] = limit8(corr_z, src_z, c000, c100, c010, c110, c001, c101, c011, c111);
+                out_x[c] = v3_grid_limit8_at_indices(corr_x, src_x, c000, c100, c010, c110, c001, c101, c011, c111);
+                out_y[c] = v3_grid_limit8_at_indices(corr_y, src_y, c000, c100, c010, c110, c001, c101, c011, c111);
+                out_z[c] = v3_grid_limit8_at_indices(corr_z, src_z, c000, c100, c010, c110, c001, c101, c011, c111);
             }
         }
     }
 }
 
-/**
- * Clamp `value` to the min/max of eight cells of `data`.
- */
-function limit8(value, data, c0, c1, c2, c3, c4, c5, c6, c7) {
-    let mn = data[c0];
-    let mx = mn;
-    let v = data[c1]; if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[c2];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[c3];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[c4];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[c5];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[c6];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[c7];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    return value < mn ? mn : (value > mx ? mx : value);
-}
 
 /** Module-static sample destination — avoids per-cell allocation. */
 const scratch_sample = new Float32Array(3);

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_advect_sl_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_sl_velocity.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,oDAdW,YAAY,EAAE,WACd,YAAY,EAAE,aAEd,YAAY,aACZ,YAAY,aACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA+DpB"}
+{"version":3,"file":"v3_grid_advect_sl_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_sl_velocity.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,oDAdW,YAAY,EAAE,WACd,YAAY,EAAE,aAEd,YAAY,aACZ,YAAY,aACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA+DpB"}

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

@@ -1,6 +1,13 @@
 import { assert } from "../../../../core/assert.js";
 import { scs3d_sample_linear3 } from "../../../graphics/texture/3d/scs3d_sample_linear3.js";
 
+/*
+ * COLLOCATED VARIANT. FluidSimulator transports through the MAC (staggered-grid) kernels in the sibling
+ * v3_mac_* files; this collocated family is exported public surface and is not used by the simulator. The
+ * two families implement the same algorithms against different grid layouts, so a fix to one does not
+ * reach the other -- check both.
+ */
+
 /**
  * Semi-Lagrangian advection of a 3-component velocity field along a separate
  * carrier velocity field.

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_apply_advection_forward.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_advection_forward.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,yDAXW,YAAY,EAAE,UACd,YAAY,EAAE,SAEd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SAEN,UAAU,QA6DpB"}
+{"version":3,"file":"v3_grid_apply_advection_forward.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_advection_forward.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,yDAXW,YAAY,EAAE,UACd,YAAY,EAAE,SAEd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SAEN,UAAU,QAWpB"}

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

@@ -1,6 +1,14 @@
+import { v3_grid_advect_sl_velocity } from "./v3_grid_advect_sl_velocity.js";
 import { assert } from "../../../../core/assert.js";
 import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
 
+/*
+ * COLLOCATED VARIANT. FluidSimulator transports through the MAC (staggered-grid) kernels in the sibling
+ * v3_mac_* files; this collocated family is exported public surface and is not used by the simulator. The
+ * two families implement the same algorithms against different grid layouts, so a fix to one does not
+ * reach the other -- check both.
+ */
+
 /**
  * Semi-Lagrangian self-advection of a cell-centered 3D velocity field.
  *
@@ -30,61 +38,11 @@ import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_l
  *                                   domain); non-zero cells are not updated.
  */
 export function v3_grid_apply_advection_forward(outputs, inputs, res_x, res_y, res_z, time_delta, solid) {
-    assert.equal(outputs.length, 3, "outputs is a 3-component array");
-    assert.equal(inputs.length, 3, "inputs is a 3-component array");
-
-    const out_x = outputs[0];
-    const out_y = outputs[1];
-    const out_z = outputs[2];
-
-    const in_x = inputs[0];
-    const in_y = inputs[1];
-    const in_z = inputs[2];
-
-    const cell_count = res_x * res_y * res_z;
-
-    assert.greaterThanOrEqual(out_x.length, cell_count, "out_x covers grid");
-    assert.greaterThanOrEqual(out_y.length, cell_count, "out_y covers grid");
-    assert.greaterThanOrEqual(out_z.length, cell_count, "out_z covers grid");
-    assert.greaterThanOrEqual(in_x.length, cell_count, "in_x covers grid");
-    assert.greaterThanOrEqual(in_y.length, cell_count, "in_y covers grid");
-    assert.greaterThanOrEqual(in_z.length, cell_count, "in_z covers grid");
-
-    assert.notEqual(out_x, in_x, "out_x must not alias in_x");
-    assert.notEqual(out_y, in_y, "out_y must not alias in_y");
-    assert.notEqual(out_z, in_z, "out_z must not alias in_z");
-
-    const slice_size = res_x * res_y;
-
-    for (let z = 0; z < res_z; z++) {
-        const z_off = z * slice_size;
-
-        for (let y = 0; y < res_y; y++) {
-            const y_off = y * res_x;
-
-            for (let x = 0; x < res_x; x++) {
-                const c = z_off + y_off + x;
-
-                if (solid[c] !== 0) {
-                    out_x[c] = in_x[c];
-                    out_y[c] = in_y[c];
-                    out_z[c] = in_z[c];
-                    continue;
-                }
-
-                const v_x = in_x[c];
-                const v_y = in_y[c];
-                const v_z = in_z[c];
-
-                // Trace back to where this parcel came from one timestep ago.
-                const s_x = x - v_x * time_delta;
-                const s_y = y - v_y * time_delta;
-                const s_z = z - v_z * time_delta;
-
-                out_x[c] = scs3d_sample_linear(in_x, res_x, res_y, res_z, s_x, s_y, s_z);
-                out_y[c] = scs3d_sample_linear(in_y, res_x, res_y, res_z, s_x, s_y, s_z);
-                out_z[c] = scs3d_sample_linear(in_z, res_x, res_y, res_z, s_x, s_y, s_z);
-            }
-        }
-    }
+    // self-advection: the field being transported is also the carrier
+    v3_grid_advect_sl_velocity(
+        outputs, inputs,
+        inputs[0], inputs[1], inputs[2],
+        res_x, res_y, res_z,
+        time_delta, solid
+    );
 }

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_apply_scalar_advection.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_scalar_advection.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uDAbW,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QAuCpB"}
+{"version":3,"file":"v3_grid_apply_scalar_advection.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_scalar_advection.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uDAbW,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QAuCpB"}

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

@@ -1,6 +1,13 @@
 import { assert } from "../../../../core/assert.js";
 import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
 
+/*
+ * COLLOCATED VARIANT. FluidSimulator transports through the MAC (staggered-grid) kernels in the sibling
+ * v3_mac_* files; this collocated family is exported public surface and is not used by the simulator. The
+ * two families implement the same algorithms against different grid layouts, so a fix to one does not
+ * reach the other -- check both.
+ */
+
 /**
  * Semi-Lagrangian advection of a scalar field by a separate velocity field.
  *

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

@@ -0,0 +1,28 @@
+/**
+ * Clamp `value` into the range spanned by the eight samples `data[c0..c7]` — the Selle monotone limiter
+ * used to keep a MacCormack correction from overshooting the trilinear stencil it was interpolated from.
+ *
+ * The eight indices are the corners of one grid cell; the caller derives them, because the two callers
+ * address their grids differently (a collocated kernel already holds the corner offsets, while the
+ * staggered kernel derives them from a clamped fractional position).
+ *
+ * The comparison order is load-bearing: it is preserved exactly from the copies this replaces so the
+ * limiter stays bit-identical, and the fluid solver is under a determinism contract.
+ *
+ * @param {number} value candidate value to clamp
+ * @param {Float32Array} data field being sampled
+ * @param {number} c0 index of corner 0
+ * @param {number} c1
+ * @param {number} c2
+ * @param {number} c3
+ * @param {number} c4
+ * @param {number} c5
+ * @param {number} c6
+ * @param {number} c7
+ * @returns {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v3_grid_limit8_at_indices(value: number, data: Float32Array, c0: number, c1: number, c2: number, c3: number, c4: number, c5: number, c6: number, c7: number): number;
+//# sourceMappingURL=v3_grid_limit8_at_indices.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_limit8_at_indices.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_limit8_at_indices.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,iDAfW,MAAM,QACN,YAAY,MACZ,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAgBlB"}

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

@@ -0,0 +1,38 @@
+/**
+ * Clamp `value` into the range spanned by the eight samples `data[c0..c7]` — the Selle monotone limiter
+ * used to keep a MacCormack correction from overshooting the trilinear stencil it was interpolated from.
+ *
+ * The eight indices are the corners of one grid cell; the caller derives them, because the two callers
+ * address their grids differently (a collocated kernel already holds the corner offsets, while the
+ * staggered kernel derives them from a clamped fractional position).
+ *
+ * The comparison order is load-bearing: it is preserved exactly from the copies this replaces so the
+ * limiter stays bit-identical, and the fluid solver is under a determinism contract.
+ *
+ * @param {number} value candidate value to clamp
+ * @param {Float32Array} data field being sampled
+ * @param {number} c0 index of corner 0
+ * @param {number} c1
+ * @param {number} c2
+ * @param {number} c3
+ * @param {number} c4
+ * @param {number} c5
+ * @param {number} c6
+ * @param {number} c7
+ * @returns {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v3_grid_limit8_at_indices(value, data, c0, c1, c2, c3, c4, c5, c6, c7) {
+    let mn = data[c0];
+    let mx = mn;
+    let v = data[c1]; if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c2];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c3];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c4];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c5];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c6];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c7];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    return value < mn ? mn : (value > mx ? mx : value);
+}

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

@@ -1 +1 @@
-{"version":3,"file":"v3_mac_advect_maccormack_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_advect_maccormack_velocity.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,2DAbW,YAAY,EAAE,WACd,YAAY,EAAE,WACd,YAAY,EAAE,mBACd,YAAY,EAAE,SACd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,gBACN,UAAU,gBACV,UAAU,gBACV,UAAU,SACV,UAAU,QA0MpB"}
+{"version":3,"file":"v3_mac_advect_maccormack_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_advect_maccormack_velocity.js"],"names":[],"mappings":"AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,2DAbW,YAAY,EAAE,WACd,YAAY,EAAE,WACd,YAAY,EAAE,mBACd,YAAY,EAAE,SACd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,gBACN,UAAU,gBACV,UAAU,gBACV,UAAU,SACV,UAAU,QA0MpB"}

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

@@ -1,3 +1,4 @@
+import { v3_grid_limit8_at_indices } from "./v3_grid_limit8_at_indices.js";
 import { assert } from "../../../../core/assert.js";
 import { clamp } from "../../../../core/math/clamp.js";
 import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
@@ -148,7 +149,7 @@ export function v3_mac_advect_maccormack_velocity(outputs, sources, carrier, for
                     const backward = scs3d_sample_linear(fwd_u, sx, res_y, res_z, qx + 0.5, qy, qz);
                     const corrected = fwd_u[f] + 0.5 * (src_u[f] - backward);
 
-                    out_u[f] = limit8(corrected, src_u,
+                    out_u[f] = limit8_at_position(corrected, src_u,
                         bx + 0.5, by, bz,
                         sx, res_y, res_z, sx, u_slice);
                 }
@@ -205,7 +206,7 @@ export function v3_mac_advect_maccormack_velocity(outputs, sources, carrier, for
                     const backward = scs3d_sample_linear(fwd_v, res_x, sy, res_z, qx, qy + 0.5, qz);
                     const corrected = fwd_v[f] + 0.5 * (src_v[f] - backward);
 
-                    out_v[f] = limit8(corrected, src_v,
+                    out_v[f] = limit8_at_position(corrected, src_v,
                         bx, by + 0.5, bz,
                         res_x, sy, res_z, res_x, v_slice);
                 }
@@ -264,7 +265,7 @@ export function v3_mac_advect_maccormack_velocity(outputs, sources, carrier, for
                     const backward = scs3d_sample_linear(fwd_w, res_x, res_y, sz, qx, qy, qz + 0.5);
                     const corrected = fwd_w[f] + 0.5 * (src_w[f] - backward);
 
-                    out_w[f] = limit8(corrected, src_w,
+                    out_w[f] = limit8_at_position(corrected, src_w,
                         bx, by, bz + 0.5,
                         res_x, res_y, sz, res_x, cell_slice);
                 }
@@ -290,7 +291,7 @@ export function v3_mac_advect_maccormack_velocity(outputs, sources, carrier, for
  * @param {number} slice  lattice slice stride
  * @return {number}
  */
-function limit8(value, data, lx, ly, lz, dim_x, dim_y, dim_z, row, slice) {
+function limit8_at_position(value, data, lx, ly, lz, dim_x, dim_y, dim_z, row, slice) {
     const bx = clamp(lx, 0, dim_x - 1);
     const by = clamp(ly, 0, dim_y - 1);
     const bz = clamp(lz, 0, dim_z - 1);
@@ -306,14 +307,11 @@ function limit8(value, data, lx, ly, lz, dim_x, dim_y, dim_z, row, slice) {
     const y0_off = y0 * row;
     const y1_off = y1 * row;
 
-    let mn = data[z0_off + y0_off + x0];
-    let mx = mn;
-    let v = data[z0_off + y0_off + x1]; if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[z0_off + y1_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[z0_off + y1_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[z1_off + y0_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[z1_off + y0_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[z1_off + y1_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    v = data[z1_off + y1_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
-    return value < mn ? mn : (value > mx ? mx : value);
+    return v3_grid_limit8_at_indices(
+        value, data,
+        z0_off + y0_off + x0, z0_off + y0_off + x1,
+        z0_off + y1_off + x0, z0_off + y1_off + x1,
+        z1_off + y0_off + x0, z1_off + y0_off + x1,
+        z1_off + y1_off + x0, z1_off + y1_off + x1
+    );
 }

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

@@ -1 +1 @@
-{"version":3,"file":"v3_mac_apply_vorticity_confinement.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_apply_vorticity_confinement.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,0DApBW,YAAY,SACZ,YAAY,SACZ,YAAY,gBACZ,UAAU,gBACV,UAAU,gBACV,UAAU,cACV,YAAY,cAEZ,YAAY,cACZ,YAAY,cACZ,YAAY,cACZ,YAAY,cACZ,YAAY,gBACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA8HpB"}
+{"version":3,"file":"v3_mac_apply_vorticity_confinement.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_apply_vorticity_confinement.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,0DApBW,YAAY,SACZ,YAAY,SACZ,YAAY,gBACZ,UAAU,gBACV,UAAU,gBACV,UAAU,cACV,YAAY,cAEZ,YAAY,cACZ,YAAY,cACZ,YAAY,cACZ,YAAY,cACZ,YAAY,gBACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA8HpB"}

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

@@ -1,5 +1,14 @@
 import { assert } from "../../../../core/assert.js";
 
+/*
+ * Passes 2 and 3 below mirror the two passes of the collocated v3_grid_apply_vorticity_confinement: same
+ * central-difference curl, same magnitude floor, same N x omega force. They are NOT shared. Extracting
+ * them means the force helper writes three floats to a module-static buffer per cell instead of keeping
+ * them in registers, across the whole grid, every step -- and this kernel is under both a determinism
+ * contract and a measured performance budget. Any unification here must lead with a benchmark, not with
+ * the line count.
+ */
+
 /**
  * Vorticity confinement (Fedkiw, Stam, Jensen 2001) for a MAC velocity field.
  *

package/src/engine/physics/mls-mpm/MLS_MPM.d.ts

@@ -12,6 +12,18 @@ export class MLS_MPMSolver {
      * @param {number} dt
      */
     advance(dt: number): void;
-    add_rnd_square(center: any, c: any, count?: number): void;
+    /**
+     * Scatter `count` particles uniformly inside a square centred on `center`.
+     *
+     * `random` is a required argument rather than an internal `Math.random()`, matching every other
+     * sampler in the engine (see `sample_random_point_in_volume` on the core shapes). A simulation whose
+     * particle layout comes from an unseeded global cannot be replayed or reproduced across runs.
+     *
+     * @param {number[]} center
+     * @param {number} c
+     * @param {function():number} random source of uniform randomness in [0, 1)
+     * @param {number} [count]
+     */
+    add_rnd_square(center: number[], c: number, random: () => number, count?: number): void;
 }
 //# sourceMappingURL=MLS_MPM.d.ts.map

package/src/engine/physics/mls-mpm/MLS_MPM.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MLS_MPM.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/mls-mpm/MLS_MPM.js"],"names":[],"mappings":"AAcA;IAGQ,iBAAmB;IAGnB;;;;;OAKG;IACH,MAFU,YAAY,CAEiB;IAI3C;;;OAGG;IACH,YAFW,MAAM,QAyVhB;IAED,0DAeC;CACJ"}
+{"version":3,"file":"MLS_MPM.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/mls-mpm/MLS_MPM.js"],"names":[],"mappings":"AAcA;IAGQ,iBAAmB;IAGnB;;;;;OAKG;IACH,MAFU,YAAY,CAEiB;IAI3C;;;OAGG;IACH,YAFW,MAAM,QAyVhB;IAED;;;;;;;;;;;OAWG;IACH,uBALW,MAAM,EAAE,KACR,MAAM,gBACK,MAAM,UACjB,MAAM,QAgBhB;CACJ"}

package/src/engine/physics/mls-mpm/MLS_MPM.js

@@ -377,16 +377,27 @@ export class MLS_MPMSolver {
         }
     }
 
-    add_rnd_square(center, c, count=1000) {
+    /**
+     * Scatter `count` particles uniformly inside a square centred on `center`.
+     *
+     * `random` is a required argument rather than an internal `Math.random()`, matching every other
+     * sampler in the engine (see `sample_random_point_in_volume` on the core shapes). A simulation whose
+     * particle layout comes from an unseeded global cannot be replayed or reproduced across runs.
+     *
+     * @param {number[]} center
+     * @param {number} c
+     * @param {function():number} random source of uniform randomness in [0, 1)
+     * @param {number} [count]
+     */
+    add_rnd_square(center, c, random, count = 1000) {
         const particles = this.particles;
 
         for (let i = 0; i < count; i++) {
-            // Randomly sample 1000 particles in the square
             particles.push(
                 new Particle(
                     [
-                        (Math.random() * 2 - 1) * 0.08 + center[0],
-                        (Math.random() * 2 - 1) * 0.08 + center[1]
+                        (random() * 2 - 1) * 0.08 + center[0],
+                        (random() * 2 - 1) * 0.08 + center[1]
                     ],
                     c
                 )