@woosh/meep-engine 3.30.0 → 3.32.0

package/src/engine/physics/fluid/solver/NOTES.md

@@ -0,0 +1,46 @@
+# Two generations of kernel live in here
+
+`FluidField` and `FluidSimulator` run the **`v3_mac_*`** kernels — the staggered (MAC) grid — plus the
+grid-generic helpers `v3_grid_apply_diffusion`, `v3_grid_solve_pressure*`,
+`v3_grid_compute_solid_neighbour_mask`, `v3_grid_shift_in_place`, `v3_grid_sample_scalar_masked` and the
+two edge-patch helpers.
+
+The **collocated** `v3_grid_advect_*` family is the previous generation of the same algorithms, on a
+collocated grid instead of a staggered one. It is reachable only from itself and its own specs:
+
+- `v3_grid_advect_maccormack_velocity`
+- `v3_grid_advect_sl_velocity` (one importer, `v3_grid_apply_advection_forward`, itself unreferenced)
+- `v3_grid_advect_maccormack_scalar`
+- `v3_grid_apply_advection_forward`
+- `v3_grid_apply_scalar_advection`
+- `v3_grid_compute_divergence`
+- `v3_grid_subtract_pressure_gradient`
+- `v3_grid_apply_vorticity_confinement`
+
+834 lines across the eight. `v3_mac_advect_maccormack_scalar` (in `v3_mac_advect_scalar.js`) is a ninth
+unreferenced kernel, on the live staggering: gather-MacCormack was **measured** non-conservative for
+scalars and rejected, which the `AdvectionScheme` docstring records.
+
+## Why they are still here
+
+`@woosh/meep-engine` publishes raw `src`, so an unreferenced export is public surface rather than dead
+code. A consumer running a collocated solver — the shape most fluid tutorials and most ported code use —
+wants exactly these, and they are correct for that grid.
+
+## What to know before using one
+
+**They are not interchangeable with the MAC kernels.** The staggering is the whole difference: a
+collocated kernel reads and writes velocity at cell centres, a MAC one at face centres. Feeding one
+family's field to the other gives a half-cell-shifted velocity everywhere, which looks like excessive
+diffusion rather than like a bug.
+
+**The collocated MacCormack limiter is not the MAC one.** It takes its extrema from the eight
+surrounding taps through `v3_grid_limit8_at_indices`, over raw samples. The live MAC scalar path clips
+the trace (`v3_mac_clip_trace`) and samples solid-masked, so the two disagree about wall handling: near
+a solid boundary the collocated limiter will admit a value from inside the wall as a legitimate extremum.
+If a collocated solver here is ever put on a path with solid boundaries that matter, that is the gap to
+close first.
+
+**Two of them have MAC twins whose docstrings describe them as the replacement** —
+`v3_mac_compute_divergence` and the MAC pressure-gradient subtraction each say they are "the face-exact
+counterpart of the collocated …". Read the MAC one first if you are trying to work out which is current.

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

@@ -6,7 +6,7 @@ import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_l
  * 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.
+ * reach the other -- check both. See NOTES.md in this directory.
  */
 
 /**

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

@@ -7,7 +7,7 @@ import { scs3d_sample_linear3 } from "../../../graphics/texture/3d/scs3d_sample_
  * 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.
+ * reach the other -- check both. See NOTES.md in this directory.
  */
 
 /**

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

@@ -5,7 +5,7 @@ import { scs3d_sample_linear3 } from "../../../graphics/texture/3d/scs3d_sample_
  * 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.
+ * reach the other -- check both. See NOTES.md in this directory.
  */
 
 /**

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

@@ -6,7 +6,7 @@ import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_l
  * 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.
+ * reach the other -- check both. See NOTES.md in this directory.
  */
 
 /**

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

@@ -5,7 +5,7 @@ import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_l
  * 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.
+ * reach the other -- check both. See NOTES.md in this directory.
  */
 
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_apply_vorticity_confinement.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_vorticity_confinement.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,2DAdW,YAAY,SACZ,YAAY,SACZ,YAAY,cACZ,YAAY,cACZ,YAAY,cACZ,YAAY,gBACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SAEN,UAAU,QA0FpB"}
+{"version":3,"file":"v3_grid_apply_vorticity_confinement.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_vorticity_confinement.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,2DAdW,YAAY,SACZ,YAAY,SACZ,YAAY,cACZ,YAAY,cACZ,YAAY,cACZ,YAAY,gBACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SAEN,UAAU,QA0FpB"}

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

