@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -1,9 +1,11 @@
 /**
- * The global atmosphere: every fluid face in every field integrates the same
- * linear flow model each step,
+ * The global atmosphere: the air nothing else touches, everywhere. Every fluid face in
+ * every field follows the same linear flow model,
  *
  *     dv/dt = force + drag · (wind − v)
  *
+ * plus a gust carried on top of the wind.
+ *
  * One effector covers the whole family of "push everything" behaviours —
  * pick the regime by which fields you set:
  *
@@ -14,7 +16,7 @@
  *     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
+ *     velocity at `drag` per second; wakes and splats decay back to
  *     the ambient flow. The fixed point is exactly `wind`.
  *
  *   - **`force` + `drag` (+ `wind`)** — bounded forcing with a terminal
@@ -26,21 +28,32 @@
  *     is the solver-level stability knob that exists even when no effectors
  *     are wired.)
  *
+ *   - **`gust`** — weather on top of the wind: three sinusoids per axis, bounded
+ *     by `gust` per axis, which the air carries rather than relaxes toward. See
+ *     {@link gust}.
+ *
  * `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:
+ * ## The far field
  *
- *     v ← v∞ + (v − v∞) · e^(−drag·dt),   v∞ = wind + force / drag
+ * In a scene, globals act through {@link FluidEffectorsSystem}: once a tick it folds
+ * every global into one far field — `D = Σ drag`, the drag-weighted mean of the
+ * winds, the sum of the gusts and the sum of the forces — and integrates
+ * `v_far = u + g`, where `u` relaxes toward the mean wind at `D` and `g` is the summed
+ * gust, unfiltered. {@link FluidSystem} and {@link WorkerFluidSystem} then bring every
+ * field to that far field once a step through the atmosphere identity
+ * (`fluid_apply_atmosphere`), so several globals act as one, whatever order they are
+ * in. A global has no `apply` of its own: it acts only through the far field, and
+ * `FluidSimulator#step` refuses one handed to it in its effector list.
  *
- * (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.
+ * `force` is not part of the far field: it is a term inside CPU fields, applied exactly
+ * in the same step.
  *
- * 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.
+ * All quantities are WORLD-space: `force` in units/s², `wind` and `gust` in units/s,
+ * `drag` in 1/s. The `world_to_grid` matrix's linear part converts the vectors per
+ * field, 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
@@ -64,12 +77,59 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
     /**
      * 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`
+     * wakes linger. A disturbance decays to ~37% in `1/drag`
      * seconds. `0` disables the relaxation term entirely.
      *
      * @type {number}
      */
     drag: number;
+    /**
+     * Peak gust speed on top of the wind, WORLD units per second: a bound, `|g| ≤ gust`
+     * on every axis, since the component amplitudes 4/7, 2/7 and 1/7 sum to one. Cloth reads it
+     * through the far field (`ClothGPUFluidWind`, `ClothFluidWind`); the gust cloth once kept
+     * itself had this meaning, unchanged.
+     *
+     * Per axis the gust is three sinusoids at 1, 2.41 and 5.83 times the base
+     * frequency `1 / gust_period`, the axes a third of a turn apart, so it turns as
+     * well as pulses:
+     *
+     *     g_axis = gust · Σ_k a_k · sin(2π·phase_k + (k+1)·φ_axis)
+     *
+     * The air carries the gust; it does not relax toward it, so `drag` does not filter
+     * it. `0` (default) is no gust.
+     *
+     * @type {number}
+     */
+    gust: number;
+    /**
+     * Period of the gust's slowest component, seconds. Four is a breeze that
+     * arrives and leaves a few times a minute; a fraction of a second is a flutter.
+     * A value that is not positive reads as 1.
+     *
+     * The phases are integrated in {@link advance}, not computed from a clock, so
+     * editing the period changes how fast the gust moves from now on and never makes
+     * it jump.
+     *
+     * @type {number}
+     */
+    gust_period: number;
+    /**
+     * The gust's three phases, in turns, each in `[0, 1)`: state, advanced once a tick
+     * by {@link advance}. Written by hand only to restore a saved gust.
+     *
+     * @type {Float64Array}
+     */
+    gust_phase: Float64Array;
+    /**
+     * The gust at the current phases, WORLD units per second.
+     *
+     * @param {Float64Array|number[]} out written at 0..2
+     * @returns {Float64Array|number[]} `out`
+     */
+    compute_gust(out: Float64Array | number[]): Float64Array | number[];
+}
+export namespace GlobalFluidEffector {
+    let typeName: string;
 }
 import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
 //# sourceMappingURL=GlobalFluidEffector.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GlobalFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/GlobalFluidEffector.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IAEI;;;;;OAKG;IACH,OAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEhB;IAElB;;;;;OAKG;IACH,MAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEjB;IAEjB;;;;;;;OAOG;IACH,MAFU,MAAM,CAEP;CA+HZ;sCA3MqC,4BAA4B"}
