@woosh/meep-engine 2.138.19 → 2.139.0

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

@@ -1,91 +1,102 @@
-import { MetricCollection } from "../../development/performance/MetricCollection.js";
-import {
-    MetricCollectionConsoleMonitor
-} from "../../development/performance/monitor/MetricCollectionConsoleMonitor.js";
-import Entity from "../../ecs/Entity.js";
-import GUIElement from "../../ecs/gui/GUIElement.js";
-import GUIElementSystem from "../../ecs/gui/GUIElementSystem.js";
-import { EngineHarness } from "../../EngineHarness.js";
-import { BehaviorComponent } from "../../intelligence/behavior/ecs/BehaviorComponent.js";
-import { BehaviorSystem } from "../../intelligence/behavior/ecs/BehaviorSystem.js";
-import { FluidField } from "./FluidField.js";
-import { FluidSimulator } from "./FluidSimulator.js";
-import { SliceVisualiser } from "./SliceVisualiser.js";
-
-const harness = new EngineHarness();
-
-const metrics = new MetricCollection();
-
-metrics.create({ name: 'sim' })
-
-/**
- *
- * @param {Engine} engine
- */
-function main(engine) {
-
-    const ecd = engine.entityManager.dataset;
-
-    const field = new FluidField();
-
-    field.addAttribute('x');
-    field.addAttribute('y');
-    field.addAttribute('z');
-
-    field.resolution = [32, 32, 64];
-
-    field.build();
-
-    field.setAttributeAt(0, 15, 16, 0, -100);
-    field.setAttributeAt(0, 17, 16, 0, 100);
-    field.setAttributeAt(1, 16, 15, 0, -100);
-    field.setAttributeAt(1, 16, 17, 0, 100);
-
-    field.setAttributeAt(2, 15, 16, 0, 100);
-    field.setAttributeAt(2, 17, 16, 0, 100);
-    field.setAttributeAt(2, 16, 15, 0, 100);
-    field.setAttributeAt(2, 16, 17, 0, 100);
-
-
-    const sim = new FluidSimulator();
-
-
-    const slice_view = new SliceVisualiser();
-
-    slice_view.size.set(432, 1000);
-    slice_view.scale.setScalar(2);
-    slice_view.transformOrigin.set(0, 0);
-
-    slice_view.setData(field.buffer, field.resolution);
-
-
-    new Entity()
-        .add(BehaviorComponent.loop(time_delta => {
-
-            const t0 = performance.now();
-
-            sim.step(field, 0.015);
-
-            metrics.get('sim').record(performance.now() - t0);
-
-            slice_view.setData(field.buffer, field.resolution);
-
-            slice_view.draw();
-
-        }))
-        .build(ecd);
-
-    MetricCollectionConsoleMonitor.from(metrics).start()
-
-    new Entity()
-        .add(GUIElement.fromView(slice_view))
-        .build(ecd);
-
-}
-
-harness.initialize({
-    configuration(config, engine) {
-        config.addSystem(new GUIElementSystem(engine.gameView, engine))
-        config.addSystem(new BehaviorSystem(engine))
-    }
-}).then(main)
+import { MetricCollection } from "../../development/performance/MetricCollection.js";
+import {
+    MetricCollectionConsoleMonitor
+} from "../../development/performance/monitor/MetricCollectionConsoleMonitor.js";
+import Entity from "../../ecs/Entity.js";
+import GUIElement from "../../ecs/gui/GUIElement.js";
+import GUIElementSystem from "../../ecs/gui/GUIElementSystem.js";
+import { EngineHarness } from "../../EngineHarness.js";
+import { BehaviorComponent } from "../../intelligence/behavior/ecs/BehaviorComponent.js";
+import { BehaviorSystem } from "../../intelligence/behavior/ecs/BehaviorSystem.js";
+import { FluidComponent } from "./ecs/FluidComponent.js";
+import { FluidEffectorsComponent } from "./ecs/FluidEffectorsComponent.js";
+import { FluidSystem } from "./ecs/FluidSystem.js";
+import { GlobalFluidEffector } from "./effector/GlobalFluidEffector.js";
+import { ImpulseFluidEffector } from "./effector/ImpulseFluidEffector.js";
+import { SliceVisualiser } from "./SliceVisualiser.js";
+
+const harness = new EngineHarness();
+const metrics = new MetricCollection();
+metrics.create({ name: 'sim' });
+
+/**
+ * @param {Engine} engine
+ */
+function main(engine) {
+    const ecd = engine.entityManager.dataset;
+
+    const RES_X = 32, RES_Y = 32, RES_Z = 8;
+
+    // Fluid volume entity: holds the field + its world placement. The FluidSystem
+    // will step it each fixed update.
+    const fluid_component = new FluidComponent();
+    fluid_component.field.setResolution(RES_X, RES_Y, RES_Z);
+    fluid_component.field.addScalar("dye");
+    fluid_component.field.build();
+    fluid_component.origin = [0, 0, 0];
+    fluid_component.cell_size = 1; // world = grid for this demo
+
+    // Seed a dye blob in the middle so the advection is visually obvious.
+    const field = fluid_component.field;
+    for (let z = 1; z < RES_Z - 1; z++) {
+        for (let dy = -2; dy <= 2; dy++) {
+            for (let dx = -2; dx <= 2; dx++) {
+                field.setScalarAtIndex(0,
+                    (RES_X >> 1) + dx, (RES_Y >> 1) + dy, z,
+                    1);
+            }
+        }
+    }
+
+    new Entity().add(fluid_component).build(ecd);
+
+    // Effector entity: separate from the fluid volume. With cell_size=1 above, world
+    // coords here line up 1:1 with grid coords.
+    const effectors = new FluidEffectorsComponent();
+
+    const gravity = new GlobalFluidEffector();
+    gravity.force = [0, -5, 0];
+    effectors.addEffector(gravity);
+
+    const swirl = new ImpulseFluidEffector();
+    swirl.position = [RES_X >> 1, RES_Y >> 1, RES_Z >> 1];
+    swirl.force = [15, 0, 0];
+    swirl.radius = 3;
+    effectors.addEffector(swirl);
+
+    new Entity().add(effectors).build(ecd);
+
+    // Debug visualisation — a per-frame behavior, separate from the fluid stepping.
+    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")],
+        field.getResolution()
+    );
+
+    new Entity()
+        .add(BehaviorComponent.loop(() => {
+            // FluidSystem.fixedUpdate is what advances the sim; we just observe and
+            // time the draw cost here.
+            const t0 = performance.now();
+            slice_view.draw();
+            metrics.get('sim').record(performance.now() - t0);
+        }))
+        .build(ecd);
+
+    MetricCollectionConsoleMonitor.from(metrics).start();
+
+    new Entity()
+        .add(GUIElement.fromView(slice_view))
+        .build(ecd);
+}
+
+harness.initialize({
+    configuration(config, engine) {
+        config.addSystem(new GUIElementSystem(engine.gameView, engine));
+        config.addSystem(new BehaviorSystem(engine));
+        config.addSystem(new FluidSystem());
+    }
+}).then(main);

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