@@ -1,5 +1,13 @@
 import { assert } from "../../../../core/assert.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. See NOTES.md in this directory.
+ */
+
+
 /**
  * Vorticity confinement (Fedkiw, Stam, Jensen 2001 — "Visual Simulation of
  * Smoke"): re-inject the small-scale rotational motion that coarse grids and

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

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

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

@@ -1,5 +1,13 @@
 import { assert } from "../../../../core/assert.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. See NOTES.md in this directory.
+ */
+
+
 /**
  * Compute the divergence of a cell-centered velocity field into a scalar field.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_subtract_pressure_gradient.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,0DAVW,YAAY,SACZ,YAAY,SACZ,YAAY,YACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,kBACN,UAAU,QAuDpB"}
+{"version":3,"file":"v3_grid_subtract_pressure_gradient.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,0DAVW,YAAY,SACZ,YAAY,SACZ,YAAY,YACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,kBACN,UAAU,QAuDpB"}

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

@@ -1,5 +1,13 @@
 import { assert } from "../../../../core/assert.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. See NOTES.md in this directory.
+ */
+
+
 /**
  * Subtract the pressure gradient from a velocity field in-place, making the velocity
  * (approximately) divergence-free:

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

@@ -37,6 +37,11 @@ export function v3_mac_advect_sl_scalar(output: Float32Array, input: Float32Arra
  * fluid the corrected value is discarded in favour of the first-order
  * forward result.
  *
+ * **Not scheduled.** `AdvectionScheme`'s docstring records that gather-MacCormack was *measured*
+ * non-conservative for scalars and rejected, so `FluidSimulator` runs the semi-Lagrangian scalar path
+ * instead. Exported because raw `src` is published; see NOTES.md in this directory for the rest of the
+ * unscheduled surface here.
+ *
  * @param {Float32Array} output           Destination. Mutated.
  * @param {Float32Array} input            Source. NOT mutated.
  * @param {Float32Array} forward_scratch  Working buffer for the forward pass.

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

@@ -1 +1 @@
-{"version":3,"file":"v3_mac_advect_scalar.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_advect_scalar.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,gDAXW,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA4CpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wDAZW,YAAY,SACZ,YAAY,mBACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA8GpB"}
+{"version":3,"file":"v3_mac_advect_scalar.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_advect_scalar.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,gDAXW,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA4CpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wDAZW,YAAY,SACZ,YAAY,mBACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA8GpB"}

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

@@ -113,6 +113,11 @@ export function v3_mac_advect_sl_scalar(output, input, vel_u, vel_v, vel_w, res_
  * fluid the corrected value is discarded in favour of the first-order
  * forward result.
  *
+ * **Not scheduled.** `AdvectionScheme`'s docstring records that gather-MacCormack was *measured*
+ * non-conservative for scalars and rejected, so `FluidSimulator` runs the semi-Lagrangian scalar path
+ * instead. Exported because raw `src` is published; see NOTES.md in this directory for the rest of the
+ * unscheduled surface here.
+ *
  * @param {Float32Array} output           Destination. Mutated.
  * @param {Float32Array} input            Source. NOT mutated.
  * @param {Float32Array} forward_scratch  Working buffer for the forward pass.

package/src/engine/physics/integration/integrate_velocity.d.ts

@@ -14,6 +14,21 @@
  * Kinematic and Static bodies are skipped — their velocity is the
  * user / animation system's responsibility.
  *
+ * ## Not what the TGS step runs
+ *
+ * `PhysicsSystem` imports {@link integrate_velocity_forces} (once per outer step, forces only, no
+ * damping) and {@link integrate_velocity_gravity} (per substep, gravity and damping, over the
+ * `SolverBodyState` span). This function is the *non-substepped* form: it folds gravity into the force
+ * pass and applies damping at the caller's `dt`, which is the pattern `solve_contacts` names as what
+ * "over-pushes resting contacts and jitters / explodes deep stacks". Dropping it into a substepped loop
+ * applies gravity once per substep at the outer damping rate and is wrong in both halves.
+ *
+ * It also writes the `RigidBody` component where `integrate_velocity_gravity` writes the solver span, so
+ * it is not expressible in terms of the pair and is not a candidate for being folded into them. It is kept
+ * because it is a correct single-pass semi-implicit Euler integrator and a published export — a consumer
+ * stepping bodies outside the TGS solver wants exactly this — and its spec is a spec of *it*, not of the
+ * engine's integration path.
+ *
  * @param {RigidBody} rb
  * @param {Transform64} transform  used to rotate body-frame inertia into world
  * @param {number} gx world gravity x

package/src/engine/physics/integration/integrate_velocity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integrate_velocity.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_velocity.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8EALW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAoDhB;AAED;;;;;;;;;;;;GAYG;AACH,qFAFW,MAAM,QAkDhB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,+CARW,YAAY,QACZ,MAAM,qBAEN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAkChB"}
+{"version":3,"file":"integrate_velocity.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_velocity.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,8EALW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAoDhB;AAED;;;;;;;;;;;;GAYG;AACH,qFAFW,MAAM,QAkDhB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,+CARW,YAAY,QACZ,MAAM,qBAEN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAkChB"}

package/src/engine/physics/integration/integrate_velocity.js

@@ -43,6 +43,21 @@ function locked_inverse_inertia(rb) {
  * Kinematic and Static bodies are skipped — their velocity is the
  * user / animation system's responsibility.
  *
+ * ## Not what the TGS step runs
+ *
+ * `PhysicsSystem` imports {@link integrate_velocity_forces} (once per outer step, forces only, no
+ * damping) and {@link integrate_velocity_gravity} (per substep, gravity and damping, over the
+ * `SolverBodyState` span). This function is the *non-substepped* form: it folds gravity into the force
+ * pass and applies damping at the caller's `dt`, which is the pattern `solve_contacts` names as what
+ * "over-pushes resting contacts and jitters / explodes deep stacks". Dropping it into a substepped loop
+ * applies gravity once per substep at the outer damping rate and is wrong in both halves.
+ *
+ * It also writes the `RigidBody` component where `integrate_velocity_gravity` writes the solver span, so
+ * it is not expressible in terms of the pair and is not a candidate for being folded into them. It is kept
+ * because it is a correct single-pass semi-implicit Euler integrator and a published export — a consumer
+ * stepping bodies outside the TGS solver wants exactly this — and its spec is a spec of *it*, not of the
+ * engine's integration path.
+ *
  * @param {RigidBody} rb
  * @param {Transform64} transform  used to rotate body-frame inertia into world
  * @param {number} gx world gravity x

package/src/engine/physics/island/IslandBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IslandBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/island/IslandBuilder.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH;IAuFI;;;;;OAKG;IACH,gCAOC;IA0ND;;;;;;;;;;;;;OAaG;IACH,2CAmBC;IAED;;;;;OAKG;IACH,6BAIC;IAED;;;OAGG;IACH,6BAIC;IAnXD;;;;;OAKG;IACH,QAFU,WAAW,CAEQ;IAE7B;;;;OAIG;IACH,gBAFU,UAAU,CAEgB;IAEpC;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,cAFU,WAAW,CAEa;IAElC;;;;OAIG;IACH,WAFU,WAAW,CAEW;IAEhC;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,iBAFU,WAAW,CAEgB;IAErC;;;;OAIG;IACH,cAFU,WAAW,CAEc;IAEnC;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;OAKG;IACH,yBAAsC;IAEtC;;;;;OAKG;IACH,wBAAsC;IAEtC;;;;OAIG;IACH,kBAA+B;IAiB/B;;;;;;;;;;;OAWG;IACH,8DANW,WAAW,uBACX,OAAO,UACP,OAAO,QAqGjB;IAED;;;;OAIG;IACH,yBA+CC;IAED;;;;;;OAMG;IACH,4BA0CC;IA2DD;;;;;;;;;OASG;IACH,yBAsBC;IAID;;;OAGG;IACH,+BAQC;IAED;;;OAGG;IACH,uCAOC;IAED;;;OAGG;IACH,oCAIC;IAED;;;OAGG;IACH,uCAIC;CACJ"}
+{"version":3,"file":"IslandBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/island/IslandBuilder.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH;IAuFI;;;;;OAKG;IACH,gCAMC;IA0ND;;;;;;;;;;;;;OAaG;IACH,2CAmBC;IAED;;;;;OAKG;IACH,6BAIC;IAED;;;OAGG;IACH,6BAIC;IAlXD;;;;;OAKG;IACH,QAFU,WAAW,CAEQ;IAE7B;;;;OAIG;IACH,gBAFU,UAAU,CAEgB;IAEpC;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,cAFU,WAAW,CAEa;IAElC;;;;OAIG;IACH,WAFU,WAAW,CAEW;IAEhC;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,iBAFU,WAAW,CAEgB;IAErC;;;;OAIG;IACH,cAFU,WAAW,CAEc;IAEnC;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;OAKG;IACH,yBAAsC;IAEtC;;;;;OAKG;IACH,wBAAsC;IAEtC;;;;OAIG;IACH,kBAA+B;IAgB/B;;;;;;;;;;;OAWG;IACH,8DANW,WAAW,uBACX,OAAO,UACP,OAAO,QAqGjB;IAED;;;;OAIG;IACH,yBA+CC;IAED;;;;;;OAMG;IACH,4BA0CC;IA2DD;;;;;;;;;OASG;IACH,yBAsBC;IAID;;;OAGG;IACH,+BAQC;IAED;;;OAGG;IACH,uCAOC;IAED;;;OAGG;IACH,oCAIC;IAED;;;OAGG;IACH,uCAIC;CACJ"}

package/src/engine/physics/island/IslandBuilder.js

@@ -1,7 +1,7 @@
 import { ceilPowerOfTwo } from "../../../core/binary/operations/ceilPowerOfTwo.js";
 import { body_id_index } from "../body/BodyStorage.js";
 import { BodyKind } from "../ecs/BodyKind.js";
-import { is_sensor } from "../ecs/is_sensor.js";
+import { body_is_wholly_sensor } from "../ecs/is_sensor.js";
 import { JOINT_WORLD } from "../ecs/Joint.js";
 import { uf_find, uf_init, uf_union } from "../../../core/collection/union-find/union_find.js";
 
@@ -142,12 +142,11 @@ export class IslandBuilder {
      * @private
      */
     static __body_is_sensor(rb, collider_list) {
-        // v1 approximation: the body's primary (first) collider stands in for
-        // the whole body, matching the solver's pair_is_sensor / raycast checks.
-        const collider = (collider_list !== undefined && collider_list.length > 0)
-            ? collider_list[0].collider
-            : null;
-        return is_sensor(rb, collider);
+        // Every collider, not the first one: the primary-collider shortcut made
+        // a [trigger volume, solid hull] body read as a sensor and drop out of
+        // every island, so nothing it carried ever solved. See
+        // body_is_wholly_sensor.
+        return body_is_wholly_sensor(rb, collider_list);
     }
 
     /**

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;IACI,iBAAe;IAIX;;;;;OAKG;IACH,MAFU,YAAY,CAEiB;IAG3C;;;OAGG;IACH,YAFW,MAAM,QAuWhB;IAED;;;;;;;;;;;OAWG;IACH,uBALW,MAAM,EAAE,KACR,MAAM,gBACK,MAAM,UACjB,MAAM,QAgBhB;CACJ"}
+{"version":3,"file":"MLS_MPM.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/mls-mpm/MLS_MPM.js"],"names":[],"mappings":"AAcA;IACI,iBAAe;IAIX;;;;;OAKG;IACH,MAFU,YAAY,CAEiB;IAG3C;;;OAGG;IACH,YAFW,MAAM,QAuXhB;IAED;;;;;;;;;;;OAWG;IACH,uBALW,MAAM,EAAE,KACR,MAAM,gBACK,MAAM,UACjB,MAAM,QAgBhB;CACJ"}

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

@@ -112,9 +112,14 @@ export class MLS_MPMSolver {
             const particle_position_x = particle_position[0];
             const particle_position_y = particle_position[1];
 
-            // element-wise floor
-            const base_coordinate_x = (particle_position_x * inv_dx - 0.5) | 0;
-            const base_coordinate_y = (particle_position_y * inv_dx - 0.5) | 0;
+            // Element-wise floor, and `| 0` will not do it: that truncates toward zero,
+            // so for a particle in the first half-cell — where the argument is negative —
+            // it gives 0 where floor gives -1. `fx` then lands in [0, 0.5) instead of the
+            // [1, 1.5) the quadratic kernel is derived for, and the middle weight
+            // `0.75 - (fx - 1)^2` comes out NEGATIVE, depositing negative mass and
+            // negative momentum into a real node.
+            const base_coordinate_x = Math.floor(particle_position_x * inv_dx - 0.5);
+            const base_coordinate_y = Math.floor(particle_position_y * inv_dx - 0.5);
 
             // base position in grid units
             const fx_x = particle_position_x * inv_dx - base_coordinate_x;
@@ -273,9 +278,14 @@ export class MLS_MPMSolver {
             const particle_position_x = particle_position[0];
             const particle_position_y = particle_position[1];
 
-            // element-wise floor
-            const base_coordinate_x = (particle_position_x * inv_dx - 0.5) | 0;
-            const base_coordinate_y = (particle_position_y * inv_dx - 0.5) | 0;
+            // Element-wise floor, and `| 0` will not do it: that truncates toward zero,
+            // so for a particle in the first half-cell — where the argument is negative —
+            // it gives 0 where floor gives -1. `fx` then lands in [0, 0.5) instead of the
+            // [1, 1.5) the quadratic kernel is derived for, and the middle weight
+            // `0.75 - (fx - 1)^2` comes out NEGATIVE, depositing negative mass and
+            // negative momentum into a real node.
+            const base_coordinate_x = Math.floor(particle_position_x * inv_dx - 0.5);
+            const base_coordinate_y = Math.floor(particle_position_y * inv_dx - 0.5);
 
             // base position in grid units
             const fx_x = particle_position_x * inv_dx - base_coordinate_x;
@@ -316,13 +326,19 @@ export class MLS_MPMSolver {
 
                 const grid_y = base_coordinate_y + j;
 
-                // Same guard as the scatter above, which this loop was missing entirely. The stencil
-                // reaches `base + 2` and the base reaches the last cell, so a particle near the far
-                // corner indexed past the end of the flat grid, read `undefined`, and turned itself
-                // into NaN for the rest of the simulation - the hardening `Math.exp` and the polar
-                // decomposition both propagate it, and its next scatter poisons whatever node
+                // The gather has to stay inside the lattice, and the lattice is
+                // `grid_width * grid_height` nodes rather than `n` cells: node index
+                // `n` is a real node, which the boundary pass holds at zero.
+                //
+                // Same guard as the scatter above, which this loop was missing
+                // entirely. A particle in the first half-cell has a base coordinate
+                // of -1, and the stencil reaches `base + 2` from a base in the last
+                // cell, so either end indexed past the flat typed array, read
+                // `undefined`, and turned the particle into NaN for the rest of the
+                // simulation — the hardening `Math.exp` and the polar decomposition
+                // both propagate it, and its next scatter poisons whatever node
                 // `(NaN | 0)` maps to, which is the corner of the domain.
-                if (grid_y < 0 || grid_y >= n) {
+                if (grid_y < 0 || grid_y >= grid_height) {
                     continue;
                 }
 
@@ -333,7 +349,7 @@ export class MLS_MPMSolver {
 
                     const grid_x = base_coordinate_x + i;
 
-                    if (grid_x < 0 || grid_x >= n) {
+                    if (grid_x < 0 || grid_x >= grid_width) {
                         continue;
                     }
 

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

@@ -0,0 +1,29 @@
+/**
+ * Populate a solver with the demo's particles.
+ *
+ * @param {import("./MLS_MPM.js").MLS_MPMSolver} solver
+ * @param {function():number} random uniform in [0, 1) — required, so the layout
+ *   is reproducible across runs
+ * @returns {void}
+ */
+export function add_mls_mpm_demo_squares(solver: import("./MLS_MPM.js").MLS_MPMSolver, random: () => number): void;
+/**
+ * The three blocks of snow the MLS-MPM demo drops, as a function rather than as
+ * three statements inside a file that also builds a canvas.
+ *
+ * The driver is DOM-only and runs at import, so nothing could check its calls;
+ * that is how it came to be passing two arguments to a three-argument
+ * `add_rnd_square` and throwing before its first frame. The scene is the part
+ * worth checking, so it lives here where a spec can reach it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Seed the demo uses, so two runs of the page produce the same picture. Any
+ * value does; this one is only here to be a written-down constant rather than
+ * a literal in a call.
+ * @type {number}
+ */
+export const MLS_MPM_DEMO_SEED: number;
+//# sourceMappingURL=mls_mpm_demo_scene.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mls_mpm_demo_scene.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/mls-mpm/mls_mpm_demo_scene.js"],"names":[],"mappings":"AA+BA;;;;;;;GAOG;AACH,iDALW,OAAO,cAAc,EAAE,aAAa,gBACzB,MAAM,GAEf,IAAI,CAMhB;AA3CD;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,gCAFU,MAAM,CAEsB"}

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