+{"version":3,"file":"GlobalFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/GlobalFluidEffector.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH;IAEI;;;;;OAKG;IACH,OAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEhB;IAElB;;;;;OAKG;IACH,MAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEjB;IAEjB;;;;;;;OAOG;IACH,MAFU,MAAM,CAEP;IAET;;;;;;;;;;;;;;;;OAgBG;IACH,MAFU,MAAM,CAEP;IAET;;;;;;;;;;OAUG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,YAFU,YAAY,CAEW;IAsBjC;;;;;OAKG;IACH,kBAHW,YAAY,GAAC,MAAM,EAAE,GACnB,YAAY,GAAC,MAAM,EAAE,CAoCjC;CAqEJ;;kBAIS,MAAM;;sCAxQsB,4BAA4B"}

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

@@ -3,11 +3,13 @@ import { computeHashFloat } from "../../../../core/primitives/numbers/computeHas
 import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
 
 /**
- * The global atmosphere: every fluid face in every field integrates the same
- * linear flow model each step,
+ * The global atmosphere: the air nothing else touches, everywhere. Every fluid face in
+ * every field follows the same linear flow model,
  *
  *     dv/dt = force + drag · (wind − v)
  *
+ * plus a gust carried on top of the wind.
+ *
  * One effector covers the whole family of "push everything" behaviours —
  * pick the regime by which fields you set:
  *
@@ -18,7 +20,7 @@ import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
  *     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
+ *     velocity at `drag` per second; wakes and splats decay back to
  *     the ambient flow. The fixed point is exactly `wind`.
  *
  *   - **`force` + `drag` (+ `wind`)** — bounded forcing with a terminal
@@ -30,21 +32,32 @@ import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
  *     is the solver-level stability knob that exists even when no effectors
  *     are wired.)
  *
+ *   - **`gust`** — weather on top of the wind: three sinusoids per axis, bounded
+ *     by `gust` per axis, which the air carries rather than relaxes toward. See
+ *     {@link gust}.
+ *
  * `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:
+ * ## The far field
  *
- *     v ← v∞ + (v − v∞) · e^(−drag·dt),   v∞ = wind + force / drag
+ * In a scene, globals act through {@link FluidEffectorsSystem}: once a tick it folds
+ * every global into one far field — `D = Σ drag`, the drag-weighted mean of the
+ * winds, the sum of the gusts and the sum of the forces — and integrates
+ * `v_far = u + g`, where `u` relaxes toward the mean wind at `D` and `g` is the summed
+ * gust, unfiltered. {@link FluidSystem} and {@link WorkerFluidSystem} then bring every
+ * field to that far field once a step through the atmosphere identity
+ * (`fluid_apply_atmosphere`), so several globals act as one, whatever order they are
+ * in. A global has no `apply` of its own: it acts only through the far field, and
+ * `FluidSimulator#step` refuses one handed to it in its effector list.
  *
- * (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.
+ * `force` is not part of the far field: it is a term inside CPU fields, applied exactly
+ * in the same step.
  *
- * 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.
+ * All quantities are WORLD-space: `force` in units/s², `wind` and `gust` in units/s,
+ * `drag` in 1/s. The `world_to_grid` matrix's linear part converts the vectors per
+ * field, 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
@@ -71,7 +84,7 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
     /**
      * 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`
+     * wakes linger. A disturbance decays to ~37% in `1/drag`
      * seconds. `0` disables the relaxation term entirely.
      *
      * @type {number}
@@ -79,84 +92,111 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
     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 and wind are
-     *                                               directions.
+     * Peak gust speed on top of the wind, WORLD units per second: a bound, `|g| ≤ gust`
+     * on every axis, since the component amplitudes 4/7, 2/7 and 1/7 sum to one. Cloth reads it
+     * through the far field (`ClothGPUFluidWind`, `ClothFluidWind`); the gust cloth once kept
+     * itself had this meaning, unchanged.
+     *
+     * Per axis the gust is three sinusoids at 1, 2.41 and 5.83 times the base
+     * frequency `1 / gust_period`, the axes a third of a turn apart, so it turns as
+     * well as pulses:
+     *
+     *     g_axis = gust · Σ_k a_k · sin(2π·phase_k + (k+1)·φ_axis)
+     *
+     * The air carries the gust; it does not relax toward it, so `drag` does not filter
+     * it. `0` (default) is no gust.
+     *
+     * @type {number}
      */