@@ -0,0 +1,33 @@
+/**
+ * Optimal SOR relaxation factor for the 7-point Laplacian on a cell-centered grid
+ * with Neumann boundaries (the discretisation {@link v3_grid_solve_pressure} uses).
+ *
+ * For a Poisson problem on a uniform grid of side `N`, the Jacobi iteration matrix
+ * has spectral radius `ρ_J ≈ cos(π/N)`. The classical optimal SOR factor is
+ *
+ *     ω_opt = 2 / (1 + √(1 - ρ_J²)) = 2 / (1 + sin(π/N))
+ *
+ * On non-cubic grids the slowest-converging mode has a wavelength bounded below by
+ * the longest side, so we use `N = max(res_x, res_y, res_z)`. This is slightly
+ * conservative on lopsided grids — the true optimum would also account for the
+ * shorter axes — but it never overshoots into the divergent ω ≥ 2 region, and the
+ * dropoff in convergence rate around the optimum is mild.
+ *
+ * Reference values:
+ *   N =   8 → ω ≈ 1.446
+ *   N =  16 → ω ≈ 1.674
+ *   N =  32 → ω ≈ 1.821
+ *   N =  64 → ω ≈ 1.906
+ *   N = 128 → ω ≈ 1.952
+ *
+ * Note the value is always in `(1, 2)` — `1 < ω` for `N ≥ 2`, and `ω → 2` as
+ * `N → ∞`. A hardcoded 1.7 is roughly correct for 16³ and dramatically too
+ * cautious for 128³.
+ *
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @returns {number} ω in (0, 2)
+ */
+export function optimal_sor_omega(res_x: number, res_y: number, res_z: number): number;
+//# sourceMappingURL=optimal_sor_omega.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"optimal_sor_omega.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/optimal_sor_omega.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,yCALW,MAAM,SACN,MAAM,SACN,MAAM,GACJ,MAAM,CASlB"}

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

