@woosh/meep-engine 2.156.0 → 2.157.0

package/src/engine/physics/fluid/effector/AmbientWindFluidEffector.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Drives every fluid cell toward a target ambient wind velocity — the standard
+ * way to model prevailing wind in a scrolling wind volume.
+ *
+ * Unlike {@link GlobalFluidEffector} (which integrates a constant ACCELERATION
+ * and therefore grows the velocity without bound — incompressible projection
+ * cannot oppose a uniform force), this effector relaxes the field toward a
+ * fixed VELOCITY:
+ *
+ *     v ← v + α · (target − v),   α = 1 − exp(−rate · dt)
+ *
+ * The fixed point is exactly `target`; gusts and wakes splatted on top decay
+ * back toward the ambient wind at `rate` per second. The exponential form is
+ * frame-rate independent — two half-steps relax exactly as much as one full
+ * step.
+ *
+ * `velocity` is in WORLD units per second. The `world_to_grid` matrix's linear
+ * part converts it into the target field's grid-cell units at apply time, so
+ * the same effector instance produces the same world-space wind on fields of
+ * different `cell_size`.
+ *
+ * Solid cells are left untouched — the projection zeroes them anyway, and
+ * skipping the write keeps the solid mask authoritative for effectors too.
+ */
+export class AmbientWindFluidEffector extends AbstractFluidEffector {
+    /**
+     * Target wind velocity in WORLD units per second.
+     * @type {[number, number, number]}
+     */
+    velocity: [number, number, number];
+    /**
+     * Relaxation rate toward {@link velocity}, per second. Higher = stiffer
+     * wind that re-asserts itself quickly after disturbances; lower = gusts
+     * and wakes linger. At rate `r`, a disturbance decays to ~37% in `1/r`
+     * seconds. `0` disables the effector.
+     * @type {number}
+     */
+    rate: number;
+}
+import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
+//# sourceMappingURL=AmbientWindFluidEffector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AmbientWindFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/AmbientWindFluidEffector.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAEI;;;OAGG;IACH,UAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEb;IAErB;;;;;;OAMG;IACH,MAFU,MAAM,CAEP;CAgFZ;sCAzHqC,4BAA4B"}

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

@@ -0,0 +1,124 @@
+import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
+
+/**
+ * Drives every fluid cell toward a target ambient wind velocity — the standard
+ * way to model prevailing wind in a scrolling wind volume.
+ *
+ * Unlike {@link GlobalFluidEffector} (which integrates a constant ACCELERATION
+ * and therefore grows the velocity without bound — incompressible projection
+ * cannot oppose a uniform force), this effector relaxes the field toward a
+ * fixed VELOCITY:
+ *
+ *     v ← v + α · (target − v),   α = 1 − exp(−rate · dt)
+ *
+ * The fixed point is exactly `target`; gusts and wakes splatted on top decay
+ * back toward the ambient wind at `rate` per second. The exponential form is
+ * frame-rate independent — two half-steps relax exactly as much as one full
+ * step.
+ *
+ * `velocity` is in WORLD units per second. The `world_to_grid` matrix's linear
+ * part converts it into the target field's grid-cell units at apply time, so
+ * the same effector instance produces the same world-space wind on fields of
+ * different `cell_size`.
+ *
+ * Solid cells are left untouched — the projection zeroes them anyway, and
+ * skipping the write keeps the solid mask authoritative for effectors too.
+ */
+export class AmbientWindFluidEffector extends AbstractFluidEffector {
+
+    /**
+     * Target wind velocity in WORLD units per second.
+     * @type {[number, number, number]}
+     */
+    velocity = [0, 0, 0];
+
+    /**
+     * Relaxation rate toward {@link velocity}, per second. Higher = stiffer
+     * wind that re-asserts itself quickly after disturbances; lower = gusts
+     * and wakes linger. At rate `r`, a disturbance decays to ~37% in `1/r`
+     * seconds. `0` disables the effector.
+     * @type {number}
+     */
+    rate = 1;
+
+    /**
+     * @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 velocity is a direction.
+     */
+    apply(field, dt, world_to_grid) {
+        if (this.rate <= 0 || dt <= 0) {
+            return;
+        }
+
+        const wx = this.velocity[0];
+        const wy = this.velocity[1];
+        const wz = this.velocity[2];
+
+        // Direction-transform the world-space target into grid units.
+        const m = world_to_grid;
+        const tx = m[0] * wx + m[4] * wy + m[8]  * wz;
+        const ty = m[1] * wx + m[5] * wy + m[9]  * wz;
+        const tz = m[2] * wx + m[6] * wy + m[10] * wz;
+
+        // Exact exponential relaxation factor for this dt.
+        const alpha = 1 - Math.exp(-this.rate * dt);
+
+        const vx = field.velocity_x;
+        const vy = field.velocity_y;
+        const vz = field.velocity_z;
+        const solid = field.solid;
+        const n = field.cellCount();
+
+        for (let i = 0; i < n; i++) {
+            if (solid[i] !== 0) {
+                continue;
+            }
+            vx[i] += alpha * (tx - vx[i]);
+            vy[i] += alpha * (ty - vy[i]);
+            vz[i] += alpha * (tz - vz[i]);
+        }
+    }
+
+    /**
+     * @param {AbstractFluidEffector} other
+     * @return {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+        if (!(other instanceof AmbientWindFluidEffector)) {
+            return false;
+        }
+        return this.rate === other.rate
+            && this.velocity[0] === other.velocity[0]
+            && this.velocity[1] === other.velocity[1]
+            && this.velocity[2] === other.velocity[2];
+    }
+
+    /**
+     * @return {number}
+     */
+    hash() {
+        return combine_hash(
+            computeHashFloat(this.velocity[0]),
+            computeHashFloat(this.velocity[1]),
+            computeHashFloat(this.velocity[2]),
+            computeHashFloat(this.rate)
+        );
+    }
+
+    /**
+     * Position-free — applies to every cell of any field. Infinite bounds means
+     * the broad-phase will never cull this effector.
+     * @param {AABB3} out
+     */
+    getBoundingBox(out) {
+        out.setInfiniteBounds();
+    }
+}

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

@@ -7,8 +7,25 @@
  * `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
@@ -36,9 +53,10 @@ export class WakeFluidEffector extends AbstractFluidEffector {
      */
     position: [number, number, number];
     /**
-     * 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: [number, number, number];
@@ -57,9 +75,10 @@ export class WakeFluidEffector extends AbstractFluidEffector {
      */
     strength: number;
     /**
-     * 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.
+     * 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(): void;
     #private;

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAEI;;;;;OAKG;IACH,UAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEb;IAErB;;;;;OAKG;IACH,mBAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEJ;IAE9B;;;;;OAKG;IACH,QAFU,MAAM,CAEL;IAEX;;;;;OAKG;IACH,UAFU,MAAM,CAEH;IASb;;;;OAIG;IACH,oBAKC;;CAqNJ;sCA1SqC,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;;CAwOJ;sCA3VqC,4BAA4B"}

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;
@@ -172,7 +216,7 @@ export class WakeFluidEffector extends AbstractFluidEffector {
 
         if (x_min > x_max || y_min > y_max || z_min > z_max) {
             // Swept tube doesn't intersect the field at all.
-            this.#advance_trail();
+            this.#advance_trail_if_manual();
             return;
         }
 
@@ -225,14 +269,19 @@ export class WakeFluidEffector extends AbstractFluidEffector {
             }
         }
 
-        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/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"}