@woosh/meep-engine 2.156.0 → 2.158.0

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

@@ -15,8 +15,25 @@ const scratch_b = new Float32Array(3);
  * `world_to_grid` converts both endpoints into the target field's grid space, and the
  * effector splats `(position - previous_position) / dt * strength` into every fluid
  * cell within the kernel of that grid-space segment, weighted by a smooth
- * `(1 - d/R)²` falloff. After the splat the effector copies `position` into
- * `previous_position` so the next call automatically tracks the next segment.
+ * `(1 - d/R)²` falloff.
+ *
+ * Trail advancement (copying `position` into `previous_position`) depends on who
+ * drives the effector:
+ *
+ *   - **Transform-managed** (entity has a `Transform`; {@link FluidSystem} calls
+ *     {@link syncFromTransform} once per fixed update): the trail advances inside
+ *     the sync, NOT inside {@link apply}. The segment is "movement since the last
+ *     tick", and `apply` is a pure read — the same instance can be applied to any
+ *     number of overlapping fluid fields in one step and every field receives the
+ *     same wake. (Advancing in `apply` would hand the whole segment to whichever
+ *     field stepped first and a zero segment to the rest.)
+ *
+ *   - **Manually driven** (user code sets {@link position} directly; no sync):
+ *     `apply` advances the trail after splatting, so consecutive applies follow
+ *     the moving source. With multiple fields this mode gives the segment to the
+ *     first field only — pair manual driving with a single field, or call
+ *     {@link syncFromTransform}-style bookkeeping yourself by resetting
+ *     {@link previous_position} between steps.
  *
  * Works at any user-supplied {@link radius}, including sub-cell. The kernel is
  * internally floored at `1` grid cell — small user radii (bullets, arrows) still
@@ -46,9 +63,10 @@ export class WakeFluidEffector extends AbstractFluidEffector {
     position = [0, 0, 0];
 
     /**
-     * Position at the start of the swept segment, world space. {@link apply} copies
-     * `position` into this at the end of every successful splat. Caller normally
-     * doesn't touch it directly.
+     * Position at the start of the swept segment, world space. Advanced to
+     * `position` by {@link syncFromTransform} (transform-managed mode) or at the
+     * end of {@link apply} (manual mode) — see the class docstring. Caller
+     * normally doesn't touch it directly.
      * @type {[number, number, number]}
      */
     previous_position = [0, 0, 0];
@@ -70,31 +88,57 @@ export class WakeFluidEffector extends AbstractFluidEffector {
     strength = 1;
 
     /**
-     * True once syncFromTransform has been called at least once. Used to seed
-     * previous_position on the first sync, avoiding a spurious wake from the origin.
+     * True when a sync has adopted a position since construction / the last
+     * {@link reset_trail}. While false, the next {@link syncFromTransform} seeds
+     * `previous_position = position` instead of advancing the trail — suppressing
+     * a spurious wake from the origin or across a teleport.
      * @type {boolean}
      */
     #initialized = false;
 
     /**
-     * Snap {@link previous_position} to {@link position}. Call once after manual
-     * initial placement, and after any teleport, so the next {@link apply} doesn't
-     * splat a wake across the jump.
+     * True once {@link syncFromTransform} has ever been called — the effector is
+     * driven by an entity Transform via {@link FluidSystem}. In this mode the
+     * trail advances in the sync (once per tick) and {@link apply} becomes a pure
+     * read, so one instance can serve any number of fluid fields per step.
+     * @type {boolean}
+     */
+    #transform_managed = false;
+
+    /**
+     * Snap {@link previous_position} to {@link position} and mark the trail as
+     * needing a re-seed. Call after manual initial placement and after any
+     * teleport (in either driving mode) so the next splat doesn't sweep a wake
+     * across the jump.
      */
     reset_trail() {
         this.previous_position[0] = this.position[0];
         this.previous_position[1] = this.position[1];
         this.previous_position[2] = this.position[2];
-        this.#initialized = true;
+        this.#initialized = false;
     }
 
     /**
-     * Pull world-space position off the entity Transform. On the first call, also
-     * seeds `previous_position` to suppress a wake-from-origin.
+     * Pull world-space position off the entity Transform and advance the trail:
+     * `previous_position` takes the position adopted on the LAST sync, `position`
+     * takes the transform's current one. Called by {@link FluidSystem} once per
+     * fixed update, before any field is stepped — so every field stepped this
+     * tick sees the same one-tick segment.
+     *
+     * The first call (and the first after {@link reset_trail}) seeds
+     * `previous_position = position` instead, suppressing a wake from the origin
+     * or across a teleport.
+     *
      * @param {Transform} transform
      */
     syncFromTransform(transform) {
         const p = transform.position;
+        this.#transform_managed = true;
+        if (this.#initialized) {
+            this.previous_position[0] = this.position[0];
+            this.previous_position[1] = this.position[1];
+            this.previous_position[2] = this.position[2];
+        }
         this.position[0] = p.x;
         this.position[1] = p.y;
         this.position[2] = p.z;
@@ -160,79 +204,138 @@ 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();
+            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;
+                    }
                 }
             }
         }
 