@@ -0,0 +1,44 @@
+/**
+ * The three blocks of snow the MLS-MPM demo drops, as a function rather than as
+ * three statements inside a file that also builds a canvas.
+ *
+ * The driver is DOM-only and runs at import, so nothing could check its calls;
+ * that is how it came to be passing two arguments to a three-argument
+ * `add_rnd_square` and throwing before its first frame. The scene is the part
+ * worth checking, so it lives here where a spec can reach it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Seed the demo uses, so two runs of the page produce the same picture. Any
+ * value does; this one is only here to be a written-down constant rather than
+ * a literal in a call.
+ * @type {number}
+ */
+export const MLS_MPM_DEMO_SEED = 1337;
+
+/**
+ * The three coloured squares, in the order the demo drops them.
+ * @type {Array<{center: number[], colour: number}>}
+ */
+const SQUARES = [
+    { center: [0.55, 0.45], colour: 0xED553B },
+    { center: [0.45, 0.65], colour: 0xF2B134 },
+    { center: [0.55, 0.85], colour: 0x168587 },
+];
+
+/**
+ * Populate a solver with the demo's particles.
+ *
+ * @param {import("./MLS_MPM.js").MLS_MPMSolver} solver
+ * @param {function():number} random uniform in [0, 1) — required, so the layout
+ *   is reproducible across runs
+ * @returns {void}
+ */
+export function add_mls_mpm_demo_squares(solver, random) {
+    for (const { center, colour } of SQUARES) {
+        solver.add_rnd_square(center, colour, random);
+    }
+}

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