@@ -0,0 +1,41 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Optimal SOR relaxation factor for the 7-point Laplacian on a cell-centered grid
+ * with Neumann boundaries (the discretisation {@link v3_grid_solve_pressure} uses).
+ *
+ * For a Poisson problem on a uniform grid of side `N`, the Jacobi iteration matrix
+ * has spectral radius `ρ_J ≈ cos(π/N)`. The classical optimal SOR factor is
+ *
+ *     ω_opt = 2 / (1 + √(1 - ρ_J²)) = 2 / (1 + sin(π/N))
+ *
+ * On non-cubic grids the slowest-converging mode has a wavelength bounded below by
+ * the longest side, so we use `N = max(res_x, res_y, res_z)`. This is slightly
+ * conservative on lopsided grids — the true optimum would also account for the
+ * shorter axes — but it never overshoots into the divergent ω ≥ 2 region, and the
+ * dropoff in convergence rate around the optimum is mild.
+ *
+ * Reference values:
+ *   N =   8 → ω ≈ 1.446
+ *   N =  16 → ω ≈ 1.674
+ *   N =  32 → ω ≈ 1.821
+ *   N =  64 → ω ≈ 1.906
+ *   N = 128 → ω ≈ 1.952
+ *
+ * Note the value is always in `(1, 2)` — `1 < ω` for `N ≥ 2`, and `ω → 2` as
+ * `N → ∞`. A hardcoded 1.7 is roughly correct for 16³ and dramatically too
+ * cautious for 128³.
+ *
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @returns {number} ω in (0, 2)
+ */
+export function optimal_sor_omega(res_x, res_y, res_z) {
+    assert.isPositiveInteger(res_x, "res_x");
+    assert.isPositiveInteger(res_y, "res_y");
+    assert.isPositiveInteger(res_z, "res_z");
+
+    const n = Math.max(res_x, res_y, res_z);
+    return 2 / (1 + Math.sin(Math.PI / n));
+}

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

@@ -1,9 +1,24 @@
 /**
+ * Semi-Lagrangian self-advection of a cell-centered 3D velocity field.
  *
- * @param {Float32Array[]} outputs
- * @param {Float32Array[]} inputs
- * @param {number[]} resolution
- * @param {number} time_delta
+ * For each cell, traces backward along the current velocity for one timestep, then
+ * trilinearly samples each input velocity component at that back-traced position.
+ * Stable for arbitrarily large `time_delta` (the trade-off is numerical diffusion;
+ * the field gets blurrier each step).
+ *
+ * Inputs and outputs must be disjoint Float32Arrays of length `res_x * res_y * res_z`.
+ * Cells flagged solid (non-zero in `solid`) keep their input value unchanged.
+ *
+ * @param {Float32Array[]} outputs   `[out_x, out_y, out_z]`, mutated.
+ * @param {Float32Array[]} inputs    `[in_x, in_y, in_z]`, read; expected to alias the
+ *                                   "current" velocity field that drives back-tracing.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta        Simulation timestep, in the same units as velocity
+ *                                   (grid-cells / second when used standalone).
+ * @param {Uint8Array} solid         Required cell flags (zero-filled for a wall-free
+ *                                   domain); non-zero cells are not updated.
  */