-        this.#advance_trail();
+        this.#advance_trail_if_manual();
     }
 
     /**
-     * Shift `previous_position` to `position` so the next apply() picks up where this
-     * one left off.
+     * Manual-mode trail bookkeeping: shift `previous_position` to `position` so
+     * the next apply() picks up where this one left off. Transform-managed
+     * effectors skip this — their trail advances in {@link syncFromTransform},
+     * keeping apply() pure so the same segment serves every field in the step.
      */
-    #advance_trail() {
+    #advance_trail_if_manual() {
+        if (this.#transform_managed) {
+            return;
+        }
         this.previous_position[0] = this.position[0];
         this.previous_position[1] = this.position[1];
         this.previous_position[2] = this.position[2];

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_advect_maccormack_scalar.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Unconditionally stable MacCormack advection of a scalar field — second-order
+ * accurate in space and time, at roughly twice the cost of plain
+ * semi-Lagrangian transport.
+ *
+ * Scheme (Selle, Fedkiw, Kim, Liu, Rossignac 2008):
+ *
+ *     1. forward:  φ̂(c)  = SL(φ, back-trace c by −v·dt)      — plain SL step
+ *     2. backward: φ̄(c)  = SL(φ̂, trace c by +v·dt)           — reverse it
+ *     3. correct:  φ*(c) = φ̂(c) + ½·(φ(c) − φ̄(c))
+ *     4. limit:    φ_new(c) = clamp(φ*, min/max of the 8 φ cells around the
+ *                  back-traced position) — Selle's monotone limiter; restores
+ *                  unconditional stability and forbids new extrema, at the
+ *                  price of locally reverting toward first-order where the
+ *                  correction would overshoot.
+ *
+ * The forward/backward error cancellation removes the leading-order smearing
+ * of semi-Lagrangian transport — sharp scalar features survive an order of
+ * magnitude longer.
+ *
+ * Solid destination cells pass their source value through unchanged, exactly
+ * like {@link v3_grid_apply_scalar_advection}.
+ *
+ * Aliasing: `output`, `source` and `forward_scratch` must be three distinct
+ * buffers. Velocity arrays may alias none of them is required — they are only
+ * point-read.
+ *
+ * @param {Float32Array} output           Destination, mutated.
+ * @param {Float32Array} source           Scalar values to advect. NOT mutated.
+ * @param {Float32Array} forward_scratch  Working buffer for φ̂. Mutated.
+ * @param {Float32Array} vel_x            Carrier velocity (cell-centered).
+ * @param {Float32Array} vel_y
+ * @param {Float32Array} vel_z
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} solid              Required cell flags (zero-filled for a
+ *                                        wall-free domain).
+ */
+export function v3_grid_advect_maccormack_scalar(output: Float32Array, source: Float32Array, forward_scratch: Float32Array, vel_x: Float32Array, vel_y: Float32Array, vel_z: Float32Array, res_x: number, res_y: number, res_z: number, time_delta: number, solid: Uint8Array): void;
+//# sourceMappingURL=v3_grid_advect_maccormack_scalar.d.ts.map

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

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

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