@@ -1,4 +1,6 @@
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
 import { MLS_MPMSolver } from "./MLS_MPM.js";
+import { MLS_MPM_DEMO_SEED, add_mls_mpm_demo_squares } from "./mls_mpm_demo_scene.js";
 
 const renderEvery = 5;
 const enableTiming = false;
@@ -51,9 +53,7 @@ function step() {
 }
 
 enableTiming && console.time('setup');
-solver.add_rnd_square([0.55, 0.45], 0xED553B);
-solver.add_rnd_square([0.45, 0.65], 0xF2B134);
-solver.add_rnd_square([0.55, 0.85], 0x168587);
+add_mls_mpm_demo_squares(solver, seededRandom(MLS_MPM_DEMO_SEED));
 enableTiming && console.timeEnd('setup');
 
 step();

package/src/engine/physics/narrowphase/narrowphase_step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"narrowphase_step.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/narrowphase_step.js"],"names":[],"mappings":"AAk1CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qDAZW,YAAY,GAAC,MAAM,EAAE,iCAGrB,UAAU,MAAM,CAAC,QACjB,UAAU,MAAM,CAAC,iCAGjB,UAAU,MAAM,CAAC,QACjB,UAAU,MAAM,CAAC,GAEf,MAAM,CA2ClB;AAED;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,EAAE,WAAW,CAAA;CAAC,CAAC,CAAC,QA4LpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uEAJW,MAAM,UACN,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,EAAE,WAAW,CAAA;CAAC,CAAC,UACnD,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,EAAE,WAAW,CAAA;CAAC,CAAC,QA2H7D;4BA/tD2B,oCAAoC"}
+{"version":3,"file":"narrowphase_step.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/narrowphase_step.js"],"names":[],"mappings":"AAg5CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qDAZW,YAAY,GAAC,MAAM,EAAE,iCAGrB,UAAU,MAAM,CAAC,QACjB,UAAU,MAAM,CAAC,iCAGjB,UAAU,MAAM,CAAC,QACjB,UAAU,MAAM,CAAC,GAEf,MAAM,CA2ClB;AAED;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,EAAE,WAAW,CAAA;CAAC,CAAC,CAAC,QA6LpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uEAJW,MAAM,UACN,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,EAAE,WAAW,CAAA;CAAC,CAAC,UACnD,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,EAAE,WAAW,CAAA;CAAC,CAAC,QA2H7D;4BA7xD2B,oCAAoC"}

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