-    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;
-
-        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;
-
-        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;
-
-            // 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_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]);
-            }
-            for (let i = 0; i < n_w; i++) {
-                if (pin_w[i] === 0) vw[i] += blend * (tz - vw[i]);
-            }
-            return;
-        }
+    gust = 0;
 
-        // 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;
+    /**
+     * Period of the gust's slowest component, seconds. Four is a breeze that
+     * arrives and leaves a few times a minute; a fraction of a second is a flutter.
+     * A value that is not positive reads as 1.
+     *
+     * The phases are integrated in {@link advance}, not computed from a clock, so
+     * editing the period changes how fast the gust moves from now on and never makes
+     * it jump.
+     *
+     * @type {number}
+     */
+    gust_period = 4;
+
+    /**
+     * The gust's three phases, in turns, each in `[0, 1)`: state, advanced once a tick
+     * by {@link advance}. Written by hand only to restore a saved gust.
+     *
+     * @type {Float64Array}
+     */
+    gust_phase = new Float64Array(3);
+
+    /**
+     * Advance the gust's phases by `dt`: `phase_k ← frac(phase_k + dt·rate_k / gust_period)`.
+     * {@link FluidEffectorsSystem} calls it exactly once a tick.
+     *
+     * @param {number} dt seconds
+     */
+    advance(dt) {
+        const period = this.gust_period > 0 ? this.gust_period : 1;
+
+        const phase = this.gust_phase;
+
+        const p0 = phase[0] + dt * RATE_0 / period;
+        const p1 = phase[1] + dt * RATE_1 / period;
+        const p2 = phase[2] + dt * RATE_2 / period;
+
+        phase[0] = p0 - Math.floor(p0);
+        phase[1] = p1 - Math.floor(p1);
+        phase[2] = p2 - Math.floor(p2);
+    }
+
+    /**
+     * The gust at the current phases, WORLD units per second.
+     *
+     * @param {Float64Array|number[]} out written at 0..2
+     * @returns {Float64Array|number[]} `out`
+     */
+    compute_gust(out) {
+        const gust = this.gust;
+
+        if (gust === 0) {
+            out[0] = 0;
+            out[1] = 0;
+            out[2] = 0;
+
+            return out;
         }
+
+        const phase = this.gust_phase;
+
+        const a0 = TAU * phase[0];
+        const a1 = TAU * phase[1];
+        const a2 = TAU * phase[2];
+
+        out[0] = gust * (
+            AMPLITUDE_0 * Math.sin(a0 + AXIS_PHASE_X)
+            + AMPLITUDE_1 * Math.sin(a1 + AXIS_PHASE_X * 2)
+            + AMPLITUDE_2 * Math.sin(a2 + AXIS_PHASE_X * 3)
+        );
+        out[1] = gust * (
+            AMPLITUDE_0 * Math.sin(a0 + AXIS_PHASE_Y)
+            + AMPLITUDE_1 * Math.sin(a1 + AXIS_PHASE_Y * 2)
+            + AMPLITUDE_2 * Math.sin(a2 + AXIS_PHASE_Y * 3)
+        );
+        out[2] = gust * (
+            AMPLITUDE_0 * Math.sin(a0 + AXIS_PHASE_Z)
+            + AMPLITUDE_1 * Math.sin(a1 + AXIS_PHASE_Z * 2)
+            + AMPLITUDE_2 * Math.sin(a2 + AXIS_PHASE_Z * 3)
+        );
+
+        return out;
     }
 
     /**
+     * Every field, the gust's phases included: two globals are equal when they make the
+     * same air from now on.
+     *
      * @param {AbstractFluidEffector} other
      * @return {boolean}
      */