-export function v3_grid_apply_advection_forward(outputs: Float32Array[], inputs: Float32Array[], resolution: number[], time_delta: number): void;
+export function v3_grid_apply_advection_forward(outputs: Float32Array[], inputs: Float32Array[], res_x: number, res_y: number, res_z: number, time_delta: number, solid: Uint8Array): void;
 //# sourceMappingURL=v3_grid_apply_advection_forward.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_apply_advection_forward.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_advection_forward.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,yDALW,YAAY,EAAE,UACd,YAAY,EAAE,cACd,MAAM,EAAE,cACR,MAAM,QAsDhB"}
+{"version":3,"file":"v3_grid_apply_advection_forward.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_advection_forward.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yDAXW,YAAY,EAAE,UACd,YAAY,EAAE,SAEd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SAEN,UAAU,QA6DpB"}

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

@@ -1,61 +1,83 @@
+import { assert } from "../../../../core/assert.js";
 import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
 
 /**
+ * Semi-Lagrangian self-advection of a cell-centered 3D velocity field.
  *
- * @param {Float32Array[]} outputs
- * @param {Float32Array[]} inputs
- * @param {number[]} resolution
- * @param {number} time_delta
+ * For each cell, traces backward along the current velocity for one timestep, then
+ * trilinearly samples each input velocity component at that back-traced position.
+ * Stable for arbitrarily large `time_delta` (the trade-off is numerical diffusion;
+ * the field gets blurrier each step).
+ *
+ * Inputs and outputs must be disjoint Float32Arrays of length `res_x * res_y * res_z`.
+ * Cells flagged solid (non-zero in `solid`) keep their input value unchanged.
+ *
+ * @param {Float32Array[]} outputs   `[out_x, out_y, out_z]`, mutated.
+ * @param {Float32Array[]} inputs    `[in_x, in_y, in_z]`, read; expected to alias the
+ *                                   "current" velocity field that drives back-tracing.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta        Simulation timestep, in the same units as velocity
+ *                                   (grid-cells / second when used standalone).
+ * @param {Uint8Array} solid         Required cell flags (zero-filled for a wall-free
+ *                                   domain); non-zero cells are not updated.
  */
