@woosh/meep-engine 2.140.0 → 2.142.0

package/src/engine/physics/ecs/PhysicsSystem.d.ts

@@ -157,6 +157,27 @@ export class PhysicsSystem extends System<any, any, any, any, any> {
         entity: number;
         bvhNode: number;
     }>>;
+    /**
+     * Live {@link Joint} (6-DOF constraint) instances, in a sparse array
+     * indexed by joint id. Solved alongside contacts inside the TGS
+     * substep loop. Holes (unlinked joints) are `undefined`.
+     * @type {Joint[]}
+     */
+    __joints: Joint[];
+    /**
+     * Lowest free index in {@link __joints} for slot reuse on link.
+     * @private
+     * @type {number}
+     */
+    private __joint_free;
+    /**
+     * Velocity iterations per substep for the joint solver. Joints (and
+     * especially joint chains) want a few more iterations than contacts to
+     * propagate impulses along the chain; cheap because joints are far
+     * fewer than contacts.
+     * @type {number}
+     */
+    jointIterations: number;
     /**
      * Per-body pseudo-velocity for the Catto split-impulse position
      * pass (TGS Phase 1). Flat layout, 6 doubles per body slot index:
@@ -305,6 +326,23 @@ export class PhysicsSystem extends System<any, any, any, any, any> {
      * @returns {number} body index or -1
      */
     private __find_body_index_by_entity;
+    /**
+     * Register a {@link Joint} (6-DOF constraint). Resolves the joint's
+     * entities to packed body ids and adds it to the active set, where it is
+     * solved alongside contacts in the TGS substep loop. Body A must be a
+     * linked body; body B is either a linked body or {@link JOINT_WORLD}
+     * (anchoring A to a fixed world point — `localAnchorB` is then a world
+     * coordinate).
+     *
+     * @param {Joint} joint
+     */
+    link_joint(joint: Joint): void;
+    /**
+     * Remove a previously {@link link_joint}'d joint from the active set.
+     * Idempotent.
+     * @param {Joint} joint
+     */
+    unlink_joint(joint: Joint): void;
     /**
      * Resolve a packed body id to its entity, or `-1` if the id is stale.
      * @param {number} packed_body_id
@@ -567,6 +605,20 @@ export class PhysicsSystem extends System<any, any, any, any, any> {
      * @private
      */
     private __wake_pairs;
+    /**
+     * Wake propagation across joints: if a joint connects an awake body to a
+     * sleeping one, wake the sleeper so the constraint stays coupled (a joint
+     * with one body asleep and one awake would otherwise be skipped by the
+     * solver, letting the awake side drift). A common trigger is a
+     * kinematic/motor-driven body pulling on a sleeping chain.
+     *
+     * Bodies that slept together as one island share a sleep group, so the
+     * usual atomic wake already revives the whole chain when any member is
+     * hit; this catches the cases that atomic wake doesn't (joint spanning
+     * separate groups, kinematic driver).
+     * @private
+     */
+    private __wake_joints;
     /**
      * Per-island atomic sleep test. Walks each island once and applies the
      * decision uniformly across all members:

package/src/engine/physics/ecs/PhysicsSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PhysicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsSystem.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"PhysicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsSystem.js"],"names":[],"mappings":"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"}

package/src/engine/physics/ecs/PhysicsSystem.js

@@ -25,11 +25,14 @@ import { returnTrue } from "../../../core/function/returnTrue.js";
 import {
     prepare_contacts,
     refresh_contacts,
+    redetect_concave_contacts,
     warm_start_contacts,
     solve_velocity,
     apply_restitution,
     solve_position,
 } from "../solver/solve_contacts.js";
+import { solve_joints } from "../constraint/solve_constraints.js";
+import { JOINT_WORLD, JOINT_UNALLOCATED } from "./Joint.js";
 import { world_inverse_inertia_apply } from "../inertia/world_inverse_inertia.js";
 import { PhysicsEvents } from "./PhysicsEvents.js";
 
@@ -248,6 +251,30 @@ export class PhysicsSystem extends System {
          */
         this.__body_collider_lists = [];
 
