@woosh/meep-engine 2.155.0 → 2.157.0

package/src/engine/physics/fluid/FluidField.d.ts

@@ -62,14 +62,34 @@ export class FluidField {
      * consulting the {@link solid} array.
      *
      * Computed once by {@link recomputeSolidNeighbourMask} after every solid-mask
-     * mutation. The simulator runs that recompute at the top of every project()
-     * call so callers never have to remember to invalidate it; the per-step cost
-     * is one O(N) byte-pass against the bandwidth-bound SOR sweep that runs many
-     * iterations per call.
+     * mutation. The simulator runs that recompute once per step (after effectors,
+     * which may splat solids) and at the top of every direct project() call, so
+     * callers never have to remember to invalidate it; the per-step cost is one
+     * O(N) byte-pass against the bandwidth-bound SOR sweep that runs many
+     * iterations per call. {@link shift} also refreshes it after migrating the
+     * solid mask.
      *
      * @type {Uint8Array|null}
      */
     solid_neighbour_mask: Uint8Array | null;
+    /**
+     * Per-cell pressure-Laplacian diagonal, baked alongside
+     * {@link solid_neighbour_mask} by the same kernel pass:
+     *
+     *     diag = (# fluid neighbours) + (# open faces)
+     *
+     * where an open face is one on the domain edge (out-of-bounds neighbour).
+     * The domain edge is an OPEN boundary — ghost pressure 0 — so flow can
+     * vent through it; solid faces are reflecting (Neumann) and drop out of
+     * the diagonal. A solid cell, or a fluid cell sealed on all six faces,
+     * has `diag = 0`, which is the solvers' single skip test. Sealed domains
+     * are built explicitly by lining the boundary with solid cells.
+     *
+     * Same freshness contract as {@link solid_neighbour_mask}.
+     *
+     * @type {Uint8Array|null}
+     */
+    pressure_diag: Uint8Array | null;
     /**
      * Pressure field from the most recent projection. Owned by the field rather than
      * the simulator because the simulator warm-starts each solve from the previous
@@ -263,14 +283,15 @@ export class FluidField {
      */
     hash(): number;
     /**
-     * Rebuild {@link solid_neighbour_mask} from the current {@link solid} buffer.
+     * Rebuild {@link solid_neighbour_mask} and {@link pressure_diag} from the
+     * current {@link solid} buffer.
      *
-     * O(N) — one byte-write per cell, six byte-reads per cell. Called by the
-     * simulator at the top of each project so callers never have to remember to
-     * invalidate the mask after mutating solids; the cost is amortized across the
-     * SOR sweep's many iterations.
+     * O(N) — two byte-writes per cell, six byte-reads per cell. Called by the
+     * simulator once per step and at the top of each direct project() call, so
+     * callers never have to remember to invalidate the mask after mutating
+     * solids; the cost is amortized across the SOR sweep's many iterations.
      *
-     * Encoding: see {@link solid_neighbour_mask}.
+     * Encoding: see {@link solid_neighbour_mask} and {@link pressure_diag}.
      */
     recomputeSolidNeighbourMask(): void;
     /**
@@ -288,13 +309,20 @@ export class FluidField {
      * `(0, 0, 0)` is a no-op; |shift| ≥ res on any axis zero-fills (no valid source
      * left to replicate from). Pre-build fields (buffers null) are no-op'd.
      *
-     * The solid mask is NOT migrated — it's cleared. Solids are out of scope for the
-     * shift machinery: the contract is that the caller re-voxelizes scene geometry
-     * and splats updated solid cells back into the field before the next simulation
-     * tick. Migrating the existing mask would either lie about where the walls are
-     * (if scene geometry moved) or produce double-bookkeeping problems if the caller
-     * also re-voxelizes. Clearing keeps the contract obvious: "between a shift and
-     * the next step, the field has no solids until you write them."
+     * The solid mask is migrated like every other buffer — solids are anchored to
+     * world space exactly like the fluid they bound, so a wall must stay where the
+     * world says it is when the grid hops a cell. Newly scrolled-in cells become
+     * fluid (`0`): the field knows nothing about un-simulated space, and "empty
+     * until a voxelizer says otherwise" is the only honest default. Callers that
+     * voxelize scene geometry can keep overwriting the mask each tick — the
+     * migrated values are then simply replaced. (Earlier behaviour cleared the
+     * whole mask on shift, which made every grid hop simulate one tick with no
+     * walls anywhere — fluid leaked through geometry until the caller re-splatted.)
+     *
+     * The derived {@link solid_neighbour_mask} is refreshed here too, so the field
+     * stays self-consistent for direct kernel users; the simulator's per-step
+     * refresh makes this redundant in the ECS path but shifts are rare (once per
+     * cell crossing) and the pass is one byte-write per cell.
      *
      * @param {number} shift_x  integer
      * @param {number} shift_y  integer

package/src/engine/physics/fluid/FluidField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidField.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidField.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAQI;;;;OAIG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;OAEG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;OAEG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;;;OAMG;IACH,OAFU,UAAU,GAAC,IAAI,CAEZ;IAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,sBAFU,UAAU,GAAC,IAAI,CAEG;IAE5B;;;;;;;;;;;;;OAaG;IACH,UAFU,YAAY,kBAAc,IAAI,CAExB;IAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,yBAFU,OAAO,CAEe;IAShC;;;;;;OAMG;IACH,qBAJW,MAAM,SACN,MAAM,SACN,MAAM,QAWhB;IAED;;;OAGG;IACH,iBAHY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAKnC;IAED;;;OAGG;IACH,aAHY,MAAM,CAKjB;IAED;;;;;;;;;OASG;IACH,gBAHW,MAAM,GACL,MAAM,CAejB;IAED;;;OAGG;IACH,kBAHW,MAAM,GACL,MAAM,CAIjB;IAED;;;;OAIG;IACH,oBAJW,MAAM,GACL,YAAY,GAAC,IAAI,CAM5B;IAED;;OAEG;IACH,uBAFY;QAAE,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE,CAIjD;IAED;;;OAGG;IACH,cAmBC;IAED;;;;;;OAMG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAajB;IAED;;;;;;;;OAQG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAOhB;IAED;;;;;;;;OAQG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,kCANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,SACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,cALW,MAAM,KACN,MAAM,KACN,MAAM,YACN,OAAO,QAIjB;IAED;;;;;OAKG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,OAAO,CAIlB;IAED;;;;;;;;OAQG;IACH,oBANW,YAAY,GAAC,MAAM,EAAE,KACrB,MAAM,KACN,MAAM,KACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAUhC;IAED;;;;;;;OAOG;IACH,mBANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAMjB;IAED;;;;;;;;;;OAUG;IACH,cAHW,UAAU,GACT,OAAO,CAqDlB;IAED;;;;;;;;;;;OAWG;IACH,QAFY,MAAM,CAajB;IAED;;;;;;;;;OASG;IACH,oCASC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,eAJW,MAAM,WACN,MAAM,WACN,MAAM,QAyChB;IAED;;;;OAIG;IACH,cASC;;CACJ"}
+{"version":3,"file":"FluidField.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidField.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAQI;;;;OAIG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;OAEG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;OAEG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;;;OAMG;IACH,OAFU,UAAU,GAAC,IAAI,CAEZ;IAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,sBAFU,UAAU,GAAC,IAAI,CAEG;IAE5B;;;;;;;;;;;;;;;;OAgBG;IACH,eAFU,UAAU,GAAC,IAAI,CAEJ;IAErB;;;;;;;;;;;;;OAaG;IACH,UAFU,YAAY,kBAAc,IAAI,CAExB;IAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,yBAFU,OAAO,CAEe;IAShC;;;;;;OAMG;IACH,qBAJW,MAAM,SACN,MAAM,SACN,MAAM,QAWhB;IAED;;;OAGG;IACH,iBAHY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAKnC;IAED;;;OAGG;IACH,aAHY,MAAM,CAKjB;IAED;;;;;;;;;OASG;IACH,gBAHW,MAAM,GACL,MAAM,CAejB;IAED;;;OAGG;IACH,kBAHW,MAAM,GACL,MAAM,CAIjB;IAED;;;;OAIG;IACH,oBAJW,MAAM,GACL,YAAY,GAAC,IAAI,CAM5B;IAED;;OAEG;IACH,uBAFY;QAAE,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE,CAIjD;IAED;;;OAGG;IACH,cAoBC;IAED;;;;;;OAMG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAajB;IAED;;;;;;;;OAQG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAOhB;IAED;;;;;;;;OAQG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,kCANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,SACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,cALW,MAAM,KACN,MAAM,KACN,MAAM,YACN,OAAO,QAIjB;IAED;;;;;OAKG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,OAAO,CAIlB;IAED;;;;;;;;OAQG;IACH,oBANW,YAAY,GAAC,MAAM,EAAE,KACrB,MAAM,KACN,MAAM,KACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAUhC;IAED;;;;;;;OAOG;IACH,mBANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAMjB;IAED;;;;;;;;;;OAUG;IACH,cAHW,UAAU,GACT,OAAO,CAqDlB;IAED;;;;;;;;;;;OAWG;IACH,QAFY,MAAM,CAajB;IAED;;;;;;;;;;OAUG;IACH,oCAUC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,eAJW,MAAM,WACN,MAAM,WACN,MAAM,QAuChB;IAED;;;;OAIG;IACH,cASC;;CACJ"}

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

@@ -4,6 +4,7 @@ import { is_typed_array_equals } from "../../../core/collection/array/typed/is_t
 import { sparse_typed_array_hash } from "../../../core/collection/array/typed/sparse_typed_array_hash.js";
 import { scs3d_sample_linear } from "../../graphics/texture/3d/scs3d_sample_linear.js";
 import { v3_grid_compute_solid_neighbour_mask } from "./solver/v3_grid_compute_solid_neighbour_mask.js";
+import { v3_grid_patch_edges_constant } from "./solver/v3_grid_patch_edges_constant.js";
 import { v3_grid_patch_edges_uniform } from "./solver/v3_grid_patch_edges_uniform.js";
 import { v3_grid_shift_in_place } from "./solver/v3_grid_shift_in_place.js";
 
@@ -82,15 +83,36 @@ export class FluidField {
      * consulting the {@link solid} array.
      *
      * Computed once by {@link recomputeSolidNeighbourMask} after every solid-mask
-     * mutation. The simulator runs that recompute at the top of every project()
-     * call so callers never have to remember to invalidate it; the per-step cost
-     * is one O(N) byte-pass against the bandwidth-bound SOR sweep that runs many
-     * iterations per call.
+     * mutation. The simulator runs that recompute once per step (after effectors,
+     * which may splat solids) and at the top of every direct project() call, so
+     * callers never have to remember to invalidate it; the per-step cost is one
+     * O(N) byte-pass against the bandwidth-bound SOR sweep that runs many
+     * iterations per call. {@link shift} also refreshes it after migrating the
+     * solid mask.
      *
      * @type {Uint8Array|null}
      */
     solid_neighbour_mask = null;
 
+    /**
+     * Per-cell pressure-Laplacian diagonal, baked alongside
+     * {@link solid_neighbour_mask} by the same kernel pass:
+     *
+     *     diag = (# fluid neighbours) + (# open faces)
+     *
+     * where an open face is one on the domain edge (out-of-bounds neighbour).
+     * The domain edge is an OPEN boundary — ghost pressure 0 — so flow can
+     * vent through it; solid faces are reflecting (Neumann) and drop out of
+     * the diagonal. A solid cell, or a fluid cell sealed on all six faces,
+     * has `diag = 0`, which is the solvers' single skip test. Sealed domains
+     * are built explicitly by lining the boundary with solid cells.
+     *
+     * Same freshness contract as {@link solid_neighbour_mask}.
+     *
+     * @type {Uint8Array|null}
+     */
+    pressure_diag = null;
+
     /**
      * Pressure field from the most recent projection. Owned by the field rather than
      * the simulator because the simulator warm-starts each solve from the previous
@@ -244,6 +266,7 @@ export class FluidField {
         this.velocity_z = new Float32Array(cell_count);
         this.solid = new Uint8Array(cell_count);
         this.solid_neighbour_mask = new Uint8Array(cell_count);
+        this.pressure_diag = new Uint8Array(cell_count);
         const PressureCtor = this.half_precision_pressure ? Float16Array : Float32Array;
         this.pressure = new PressureCtor(cell_count);
 
@@ -464,14 +487,15 @@ export class FluidField {
     }
 
     /**
-     * Rebuild {@link solid_neighbour_mask} from the current {@link solid} buffer.
+     * Rebuild {@link solid_neighbour_mask} and {@link pressure_diag} from the
+     * current {@link solid} buffer.
      *
-     * O(N) — one byte-write per cell, six byte-reads per cell. Called by the
-     * simulator at the top of each project so callers never have to remember to
-     * invalidate the mask after mutating solids; the cost is amortized across the
-     * SOR sweep's many iterations.
+     * O(N) — two byte-writes per cell, six byte-reads per cell. Called by the
+     * simulator once per step and at the top of each direct project() call, so
+     * callers never have to remember to invalidate the mask after mutating
+     * solids; the cost is amortized across the SOR sweep's many iterations.
      *
-     * Encoding: see {@link solid_neighbour_mask}.
+     * Encoding: see {@link solid_neighbour_mask} and {@link pressure_diag}.
      */
     recomputeSolidNeighbourMask() {
         if (!this.#built) {
@@ -479,6 +503,7 @@ export class FluidField {
         }
         v3_grid_compute_solid_neighbour_mask(
             this.solid_neighbour_mask,
+            this.pressure_diag,
             this.solid,
             this.#resolution[0], this.#resolution[1], this.#resolution[2]
         );
@@ -499,13 +524,20 @@ export class FluidField {
      * `(0, 0, 0)` is a no-op; |shift| ≥ res on any axis zero-fills (no valid source
      * left to replicate from). Pre-build fields (buffers null) are no-op'd.
      *
-     * The solid mask is NOT migrated — it's cleared. Solids are out of scope for the
-     * shift machinery: the contract is that the caller re-voxelizes scene geometry
-     * and splats updated solid cells back into the field before the next simulation
-     * tick. Migrating the existing mask would either lie about where the walls are
-     * (if scene geometry moved) or produce double-bookkeeping problems if the caller
-     * also re-voxelizes. Clearing keeps the contract obvious: "between a shift and
-     * the next step, the field has no solids until you write them."
+     * The solid mask is migrated like every other buffer — solids are anchored to
+     * world space exactly like the fluid they bound, so a wall must stay where the
+     * world says it is when the grid hops a cell. Newly scrolled-in cells become
+     * fluid (`0`): the field knows nothing about un-simulated space, and "empty
+     * until a voxelizer says otherwise" is the only honest default. Callers that
+     * voxelize scene geometry can keep overwriting the mask each tick — the
+     * migrated values are then simply replaced. (Earlier behaviour cleared the
+     * whole mask on shift, which made every grid hop simulate one tick with no
+     * walls anywhere — fluid leaked through geometry until the caller re-splatted.)
+     *
+     * The derived {@link solid_neighbour_mask} is refreshed here too, so the field
+     * stays self-consistent for direct kernel users; the simulator's per-step
+     * refresh makes this redundant in the ECS path but shifts are rare (once per
+     * cell crossing) and the pass is one byte-write per cell.
      *
      * @param {number} shift_x  integer
      * @param {number} shift_y  integer
@@ -533,12 +565,10 @@ export class FluidField {
         v3_grid_shift_in_place(this.velocity_z, rx, ry, rz, shift_x, shift_y, shift_z);
         v3_grid_patch_edges_uniform(this.velocity_z, rx, ry, rz, shift_x, shift_y, shift_z);
 
-        // Solid mask — cleared, not migrated. Caller is expected to re-voxelize and
-        // splat solids before the next simulation tick (see method docstring).
-        // The derived neighbour mask is cleared too; the simulator's next project()
-        // will repopulate it from the (potentially re-splatted) solid mask.
-        this.solid.fill(0);
-        this.solid_neighbour_mask.fill(0);
+        // Solid mask — world-anchored like the fluid; scrolled-in cells are fluid.
+        v3_grid_shift_in_place(this.solid, rx, ry, rz, shift_x, shift_y, shift_z);
+        v3_grid_patch_edges_constant(this.solid, rx, ry, rz, shift_x, shift_y, shift_z, 0);
+        v3_grid_compute_solid_neighbour_mask(this.solid_neighbour_mask, this.pressure_diag, this.solid, rx, ry, rz);
 
         // Pressure (warm-start state, carried across steps).
         v3_grid_shift_in_place(this.pressure, rx, ry, rz, shift_x, shift_y, shift_z);

package/src/engine/physics/fluid/FluidSimulator.d.ts

@@ -18,6 +18,25 @@ export namespace PressureSolver {
     let SOR: string;
     let MICPCG: string;
 }
+/**
+ * Velocity / scalar transport scheme selection.
+ *
+ *   - `"semi-lagrangian"` — first-order back-trace + trilinear gather (Stam
+ *     1999). Cheapest; strongly dissipative — a vortex loses half its kinetic
+ *     energy per second at production settings (see quality.spec.js).
+ *
+ *   - `"maccormack"` — unconditionally stable MacCormack (Selle et al. 2008):
+ *     a forward and a backward semi-Lagrangian pass with error correction and
+ *     a monotone min-max limiter. Second-order accurate in space and time at
+ *     ~2× the advection cost — and advection is the minority of step() cost
+ *     next to pressure, so the end-to-end price is small. Allocates 3
+ *     additional N-sized scratch buffers, shared with the reflection scheme.
+ */
+export type AdvectionScheme = string;
+export namespace AdvectionScheme {
+    let SEMI_LAGRANGIAN: string;
+    let MACCORMACK: string;
+}
 /**
  * Cell-centered 3D Stable Fluids solver (Stam, 1999/2003).
  *
@@ -29,12 +48,16 @@ export namespace PressureSolver {
  * the field). Scratch is cached by cell-count so per-step allocation stays at zero.
  *
  * Per step:
- *   1. Apply external forces (effectors mutate field velocity).
+ *   1. Apply external forces (effectors mutate field velocity), then the
+ *      optional exponential velocity damping.
  *   2. Diffuse velocity (viscosity; skipped when `velocity_diffusion_rate == 0`).
- *   3. Project (pressure solve + gradient subtract) to enforce ∇·v ≈ 0.
- *   4. Self-advect velocity (semi-Lagrangian back-trace).
- *   5. Project again (advection introduces small divergence).
- *   6. For each scalar attribute on the field: optionally diffuse, then advect.
+ *   3-5. Transport block — either the Stam reference sequence
+ *      project₁ → advect → project₂, or (default) the advection-reflection
+ *      form of the same two projections (see {@link advection_reflection}).
+ *      Advection itself is semi-Lagrangian or MacCormack per
+ *      {@link advection_scheme}.
+ *   6. For each scalar attribute on the field: optionally diffuse, then advect
+ *      with the same scheme.
  *
  * Pressure is warm-started from the previous step's solution (`field.pressure`),
  * which converges much faster than starting from zero once the flow reaches a
@@ -56,6 +79,24 @@ export namespace PressureSolver {
  * @type {number}
  */
 export const PRESSURE_ITERATIONS_FLOOR: number;
+/**
+ * Relative convergence tolerance handed to the MIC-PCG pressure solve: the
+ * solver stops as soon as `max|r| <= tolerance * max|−div|`. The iteration
+ * cap from {@link FluidSimulator#resolvePressureIterations} is sized for the
+ * cold-start worst case; warm-started production frames converge much
+ * earlier, and without a tolerance exit every warm frame would pay the full
+ * cold-start budget for no quality gain.
+ *
+ * 1e-3 sits below visual-fluids noticeability and below the collocated
+ * operator-mismatch floor that dominates post-projection divergence (see
+ * quality.spec.js) — iterating past it buys nothing visible.
+ *
+ * SOR has no equivalent exit: it never computes its residual (doing so would
+ * add a pass per sweep), so its cost is governed by the iteration count alone.
+ *
+ * @type {number}
+ */
+export const PCG_RELATIVE_TOLERANCE: number;
 export class FluidSimulator {
     /**
      * Implicit-diffusion coefficient (= viscosity * dt-like scaling). 0 disables.
@@ -79,6 +120,27 @@ export class FluidSimulator {
      * @type {number}
      */
     scalar_diffusion_iterations: number;
+    /**
+     * Exponential velocity damping rate, per second. Each step multiplies the
+     * whole velocity field by `exp(-velocity_damping * dt)` right after
+     * effectors run. `0` (default) disables — no pass is made.
+     *
+     * Why it exists: the solver has no other dissipation mechanism that bounds
+     * energy under sustained forcing. Incompressible projection cannot oppose
+     * a uniform body force (a uniform field is divergence-free), so a constant
+     * {@link GlobalFluidEffector} accelerates the fluid without limit — there
+     * is no terminal state. A small damping rate gives constant forcing a
+     * terminal velocity of approximately `acceleration / velocity_damping`
+     * and makes transient gusts decay back to calm, which is what wind-field
+     * use cases want (drive with {@link AmbientWindFluidEffector} for a
+     * specific ambient target instead of a force).
+     *
+     * The exponential form is frame-rate independent: two half-steps damp
+     * exactly as much as one full step.
+     *
+     * @type {number}
+     */
+    velocity_damping: number;
     /**
      * Which pressure solver to use. `PressureSolver.SOR` (default) is the
      * baseline red-black Successive Over-Relaxation. `PressureSolver.MICPCG`
@@ -96,6 +158,74 @@ export class FluidSimulator {
      * @type {string}
      */
     pressure_solver: string;
+    /**
+     * Vorticity-confinement strength ε, per second (Fedkiw et al. 2001). Each
+     * step deposits `ε·dt·(N × ω)` as a velocity increment, sharpening vortex
+     * cores that coarse grids and dissipative transport smear away. `0`
+     * (default) disables — no pass is made.
+     *
+     * Confinement ADDS energy by design; pair non-zero values with
+     * {@link velocity_damping} so gusts still decay. Visual-smoke territory
+     * starts around `ε ≈ 5–30` at 60 Hz (epsilon_dt 0.1–0.5).
+     *
+     * Cost when enabled: two extra O(N) passes (curl + force) using existing
+     * scratch — no allocations.
+     *
+     * @type {number}
+     */
+    vorticity_confinement: number;
+    /**
+     * Which transport scheme advects velocity and scalars — see
+     * {@link AdvectionScheme}.
+     *
+     * **Default semi-Lagrangian — MacCormack is gated on a MAC-staggered
+     * grid.** On the current collocated discretization the projection has an
+     * operator-mismatch floor (high-frequency divergence it cannot see, let
+     * alone remove — quality.spec.js scenario 7), and MacCormack's
+     * anti-diffusive corrector amplifies exactly that residue instead of
+     * letting first-order smearing absorb it. Measured on the sealed-vortex
+     * scenario: kinetic energy transiently grows to **1.9×** within 10 s
+     * (vs SL's monotone decay), and a passive scalar's total mass inflates
+     * **1.8×** in one second of orbiting. The kernels are correct in
+     * isolation (their specs transport clean fields sharply and monotonely) —
+     * it is the interaction with the collocated pressure floor that is
+     * unstable. Flip this on once the grid is staggered.
+     *
+     * @type {string}
+     */
+    advection_scheme: string;
+    /**
+     * Replace the plain "project → advect → project" sequence with the
+     * advection-reflection scheme (Zehnder, Narain, Thomaszewski 2018):
+     *
+     *     ũ  = advect(u, u, dt/2)        — half-step self-advection
+     *     u½ = project(ũ)
+     *     û  = 2·u½ − ũ                  — energy-preserving reflection
+     *     u′ = advect(û, u½, dt/2)       — transport the REFLECTED field
+     *                                       along the PROJECTED one
+     *     u₁ = project(u′)
+     *
+     * Same two pressure solves as the default double-projection Stam step,
+     * and two half-dt advections instead of one full-dt one — measured cost
+     * +20% of step() at 32×8×32. The reflection replaces the
+     * energy-DISSIPATING first projection with an energy-PRESERVING
+     * reflection about the divergence-free subspace.
+     *
+     * Default ON: with semi-Lagrangian advection this is measured stable
+     * (sealed-vortex kinetic energy never exceeds 0.99× its initial over
+     * 10 s) while retaining visibly more swirl — peak vorticity 0.73 vs 0.62
+     * after one second (quality.spec.js scenario 2b). With MacCormack it
+     * compounds the collocated-floor amplification (3.4× energy growth) —
+     * see {@link advection_scheme}; that combination should wait for MAC
+     * staggering.
+     *
+     * Only consulted when {@link project_before_advection} is true — the
+     * scheme is defined around the mid-step projection. With
+     * `project_before_advection = false` this flag is ignored.
+     *
+     * @type {boolean}
+     */
+    advection_reflection: boolean;
     /**
      * Run the pressure projection *before* self-advection in addition to after.
      *
@@ -175,6 +305,12 @@ export class FluidSimulator {
      * because tests and external code may need to project on demand (e.g., after
      * splatting an out-of-band impulse). `field.pressure` is read as the warm-start
      * initial guess and written with the new solution.
+     *
+     * Refreshes the field's solid-neighbour mask itself, so direct callers never
+     * have to remember invalidation after mutating solids. {@link step} refreshes
+     * the mask once for the whole step and uses the private no-recompute variant
+     * for both of its projections.
+     *
      * @param {FluidField} field
      */
     project(field: FluidField): void;

package/src/engine/physics/fluid/FluidSimulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidSimulator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidSimulator.js"],"names":[],"mappings":";;;;;;;;;;;;;;;6BAyBU,MAAM;;;;;AAOhB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;;;;;;;;;GASG;AACH,wCAFU,MAAM,CAE2B;AAE3C;IAEI;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,+BAFU,MAAM,CAEkB;IAElC;;;;;OAKG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,6BAFU,MAAM,CAEgB;IAEhC;;;;;;;;;;;;;;;OAeG;IACH,iBAFU,MAAM,CAEqB;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,0BAFU,OAAO,CAEe;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,0BAFU,MAAM,CAEgB;IA+EhC;;;;;;;;;;;;OAYG;IACH,iCALW,MAAM,SACN,MAAM,SACN,MAAM,GACL,MAAM,CAUjB;IAED;;;;;;OAMG;IACH,iCAkDC;IAqBD;;;;;;;;;;;;;OAaG;IACH,oCAVW,MAAM,aAEN,uBAAuB,iBACvB,YAAY,GAAC,MAAM,EAAE,QAyF/B;;CACJ"}
+{"version":3,"file":"FluidSimulator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidSimulator.js"],"names":[],"mappings":";;;;;;;;;;;;;;;6BA4BU,MAAM;;;;;;;;;;;;;;;;;;;8BAqBN,MAAM;;;;;AAOhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;;;;;;;;;GASG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;;;;;;;;;;;;;GAgBG;AACH,qCAFU,MAAM,CAE2B;AAE3C;IAEI;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,+BAFU,MAAM,CAEkB;IAElC;;;;;OAKG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,6BAFU,MAAM,CAEgB;IAEhC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;;;;;;;;;;OAeG;IACH,iBAFU,MAAM,CAEqB;IAErC;;;;;;;;;;;;;;OAcG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,kBAFU,MAAM,CAEmC;IAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,sBAFU,OAAO,CAEW;IAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,0BAFU,OAAO,CAEe;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,0BAFU,MAAM,CAEgB;IA4IhC;;;;;;;;;;;;OAYG;IACH,iCALW,MAAM,SACN,MAAM,SACN,MAAM,GACL,MAAM,CAUjB;IAED;;;;;;;;;;;;OAYG;IACH,iCAGC;IAuED;;;;;;;;;;;;;OAaG;IACH,oCAVW,MAAM,aAEN,uBAAuB,iBACvB,YAAY,GAAC,MAAM,EAAE,QA4K/B;;CACJ"}