@woosh/meep-engine 2.156.0 → 2.158.0

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

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

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

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

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

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

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

@@ -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;;CA8RJ;sCAjZqC,4BAA4B"}