@@ -173,7 +213,12 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
             && this.force[2] === other.force[2]
             && this.wind[0] === other.wind[0]
             && this.wind[1] === other.wind[1]
-            && this.wind[2] === other.wind[2];
+            && this.wind[2] === other.wind[2]
+            && this.gust === other.gust
+            && this.gust_period === other.gust_period
+            && this.gust_phase[0] === other.gust_phase[0]
+            && this.gust_phase[1] === other.gust_phase[1]
+            && this.gust_phase[2] === other.gust_phase[2];
     }
 
     /**
@@ -190,8 +235,20 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
                 computeHashFloat(this.wind[0]),
                 computeHashFloat(this.wind[1])
             ),
-            computeHashFloat(this.wind[2]),
-            computeHashFloat(this.drag)
+            hash_mix3(
+                computeHashFloat(this.wind[2]),
+                computeHashFloat(this.drag),
+                computeHashFloat(this.gust)
+            ),
+            hash_mix3(
+                computeHashFloat(this.gust_period),
+                computeHashFloat(this.gust_phase[0]),
+                hash_mix3(
+                    computeHashFloat(this.gust_phase[1]),
+                    computeHashFloat(this.gust_phase[2]),
+                    0
+                )
+            )
         );
     }
 
@@ -204,3 +261,65 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
         out.setInfiniteBounds();
     }
 }
+
+/**
+ * @readonly
+ * @type {string}
+ */
+GlobalFluidEffector.typeName = "GlobalFluidEffector";
+
+/**
+ * @type {number}
+ */
+const TAU = 2 * Math.PI;
+
+/**
+ * Component rates, as multiples of the base frequency `1 / gust_period`: mutually
+ * irrational enough that the sum does not visibly repeat.
+ * @type {number}
+ */
+const RATE_0 = 1;
+
+/**
+ * @type {number}
+ */
+const RATE_1 = 2.41;
+
+/**
+ * @type {number}
+ */
+const RATE_2 = 5.83;
+
+/**
+ * Component amplitudes. They sum to exactly one, which is what makes
+ * {@link GlobalFluidEffector#gust} a bound rather than a scale.
+ * @type {number}
+ */
+const AMPLITUDE_0 = 4 / 7;
+
+/**
+ * @type {number}
+ */
+const AMPLITUDE_1 = 2 / 7;
+
+/**
+ * @type {number}
+ */
+const AMPLITUDE_2 = 1 / 7;
+
+/**
+ * Per-axis phase offsets φ_axis, thirds of a turn; component k takes `(k+1)·φ_axis`,
+ * so the axes stay apart at every rate.
+ * @type {number}
+ */
+const AXIS_PHASE_X = 0;
+
+/**
+ * @type {number}
+ */
+const AXIS_PHASE_Y = 2 * Math.PI / 3;
+
+/**
+ * @type {number}
+ */
+const AXIS_PHASE_Z = 4 * Math.PI / 3;

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