-export function v3_grid_apply_advection_forward(outputs, inputs, resolution, time_delta) {
+export function v3_grid_apply_advection_forward(outputs, inputs, res_x, res_y, res_z, time_delta, solid) {
+    assert.equal(outputs.length, 3, "outputs is a 3-component array");
+    assert.equal(inputs.length, 3, "inputs is a 3-component array");
 
-    const res_x = resolution[0];
-    const res_y = resolution[1];
-    const res_z = resolution[2];
+    const out_x = outputs[0];
+    const out_y = outputs[1];
+    const out_z = outputs[2];
 
-    const input_x = inputs[0];
-    const input_y = inputs[1];
-    const input_z = inputs[2];
+    const in_x = inputs[0];
+    const in_y = inputs[1];
+    const in_z = inputs[2];
 
-    const slice_size = res_y * res_x;
+    const cell_count = res_x * res_y * res_z;
 
-    for (
-        let z = 0;
-        z < res_z - 1;
-        z++
-    ) {
+    assert.greaterThanOrEqual(out_x.length, cell_count, "out_x covers grid");
+    assert.greaterThanOrEqual(out_y.length, cell_count, "out_y covers grid");
+    assert.greaterThanOrEqual(out_z.length, cell_count, "out_z covers grid");
+    assert.greaterThanOrEqual(in_x.length, cell_count, "in_x covers grid");
+    assert.greaterThanOrEqual(in_y.length, cell_count, "in_y covers grid");
+    assert.greaterThanOrEqual(in_z.length, cell_count, "in_z covers grid");
 
-        const current_z_slice_offset = z * slice_size;
+    assert.notEqual(out_x, in_x, "out_x must not alias in_x");
+    assert.notEqual(out_y, in_y, "out_y must not alias in_y");
+    assert.notEqual(out_z, in_z, "out_z must not alias in_z");
 
-        for (
-            let y = 0;
-            y < res_y;
-            y++
-        ) {
-            const current_y_line_offset = y * res_x;
+    const slice_size = res_x * res_y;
 
-            for (let x = 0; x < res_x; x++) {
+    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;
 
-                const current_index = current_z_slice_offset + current_y_line_offset + x;
+            for (let x = 0; x < res_x; x++) {
+                const c = z_off + y_off + x;
+
+                if (solid[c] !== 0) {
+                    out_x[c] = in_x[c];
+                    out_y[c] = in_y[c];
+                    out_z[c] = in_z[c];
+                    continue;
+                }
 
-                const v_x = input_x[current_index]
-                const v_y = input_y[current_index]
-                const v_z = input_z[current_index]
+                const v_x = in_x[c];
+                const v_y = in_y[c];
+                const v_z = in_z[c];
 
-                // compute previous position of the particle
+                // Trace back to where this parcel came from one timestep ago.
                 const s_x = x - v_x * time_delta;
                 const s_y = y - v_y * time_delta;
                 const s_z = z - v_z * time_delta;
 
-                // sample values at previous position
-                const new_x = scs3d_sample_linear(input_x, res_x, res_y, res_z, s_x, s_y, s_z);
-                const new_y = scs3d_sample_linear(input_y, res_x, res_y, res_z, s_x, s_y, s_z);
-                const new_z = scs3d_sample_linear(input_z, res_x, res_y, res_z, s_x, s_y, s_z);
-
-                outputs[0][current_index] = new_x;
-                outputs[1][current_index] = new_y;
-                outputs[2][current_index] = new_z;
+                out_x[c] = scs3d_sample_linear(in_x, res_x, res_y, res_z, s_x, s_y, s_z);
+                out_y[c] = scs3d_sample_linear(in_y, res_x, res_y, res_z, s_x, s_y, s_z);
+                out_z[c] = scs3d_sample_linear(in_z, res_x, res_y, res_z, s_x, s_y, s_z);
             }
         }
     }

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

@@ -1,8 +1,29 @@
 /**
+ * Implicit (Gauss-Seidel-like) Jacobi diffusion on a 3D cell-centered scalar grid.
  *
- * @param {Float32Array} output
- * @param {Float32Array} input
- * @param {number[]} resolution
+ * Solves the implicit diffusion equation `(I - a*L) x = x0` for `x`, where L is the
+ * discrete Laplacian. Solving implicitly is unconditionally stable for any `a >= 0`,
+ * which is why Stam's "Stable Fluids" uses it instead of an explicit step.
+ *
+ * Each iteration writes into a scratch buffer and swaps; after `iterations` rounds the
+ * final result is copied into `output`. Increasing `iterations` increases accuracy at
+ * linear cost; 4-20 is the usual range. Boundary cells use Neumann (reflective)
+ * conditions — missing neighbours are treated as equal to the cell itself, which
+ * reduces the effective denominator.
+ *
+ * Solid cells (marked non-zero in `solid`) are skipped: their value in `output` is
+ * left at the corresponding `x0` value.
+ *
+ * @param {Float32Array} output      Destination (size = res_x * res_y * res_z). Mutated.
+ * @param {Float32Array} x0          Source values to diffuse. NOT mutated.
+ * @param {Float32Array} scratch     Same size as output; used for ping-pong. Mutated.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} a                 Implicit diffusion coefficient (= dt * diffusion_rate).
+ * @param {number} iterations        Jacobi iteration count.
+ * @param {Uint8Array} solid         Required cell flags (zero-filled for a wall-free
+ *                                   domain); non-zero cells are not updated.
  */
-export function v3_grid_apply_diffusion(output: Float32Array, input: Float32Array, resolution: number[]): void;
+export function v3_grid_apply_diffusion(output: Float32Array, x0: Float32Array, scratch: Float32Array, res_x: number, res_y: number, res_z: number, a: number, iterations: number, solid: Uint8Array): void;
 //# sourceMappingURL=v3_grid_apply_diffusion.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_apply_diffusion.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_diffusion.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,gDAJW,YAAY,SACZ,YAAY,cACZ,MAAM,EAAE,QA6ElB"}
+{"version":3,"file":"v3_grid_apply_diffusion.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_diffusion.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,gDAXW,YAAY,MACZ,YAAY,WACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,KACN,MAAM,cACN,MAAM,SACN,UAAU,QA2EpB"}

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

@@ -1,82 +1,102 @@
+import { assert } from "../../../../core/assert.js";
+
 /**
+ * Implicit (Gauss-Seidel-like) Jacobi diffusion on a 3D cell-centered scalar grid.
+ *
+ * Solves the implicit diffusion equation `(I - a*L) x = x0` for `x`, where L is the
+ * discrete Laplacian. Solving implicitly is unconditionally stable for any `a >= 0`,
+ * which is why Stam's "Stable Fluids" uses it instead of an explicit step.
+ *
+ * Each iteration writes into a scratch buffer and swaps; after `iterations` rounds the
+ * final result is copied into `output`. Increasing `iterations` increases accuracy at
+ * linear cost; 4-20 is the usual range. Boundary cells use Neumann (reflective)
+ * conditions — missing neighbours are treated as equal to the cell itself, which
+ * reduces the effective denominator.
  *
- * @param {Float32Array} output
- * @param {Float32Array} input
- * @param {number[]} resolution
+ * Solid cells (marked non-zero in `solid`) are skipped: their value in `output` is
+ * left at the corresponding `x0` value.
+ *
+ * @param {Float32Array} output      Destination (size = res_x * res_y * res_z). Mutated.
+ * @param {Float32Array} x0          Source values to diffuse. NOT mutated.
+ * @param {Float32Array} scratch     Same size as output; used for ping-pong. Mutated.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} a                 Implicit diffusion coefficient (= dt * diffusion_rate).
+ * @param {number} iterations        Jacobi iteration count.
+ * @param {Uint8Array} solid         Required cell flags (zero-filled for a wall-free
+ *                                   domain); non-zero cells are not updated.
  */
-export function v3_grid_apply_diffusion(output, input, resolution) {
-    let sum = 0;
-
-    const res_x = resolution[0];
-    const res_y = resolution[1];
-    const res_z = resolution[2];
-
-
-    const slice_size = res_y * res_x;
-
-    // TODO consider taking inspiration from blur filters and performing convolution in 3 separate steps, one per axis. This would require fewer samples in total and potentially offer better cache utilization
-
-    const last_z_slice_offset = (res_z - 1) * slice_size;
-    const last_y_line_offset = (res_y - 1) * res_x;
-
-    for (
-        let current_z_slice_offset = 0;
-        current_z_slice_offset <= last_z_slice_offset;
-        current_z_slice_offset += slice_size
-    ) {
-
-        for (
-            let current_y_line_offset = 0;
-            current_y_line_offset <= last_y_line_offset;
-            current_y_line_offset += res_x
-        ) {
-
-            for (let x = 0; x < res_x; x++) {
-
-                let sample_count = 1;
-
-                sum = 0;
-
-                // sample cells around
-                if (current_z_slice_offset > 0) {
-                    sample_count++;
-                    sum += input[current_z_slice_offset - slice_size + current_y_line_offset + x]
-                }
-
-
-                if (current_y_line_offset > 0) {
-                    sample_count++;
-                    sum += input[current_z_slice_offset + current_y_line_offset - res_x + x]
-                }
-
-                if (x > 0) {
-                    sample_count++;
-                    sum += input[current_z_slice_offset + current_y_line_offset + (x - 1)]
-                }
-
-
-                const current = current_z_slice_offset + current_y_line_offset + x;
-
-                sum += input[current];
-
-                if (x < res_x - 1) {
-                    sample_count++;
-                    sum += input[current_z_slice_offset + current_y_line_offset + (x + 1)]
-                }
-
-                if (current_y_line_offset < last_y_line_offset) {
-                    sample_count++;
-                    sum += input[current_z_slice_offset + current_y_line_offset + res_x + x]
-                }
+export function v3_grid_apply_diffusion(output, x0, scratch, res_x, res_y, res_z, a, iterations, solid) {
+    assert.notEqual(output, x0, "output must differ from x0 (x0 is the source and must not be mutated)");
+    assert.notEqual(output, scratch, "output must differ from scratch");
+    assert.notEqual(x0, scratch, "x0 must differ from scratch");
+    assert.greaterThanOrEqual(output.length, res_x * res_y * res_z, "output covers grid");
+    assert.greaterThanOrEqual(x0.length, res_x * res_y * res_z, "x0 covers grid");
+    assert.greaterThanOrEqual(scratch.length, res_x * res_y * res_z, "scratch covers grid");
+    assert.greaterThanOrEqual(a, 0, "a");
+    assert.isNonNegativeInteger(iterations, "iterations");
+
+    // Seed first iterate with x0.
+    output.set(x0);
+
+    if (iterations === 0 || a === 0) {
+        return;
+    }
 
-                if (current_z_slice_offset < last_z_slice_offset) {
-                    sample_count++;
-                    sum += input[current_z_slice_offset + slice_size + current_y_line_offset + x]
+    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;
+
+    let prev = output;
+    let next = scratch;
+
+    for (let iter = 0; iter < iterations; iter++) {
+
+        for (let z = 0; z < res_z; z++) {
+            const z_off = z * slice_size;
+            const has_zm = z > 0;
+            const has_zp = z < last_z;
+
+            for (let y = 0; y < res_y; y++) {
+                const y_off = y * res_x;
+                const has_ym = y > 0;
+                const has_yp = y < last_y;
+
+                for (let x = 0; x < res_x; x++) {
+                    const c = z_off + y_off + x;
+
+                    if (solid[c] !== 0) {
+                        next[c] = x0[c];
+                        continue;
+                    }
+
+                    let sum = 0;
+                    let count = 0;
+
+                    if (x > 0)       { sum += prev[c - 1];          count++; }
+                    if (x < last_x)  { sum += prev[c + 1];          count++; }
+                    if (has_ym)      { sum += prev[c - res_x];      count++; }
+                    if (has_yp)      { sum += prev[c + res_x];      count++; }
+                    if (has_zm)      { sum += prev[c - slice_size]; count++; }
+                    if (has_zp)      { sum += prev[c + slice_size]; count++; }
+
+                    // Implicit Jacobi update with Neumann boundary correction:
+                    // missing neighbours contribute as if equal to the cell, which is
+                    // equivalent to dropping them from both the numerator and the
+                    // denominator factor on `a`.
+                    next[c] = (x0[c] + a * sum) / (1 + a * count);
                 }
-
-                output[current] = sum / sample_count;
-
             }
         }
+
+        const tmp = prev;
+        prev = next;
+        next = tmp;
+    }
+
+    if (prev !== output) {
+        output.set(prev);
     }
 }