+        /**
+         * Live {@link Joint} (6-DOF constraint) instances, in a sparse array
+         * indexed by joint id. Solved alongside contacts inside the TGS
+         * substep loop. Holes (unlinked joints) are `undefined`.
+         * @type {Joint[]}
+         */
+        this.__joints = [];
+
+        /**
+         * Lowest free index in {@link __joints} for slot reuse on link.
+         * @private
+         * @type {number}
+         */
+        this.__joint_free = [];
+
+        /**
+         * Velocity iterations per substep for the joint solver. Joints (and
+         * especially joint chains) want a few more iterations than contacts to
+         * propagate impulses along the chain; cheap because joints are far
+         * fewer than contacts.
+         * @type {number}
+         */
+        this.jointIterations = 8;
+
         /**
          * Per-body pseudo-velocity for the Catto split-impulse position
          * pass (TGS Phase 1). Flat layout, 6 doubles per body slot index:
@@ -570,6 +597,53 @@ export class PhysicsSystem extends System {
         return -1;
     }
 
+    /**
+     * Register a {@link Joint} (6-DOF constraint). Resolves the joint's
+     * entities to packed body ids and adds it to the active set, where it is
+     * solved alongside contacts in the TGS substep loop. Body A must be a
+     * linked body; body B is either a linked body or {@link JOINT_WORLD}
+     * (anchoring A to a fixed world point — `localAnchorB` is then a world
+     * coordinate).
+     *
+     * @param {Joint} joint
+     */
+    link_joint(joint) {
+        const idxA = this.__find_body_index_by_entity(joint.entityA);
+        assert.notEqual(idxA, -1, `link_joint: no body for entityA ${joint.entityA}`);
+        joint._bodyIdA = this.__bodies[idxA]._bodyId;
+
+        if (joint.entityB === JOINT_WORLD) {
+            joint._bodyIdB = JOINT_WORLD;
+        } else {
+            const idxB = this.__find_body_index_by_entity(joint.entityB);
+            assert.notEqual(idxB, -1, `link_joint: no body for entityB ${joint.entityB}`);
+            joint._bodyIdB = this.__bodies[idxB]._bodyId;
+        }
+
+        // Reuse a freed slot if available so joint ids stay dense-ish.
+        let id;
+        if (this.__joint_free.length > 0) {
+            id = this.__joint_free.pop();
+        } else {
+            id = this.__joints.length;
+        }
+        joint._jointId = id;
+        this.__joints[id] = joint;
+    }
+
+    /**
+     * Remove a previously {@link link_joint}'d joint from the active set.
+     * Idempotent.
+     * @param {Joint} joint
+     */
+    unlink_joint(joint) {
+        const id = joint._jointId;
+        if (id === JOINT_UNALLOCATED || this.__joints[id] !== joint) return;
+        this.__joints[id] = undefined;
+        this.__joint_free.push(id);
+        joint._jointId = JOINT_UNALLOCATED;
+    }
+
     /**
      * Resolve a packed body id to its entity, or `-1` if the id is stale.
      * @param {number} packed_body_id
@@ -990,6 +1064,40 @@ export class PhysicsSystem extends System {
         }
     }
 
+    /**
+     * Wake propagation across joints: if a joint connects an awake body to a
+     * sleeping one, wake the sleeper so the constraint stays coupled (a joint
+     * with one body asleep and one awake would otherwise be skipped by the
+     * solver, letting the awake side drift). A common trigger is a
+     * kinematic/motor-driven body pulling on a sleeping chain.
+     *
+     * Bodies that slept together as one island share a sleep group, so the
+     * usual atomic wake already revives the whole chain when any member is
+     * hit; this catches the cases that atomic wake doesn't (joint spanning
+     * separate groups, kinematic driver).
+     * @private
+     */
+    __wake_joints() {
+        const joints = this.__joints;
+        const n = joints.length;
+        if (n === 0) return;
+        const bodies = this.__bodies;
+        const storage = this.storage;
+        for (let i = 0; i < n; i++) {
+            const joint = joints[i];
+            if (joint === undefined || joint === null) continue;
+            if (joint._bodyIdB === JOINT_WORLD) continue;
+            if (!storage.is_valid(joint._bodyIdA) || !storage.is_valid(joint._bodyIdB)) continue;
+            const a = bodies[body_id_index(joint._bodyIdA)];
+            const b = bodies[body_id_index(joint._bodyIdB)];
+            if (a === undefined || b === undefined) continue;
+            const aSleep = a.sleepState === SleepState.Sleeping;
+            const bSleep = b.sleepState === SleepState.Sleeping;
+            if (aSleep === bSleep) continue; // both awake or both asleep — leave as is
+            if (aSleep) this.__wake_body(a); else this.__wake_body(b);
+        }
+    }
+
     /**
      * Per-island atomic sleep test. Walks each island once and applies the
      * decision uniformly across all members:
@@ -1203,8 +1311,10 @@ export class PhysicsSystem extends System {
             this.__pair_filter_bound,
         );
 
-        // Stage 4: wake propagation.
+        // Stage 4: wake propagation — through broadphase pairs, then through
+        // joints (a joint must not have one body awake and one asleep).
         this.__wake_pairs();
+        this.__wake_joints();
 
         // Stage 5: narrowphase — once per outer step. The substep loop below
         // re-derives each contact's penetration analytically from the moved
@@ -1213,7 +1323,7 @@ export class PhysicsSystem extends System {
 
         // Stage 6: partition awake bodies + touched contacts into islands.
         // Consumed by the solver (flattened contact list) and the sleep test.
-        this.islands.build(this.storage, this.manifolds, this.__bodies, this.__body_collider_lists);
+        this.islands.build(this.storage, this.manifolds, this.__bodies, this.__body_collider_lists, this.__joints);
 
         // Stage 7: TGS substep loop.
         //
@@ -1249,12 +1359,24 @@ export class PhysicsSystem extends System {
                 integrate_velocity_gravity(this.__bodies[idx], this.__transforms[idx], gx, gy, gz, h);
             }
 
-            // Re-derive contact geometry at the current poses, replay the
-            // per-substep warm-start, then solve velocity.
+            // Re-derive contact geometry at the current poses: concave pairs
+            // re-run narrowphase (fresh feature/normal as the body rocks),
+            // convex pairs rotate frozen anchors analytically. Then replay
+            // the per-substep warm-start and solve velocity.
+            redetect_concave_contacts(this.manifolds, this);
             refresh_contacts(this.manifolds, this);
             warm_start_contacts(this.manifolds, this);
             solve_velocity(this.manifolds, this, this.velocityIterations);
 
+            // Joints share the substep: warm-start + velocity-solve the 6-DOF
+            // constraints on real velocity, coupled with the contacts above
+            // (a body touched by both sees one substep of Gauss-Seidel across
+            // contacts then joints). Position correction for locked DOFs is a
+            // SPOOK bias inside this solve, so no separate joint position pass.
+            if (this.__joints.length > 0) {
+                solve_joints(this.__joints, this, h, this.jointIterations);
+            }
+
             // Position correction writes pseudo-velocity (zeroed first so it
             // is a fresh per-substep correction), folded into the pose by the
             // position integrate and then discarded.

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

@@ -45,17 +45,21 @@ export class FluidField {
      * Per-cell pre-baked neighbourhood mask consumed by the pressure SOR loop.
      * One byte per cell encoding which of the 6 cardinal neighbours are fluid:
      *
-     *     bit 0 (= 1)  : -x neighbour is fluid (in-bounds AND non-solid)
-     *     bit 1 (= 2)  : +x neighbour is fluid
-     *     bit 2 (= 4)  : -y neighbour is fluid
-     *     bit 3 (= 8)  : +y neighbour is fluid
-     *     bit 4 (= 16) : -z neighbour is fluid
-     *     bit 5 (= 32) : +z neighbour is fluid
+     *     bit 0 (= 1)   : -x neighbour is fluid (in-bounds AND non-solid)
+     *     bit 1 (= 2)   : +x neighbour is fluid
+     *     bit 2 (= 4)   : -y neighbour is fluid
+     *     bit 3 (= 8)   : +y neighbour is fluid
+     *     bit 4 (= 16)  : -z neighbour is fluid
+     *     bit 5 (= 32)  : +z neighbour is fluid
+     *     bit 7 (= 128) : this cell is itself solid
      *
-     * Solid cells themselves are encoded as `mask = 0` so the SOR loop's
-     * `if (mask === 0) continue` skip handles both "this cell is solid" and
-     * "this fluid cell is isolated" with a single comparison instead of one
-     * solid-self-check plus six solid-neighbour-checks plus six boundary checks.
+     * A solid cell encodes as `128` (bit 7 set, neighbour bits clear) and an
+     * isolated fluid cell as `0`, so the SOR / PCG loops' `if ((mask & 63) === 0)
+     * continue` skip handles both "this cell is solid" and "this fluid cell is
+     * isolated" with a single comparison instead of one solid-self-check plus six
+     * solid-neighbour-checks plus six boundary checks. Bit 7 additionally lets
+     * {@link v3_grid_subtract_pressure_gradient} zero solid-cell velocity without
+     * consulting the {@link solid} array.
      *
      * Computed once by {@link recomputeSolidNeighbourMask} after every solid-mask
      * mutation. The simulator runs that recompute at the top of every project()

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":"AASA;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,sBAFU,UAAU,GAAC,IAAI,CAEG;IAE5B;;;;;;;;;;;;;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,cAmBC;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;;;;;;;;;OASG;IACH,oCASC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,eAJW,MAAM,WACN,MAAM,WACN,MAAM,QAyChB;IAED;;;;OAIG;IACH,cASC;;CACJ"}
+{"version":3,"file":"FluidField.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidField.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,sBAFU,UAAU,GAAC,IAAI,CAEG;IAE5B;;;;;;;;;;;;;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,cAmBC;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;;;;;;;;;OASG;IACH,oCASC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,eAJW,MAAM,WACN,MAAM,WACN,MAAM,QAyChB;IAED;;;;OAIG;IACH,cASC;;CACJ"}

package/src/engine/physics/fluid/FluidField.js

@@ -65,17 +65,21 @@ export class FluidField {
      * Per-cell pre-baked neighbourhood mask consumed by the pressure SOR loop.
      * One byte per cell encoding which of the 6 cardinal neighbours are fluid:
      *
-     *     bit 0 (= 1)  : -x neighbour is fluid (in-bounds AND non-solid)
-     *     bit 1 (= 2)  : +x neighbour is fluid
-     *     bit 2 (= 4)  : -y neighbour is fluid
-     *     bit 3 (= 8)  : +y neighbour is fluid
-     *     bit 4 (= 16) : -z neighbour is fluid
-     *     bit 5 (= 32) : +z neighbour is fluid
+     *     bit 0 (= 1)   : -x neighbour is fluid (in-bounds AND non-solid)
+     *     bit 1 (= 2)   : +x neighbour is fluid
+     *     bit 2 (= 4)   : -y neighbour is fluid
+     *     bit 3 (= 8)   : +y neighbour is fluid
+     *     bit 4 (= 16)  : -z neighbour is fluid
+     *     bit 5 (= 32)  : +z neighbour is fluid
+     *     bit 7 (= 128) : this cell is itself solid
      *
-     * Solid cells themselves are encoded as `mask = 0` so the SOR loop's
-     * `if (mask === 0) continue` skip handles both "this cell is solid" and
-     * "this fluid cell is isolated" with a single comparison instead of one
-     * solid-self-check plus six solid-neighbour-checks plus six boundary checks.
+     * A solid cell encodes as `128` (bit 7 set, neighbour bits clear) and an
+     * isolated fluid cell as `0`, so the SOR / PCG loops' `if ((mask & 63) === 0)
+     * continue` skip handles both "this cell is solid" and "this fluid cell is
+     * isolated" with a single comparison instead of one solid-self-check plus six
+     * solid-neighbour-checks plus six boundary checks. Bit 7 additionally lets
+     * {@link v3_grid_subtract_pressure_gradient} zero solid-cell velocity without
+     * consulting the {@link solid} array.
      *
      * Computed once by {@link recomputeSolidNeighbourMask} after every solid-mask
      * mutation. The simulator runs that recompute at the top of every project()

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

@@ -1 +1 @@
-{"version":3,"file":"FluidSimulator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidSimulator.js"],"names":[],"mappings":";;;;;;;;;;;;;;;6BAyBU,MAAM;;;;;AAOhB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;;;;;;;;;GASG;AACH,wCAFU,MAAM,CAE2B;AAE3C;IAEI;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,+BAFU,MAAM,CAEkB;IAElC;;;;;OAKG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,6BAFU,MAAM,CAEgB;IAEhC;;;;;;;;;;;;;;;OAeG;IACH,iBAFU,MAAM,CAEqB;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,0BAFU,OAAO,CAEe;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,0BAFU,MAAM,CAEgB;IA+EhC;;;;;;;;;;;;OAYG;IACH,iCALW,MAAM,SACN,MAAM,SACN,MAAM,GACL,MAAM,CAUjB;IAED;;;;;;OAMG;IACH,iCAmDC;IAqBD;;;;;;;;;;;;;OAaG;IACH,oCAVW,MAAM,aAEN,uBAAuB,iBACvB,YAAY,GAAC,MAAM,EAAE,QAyF/B;;CACJ"}
+{"version":3,"file":"FluidSimulator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidSimulator.js"],"names":[],"mappings":";;;;;;;;;;;;;;;6BAyBU,MAAM;;;;;AAOhB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;;;;;;;;;GASG;AACH,wCAFU,MAAM,CAE2B;AAE3C;IAEI;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,+BAFU,MAAM,CAEkB;IAElC;;;;;OAKG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,6BAFU,MAAM,CAEgB;IAEhC;;;;;;;;;;;;;;;OAeG;IACH,iBAFU,MAAM,CAEqB;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,0BAFU,OAAO,CAEe;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,0BAFU,MAAM,CAEgB;IA+EhC;;;;;;;;;;;;OAYG;IACH,iCALW,MAAM,SACN,MAAM,SACN,MAAM,GACL,MAAM,CAUjB;IAED;;;;;;OAMG;IACH,iCAkDC;IAqBD;;;;;;;;;;;;;OAaG;IACH,oCAVW,MAAM,aAEN,uBAAuB,iBACvB,YAAY,GAAC,MAAM,EAAE,QAyF/B;;CACJ"}

package/src/engine/physics/fluid/FluidSimulator.js

@@ -332,7 +332,6 @@ export class FluidSimulator {
             field.velocity_x, field.velocity_y, field.velocity_z,
             field.pressure,
             res[0], res[1], res[2],
-            solid,
             field.solid_neighbour_mask
         );
     }

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

@@ -4,18 +4,25 @@
  * {@link v3_grid_solve_pressure}, which uses the mask to skip boundary checks
  * and solid-neighbour checks entirely.
  *
- * Encoding (one byte per cell, low 6 bits):
+ * Encoding (one byte per cell):
  *
- *     bit 0 (= 1)  : -x neighbour is fluid
- *     bit 1 (= 2)  : +x neighbour is fluid
- *     bit 2 (= 4)  : -y neighbour is fluid
- *     bit 3 (= 8)  : +y neighbour is fluid
- *     bit 4 (= 16) : -z neighbour is fluid
- *     bit 5 (= 32) : +z neighbour is fluid
+ *     bit 0 (= 1)   : -x neighbour is fluid
+ *     bit 1 (= 2)   : +x neighbour is fluid
+ *     bit 2 (= 4)   : -y neighbour is fluid
+ *     bit 3 (= 8)   : +y neighbour is fluid
+ *     bit 4 (= 16)  : -z neighbour is fluid
+ *     bit 5 (= 32)  : +z neighbour is fluid
+ *     bit 7 (= 128) : this cell is itself solid
  *
- * Solid cells themselves are encoded as `mask = 0` (not "their own neighbours
- * are fluid") so the SOR loop's `mask === 0 → skip` branch covers both
- * "self-solid" and "fluid but no fluid neighbours" with one comparison.
+ * The low 6 bits are the fluid-neighbour set; bit 7 flags the cell as solid.
+ * A solid cell encodes as exactly `128` — bit 7 set, every neighbour bit clear
+ * — and an isolated fluid cell (no fluid neighbours) as `0`. Both therefore
+ * satisfy `(mask & 63) === 0`, so the SOR / PCG loops' "no fluid neighbours →
+ * skip" branch is a single `(mask & 63) === 0` comparison that covers
+ * "self-solid" and "fluid but no fluid neighbours" alike. The dedicated bit 7
+ * additionally lets {@link v3_grid_subtract_pressure_gradient} tell solid cells
+ * (zero the velocity) apart from isolated fluid (leave it) without the original
+ * `solid` array.
  *
  * O(N) — one byte-write per cell, up to six byte-reads per cell. The output
  * fully replaces whatever was in `mask` before; no need to zero-init.

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_compute_solid_neighbour_mask.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_compute_solid_neighbour_mask.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,2DANW,UAAU,SACV,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,QAqChB"}
+{"version":3,"file":"v3_grid_compute_solid_neighbour_mask.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_compute_solid_neighbour_mask.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,2DANW,UAAU,SACV,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,QAqChB"}

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

@@ -6,18 +6,25 @@ import { assert } from "../../../../core/assert.js";
  * {@link v3_grid_solve_pressure}, which uses the mask to skip boundary checks
  * and solid-neighbour checks entirely.
  *
- * Encoding (one byte per cell, low 6 bits):
+ * Encoding (one byte per cell):
  *
- *     bit 0 (= 1)  : -x neighbour is fluid
- *     bit 1 (= 2)  : +x neighbour is fluid
- *     bit 2 (= 4)  : -y neighbour is fluid
- *     bit 3 (= 8)  : +y neighbour is fluid
- *     bit 4 (= 16) : -z neighbour is fluid
- *     bit 5 (= 32) : +z neighbour is fluid
+ *     bit 0 (= 1)   : -x neighbour is fluid
+ *     bit 1 (= 2)   : +x neighbour is fluid
+ *     bit 2 (= 4)   : -y neighbour is fluid
+ *     bit 3 (= 8)   : +y neighbour is fluid
+ *     bit 4 (= 16)  : -z neighbour is fluid
+ *     bit 5 (= 32)  : +z neighbour is fluid
+ *     bit 7 (= 128) : this cell is itself solid
  *
- * Solid cells themselves are encoded as `mask = 0` (not "their own neighbours
- * are fluid") so the SOR loop's `mask === 0 → skip` branch covers both
- * "self-solid" and "fluid but no fluid neighbours" with one comparison.
+ * The low 6 bits are the fluid-neighbour set; bit 7 flags the cell as solid.
+ * A solid cell encodes as exactly `128` — bit 7 set, every neighbour bit clear
+ * — and an isolated fluid cell (no fluid neighbours) as `0`. Both therefore
+ * satisfy `(mask & 63) === 0`, so the SOR / PCG loops' "no fluid neighbours →
+ * skip" branch is a single `(mask & 63) === 0` comparison that covers
+ * "self-solid" and "fluid but no fluid neighbours" alike. The dedicated bit 7
+ * additionally lets {@link v3_grid_subtract_pressure_gradient} tell solid cells
+ * (zero the velocity) apart from isolated fluid (leave it) without the original
+ * `solid` array.
  *
  * O(N) — one byte-write per cell, up to six byte-reads per cell. The output
  * fully replaces whatever was in `mask` before; no need to zero-init.
@@ -49,7 +56,7 @@ export function v3_grid_compute_solid_neighbour_mask(mask, solid, res_x, res_y,
             for (let x = 0; x < res_x; x++) {
                 const c = y_off + x;
                 if (solid[c] !== 0) {
-                    mask[c] = 0;
+                    mask[c] = 128; // bit 7 = this cell is solid; neighbour bits stay clear
                     continue;
                 }
                 let m = 0;

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

@@ -11,17 +11,20 @@
  * a Uint8Array allocated and populated by {@link FluidField} via
  * {@link FluidField.recomputeSolidNeighbourMask}. The encoding is:
  *
- *     bit 0 (= 1)  : -x neighbour is fluid
- *     bit 1 (= 2)  : +x neighbour is fluid
- *     bit 2 (= 4)  : -y neighbour is fluid
- *     bit 3 (= 8)  : +y neighbour is fluid
- *     bit 4 (= 16) : -z neighbour is fluid
- *     bit 5 (= 32) : +z neighbour is fluid
+ *     bit 0 (= 1)   : -x neighbour is fluid
+ *     bit 1 (= 2)   : +x neighbour is fluid
+ *     bit 2 (= 4)   : -y neighbour is fluid
+ *     bit 3 (= 8)   : +y neighbour is fluid
+ *     bit 4 (= 16)  : -z neighbour is fluid
+ *     bit 5 (= 32)  : +z neighbour is fluid
+ *     bit 7 (= 128) : this cell is itself solid (consumed by
+ *                     {@link v3_grid_subtract_pressure_gradient}, ignored here)
  *
- * Solid cells encode as `mask = 0`, so the inner loop's `mask === 0 ? skip` covers
- * both self-solid AND fluid-with-no-fluid-neighbours in one comparison. This
- * eliminates six boundary checks plus six solid-neighbour checks per cell per
- * iteration, replacing them with a single mask read and six bit-tests on a
+ * The low 6 bits are the fluid-neighbour set. A solid cell encodes as `128` and
+ * an isolated fluid cell as `0`, so the inner loop's `(mask & 63) === 0 ? skip`
+ * covers both self-solid AND fluid-with-no-fluid-neighbours in one comparison.
+ * This eliminates six boundary checks plus six solid-neighbour checks per cell
+ * per iteration, replacing them with a single mask read and six bit-tests on a
  * register-resident value. Boundary handling (cells at x=0, x=last, etc.) is
  * implicit — the recompute step writes 0 into the boundary-facing bit, so the
  * SOR loop never reads out-of-range memory.

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_solve_pressure.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,iDAdW,YAAY,eAAa,cAEzB,YAAY,eAAa,SAEzB,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,MAAM,kBAEN,UAAU,QA+DpB"}
+{"version":3,"file":"v3_grid_solve_pressure.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,iDAdW,YAAY,eAAa,cAEzB,YAAY,eAAa,SAEzB,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,MAAM,kBAEN,UAAU,QAiEpB"}

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

@@ -30,17 +30,20 @@ const POPCOUNT_6 = (function () {
  * a Uint8Array allocated and populated by {@link FluidField} via
  * {@link FluidField.recomputeSolidNeighbourMask}. The encoding is:
  *
- *     bit 0 (= 1)  : -x neighbour is fluid
- *     bit 1 (= 2)  : +x neighbour is fluid
- *     bit 2 (= 4)  : -y neighbour is fluid
- *     bit 3 (= 8)  : +y neighbour is fluid
- *     bit 4 (= 16) : -z neighbour is fluid
- *     bit 5 (= 32) : +z neighbour is fluid
+ *     bit 0 (= 1)   : -x neighbour is fluid
+ *     bit 1 (= 2)   : +x neighbour is fluid
+ *     bit 2 (= 4)   : -y neighbour is fluid
+ *     bit 3 (= 8)   : +y neighbour is fluid
+ *     bit 4 (= 16)  : -z neighbour is fluid
+ *     bit 5 (= 32)  : +z neighbour is fluid
+ *     bit 7 (= 128) : this cell is itself solid (consumed by
+ *                     {@link v3_grid_subtract_pressure_gradient}, ignored here)
  *
- * Solid cells encode as `mask = 0`, so the inner loop's `mask === 0 ? skip` covers
- * both self-solid AND fluid-with-no-fluid-neighbours in one comparison. This
- * eliminates six boundary checks plus six solid-neighbour checks per cell per
- * iteration, replacing them with a single mask read and six bit-tests on a
+ * The low 6 bits are the fluid-neighbour set. A solid cell encodes as `128` and
+ * an isolated fluid cell as `0`, so the inner loop's `(mask & 63) === 0 ? skip`
+ * covers both self-solid AND fluid-with-no-fluid-neighbours in one comparison.
+ * This eliminates six boundary checks plus six solid-neighbour checks per cell
+ * per iteration, replacing them with a single mask read and six bit-tests on a
  * register-resident value. Boundary handling (cells at x=0, x=last, etc.) is
  * implicit — the recompute step writes 0 into the boundary-facing bit, so the
  * SOR loop never reads out-of-range memory.
@@ -101,9 +104,11 @@ export function v3_grid_solve_pressure(pressure, divergence, res_x, res_y, res_z
                         const c = z_off + y_off + x;
 
                         const mask = neighbour_mask[c];
-                        if (mask === 0) {
-                            // Solid cell OR isolated fluid with no fluid neighbours.
-                            // Either way, no degrees of freedom — skip.
+                        if ((mask & 63) === 0) {
+                            // No fluid neighbours: solid cell (bit 7 set) OR isolated
+                            // fluid. Either way, no degrees of freedom — skip. Cells
+                            // that reach past here have bit 7 clear, so `mask` indexes
+                            // POPCOUNT_6 (sized 64) in range.
                             continue;
                         }
 

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

@@ -69,9 +69,10 @@
  * the hot path that prevents MIC-PCG from parallelizing onto a GPU without
  * substantial reformulation. On single-thread JS that's not a concern.
  *
- * Solid cells (mask = 0) are excluded from the system: their pressure stays at
- * whatever it was (typically 0), their entries in r, z, s, As stay 0, and they
- * contribute nothing to dot products.
+ * Cells with no fluid neighbours — solid cells (mask bit 7 set) and isolated
+ * fluid (mask = 0), both identified by `(mask & 63) === 0` — are excluded from
+ * the system: their pressure stays at whatever it was (typically 0), their
+ * entries in r, z, s, As stay 0, and they contribute nothing to dot products.
  *
  * @param {Float32Array|Float16Array} pressure  Mutated in place. Pre-fill with 0
  *     or with the previous step's solution to warm-start.

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_solve_pressure_pcg.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure_pcg.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,qDAhBW,YAAY,eAAa,cAEzB,YAAY,eAAa,SACzB,MAAM,SACN,MAAM,SACN,MAAM,kBACN,MAAM,kBAEN,UAAU,aACV,YAAY,aACZ,YAAY,aACZ,YAAY,cACZ,YAAY,kBACZ,YAAY,QAuNtB"}
+{"version":3,"file":"v3_grid_solve_pressure_pcg.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure_pcg.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AACH,qDAhBW,YAAY,eAAa,cAEzB,YAAY,eAAa,SACzB,MAAM,SACN,MAAM,SACN,MAAM,kBACN,MAAM,kBAEN,UAAU,aACV,YAAY,aACZ,YAAY,aACZ,YAAY,cACZ,YAAY,kBACZ,YAAY,QA0NtB"}