@@ -0,0 +1,35 @@
+/**
+ * Binary serialization for {@link GlobalFluidEffector}: `force`, `wind`, `drag`, `gust`,
+ * `gust_period`, and the gust's three phases, every one an f64.
+ *
+ * The phases are state, and they are written so that a save resumes the gust where it was:
+ * a loaded global advanced from the load makes the same air, to the bit, as the saved one
+ * advanced from the save. Written as f64 for that reason; a phase rounded to f32 would put the
+ * gust a 1e-7 turn off.
+ *
+ * ## Version 0, and no upgrader
+ *
+ * A first version has no predecessor stream to upgrade from. Adding a field is a bump to 1 plus
+ * an upgrader that writes the field's pre-upgrade default, and the spec's exact byte count is
+ * what makes forgetting the bump fail rather than shift every component after this one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GlobalFluidEffectorSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof GlobalFluidEffector;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {GlobalFluidEffector} value
+     */
+    serialize(buffer: BinaryBuffer, value: GlobalFluidEffector): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {GlobalFluidEffector} value
+     */
+    deserialize(buffer: BinaryBuffer, value: GlobalFluidEffector): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { GlobalFluidEffector } from "./GlobalFluidEffector.js";
+//# sourceMappingURL=GlobalFluidEffectorSerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GlobalFluidEffectorSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/GlobalFluidEffectorSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH;;IAEI,kCAA4B;IAG5B;;;OAGG;IACH,uCAFW,mBAAmB,QAmB7B;IAED;;;OAGG;IACH,yCAFW,mBAAmB,QAmB7B;CACJ;gDAvE+C,gEAAgE;oCAC5E,0BAA0B"}

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

@@ -0,0 +1,72 @@
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { GlobalFluidEffector } from "./GlobalFluidEffector.js";
+
+/**
+ * Binary serialization for {@link GlobalFluidEffector}: `force`, `wind`, `drag`, `gust`,
+ * `gust_period`, and the gust's three phases, every one an f64.
+ *
+ * The phases are state, and they are written so that a save resumes the gust where it was:
+ * a loaded global advanced from the load makes the same air, to the bit, as the saved one
+ * advanced from the save. Written as f64 for that reason; a phase rounded to f32 would put the
+ * gust a 1e-7 turn off.
+ *
+ * ## Version 0, and no upgrader
+ *
+ * A first version has no predecessor stream to upgrade from. Adding a field is a bump to 1 plus
+ * an upgrader that writes the field's pre-upgrade default, and the spec's exact byte count is
+ * what makes forgetting the bump fail rather than shift every component after this one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GlobalFluidEffectorSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = GlobalFluidEffector;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {GlobalFluidEffector} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat64(value.force[0]);
+        buffer.writeFloat64(value.force[1]);
+        buffer.writeFloat64(value.force[2]);
+
+        buffer.writeFloat64(value.wind[0]);
+        buffer.writeFloat64(value.wind[1]);
+        buffer.writeFloat64(value.wind[2]);
+
+        buffer.writeFloat64(value.drag);
+
+        buffer.writeFloat64(value.gust);
+        buffer.writeFloat64(value.gust_period);
+
+        buffer.writeFloat64(value.gust_phase[0]);
+        buffer.writeFloat64(value.gust_phase[1]);
+        buffer.writeFloat64(value.gust_phase[2]);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {GlobalFluidEffector} value
+     */
+    deserialize(buffer, value) {
+        value.force[0] = buffer.readFloat64();
+        value.force[1] = buffer.readFloat64();
+        value.force[2] = buffer.readFloat64();
+
+        value.wind[0] = buffer.readFloat64();
+        value.wind[1] = buffer.readFloat64();
+        value.wind[2] = buffer.readFloat64();
+
+        value.drag = buffer.readFloat64();
+
+        value.gust = buffer.readFloat64();
+        value.gust_period = buffer.readFloat64();
+
+        value.gust_phase[0] = buffer.readFloat64();
+        value.gust_phase[1] = buffer.readFloat64();
+        value.gust_phase[2] = buffer.readFloat64();
+    }
+}

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

