@woosh/meep-engine 2.140.0 → 2.141.0

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

@@ -0,0 +1,234 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import { DofMode } from "../constraint/DofMode.js";
+
+/**
+ * Sentinel for {@link Joint#_jointId} before the joint is linked into a
+ * {@link PhysicsSystem}.
+ * @type {number}
+ */
+export const JOINT_UNALLOCATED = -1;
+
+/**
+ * `entityB` value meaning "the world" — body A is constrained to a fixed
+ * world anchor rather than to a second body.
+ * @type {number}
+ */
+export const JOINT_WORLD = -1;
+
+/**
+ * A configurable 6-DOF constraint between two bodies (or a body and the
+ * world). Connects body A's anchor frame to body B's; each of the 6 relative
+ * degrees of freedom (3 linear, 3 angular) is independently
+ * locked / free / limited / springy / motorised ({@link DofMode}). One
+ * constraint type expresses the whole joint taxonomy — see DofMode.
+ *
+ * The default configuration is a **ball-socket** (point-to-point): the three
+ * linear DOFs LOCKED (the two anchor points are held coincident), the three
+ * angular DOFs FREE. That alone gives chains, ropes, and pendulums.
+ *
+ * Anchors live in body-local frames. When `entityB === JOINT_WORLD`,
+ * `localAnchorB` is interpreted as a fixed **world** point instead of a
+ * local anchor on a second body.
+ *
+ * Solver state ({@link dofImpulse}, the `_*` fields) is owned by the
+ * PhysicsSystem; user code must not write it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Joint {
+
+    /**
+     * Entity owning body A (the constraint's first body — always a real body).
+     * @type {number}
+     */
+    entityA = -1;
+
+    /**
+     * Entity owning body B, or {@link JOINT_WORLD} to anchor A to the world.
+     * @type {number}
+     */
+    entityB = JOINT_WORLD;
+
+    /**
+     * Anchor point on body A, in A's local frame.
+     * @readonly
+     * @type {Vector3}
+     */
+    localAnchorA = new Vector3(0, 0, 0);
+
+    /**
+     * Anchor point on body B in B's local frame — or, when
+     * `entityB === JOINT_WORLD`, a fixed world-space anchor point.
+     * @readonly
+     * @type {Vector3}
+     */
+    localAnchorB = new Vector3(0, 0, 0);
+
+    /**
+     * Orientation of the joint's reference frame on body A, in A's local
+     * space (a unit quaternion; identity = the joint frame is the body
+     * frame). The 3 linear and 3 angular DOFs are expressed in this frame:
+     * locked/limited/etc. axes are the frame's axes, not world axes. For a
+     * hinge, the free angular axis is one of these frame axes — orient the
+     * frame so that axis is the hinge axis.
+     * @readonly
+     * @type {Quaternion}
+     */
+    localBasisA = new Quaternion();
+
+    /**
+     * Orientation of the joint's reference frame on body B, in B's local
+     * space. At rest a fully-locked joint holds frame B aligned to frame A.
+     * When `entityB === JOINT_WORLD`, the world frame is treated as identity
+     * (angular locks hold A's frame to world axes).
+     * @readonly
+     * @type {Quaternion}
+     */
+    localBasisB = new Quaternion();
+
+    /**
+     * Per-DOF mode, 6 entries: `[lin x, lin y, lin z, ang x, ang y, ang z]`.
+     * Default = ball-socket (linear locked, angular free).
+     * @readonly
+     * @type {Uint8Array}
+     */
+    dofMode = Uint8Array.from([
+        DofMode.LOCKED, DofMode.LOCKED, DofMode.LOCKED,
+        DofMode.FREE, DofMode.FREE, DofMode.FREE,
+    ]);
+
+    /**
+     * Lower / upper bounds per DOF, used by {@link DofMode.LIMITED}. Linear in
+     * metres, angular in radians. (Reserved — consumed once the LIMITED mode
+     * lands.)
+     * @readonly
+     * @type {Float64Array}
+     */
+    dofLowerLimit = new Float64Array(6);
+    /** @readonly @type {Float64Array} */
+    dofUpperLimit = new Float64Array(6);
+
+    /**
+     * Spring stiffness / damping per DOF, used by {@link DofMode.SPRING}.
+     * (Reserved — consumed once the SPRING mode lands.)
+     * @readonly
+     * @type {Float64Array}
+     */
+    dofStiffness = new Float64Array(6);
+    /** @readonly @type {Float64Array} */
+    dofDamping = new Float64Array(6);
+
+    /**
+     * Motor target velocity / max force per DOF, used by
+     * {@link DofMode.MOTOR}. (Reserved — consumed once the MOTOR mode lands.)
+     * @readonly
+     * @type {Float64Array}
+     */
+    dofMotorTargetVelocity = new Float64Array(6);
+    /** @readonly @type {Float64Array} */
+    dofMotorMaxForce = new Float64Array(6);
+
+    /**
+     * Accumulated constraint impulse per DOF — warm-start state carried across
+     * frames. System-owned.
+     * @readonly
+     * @type {Float64Array}
+     */
+    dofImpulse = new Float64Array(6);
+
+    /**
+     * Resolved packed body id of A, set at link time. System-private.
+     * @type {number}
+     */
+    _bodyIdA = -1;
+    /**
+     * Resolved packed body id of B, or {@link JOINT_WORLD}. System-private.
+     * @type {number}
+     */
+    _bodyIdB = JOINT_WORLD;
+    /**
+     * Packed joint handle assigned at link. System-private.
+     * @type {number}
+     */
+    _jointId = JOINT_UNALLOCATED;
+
+    /**
+     * Configure this joint as a ball-socket (point-to-point) between two
+     * anchors. Linear DOFs locked, angular free — the default, provided as a
+     * named helper for clarity at call sites.
+     * @returns {Joint} this
+     */
+    asBallSocket() {
+        this.dofMode[0] = DofMode.LOCKED;
+        this.dofMode[1] = DofMode.LOCKED;
+        this.dofMode[2] = DofMode.LOCKED;
+        this.dofMode[3] = DofMode.FREE;
+        this.dofMode[4] = DofMode.FREE;
+        this.dofMode[5] = DofMode.FREE;
+        return this;
+    }
+
+    /**
+     * Configure as a weld (fixed) joint: all 6 DOFs locked, holding the two
+     * bodies rigidly in their relative pose.
+     * @returns {Joint} this
+     */
+    asWeld() {
+        for (let i = 0; i < 6; i++) this.dofMode[i] = DofMode.LOCKED;
+        return this;
+    }
+
+    /**
+     * Configure as a hinge (revolute): 3 linear + 2 angular locked, free to
+     * rotate about a single frame axis. Orient {@link localBasisA} /
+     * {@link localBasisB} so that frame axis is the desired hinge axis.
+     *
+     * @param {number} [freeAngularAxis] which frame axis is free: 0 = x
+     *   (default), 1 = y, 2 = z.
+     * @returns {Joint} this
+     */
+    asHinge(freeAngularAxis = 0) {
+        this.dofMode[0] = DofMode.LOCKED;
+        this.dofMode[1] = DofMode.LOCKED;
+        this.dofMode[2] = DofMode.LOCKED;
+        this.dofMode[3] = DofMode.LOCKED;
+        this.dofMode[4] = DofMode.LOCKED;
+        this.dofMode[5] = DofMode.LOCKED;
+        this.dofMode[3 + freeAngularAxis] = DofMode.FREE;
+        return this;
+    }
+
+    /**
+     * Configure as a prismatic (slider): 2 linear + 3 angular locked, free to
+     * translate along a single frame axis. Orient {@link localBasisA} /
+     * {@link localBasisB} so that frame axis is the desired slide direction.
+     *
+     * @param {number} [freeLinearAxis] which frame axis is free: 0 = x
+     *   (default), 1 = y, 2 = z.
+     * @returns {Joint} this
+     */
+    asPrismatic(freeLinearAxis = 0) {
+        this.dofMode[0] = DofMode.LOCKED;
+        this.dofMode[1] = DofMode.LOCKED;
+        this.dofMode[2] = DofMode.LOCKED;
+        this.dofMode[freeLinearAxis] = DofMode.FREE;
+        this.dofMode[3] = DofMode.LOCKED;
+        this.dofMode[4] = DofMode.LOCKED;
+        this.dofMode[5] = DofMode.LOCKED;
+        return this;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+Joint.typeName = "Joint";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+Joint.prototype.isJoint = true;

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"}