@@ -0,0 +1,136 @@
+import { assert } from "../../../../core/assert.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
+
+/**
+ * Unconditionally stable MacCormack advection of a scalar field — second-order
+ * accurate in space and time, at roughly twice the cost of plain
+ * semi-Lagrangian transport.
+ *
+ * Scheme (Selle, Fedkiw, Kim, Liu, Rossignac 2008):
+ *
+ *     1. forward:  φ̂(c)  = SL(φ, back-trace c by −v·dt)      — plain SL step
+ *     2. backward: φ̄(c)  = SL(φ̂, trace c by +v·dt)           — reverse it
+ *     3. correct:  φ*(c) = φ̂(c) + ½·(φ(c) − φ̄(c))
+ *     4. limit:    φ_new(c) = clamp(φ*, min/max of the 8 φ cells around the
+ *                  back-traced position) — Selle's monotone limiter; restores
+ *                  unconditional stability and forbids new extrema, at the
+ *                  price of locally reverting toward first-order where the
+ *                  correction would overshoot.
+ *
+ * The forward/backward error cancellation removes the leading-order smearing
+ * of semi-Lagrangian transport — sharp scalar features survive an order of
+ * magnitude longer.
+ *
+ * Solid destination cells pass their source value through unchanged, exactly
+ * like {@link v3_grid_apply_scalar_advection}.
+ *
+ * Aliasing: `output`, `source` and `forward_scratch` must be three distinct
+ * buffers. Velocity arrays may alias none of them is required — they are only
+ * point-read.
+ *
+ * @param {Float32Array} output           Destination, mutated.
+ * @param {Float32Array} source           Scalar values to advect. NOT mutated.
+ * @param {Float32Array} forward_scratch  Working buffer for φ̂. Mutated.
+ * @param {Float32Array} vel_x            Carrier velocity (cell-centered).
+ * @param {Float32Array} vel_y
+ * @param {Float32Array} vel_z
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} solid              Required cell flags (zero-filled for a
+ *                                        wall-free domain).
+ */
+export function v3_grid_advect_maccormack_scalar(output, source, forward_scratch, vel_x, vel_y, vel_z, res_x, res_y, res_z, time_delta, solid) {
+    const cell_count = res_x * res_y * res_z;
+
+    assert.notEqual(output, source, "output must not alias source");
+    assert.notEqual(output, forward_scratch, "output must not alias forward_scratch");
+    assert.notEqual(source, forward_scratch, "source must not alias forward_scratch");
+    assert.greaterThanOrEqual(output.length, cell_count, "output covers grid");
+    assert.greaterThanOrEqual(source.length, cell_count, "source covers grid");
+    assert.greaterThanOrEqual(forward_scratch.length, cell_count, "forward_scratch covers grid");
+    assert.greaterThanOrEqual(vel_x.length, cell_count, "vel_x covers grid");
+    assert.greaterThanOrEqual(vel_y.length, cell_count, "vel_y covers grid");
+    assert.greaterThanOrEqual(vel_z.length, cell_count, "vel_z covers grid");
+
+    const slice_size = res_x * res_y;
+    const last_x = res_x - 1;
+    const last_y = res_y - 1;
+    const last_z = res_z - 1;
+
+    const fwd = forward_scratch;
+
+    // ─── pass 1: forward SL step into the scratch ───────────────────────────
+    for (let z = 0; z < res_z; z++) {
+        const z_off = z * slice_size;
+        for (let y = 0; y < res_y; y++) {
+            const y_off = y * res_x;
+            for (let x = 0; x < res_x; x++) {
+                const c = z_off + y_off + x;
+                if (solid[c] !== 0) {
+                    fwd[c] = source[c];
+                    continue;
+                }
+                const s_x = x - vel_x[c] * time_delta;
+                const s_y = y - vel_y[c] * time_delta;
+                const s_z = z - vel_z[c] * time_delta;
+                fwd[c] = scs3d_sample_linear(source, res_x, res_y, res_z, s_x, s_y, s_z);
+            }
+        }
+    }
+
+    // ─── pass 2: backward step, correction, monotone limit ──────────────────
+    for (let z = 0; z < res_z; z++) {
+        const z_off = z * slice_size;
+        for (let y = 0; y < res_y; y++) {
+            const y_off = y * res_x;
+            for (let x = 0; x < res_x; x++) {
+                const c = z_off + y_off + x;
+                if (solid[c] !== 0) {
+                    output[c] = source[c];
+                    continue;
+                }
+
+                const vx = vel_x[c] * time_delta;
+                const vy = vel_y[c] * time_delta;
+                const vz = vel_z[c] * time_delta;
+
+                // Reverse trace samples the forward result.
+                const backward = scs3d_sample_linear(fwd, res_x, res_y, res_z, x + vx, y + vy, z + vz);
+                const corrected = fwd[c] + 0.5 * (source[c] - backward);
+
+                // Limiter bounds: extrema of the 8 source cells around the
+                // back-traced position (same clamped corner set the pass-1
+                // sampler interpolated from).
+                const bx = clamp(x - vx, 0, last_x);
+                const by = clamp(y - vy, 0, last_y);
+                const bz = clamp(z - vz, 0, last_z);
+                const x0 = bx | 0;
+                const y0 = by | 0;
+                const z0 = bz | 0;
+                const x1 = bx === x0 ? x0 : x0 + 1;
+                const y1 = by === y0 ? y0 : y0 + 1;
+                const z1 = bz === z0 ? z0 : z0 + 1;
+
+                const z0_off = z0 * slice_size;
+                const z1_off = z1 * slice_size;
+                const y0_off = y0 * res_x;
+                const y1_off = y1 * res_x;
+
+                let mn = source[z0_off + y0_off + x0];
+                let mx = mn;
+                let v = source[z0_off + y0_off + x1]; if (v < mn) mn = v; else if (v > mx) mx = v;
+                v = source[z0_off + y1_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
+                v = source[z0_off + y1_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
+                v = source[z1_off + y0_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
+                v = source[z1_off + y0_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
+                v = source[z1_off + y1_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
+                v = source[z1_off + y1_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
+
+                output[c] = corrected < mn ? mn : (corrected > mx ? mx : corrected);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Unconditionally stable MacCormack advection of a 3-component velocity field
+ * along a separate carrier field — the velocity counterpart of
+ * {@link v3_grid_advect_maccormack_scalar}, sharing one back-trace and one
+ * fused 3-channel sample per cell per pass.
+ *
+ * Scheme per component (Selle et al. 2008):
+ *
+ *     1. forward:  û  = SL(src, back-trace by carrier·dt)
+ *     2. backward: ū  = SL(û, trace by +carrier·dt)
+ *     3. correct:  u* = û + ½·(src − ū)
+ *     4. limit:    clamp to min/max of the 8 src cells around the back-traced
+ *                  position (per component) — Selle's monotone limiter.
+ *
+ * The carrier is read only at each cell's own index (the trace origin), so
+ * `outputs` MAY alias the carrier arrays — the advection-reflection step
+ * advects the reflected field along the projected field that lives in the
+ * output buffers. `sources` and `forward_scratch` must be distinct from
+ * outputs and from each other.
+ *
+ * Solid destination cells pass their source value through unchanged.
+ *
+ * @param {Float32Array[]} outputs         `[out_x, out_y, out_z]`, mutated.
+ * @param {Float32Array[]} sources         `[src_x, src_y, src_z]`. NOT mutated.
+ * @param {Float32Array} carrier_x         Velocity driving the traces.
+ * @param {Float32Array} carrier_y
+ * @param {Float32Array} carrier_z
+ * @param {Float32Array[]} forward_scratch `[fwd_x, fwd_y, fwd_z]` working
+ *                                         buffers for û. Mutated.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} solid               Required cell flags.
+ */
+export function v3_grid_advect_maccormack_velocity(outputs: Float32Array[], sources: Float32Array[], carrier_x: Float32Array, carrier_y: Float32Array, carrier_z: Float32Array, forward_scratch: Float32Array[], res_x: number, res_y: number, res_z: number, time_delta: number, solid: Uint8Array): void;
+//# sourceMappingURL=v3_grid_advect_maccormack_velocity.d.ts.map

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

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