@@ -1,8 +1,9 @@
 import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
 import { Triangle3D } from "../../../core/geom/3d/shape/Triangle3D.js";
 import { body_id_index } from "../body/BodyStorage.js";
+import { ColliderFlags } from "../ecs/ColliderFlags.js";
 import { combine_friction, combine_restitution } from "../contact/combine_material.js";
-import { CONTACT_STRIDE, MAX_CONTACTS_PER_MANIFOLD } from "../contact/ManifoldStore.js";
+import { CONTACT_FLAG_SENSOR, CONTACT_STRIDE, MAX_CONTACTS_PER_MANIFOLD } from "../contact/ManifoldStore.js";
 import { GJK_SEPARATED, gjk_epa_penetration } from "../../../core/geom/3d/gjk/gjk_epa_penetration.js";
 import { reduce_manifold_contacts } from "./reduce_manifold_contacts.js";
 import { mpr } from "../../../core/geom/3d/gjk/mpr.js";
@@ -72,7 +73,7 @@ const capsule_box_multi_result = new Float64Array(CAPSULE_BOX_MAX_CONTACTS * CAP
  *
  * @type {number}
  */
-const CANDIDATE_STRIDE = 13;
+const CANDIDATE_STRIDE = 14;
 
 /**
  * Combined friction / restitution for the collider pair currently being
@@ -85,6 +86,16 @@ const CANDIDATE_STRIDE = 13;
 let g_pair_friction = 0;
 let g_pair_restitution = 0;
 
+/**
+ * Per-contact flags for the collider pair being dispatched — see
+ * {@link CONTACT_FLAG_SENSOR}. Stamped onto every contact the dispatch
+ * appends, for the same reason the materials are: the solver cannot tell which
+ * collider pair produced a contact, and a body's colliders need not agree
+ * about being solid.
+ * @type {number}
+ */
+let g_pair_flags = 0;
+
 /**
  * Maximum number of contacts emitted into the per-pair manifold after the
  * reduction step. Mirrors {@link MAX_CONTACTS_PER_MANIFOLD} in ManifoldStore.
@@ -161,26 +172,63 @@ const prev_claimed = new Uint8Array(MAX_CONTACTS_PER_MANIFOLD);
  */
 const cand_to_prev = new Int32Array(MAX_KEPT);
 
+/**
+ * Candidate capacity a fresh process starts at: enough for a typical compound
+ * pair (4 colliders per body × 4 colliders × 4 contacts). It grows from here.
+ * @type {number}
+ */
+const CANDIDATE_CAPACITY_INITIAL = 64;
+
 /**
  * Per-candidate "already claimed" flags for {@link redetect_pair_geometry}'s
- * 1:1 existing-contact → fresh-candidate matching. Sized to the candidate
- * buffer capacity (64) so it covers any per-pair candidate count. Without it,
+ * 1:1 existing-contact → fresh-candidate matching. Kept the same length as the
+ * candidate buffer so it covers any per-pair candidate count. Without it,
  * several existing contacts that share one triangle's `feature_id` (the
  * box/capsule-triangle paths emit multiple contacts per triangle) would all
  * match the same first candidate, collapsing the manifold to duplicate witness
  * points.
  * @type {Uint8Array}
  */
-const redetect_claimed = new Uint8Array(64);
+let redetect_claimed = new Uint8Array(CANDIDATE_CAPACITY_INITIAL);
 
 /**
  * Per body-pair scratch buffer for candidate contacts produced by the
- * cross-product of A's colliders × B's colliders. Sized generously for
- * typical compound bodies (each collider-pair contributes 1..4 contacts;
- * 64 covers up to 4 colliders per body × 4 colliders × 4 contacts = 64).
+ * cross-product of A's colliders × B's colliders.
+ *
+ * It grows by doubling, the way {@link PairList} and the broadphase's per-leaf
+ * buffer do, because the compound cross-product is not the only thing that
+ * feeds it: the concave path inside a SINGLE `dispatch_pair` enumerates up to
+ * {@link MAX_TRIANGLES_PER_PAIR} triangles and the box / capsule fast-paths
+ * emit up to 4 contacts each, deduped only against contacts sharing both a
+ * normal and a witness — so triangles at different heights or orientations
+ * each contribute a fresh entry. A fixed 64 filled inside the first few per
+ * cent of a rough heightmap's triangle list, and the overflow was a silent
+ * drop of everything after it in enumeration order, so the reduction picked
+ * "the deepest" out of the first sixty-four rather than out of the contacts.
+ * A 65×65 heightmap under an 8 m box dropped 955 contacts and reported the
+ * same penetration wherever the deepest spike was put.
+ *
+ * The high-water mark is kept for the process, which is what a scratch buffer
+ * is for; the triangle cap bounds it.
+ *
  * @type {Float64Array}
  */
-const candidates = new Float64Array(64 * CANDIDATE_STRIDE);
+let candidates = new Float64Array(CANDIDATE_CAPACITY_INITIAL * CANDIDATE_STRIDE);
+
+/**
+ * Double the candidate buffer, preserving what is in it, and resize the
+ * claim flags with it.
+ */
+function grow_candidates() {
+    const capacity = (candidates.length / CANDIDATE_STRIDE) * 2;
+
+    const grown = new Float64Array(capacity * CANDIDATE_STRIDE);
+
+    grown.set(candidates);
+
+    candidates = grown;
+    redetect_claimed = new Uint8Array(capacity);
+}
 
 /**
  * Maximum triangles a concave-side enumerator can produce per pair.
@@ -295,7 +343,7 @@ const scratch_tri_world = new Float64Array(9);
  */
 function append_contact(count, wax, way, waz, wbx, wby, wbz, nx, ny, nz, depth, feature_id) {
     if (count * CANDIDATE_STRIDE >= candidates.length){
-        return count;
+        grow_candidates();
     }
 
     const off = count * CANDIDATE_STRIDE;
@@ -307,6 +355,7 @@ function append_contact(count, wax, way, waz, wbx, wby, wbz, nx, ny, nz, depth,
     candidates[off + 10] = feature_id;
     candidates[off + 11] = g_pair_friction;
     candidates[off + 12] = g_pair_restitution;
+    candidates[off + 13] = g_pair_flags;
 
     return count + 1;
 }
@@ -453,6 +502,19 @@ function dispatch_pair(count, colA, trA, colB, trB) {
         g_pair_restitution = 0;
     }
 
+    // Sensor-ness is per COLLIDER, and the solver has no way to tell which
+    // collider pair a contact came from. A body built as
+    // [trigger volume, solid hull] used to have the whole manifold skipped
+    // because the solver asked its first collider, so everything fell through
+    // the solid hull; built the other way round, the trigger pushed.
+    //
+    // The body-level sensor flag is not here: it is uniform over the body, so
+    // the solver still reads that per pair.
+    const sensor_a = colA.flags !== undefined && (colA.flags & ColliderFlags.IsSensor) !== 0;
+    const sensor_b = colB.flags !== undefined && (colB.flags & ColliderFlags.IsSensor) !== 0;
+
+    g_pair_flags = (sensor_a || sensor_b) ? CONTACT_FLAG_SENSOR : 0;
+
     // isSphereShape3D covers both UnitSphereShape3D (fixed radius 1) and
     // SphereShape3D (arbitrary radius). Both expose `radius`.
     const isSphereA = shapeA.isSphereShape3D === true;
@@ -1624,7 +1686,8 @@ export function narrowphase_step(pair_list, manifolds, lists) {
                 candidates[off + 6], candidates[off + 7], candidates[off + 8],
                 candidates[off + 9],
                 candidates[off + 10],
-                candidates[off + 11], candidates[off + 12]
+                candidates[off + 11], candidates[off + 12],
+                candidates[off + 13]
             );
             const prev_j = cand_to_prev[k];
             if (prev_j !== -1) {

package/src/engine/physics/queries/overlap_shape.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW,MAAM,EAAE,GAAC,YAAY,YAErB,MAAM,EAAE,GAAC,YAAY,UAErB,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,WACN,CAAC,MAAM,EAAC,MAAM,EAAE,QAAQ,UAAS,KAAG,OAAO,GAEzC,MAAM,CAmHlB"}
+{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AAiEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW,MAAM,EAAE,GAAC,YAAY,YAErB,MAAM,EAAE,GAAC,YAAY,UAErB,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,WACN,CAAC,MAAM,EAAC,MAAM,EAAE,QAAQ,UAAS,KAAG,OAAO,GAEzC,MAAM,CA+IlB"}