@@ -8,11 +8,17 @@
  * hard sphere.
  *
  * Everything is in WORLD units: {@link position} (point), {@link force} (direction
- * vector), {@link radius} (scalar length). The `world_to_grid` matrix supplied to
- * {@link apply} converts them at splat time. Works at any user-supplied radius
- * including sub-cell: the effective kernel radius is internally floored at 1 grid
- * cell so a small world-space radius still produces a roughly one-cell-wide splat
- * instead of silently missing every cell.
+ * vector), {@link radius} (scalar length). {@link apply} evaluates the effector's GPU record
+ * ({@link write_gpu_record}) on the field through `fluid_record_apply`, so the CPU fluid and the
+ * GPU fluid deposit the same push. Works at any radius, sub-cell included: a push narrower than
+ * two of the field's cells is evaluated two cells wide with its amplitude scaled by `(R/R_eff)³`,
+ * so it carries the momentum it would have had (the record's kernel floor). From two cells up the
+ * deposit is the kernel itself.
+ *
+ * {@link spread} widens the push from a jet into a cone, and at π into a burst: each face
+ * takes `|force|·dt·w` along the direction from the centre to the face, clamped into the cone
+ * of half-angle `spread` about `force` (`v3_clamp_to_cone`). At 0 every face is pushed along
+ * `force`, exactly as before the field existed.
  *
  * For moving sources that should leave a trail, see {@link WakeFluidEffector}.
  */
@@ -24,20 +30,38 @@ export class ImpulseFluidEffector extends AbstractFluidEffector {
     position: [number, number, number];
     /**
      * Acceleration vector in WORLD units per second squared. Per-step deposit is
-     * `world_to_grid · force × dt × falloff_weight`. Same world-units convention as
+     * `force × dt × falloff_weight`, turned into the field's grid units. Same world-units convention as
      * {@link GlobalFluidEffector.force} — gravity stays gravity across fields with
      * different `cell_size`.
      * @type {[number, number, number]}
      */
     force: [number, number, number];
     /**
-     * Influence radius in WORLD units. Cells past `radius` from the splat point are
-     * unaffected by the falloff. Internally floored to 1 grid cell so sub-cell
-     * world-radii still hit cells (the alternative is silently dropping the splat
-     * at fractional positions — see class docstring).
+     * Influence radius in WORLD units. Faces past `radius` from the splat point are
+     * unaffected by the falloff. Below two of a field's cells the push is evaluated two cells
+     * wide with its momentum kept (see the class docstring). 0 or less disables it.
      * @type {number}
      */
     radius: number;
+    /**
+     * Half-angle, in radians, of the cone the push fans into, in [0, π].
+     *
+     * - `0` (default): every face is pushed along {@link force}.
+     * - Between: a face is pushed along the direction from {@link position} to it, turned toward
+     *   `force` just far enough to lie in the cone of this half-angle about it. Inside the cone a
+     *   face is pushed straight outward.
+     * - `π`: every direction is inside the cone, so every face is pushed straight outward — an
+     *   omnidirectional burst, with `force`'s length as its strength.
+     *
+     * A face at the centre itself has no direction from it and is pushed along `force`.
+     *
+     * @type {number}
+     */
+    spread: number;
+    has_gpu_record: boolean;
+}
+export namespace ImpulseFluidEffector {
+    let typeName: string;
 }
 import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
 //# sourceMappingURL=ImpulseFluidEffector.d.ts.map