@woosh/meep-engine 2.157.0 → 2.158.0

package/src/engine/physics/fluid/effector/GlobalFluidEffector.js

@@ -3,67 +3,156 @@ import { computeHashFloat } from "../../../../core/primitives/numbers/computeHas
 import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
 
 /**
- * Adds the same acceleration to every fluid cell each step (gravity, ambient wind).
+ * The global atmosphere: every fluid face in every field integrates the same
+ * linear flow model each step,
  *
- * `force` is in WORLD units per second squared. The `world_to_grid` matrix is applied
- * (as a direction transform — translation ignored) inside {@link apply} to convert
- * the force into the target field's grid-cell units before depositing. The same
- * GlobalFluidEffector applied to fields with different `cell_size` therefore produces
- * the same world-space acceleration on each — gravity stays gravity.
+ *     dv/dt = force + drag · (wind − v)
  *
- * Solid cells are left untouched — the projection step would zero them anyway, but
- * skipping the write is slightly cheaper and keeps the solid mask authoritative for
- * effectors as well as the solver.
+ * One effector covers the whole family of "push everything" behaviours —
+ * pick the regime by which fields you set:
+ *
+ *   - **`force` alone** — constant body force (gravity, buoyancy). NOTE:
+ *     incompressible projection cannot oppose a uniform force (a uniform
+ *     field is divergence-free), so without `drag`, a sealed container, or
+ *     {@link FluidSimulator#velocity_damping}, the velocity grows without
+ *     bound. This is the legacy GlobalFluidEffector behaviour.
+ *
+ *   - **`wind` + `drag`** — prevailing wind: the air relaxes toward the wind
+ *     velocity at `drag` per second; gusts, wakes and splats decay back to
+ *     the ambient flow. The fixed point is exactly `wind`.
+ *
+ *   - **`force` + `drag` (+ `wind`)** — bounded forcing with a terminal
+ *     velocity of `wind + force / drag`: falling smoke, drifting ash, rain
+ *     sheets in a breeze.
+ *
+ *   - **`drag` alone** — pure exponential calming toward still air. (The
+ *     scene-content twin of {@link FluidSimulator#velocity_damping}, which
+ *     is the solver-level stability knob that exists even when no effectors
+ *     are wired.)
+ *
+ * `wind` only enters through the drag term — with `drag = 0` it is inert by
+ * construction (the model degenerates to dv/dt = force).
+ *
+ * The step uses the EXACT solution of the linear ODE, not an Euler step:
+ *
+ *     v ← v∞ + (v − v∞) · e^(−drag·dt),   v∞ = wind + force / drag
+ *
+ * (and plain `v += force·dt`, also exact, when `drag = 0`). Exactness makes
+ * the effector frame-rate independent — two half-steps land exactly where
+ * one full step does, including with both terms active.
+ *
+ * All quantities are WORLD-space: `force` in units/s², `wind` in units/s,
+ * `drag` in 1/s. The `world_to_grid` matrix's linear part converts the two
+ * vectors at apply time, so one instance produces the same world-space
+ * atmosphere on fields of any `cell_size` — gravity stays gravity.
+ *
+ * Pinned faces (either adjacent cell solid) are skipped — the projection
+ * owns those as boundary conditions, and skipping keeps the solid mask
+ * authoritative for effectors as well as the solver.
  */
 export class GlobalFluidEffector extends AbstractFluidEffector {
 
     /**
-     * Acceleration vector in WORLD units per second squared (e.g. `[0, -9.8, 0]` for
-     * Earth gravity in metres-and-seconds). Per-step deposit into the velocity field
-     * is `world_to_grid · force × dt`.
+     * Body-force acceleration in WORLD units per second squared (e.g.
+     * `[0, -9.8, 0]` for Earth gravity in metres-and-seconds).
      *
      * @type {[number, number, number]}
      */
     force = [0, 0, 0];
 
+    /**
+     * Ambient wind velocity in WORLD units per second — the velocity the air
+     * relaxes toward. Only effective when {@link drag} is non-zero.
+     *
+     * @type {[number, number, number]}
+     */
+    wind = [0, 0, 0];
+
+    /**
+     * Relaxation rate toward the ambient flow, per second. Higher = stiffer
+     * atmosphere that re-asserts itself quickly after disturbances; lower =
+     * gusts and wakes linger. A disturbance decays to ~37% in `1/drag`
+     * seconds. `0` disables the relaxation term entirely.
+     *
+     * @type {number}
+     */
+    drag = 0;
+
     /**
      * @param {FluidField} field
      * @param {number} dt
      * @param {Float32Array|number[]} world_to_grid  Column-major 4×4 affine; only the
      *                                               linear (upper-left 3×3) part is
-     *                                               used since force is a direction.
+     *                                               used since force and wind are
+     *                                               directions.
      */
     apply(field, dt, world_to_grid) {
+        const m = world_to_grid;
+
+        // Direction-transform both vectors into grid units (translation in
+        // m[12..14] is for points, not directions). For the axis-aligned
+        // uniform-scale matrices built by FluidSystem this collapses to
+        // division by cell_size.
         const wfx = this.force[0];
         const wfy = this.force[1];
         const wfz = this.force[2];
+        const ax = m[0] * wfx + m[4] * wfy + m[8]  * wfz;
+        const ay = m[1] * wfx + m[5] * wfy + m[9]  * wfz;
+        const az = m[2] * wfx + m[6] * wfy + m[10] * wfz;
 
-        if (wfx === 0 && wfy === 0 && wfz === 0) {
-            return;
-        }
+        const vu = field.velocity_x;
+        const vv = field.velocity_y;
+        const vw = field.velocity_z;
+        const pin_u = field.face_solid_x;
+        const pin_v = field.face_solid_y;
+        const pin_w = field.face_solid_z;
+        const n_u = vu.length;
+        const n_v = vv.length;
+        const n_w = vw.length;
 
-        // Direction-transform: apply the linear part of world_to_grid (translation in
-        // m[12..14] is for points, not directions). For the axis-aligned uniform-scale
-        // matrices built by FluidSystem this collapses to division by cell_size, so
-        // world m/s² becomes grid cells/s².
-        const m = world_to_grid;
-        const fx = (m[0] * wfx + m[4] * wfy + m[8]  * wfz) * dt;
-        const fy = (m[1] * wfx + m[5] * wfy + m[9]  * wfz) * dt;
-        const fz = (m[2] * wfx + m[6] * wfy + m[10] * wfz) * dt;
+        if (this.drag > 0) {
+            const wwx = this.wind[0];
+            const wwy = this.wind[1];
+            const wwz = this.wind[2];
+            const gx = m[0] * wwx + m[4] * wwy + m[8]  * wwz;
+            const gy = m[1] * wwx + m[5] * wwy + m[9]  * wwz;
+            const gz = m[2] * wwx + m[6] * wwy + m[10] * wwz;
 
-        const vx = field.velocity_x;
-        const vy = field.velocity_y;
-        const vz = field.velocity_z;
-        const solid = field.solid;
-        const n = vx.length;
+            // Exact step of dv/dt = a + k(w − v): relax toward the terminal
+            // velocity v∞ = w + a/k by 1 − e^(−k·dt).
+            const inv_drag = 1 / this.drag;
+            const tx = gx + ax * inv_drag;
+            const ty = gy + ay * inv_drag;
+            const tz = gz + az * inv_drag;
+            const blend = 1 - Math.exp(-this.drag * dt);
 
-        for (let i = 0; i < n; i++) {
-            if (solid[i] !== 0) {
-                continue;
+            for (let i = 0; i < n_u; i++) {
+                if (pin_u[i] === 0) vu[i] += blend * (tx - vu[i]);
+            }
+            for (let i = 0; i < n_v; i++) {
+                if (pin_v[i] === 0) vv[i] += blend * (ty - vv[i]);
             }
-            vx[i] += fx;
-            vy[i] += fy;
-            vz[i] += fz;
+            for (let i = 0; i < n_w; i++) {
+                if (pin_w[i] === 0) vw[i] += blend * (tz - vw[i]);
+            }
+            return;
+        }
+
+        // No drag: pure body force, v += a·dt (exact for constant acceleration).
+        const dx = ax * dt;
+        const dy = ay * dt;
+        const dz = az * dt;
+        if (dx === 0 && dy === 0 && dz === 0) {
+            return;
+        }
+        for (let i = 0; i < n_u; i++) {
+            if (pin_u[i] === 0) vu[i] += dx;
+        }
+        for (let i = 0; i < n_v; i++) {
+            if (pin_v[i] === 0) vv[i] += dy;
+        }
+        for (let i = 0; i < n_w; i++) {
+            if (pin_w[i] === 0) vw[i] += dz;
         }
     }
 
@@ -78,9 +167,13 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
         if (!(other instanceof GlobalFluidEffector)) {
             return false;
         }
-        return this.force[0] === other.force[0]
+        return this.drag === other.drag
+            && this.force[0] === other.force[0]
             && this.force[1] === other.force[1]
-            && this.force[2] === other.force[2];
+            && this.force[2] === other.force[2]
+            && this.wind[0] === other.wind[0]
+            && this.wind[1] === other.wind[1]
+            && this.wind[2] === other.wind[2];
     }
 
     /**
@@ -90,7 +183,11 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
         return combine_hash(
             computeHashFloat(this.force[0]),
             computeHashFloat(this.force[1]),
-            computeHashFloat(this.force[2])
+            computeHashFloat(this.force[2]),
+            computeHashFloat(this.wind[0]),
+            computeHashFloat(this.wind[1]),
+            computeHashFloat(this.wind[2]),
+            computeHashFloat(this.drag)
         );
     }
 

package/src/engine/physics/fluid/effector/ImpulseFluidEffector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ImpulseFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/ImpulseFluidEffector.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAEI;;;OAGG;IACH,UAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEb;IAErB;;;;;;OAMG;IACH,OAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEhB;IAElB;;;;;;OAMG;IACH,QAFU,MAAM,CAEL;CAgKd;sCA9MqC,4BAA4B"}
+{"version":3,"file":"ImpulseFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/ImpulseFluidEffector.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAEI;;;OAGG;IACH,UAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEb;IAErB;;;;;;OAMG;IACH,OAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEhB;IAElB;;;;;;OAMG;IACH,QAFU,MAAM,CAEL;CA+Md;sCA7PqC,4BAA4B"}

package/src/engine/physics/fluid/effector/ImpulseFluidEffector.js

@@ -93,52 +93,99 @@ export class ImpulseFluidEffector extends AbstractFluidEffector {
         const res_x = res[0];
         const res_y = res[1];
         const res_z = res[2];
-        const slice_size = res_x * res_y;
-
-        const x_min = Math.max(0, Math.floor(px - r));
-        const x_max = Math.min(res_x - 1, Math.ceil(px + r));
-        const y_min = Math.max(0, Math.floor(py - r));
-        const y_max = Math.min(res_y - 1, Math.ceil(py + r));
-        const z_min = Math.max(0, Math.floor(pz - r));
-        const z_max = Math.min(res_z - 1, Math.ceil(pz + r));
-
-        if (x_min > x_max || y_min > y_max || z_min > z_max) {
-            return;
-        }
 
         const r_inv = 1 / r;
 
-        const vx = field.velocity_x;
-        const vy = field.velocity_y;
-        const vz = field.velocity_z;
-        const solid = field.solid;
-
-        for (let z = z_min; z <= z_max; z++) {
-            const dz = z - pz;
-            const z_off = z * slice_size;
-
-            for (let y = y_min; y <= y_max; y++) {
-                const dy = y - py;
-                const y_off = y * res_x;
-
-                for (let x = x_min; x <= x_max; x++) {
-                    const dx = x - px;
+        // Each velocity component deposits onto its own face lattice, with the
+        // falloff evaluated at the face position (the lattice is offset by
+        // −0.5 on its own axis relative to cell centers). Pinned faces
+        // (adjacent solid) are skipped.
 
-                    const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
-                    const t = dist * r_inv;
-                    if (t >= 1) {
-                        continue;
+        // u (x-faces) — face (x, y, z) sits at (x − 0.5, y, z).
+        {
+            const vu = field.velocity_x;
+            const pin = field.face_solid_x;
+            const sx = res_x + 1;
+            const x_min = Math.max(0, Math.floor(px + 0.5 - r));
+            const x_max = Math.min(res_x, Math.ceil(px + 0.5 + r));
+            const y_min = Math.max(0, Math.floor(py - r));
+            const y_max = Math.min(res_y - 1, Math.ceil(py + r));
+            const z_min = Math.max(0, Math.floor(pz - r));
+            const z_max = Math.min(res_z - 1, Math.ceil(pz + r));
+            for (let z = z_min; z <= z_max; z++) {
+                const dz = z - pz;
+                const z_off = z * sx * res_y;
+                for (let y = y_min; y <= y_max; y++) {
+                    const dy = y - py;
+                    const y_off = z_off + y * sx;
+                    for (let x = x_min; x <= x_max; x++) {
+                        const dx = x - 0.5 - px;
+                        const t = Math.sqrt(dx * dx + dy * dy + dz * dz) * r_inv;
+                        if (t >= 1) continue;
+                        const f = y_off + x;
+                        if (pin[f] !== 0) continue;
+                        const w = (1 - t) * (1 - t);
+                        vu[f] += fx * w;
                     }
-                    const w = (1 - t) * (1 - t);
+                }
+            }
+        }
 
-                    const c = z_off + y_off + x;
-                    if (solid[c] !== 0) {
-                        continue;
+        // v (y-faces) — face (x, y, z) sits at (x, y − 0.5, z).
+        {
+            const vv = field.velocity_y;
+            const pin = field.face_solid_y;
+            const x_min = Math.max(0, Math.floor(px - r));
+            const x_max = Math.min(res_x - 1, Math.ceil(px + r));
+            const y_min = Math.max(0, Math.floor(py + 0.5 - r));
+            const y_max = Math.min(res_y, Math.ceil(py + 0.5 + r));
+            const z_min = Math.max(0, Math.floor(pz - r));
+            const z_max = Math.min(res_z - 1, Math.ceil(pz + r));
+            for (let z = z_min; z <= z_max; z++) {
+                const dz = z - pz;
+                const z_off = z * res_x * (res_y + 1);
+                for (let y = y_min; y <= y_max; y++) {
+                    const dy = y - 0.5 - py;
+                    const y_off = z_off + y * res_x;
+                    for (let x = x_min; x <= x_max; x++) {
+                        const dx = x - px;
+                        const t = Math.sqrt(dx * dx + dy * dy + dz * dz) * r_inv;
+                        if (t >= 1) continue;
+                        const f = y_off + x;
+                        if (pin[f] !== 0) continue;
+                        const w = (1 - t) * (1 - t);
+                        vv[f] += fy * w;
                     }
+                }
+            }
+        }
 
-                    vx[c] += fx * w;
-                    vy[c] += fy * w;
-                    vz[c] += fz * w;
+        // w (z-faces) — face (x, y, z) sits at (x, y, z − 0.5).
+        {
+            const vw = field.velocity_z;
+            const pin = field.face_solid_z;
+            const slice = res_x * res_y;
+            const x_min = Math.max(0, Math.floor(px - r));
+            const x_max = Math.min(res_x - 1, Math.ceil(px + r));
+            const y_min = Math.max(0, Math.floor(py - r));
+            const y_max = Math.min(res_y - 1, Math.ceil(py + r));
+            const z_min = Math.max(0, Math.floor(pz + 0.5 - r));
+            const z_max = Math.min(res_z, Math.ceil(pz + 0.5 + r));
+            for (let z = z_min; z <= z_max; z++) {
+                const dz = z - 0.5 - pz;
+                const z_off = z * slice;
+                for (let y = y_min; y <= y_max; y++) {
+                    const dy = y - py;
+                    const y_off = z_off + y * res_x;
+                    for (let x = x_min; x <= x_max; x++) {
+                        const dx = x - px;
+                        const t = Math.sqrt(dx * dx + dy * dy + dz * dz) * r_inv;
+                        if (t >= 1) continue;
+                        const f = y_off + x;
+                        if (pin[f] !== 0) continue;
+                        const w = (1 - t) * (1 - t);
+                        vw[f] += fz * w;
+                    }
                 }
             }
         }

package/src/engine/physics/fluid/effector/WakeFluidEffector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WakeFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/WakeFluidEffector.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IAEI;;;;;OAKG;IACH,UAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEb;IAErB;;;;;;OAMG;IACH,mBAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEJ;IAE9B;;;;;OAKG;IACH,QAFU,MAAM,CAEL;IAEX;;;;;OAKG;IACH,UAFU,MAAM,CAEH;IAoBb;;;;;OAKG;IACH,oBAKC;;CAwOJ;sCA3VqC,4BAA4B"}
+{"version":3,"file":"WakeFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/WakeFluidEffector.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IAEI;;;;;OAKG;IACH,UAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEb;IAErB;;;;;;OAMG;IACH,mBAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEJ;IAE9B;;;;;OAKG;IACH,QAFU,MAAM,CAEL;IAEX;;;;;OAKG;IACH,UAFU,MAAM,CAEH;IAoBb;;;;;OAKG;IACH,oBAKC;;CA8RJ;sCAjZqC,4BAA4B"}

package/src/engine/physics/fluid/effector/WakeFluidEffector.js

@@ -204,67 +204,121 @@ export class WakeFluidEffector extends AbstractFluidEffector {
         const res_x = res[0];
         const res_y = res[1];
         const res_z = res[2];
-        const slice_size = res_x * res_y;
 
-        // AABB of the swept tube, clipped to grid.
-        const x_min = Math.max(0, Math.floor(Math.min(ax, bx) - r));
-        const x_max = Math.min(res_x - 1, Math.ceil(Math.max(ax, bx) + r));
-        const y_min = Math.max(0, Math.floor(Math.min(ay, by) - r));
-        const y_max = Math.min(res_y - 1, Math.ceil(Math.max(ay, by) + r));
-        const z_min = Math.max(0, Math.floor(Math.min(az, bz) - r));
-        const z_max = Math.min(res_z - 1, Math.ceil(Math.max(az, bz) + r));
+        const r_inv = 1 / r;
+        const inv_seg_len_sq = 1 / seg_len_sq;
 
-        if (x_min > x_max || y_min > y_max || z_min > z_max) {
+        // Conservative AABB of the swept tube in cell coordinates; each face
+        // lattice clips it to its own index range below.
+        const box_x_min = Math.min(ax, bx) - r;
+        const box_x_max = Math.max(ax, bx) + r;
+        const box_y_min = Math.min(ay, by) - r;
+        const box_y_max = Math.max(ay, by) + r;
+        const box_z_min = Math.min(az, bz) - r;
+        const box_z_max = Math.max(az, bz) + r;
+
+        if (Math.max(0, Math.floor(box_x_min)) > Math.min(res_x, Math.ceil(box_x_max))
+            || Math.max(0, Math.floor(box_y_min)) > Math.min(res_y, Math.ceil(box_y_max))
+            || Math.max(0, Math.floor(box_z_min)) > Math.min(res_z, Math.ceil(box_z_max))) {
             // Swept tube doesn't intersect the field at all.
             this.#advance_trail_if_manual();
             return;
         }
 
-        const vx = field.velocity_x;
-        const vy = field.velocity_y;
-        const vz = field.velocity_z;
-        const solid = field.solid;
-
-        const r_inv = 1 / r;
-        const inv_seg_len_sq = 1 / seg_len_sq;
-
-        for (let z = z_min; z <= z_max; z++) {
-            const z_off = z * slice_size;
-            const cell_dz = z - az;
-
-            for (let y = y_min; y <= y_max; y++) {
-                const y_off = y * res_x;
-                const cell_dy = y - ay;
-
-                for (let x = x_min; x <= x_max; x++) {
-                    const cell_dx = x - ax;
-
-                    // Project (cell - a) onto segment direction; clamp to [0, 1].
-                    let t = (cell_dx * seg_dx + cell_dy * seg_dy + cell_dz * seg_dz) * inv_seg_len_sq;
-                    if (t < 0) t = 0;
-                    else if (t > 1) t = 1;
-
-                    // Perpendicular offset from the closest point on the segment.
-                    const ndx = cell_dx - t * seg_dx;
-                    const ndy = cell_dy - t * seg_dy;
-                    const ndz = cell_dz - t * seg_dz;
-
-                    const dist = Math.sqrt(ndx * ndx + ndy * ndy + ndz * ndz);
-                    const tt = dist * r_inv;
-                    if (tt >= 1) {
-                        continue;
+        // Weight of the (1 − d/R)² falloff at a query position, or 0 outside
+        // the tube.
+        const tube_weight = (qx, qy, qz) => {
+            const dx = qx - ax;
+            const dy = qy - ay;
+            const dz = qz - az;
+            let t = (dx * seg_dx + dy * seg_dy + dz * seg_dz) * inv_seg_len_sq;
+            if (t < 0) t = 0;
+            else if (t > 1) t = 1;
+            const ndx = dx - t * seg_dx;
+            const ndy = dy - t * seg_dy;
+            const ndz = dz - t * seg_dz;
+            const tt = Math.sqrt(ndx * ndx + ndy * ndy + ndz * ndz) * r_inv;
+            if (tt >= 1) return 0;
+            const fall = 1 - tt;
+            return fall * fall;
+        };
+
+        // Each component deposits onto its own face lattice at face positions
+        // (offset −0.5 on its own axis). Pinned faces are skipped.
+
+        // u (x-faces).
+        {
+            const vu = field.velocity_x;
+            const pin = field.face_solid_x;
+            const sx = res_x + 1;
+            const x_min = Math.max(0, Math.floor(box_x_min + 0.5));
+            const x_max = Math.min(res_x, Math.ceil(box_x_max + 0.5));
+            const y_min = Math.max(0, Math.floor(box_y_min));
+            const y_max = Math.min(res_y - 1, Math.ceil(box_y_max));
+            const z_min = Math.max(0, Math.floor(box_z_min));
+            const z_max = Math.min(res_z - 1, Math.ceil(box_z_max));
+            for (let z = z_min; z <= z_max; z++) {
+                const z_off = z * sx * res_y;
+                for (let y = y_min; y <= y_max; y++) {
+                    const y_off = z_off + y * sx;
+                    for (let x = x_min; x <= x_max; x++) {
+                        const w = tube_weight(x - 0.5, y, z);
+                        if (w === 0) continue;
+                        const f = y_off + x;
+                        if (pin[f] !== 0) continue;
+                        vu[f] += impulse_x * w;
                     }
+                }
+            }
+        }
 
-                    const w = (1 - tt) * (1 - tt);
-
-                    const c = z_off + y_off + x;
-                    if (solid[c] !== 0) {
-                        continue;
+        // v (y-faces).
+        {
+            const vv = field.velocity_y;
+            const pin = field.face_solid_y;
+            const x_min = Math.max(0, Math.floor(box_x_min));
+            const x_max = Math.min(res_x - 1, Math.ceil(box_x_max));
+            const y_min = Math.max(0, Math.floor(box_y_min + 0.5));
+            const y_max = Math.min(res_y, Math.ceil(box_y_max + 0.5));
+            const z_min = Math.max(0, Math.floor(box_z_min));
+            const z_max = Math.min(res_z - 1, Math.ceil(box_z_max));
+            for (let z = z_min; z <= z_max; z++) {
+                const z_off = z * res_x * (res_y + 1);
+                for (let y = y_min; y <= y_max; y++) {
+                    const y_off = z_off + y * res_x;
+                    for (let x = x_min; x <= x_max; x++) {
+                        const w = tube_weight(x, y - 0.5, z);
+                        if (w === 0) continue;
+                        const f = y_off + x;
+                        if (pin[f] !== 0) continue;
+                        vv[f] += impulse_y * w;
                     }
+                }
+            }
+        }
 
-                    vx[c] += impulse_x * w;
-                    vy[c] += impulse_y * w;
-                    vz[c] += impulse_z * w;
+        // w (z-faces).
+        {
+            const vw = field.velocity_z;
+            const pin = field.face_solid_z;
+            const slice = res_x * res_y;
+            const x_min = Math.max(0, Math.floor(box_x_min));
+            const x_max = Math.min(res_x - 1, Math.ceil(box_x_max));
+            const y_min = Math.max(0, Math.floor(box_y_min));
+            const y_max = Math.min(res_y - 1, Math.ceil(box_y_max));
+            const z_min = Math.max(0, Math.floor(box_z_min + 0.5));
+            const z_max = Math.min(res_z, Math.ceil(box_z_max + 0.5));
+            for (let z = z_min; z <= z_max; z++) {
+                const z_off = z * slice;
+                for (let y = y_min; y <= y_max; y++) {
+                    const y_off = z_off + y * res_x;
+                    for (let x = x_min; x <= x_max; x++) {
+                        const w = tube_weight(x, y, z - 0.5);
+                        if (w === 0) continue;
+                        const f = y_off + x;
+                        if (pin[f] !== 0) continue;
+                        vw[f] += impulse_z * w;
+                    }
                 }
             }
         }

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

@@ -67,12 +67,35 @@ function main(engine) {
     new Entity().add(effectors).build(ecd);
 
     // Debug visualisation — a per-frame behavior, separate from the fluid stepping.
+    // The MAC velocity lives on three face lattices of different sizes; the
+    // visualiser wants cell-resolution channels, so sample to cell centers
+    // into cached buffers each frame.
+    const cell_count = field.cellCount();
+    const view_vx = new Float32Array(cell_count);
+    const view_vy = new Float32Array(cell_count);
+    const view_vz = new Float32Array(cell_count);
+    const sample_scratch = new Float32Array(3);
+
+    function refresh_velocity_views() {
+        for (let z = 0; z < RES_Z; z++) {
+            for (let y = 0; y < RES_Y; y++) {
+                for (let x = 0; x < RES_X; x++) {
+                    field.sampleVelocity(sample_scratch, x, y, z);
+                    const c = field.cellIndex(x, y, z);
+                    view_vx[c] = sample_scratch[0];
+                    view_vy[c] = sample_scratch[1];
+                    view_vz[c] = sample_scratch[2];
+                }
+            }
+        }
+    }
+
     const slice_view = new SliceVisualiser();
     slice_view.size.set(RES_X * 6, RES_Y * 2);
     slice_view.scale.setScalar(2);
     slice_view.transformOrigin.set(0, 0);
     slice_view.setChannels(
-        [field.velocity_x, field.velocity_y, field.velocity_z, field.getScalarData("dye")],
+        [view_vx, view_vy, view_vz, field.getScalarData("dye")],
         field.getResolution()
     );
 
@@ -81,6 +104,7 @@ function main(engine) {
             // FluidSystem.fixedUpdate is what advances the sim; we just observe and
             // time the draw cost here.
             const t0 = performance.now();
+            refresh_velocity_views();
             slice_view.draw();
             metrics.get('sim').record(performance.now() - t0);
         }))

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

@@ -0,0 +1,30 @@
+/**
+ * Trilinearly sample a cell-centered scalar at a fractional position,
+ * EXCLUDING solid cells from the interpolation: solid taps contribute zero
+ * weight and the remaining weights are renormalized. This is the
+ * free-boundary-aware sampling of Bridson §3.x — without it, a back-trace
+ * landing NEAR a wall blends the frozen in-wall value into the fluid, which
+ * reads as dye bleeding out of (or being eaten by) walls.
+ *
+ * When every tap is solid (a trace clipped into a fully walled corner) there
+ * is nothing valid to interpolate; `fallback` — typically the destination
+ * cell's own previous value, i.e. "no transport this step" — is returned.
+ *
+ * Positions clamp to the cell lattice exactly like
+ * {@link scs3d_sample_linear}; with a zero-filled `solid` grid the result
+ * matches that sampler up to floating-point reassociation (the weights sum
+ * to 1 and renormalization divides by it).
+ *
+ * @param {Float32Array} data    Cell-centered scalar field.
+ * @param {Uint8Array} solid     Cell-centered solid flags.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} fallback      Returned when no fluid tap is available.
+ * @return {number}
+ */
+export function v3_grid_sample_scalar_masked(data: Float32Array, solid: Uint8Array, res_x: number, res_y: number, res_z: number, x: number, y: number, z: number, fallback: number): number;
+//# sourceMappingURL=v3_grid_sample_scalar_masked.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_sample_scalar_masked.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_sample_scalar_masked.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,mDAXW,YAAY,SACZ,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACL,MAAM,CA+DjB"}