@woosh/meep-engine 3.68.0 → 3.70.0

package/src/engine/physics/cloth/wind/ClothFluidWind.js

@@ -4,6 +4,7 @@ import { FluidComponent } from "../../fluid/ecs/FluidComponent.js";
 import { fluid_sample_domain_bounds } from "../../fluid/ecs/fluid_sample_domain_bounds.js";
 import { fluid_sample_velocity_world_mps } from "../../fluid/ecs/fluid_sample_velocity_world_mps.js";
 import { AbstractClothWind } from "./AbstractClothWind.js";
+import { fluid_atmosphere_velocity_at } from "../../fluid/turbulence/fluid_atmosphere_velocity_at.js";
 
 /**
  * # The air, read out of the CPU fluid simulation that is already running
@@ -22,9 +23,9 @@ import { AbstractClothWind } from "./AbstractClothWind.js";
  * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6). So this is the one source a
  * CPU-fluid scene needs rather than a thing to switch between: a banner inside
  * a wind tunnel volume reads the tunnel, the same banner carried outside reads
- * the prevailing weather and its gust, and the cloth never learns which
- * happened. The gust runs on the scene's clock (G2), so `sample`'s `time` is not
- * read.
+ * the prevailing weather and its turbulence where it hangs, and the cloth never
+ * learns which happened. The far field runs on the scene's clock (G2), so
+ * `sample`'s `time` is not read.
  *
  * ## Two units problems, and they are the reason this class exists at all
  *
@@ -201,7 +202,7 @@ export class ClothFluidWind extends AbstractClothWind {
      * @param {number} y
      * @param {number} z
      * @param {number} time not read: a field's velocities are a snapshot of this
-     *   tick, and the far field's gust runs on the scene clock
+     *   tick, and the far field runs on the scene clock
      * @returns {Float64Array|number[]}
      */
     sample(out, x, y, z, time) {
@@ -224,11 +225,8 @@ export class ClothFluidWind extends AbstractClothWind {
             return out;
         }
 
-        const atmosphere = this.__atmosphere;
-
-        out[0] = atmosphere[FluidAtmosphere.VELOCITY_X];
-        out[1] = atmosphere[FluidAtmosphere.VELOCITY_Y];
-        out[2] = atmosphere[FluidAtmosphere.VELOCITY_Z];
+        // the far field there, its turbulence included
+        fluid_atmosphere_velocity_at(out, this.__atmosphere, 0, x, y, z);
 
         return out;
     }

package/src/engine/physics/cloth/wind/ClothGPUFluidWind.d.ts

@@ -10,8 +10,8 @@ export const CLOTH_GPU_FLUID_WIND_AXIS_LIMIT: number;
  *
  * GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §12: the default source for a scene with the GPU wind —
  * an adapter over `GPUFluidSystem`'s CPU read API, so cloth reads the same wind particles, water and
- * volumetrics do: the fluid's cascades around its domain, its far field (`GlobalFluidEffector`s and
- * their gust) everywhere else.
+ * volumetrics do: the fluid's cascades around its domain, its far field (`GlobalFluidEffector`s, their
+ * mean wind and its turbulence) everywhere else.
  *
  * `ClothWorld` makes one by itself while the scene has a domain and nothing was assigned to its
  * `wind` (`ClothWorld#wind`); assigning one is the same source, made by hand:
@@ -23,23 +23,23 @@ export const CLOTH_GPU_FLUID_WIND_AXIS_LIMIT: number;
  * The GPU's answer is a frame or more late, so cloth reads **lattices**: the wind on a grid over a
  * box padded around each cloth, asked for ahead and interpolated when it lands.
  *
- * - **{@link begin}**, once a tick, takes the far field and swaps in the lattices delivered since the
- *   last tick. A lattice no cloth read during the last tick is let go; one only {@link sample} read
+ * - **{@link begin}**, once a tick, swaps in the lattices delivered since the last tick. A lattice no cloth read during the last tick is let go; one only {@link sample} read
  *   (a sleeping cloth's wake test) is asked for again over its own box, so a banner asleep inside it
  *   still notices a gust.
  * - **{@link varies}** answers whether a delivered lattice covers the cloth's box — then the cloth
  *   samples per particle — and asks for the box padded by {@link padding}, unless a request in flight
  *   already covers it: one request at a time per cloth, a new lattice as fast as they land.
  * - **{@link sample}** interpolates the newest delivered lattice holding the point
- *   (`scs3d_sample_linear3_strided`, x fastest, four floats a point), or answers the far field.
+ *   (`scs3d_sample_linear3_strided`, x fastest, four floats a point), or answers the far field there
+ *   (`GPUFluidSystem#far_field_at`).
  *
- * Before the first delivery, and wherever no lattice reaches, the air is the far field: uniform, so
- * a cloth costs one sample.
+ * Before the first delivery, and wherever no lattice reaches, the air is the far field, which a cloth
+ * samples once: its mean, and its turbulence where the cloth asks.
  *
  * ## Clocks
  *
- * The far field's gust runs on the scene's clock (G2, `GlobalFluidEffector#advance`), not the
- * cloth's age: `sample`'s `time` is not read. Lattices arrive when the GPU answers, so two runs of a
+ * The far field runs on the scene's clock (G2, `FluidEffectorsSystem`'s fold), not the cloth's
+ * age: `sample`'s `time` is not read. Lattices arrive when the GPU answers, so two runs of a
  * scene need not read the same air (F4, accepted): the parity gate of the worker against the inline
  * system holds for cloths registered on the same tick and for a time-invariant wind
  * (`WorkerClothSystem.spec.js`).
@@ -58,7 +58,7 @@ export const CLOTH_GPU_FLUID_WIND_AXIS_LIMIT: number;
 export class ClothGPUFluidWind extends AbstractClothWind {
     /**
      * @param {import("../../../graphics3/GPUFluidSystem.js").GPUFluidSystem} fluid the scene's GPU
-     *   fluid: its `far_field`, `request` and `status`
+     *   fluid: its `far_field_at`, `request` and `status`
      */
     constructor(fluid: import("../../../graphics3/GPUFluidSystem.js").GPUFluidSystem);
     /**

package/src/engine/physics/cloth/wind/ClothGPUFluidWind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClothGPUFluidWind.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/wind/ClothGPUFluidWind.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,8CAFU,MAAM,CAEkC;AAuDlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH;IAyCI;;;OAGG;IACH,mBAHW,OAAO,sCAAsC,EAAE,cAAc,EAUvE;IAlDD;;;;;OAKG;IACH,SAFU,MAAM,CAEF;IAEd;;;;;OAKG;IACH,SAFU,MAAM,CAEF;IAsCd;;;OAGG;IACH,2EAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,4BAEC;;CAwPJ;kCArbiC,wBAAwB"}
+{"version":3,"file":"ClothGPUFluidWind.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/wind/ClothGPUFluidWind.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,8CAFU,MAAM,CAEkC;AAuDlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH;IAuCI;;;OAGG;IACH,mBAHW,OAAO,sCAAsC,EAAE,cAAc,EAUvE;IAhDD;;;;;OAKG;IACH,SAFU,MAAM,CAEF;IAEd;;;;;OAKG;IACH,SAFU,MAAM,CAEF;IAoCd;;;OAGG;IACH,2EAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,4BAEC;;CAkPJ;kCA7aiC,wBAAwB"}

package/src/engine/physics/cloth/wind/ClothGPUFluidWind.js

@@ -69,8 +69,8 @@ function lattice_covers(lattice, min_x, min_y, min_z, max_x, max_y, max_z) {
  *
  * GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §12: the default source for a scene with the GPU wind —
  * an adapter over `GPUFluidSystem`'s CPU read API, so cloth reads the same wind particles, water and
- * volumetrics do: the fluid's cascades around its domain, its far field (`GlobalFluidEffector`s and
- * their gust) everywhere else.
+ * volumetrics do: the fluid's cascades around its domain, its far field (`GlobalFluidEffector`s, their
+ * mean wind and its turbulence) everywhere else.
  *
  * `ClothWorld` makes one by itself while the scene has a domain and nothing was assigned to its
  * `wind` (`ClothWorld#wind`); assigning one is the same source, made by hand:
@@ -82,23 +82,23 @@ function lattice_covers(lattice, min_x, min_y, min_z, max_x, max_y, max_z) {
  * The GPU's answer is a frame or more late, so cloth reads **lattices**: the wind on a grid over a
  * box padded around each cloth, asked for ahead and interpolated when it lands.
  *
- * - **{@link begin}**, once a tick, takes the far field and swaps in the lattices delivered since the
- *   last tick. A lattice no cloth read during the last tick is let go; one only {@link sample} read
+ * - **{@link begin}**, once a tick, swaps in the lattices delivered since the last tick. A lattice no cloth read during the last tick is let go; one only {@link sample} read
  *   (a sleeping cloth's wake test) is asked for again over its own box, so a banner asleep inside it
  *   still notices a gust.
  * - **{@link varies}** answers whether a delivered lattice covers the cloth's box — then the cloth
  *   samples per particle — and asks for the box padded by {@link padding}, unless a request in flight
  *   already covers it: one request at a time per cloth, a new lattice as fast as they land.
  * - **{@link sample}** interpolates the newest delivered lattice holding the point
- *   (`scs3d_sample_linear3_strided`, x fastest, four floats a point), or answers the far field.
+ *   (`scs3d_sample_linear3_strided`, x fastest, four floats a point), or answers the far field there
+ *   (`GPUFluidSystem#far_field_at`).
  *
- * Before the first delivery, and wherever no lattice reaches, the air is the far field: uniform, so
- * a cloth costs one sample.
+ * Before the first delivery, and wherever no lattice reaches, the air is the far field, which a cloth
+ * samples once: its mean, and its turbulence where the cloth asks.
  *
  * ## Clocks
  *
- * The far field's gust runs on the scene's clock (G2, `GlobalFluidEffector#advance`), not the
- * cloth's age: `sample`'s `time` is not read. Lattices arrive when the GPU answers, so two runs of a
+ * The far field runs on the scene's clock (G2, `FluidEffectorsSystem`'s fold), not the cloth's
+ * age: `sample`'s `time` is not read. Lattices arrive when the GPU answers, so two runs of a
  * scene need not read the same air (F4, accepted): the parity gate of the worker against the inline
  * system holds for cloths registered on the same tick and for a time-invariant wind
  * (`WorkerClothSystem.spec.js`).
@@ -135,8 +135,6 @@ export class ClothGPUFluidWind extends AbstractClothWind {
     /** @type {import("../../../graphics3/GPUFluidSystem.js").GPUFluidSystem} */
     #fluid;
 
-    /** The far field this tick. */
-    #far = new Float64Array(3);
 
     /** Delivered lattices, oldest first. @type {ClothWindLattice[]} */
     #current = [];
@@ -157,7 +155,7 @@ export class ClothGPUFluidWind extends AbstractClothWind {
 
     /**
      * @param {import("../../../graphics3/GPUFluidSystem.js").GPUFluidSystem} fluid the scene's GPU
-     *   fluid: its `far_field`, `request` and `status`
+     *   fluid: its `far_field_at`, `request` and `status`
      */
     constructor(fluid) {
         super();
@@ -193,14 +191,12 @@ export class ClothGPUFluidWind extends AbstractClothWind {
     }
 
     /**
-     * @param {number} time not read: the gust runs on the scene clock
+     * @param {number} time not read: the far field runs on the scene clock
      * @param {EntityComponentDataset} ecd not read
      */
     begin(time, ecd) {
         const fluid = this.#fluid;
 
-        fluid.far_field(this.#far);
-
         // the last tick's reads decide what stays
         const current = this.#current;
         let kept = 0;
@@ -403,24 +399,20 @@ export class ClothGPUFluidWind extends AbstractClothWind {
 
     /**
      * The air at a world point, m/s: the newest delivered lattice holding it, interpolated, or the far
-     * field.
+     * field there (`GPUFluidSystem#far_field_at`), its turbulence included.
      *
      * @param {Float64Array|number[]} out
      * @param {number} x
      * @param {number} y
      * @param {number} z
-     * @param {number} time not read: the gust runs on the scene clock
+     * @param {number} time not read: the far field runs on the scene clock
      * @returns {Float64Array|number[]}
      */
     sample(out, x, y, z, time) {
         const lattice = this.#containing(x, y, z);
 
         if (lattice === null) {
-            const far = this.#far;
-
-            out[0] = far[0];
-            out[1] = far[1];
-            out[2] = far[2];
+            this.#fluid.far_field_at(out, x, y, z);
 
             return out;
         }

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

@@ -9,8 +9,8 @@
  * ({@link fluid_apply_atmosphere }).
  *
  *   - `TIME`: seconds the effectors system has integrated, at the end of its last tick.
- *   - `VELOCITY_*`: the far field `v_far = u + g`: `u` relaxes toward the globals'
- *     drag-weighted mean wind at `DRAG`, and `g` is the sum of their gusts, unfiltered.
+ *   - `VELOCITY_*`: `u`, the far field's mean: it relaxes toward the globals' drag-weighted
+ *     mean wind at `DRAG`. Where a reader takes the far field as one vector, this is it.
  *   - `LAMBDA`: `Λ = ∫ D dt`, so air left to the far field over an interval keeps
  *     `e^(−ΔΛ)` of its deviation from it, however `D` varied.
  *   - `FORCED_*`: `P`, the velocity the summed body force has given air the atmosphere
@@ -20,6 +20,15 @@
  *     `F` and `D` varied. Not part of the far field: a term inside CPU fields only.
  *   - `FORCE_*`: `F`, the sum of the globals' body forces, this tick.
  *   - `DRAG`: `D`, the sum of the globals' drags, this tick.
+ *   - `TURBULENCE_OFFSET_*`: `o = ∫ u dt`, how far the mean has carried the turbulence since the
+ *     first tick, WORLD units, integrated exactly tick by tick.
+ *   - `TURBULENCE_SIGMA`: `σ`, the turbulence's rms on each axis, `intensity · |u|`, WORLD units per
+ *     second; 0 is none.
+ *   - `TURBULENCE_LENGTH`: `L`, its length scale, WORLD units.
+ *
+ * The far field at a point `x` is `u + σ·T((x − o) ⊙ S⁻¹)` ({@link fluid_atmosphere_velocity_at }),
+ * `T` the unit-rms turbulence tile and `S` its size in the world for `L`. Not part of CPU fields,
+ * which take `u` alone.
  */
 export type FluidAtmosphere = number;
 export namespace FluidAtmosphere {
@@ -35,6 +44,11 @@ export namespace FluidAtmosphere {
     let FORCE_Y: number;
     let FORCE_Z: number;
     let DRAG: number;
+    let TURBULENCE_OFFSET_X: number;
+    let TURBULENCE_OFFSET_Y: number;
+    let TURBULENCE_OFFSET_Z: number;
+    let TURBULENCE_SIGMA: number;
+    let TURBULENCE_LENGTH: number;
 }
 /**
  * Words in an atmosphere record.

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

@@ -1 +1 @@
-{"version":3,"file":"FluidAtmosphere.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidAtmosphere.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;8BAwBU,MAAM;;;;;;;;;;;;;;;AAiBhB;;;GAGG;AACH,qCAFU,MAAM,CAEyB;;;;;;;;;;;;mCAc/B,MAAM;;;;;;;;;;;;;;;;;;;;AAchB;;;GAGG;AACH,2CAFU,MAAM,CAE8B"}
+{"version":3,"file":"FluidAtmosphere.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidAtmosphere.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BAiCU,MAAM;;;;;;;;;;;;;;;;;;;;AAsBhB;;;GAGG;AACH,qCAFU,MAAM,CAEyB;;;;;;;;;;;;mCAc/B,MAAM;;;;;;;;;;;;;;;;;;;;AAchB;;;GAGG;AACH,2CAFU,MAAM,CAE8B"}

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

@@ -9,8 +9,8 @@
  * ({@link fluid_apply_atmosphere}).
  *
  *   - `TIME`: seconds the effectors system has integrated, at the end of its last tick.
- *   - `VELOCITY_*`: the far field `v_far = u + g`: `u` relaxes toward the globals'
- *     drag-weighted mean wind at `DRAG`, and `g` is the sum of their gusts, unfiltered.
+ *   - `VELOCITY_*`: `u`, the far field's mean: it relaxes toward the globals' drag-weighted
+ *     mean wind at `DRAG`. Where a reader takes the far field as one vector, this is it.
  *   - `LAMBDA`: `Λ = ∫ D dt`, so air left to the far field over an interval keeps
  *     `e^(−ΔΛ)` of its deviation from it, however `D` varied.
  *   - `FORCED_*`: `P`, the velocity the summed body force has given air the atmosphere
@@ -20,6 +20,15 @@
  *     `F` and `D` varied. Not part of the far field: a term inside CPU fields only.
  *   - `FORCE_*`: `F`, the sum of the globals' body forces, this tick.
  *   - `DRAG`: `D`, the sum of the globals' drags, this tick.
+ *   - `TURBULENCE_OFFSET_*`: `o = ∫ u dt`, how far the mean has carried the turbulence since the
+ *     first tick, WORLD units, integrated exactly tick by tick.
+ *   - `TURBULENCE_SIGMA`: `σ`, the turbulence's rms on each axis, `intensity · |u|`, WORLD units per
+ *     second; 0 is none.
+ *   - `TURBULENCE_LENGTH`: `L`, its length scale, WORLD units.
+ *
+ * The far field at a point `x` is `u + σ·T((x − o) ⊙ S⁻¹)` ({@link fluid_atmosphere_velocity_at}),
+ * `T` the unit-rms turbulence tile and `S` its size in the world for `L`. Not part of CPU fields,
+ * which take `u` alone.
  *
  * @readonly
  * @enum {number}
@@ -37,13 +46,18 @@ export const FluidAtmosphere = {
     FORCE_Y: 9,
     FORCE_Z: 10,
     DRAG: 11,
+    TURBULENCE_OFFSET_X: 12,
+    TURBULENCE_OFFSET_Y: 13,
+    TURBULENCE_OFFSET_Z: 14,
+    TURBULENCE_SIGMA: 15,
+    TURBULENCE_LENGTH: 16,
 };
 
 /**
  * Words in an atmosphere record.
  * @type {number}
  */
-export const FLUID_ATMOSPHERE_WORDS = 12;
+export const FLUID_ATMOSPHERE_WORDS = 17;
 
 /**
  * Layout of a field's own atmosphere record, {@link FluidField#atmosphere}: the instant

package/src/engine/physics/fluid/ecs/FluidEffectorsComponentSerializationAdapter.d.ts

@@ -6,8 +6,7 @@
  * Every effector class in a saved component needs its adapter in the same registry: the engine's
  * are {@link GlobalFluidEffectorSerializationAdapter}, {@link ImpulseFluidEffectorSerializationAdapter},
  * {@link WakeFluidEffectorSerializationAdapter} and {@link VortexFluidEffectorSerializationAdapter}, and
- * an effector class of your own needs a `typeName` and an adapter of its own. A global's gust phases
- * go with it, so a save resumes the gust where it was.
+ * an effector class of your own needs a `typeName` and an adapter of its own.
  *
  * Like the other physics adapters this is not in `populateEngineSerializationRegistry`; the host
  * registers it with the effector adapters.

package/src/engine/physics/fluid/ecs/FluidEffectorsComponentSerializationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidEffectorsComponentSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidEffectorsComponentSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH;;IAEI,sCAAgC;IAGhC;;OAEG;IACH,eAFU,mCAAiC,IAAI,CAE1B;IAErB;;;OAGG;IACH,+EAEC;IAED;;;OAGG;IACH,uCAFW,uBAAuB,QAWjC;IAED;;;;;OAKG;IACH,yCAFW,uBAAuB,QAWjC;CACJ;gDAvE+C,gEAAgE;wCACxE,8BAA8B"}
+{"version":3,"file":"FluidEffectorsComponentSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidEffectorsComponentSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH;;IAEI,sCAAgC;IAGhC;;OAEG;IACH,eAFU,mCAAiC,IAAI,CAE1B;IAErB;;;OAGG;IACH,+EAEC;IAED;;;OAGG;IACH,uCAFW,uBAAuB,QAWjC;IAED;;;;;OAKG;IACH,yCAFW,uBAAuB,QAWjC;CACJ;gDAtE+C,gEAAgE;wCACxE,8BAA8B"}

package/src/engine/physics/fluid/ecs/FluidEffectorsComponentSerializationAdapter.js

@@ -9,8 +9,7 @@ import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
  * Every effector class in a saved component needs its adapter in the same registry: the engine's
  * are {@link GlobalFluidEffectorSerializationAdapter}, {@link ImpulseFluidEffectorSerializationAdapter},
  * {@link WakeFluidEffectorSerializationAdapter} and {@link VortexFluidEffectorSerializationAdapter}, and
- * an effector class of your own needs a `typeName` and an adapter of its own. A global's gust phases
- * go with it, so a save resumes the gust where it was.
+ * an effector class of your own needs a `typeName` and an adapter of its own.
  *
  * Like the other physics adapters this is not in `populateEngineSerializationRegistry`; the host
  * registers it with the effector adapters.

package/src/engine/physics/fluid/ecs/FluidEffectorsSystem.d.ts

@@ -11,22 +11,25 @@
  *
  *   3. the fold of every {@link GlobalFluidEffector} into one far field, integrated in f64.
  *
- * Effectors carry state across ticks — a wake's trail advances in its sync, a global's gust in
- * its advance — so this has to happen exactly once a tick however many fluid systems apply the
- * effectors. It used to be a line in each fluid system, and a scene with two of them advanced
+ * Effectors carry state across ticks — a wake's trail advances in its sync — so this has to happen
+ * exactly once a tick however many fluid systems apply the effectors. It used to be a line in each fluid system, and a scene with two of them advanced
  * every wake twice.
  *
  * ## The far field
  *
  * The globals fold into `D = Σ d` (their drags), `W = Σ (d/D)·w` (the drag-weighted mean of their
- * winds), `g = Σ gust` and `F = Σ force`. The far field is `v_far = u + g`:
+ * winds), `I = Σ (d/D)·i` and `L = Σ (d/D)·l` (of their turbulence intensities and length scales)
+ * and `F = Σ force`. The far field is `u`, its mean, plus turbulence of rms `σ = I·|u|`:
  *
  *   - `u` relaxes toward `W` exactly, `u ← W + (u − W)·e^(−D·dt)`. Only this system's first fold
  *     seeds it at `W`, so a scene that starts with its globals starts in steady state; a global
  *     that arrives later relaxes the air from where it is, at its drag. With `D = 0` — the last
  *     global gone included — nothing relaxes it and it holds. A scene that never had a global is
  *     still air; calm is authored as a global with wind 0 and a drag.
- *   - `g` is added, not drag-filtered: the air carries the authored gust.
+ *   - `I` and `L` are this tick's, and with `D = 0` hold where they were, like `u`.
+ *   - the turbulence is carried by `u`: its offset `o = ∫ u dt` is integrated exactly over each tick
+ *     along `u`'s relaxation, `W·dt + (u₀ − W)·(1 − e^(−D·dt))/D`, or `u·dt` with no drag. `o` is this
+ *     system's own and starts at 0, so a scene loaded from a save starts the eddies over.
  *   - `Λ += D·dt`, so a field brought from one instant to another keeps `e^(−ΔΛ)` of its deviation
  *     from the far field however `D` varied in between.
  *   - `F` is not part of the far field: a world-wide body force would be an unbounded downdraft at

package/src/engine/physics/fluid/ecs/FluidEffectorsSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidEffectorsSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidEffectorsSystem.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;;IAEI,mIAME;IA6DF;;;;;;;;OAQG;IACH,qBAHW,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,QAQhB;;CAsKJ;uBAhTsB,wBAAwB;wCAIP,8BAA8B;4CAL1B,uDAAuD;4BAEvE,uCAAuC"}
+{"version":3,"file":"FluidEffectorsSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidEffectorsSystem.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH;;IAEI,mIAME;IAyEF;;;;;;;;OAQG;IACH,qBAHW,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,QAQhB;;CAkMJ;uBA3VsB,wBAAwB;wCAIP,8BAA8B;4CAL1B,uDAAuD;4BAEvE,uCAAuC"}

package/src/engine/physics/fluid/ecs/FluidEffectorsSystem.js

@@ -20,22 +20,25 @@ import { fluid_sync_effectors_from_transform } from "./fluid_sync_effectors_from
  *
  *   3. the fold of every {@link GlobalFluidEffector} into one far field, integrated in f64.
  *
- * Effectors carry state across ticks — a wake's trail advances in its sync, a global's gust in
- * its advance — so this has to happen exactly once a tick however many fluid systems apply the
- * effectors. It used to be a line in each fluid system, and a scene with two of them advanced
+ * Effectors carry state across ticks — a wake's trail advances in its sync — so this has to happen
+ * exactly once a tick however many fluid systems apply the effectors. It used to be a line in each fluid system, and a scene with two of them advanced
  * every wake twice.
  *
  * ## The far field
  *
  * The globals fold into `D = Σ d` (their drags), `W = Σ (d/D)·w` (the drag-weighted mean of their
- * winds), `g = Σ gust` and `F = Σ force`. The far field is `v_far = u + g`:
+ * winds), `I = Σ (d/D)·i` and `L = Σ (d/D)·l` (of their turbulence intensities and length scales)
+ * and `F = Σ force`. The far field is `u`, its mean, plus turbulence of rms `σ = I·|u|`:
  *
  *   - `u` relaxes toward `W` exactly, `u ← W + (u − W)·e^(−D·dt)`. Only this system's first fold
  *     seeds it at `W`, so a scene that starts with its globals starts in steady state; a global
  *     that arrives later relaxes the air from where it is, at its drag. With `D = 0` — the last
  *     global gone included — nothing relaxes it and it holds. A scene that never had a global is
  *     still air; calm is authored as a global with wind 0 and a drag.
- *   - `g` is added, not drag-filtered: the air carries the authored gust.
+ *   - `I` and `L` are this tick's, and with `D = 0` hold where they were, like `u`.
+ *   - the turbulence is carried by `u`: its offset `o = ∫ u dt` is integrated exactly over each tick
+ *     along `u`'s relaxation, `W·dt + (u₀ − W)·(1 − e^(−D·dt))/D`, or `u·dt` with no drag. `o` is this
+ *     system's own and starts at 0, so a scene loaded from a save starts the eddies over.
  *   - `Λ += D·dt`, so a field brought from one instant to another keeps `e^(−ΔΛ)` of its deviation
  *     from the far field however `D` varied in between.
  *   - `F` is not part of the far field: a world-wide body force would be an unbounded downdraft at
@@ -91,10 +94,22 @@ export class FluidEffectorsSystem extends System {
     #global_count = 0;
 
     /**
-     * Scratch for one global's gust.
+     * `o`, how far `u` has carried the turbulence, WORLD units.
      * @type {Float64Array}
      */
-    #gust = new Float64Array(3);
+    #turbulence_offset = new Float64Array(3);
+
+    /**
+     * `I`, the folded turbulence intensity, held with `D = 0`.
+     * @type {number}
+     */
+    #turbulence_intensity = 0;
+
+    /**
+     * `L`, the folded length scale, held with `D = 0`; 0 before any global with drag.
+     * @type {number}
+     */
+    #turbulence_length = 0;
 
     /**
      * `u`, the far field's steady part, WORLD units per second.
@@ -207,10 +222,8 @@ export class FluidEffectorsSystem extends System {
     #fold(dt) {
         const globals = this.#globals;
         const count = this.#global_count;
-        const gust = this.#gust;
 
         let D = 0;
-        let gx = 0, gy = 0, gz = 0;
         let fx = 0, fy = 0, fz = 0;
 
         for (let i = 0; i < count; i++) {
@@ -224,19 +237,16 @@ export class FluidEffectorsSystem extends System {
             fx += force[0];
             fy += force[1];
             fz += force[2];
-
-            effector.compute_gust(gust);
-            gx += gust[0];
-            gy += gust[1];
-            gz += gust[2];
         }
 
         const steady = this.#steady;
+        const offset = this.#turbulence_offset;
 
         // With no drag (no global at all included) nothing relaxes the air: `u` holds.
         if (D > 0) {
             // Weights d/D, so one global's mean wind is its own wind exactly.
             let wx = 0, wy = 0, wz = 0;
+            let intensity = 0, length = 0;
 
             for (let i = 0; i < count; i++) {
                 const effector = globals[i];
@@ -251,11 +261,24 @@ export class FluidEffectorsSystem extends System {
                 wx += weight * wind[0];
                 wy += weight * wind[1];
                 wz += weight * wind[2];
+
+                intensity += weight * effector.turbulence_intensity;
+                length += weight * effector.turbulence_length;
             }
 
+            this.#turbulence_intensity = intensity;
+            this.#turbulence_length = length;
+
             if (this.#first_fold_done) {
                 const keep = Math.exp(-D * dt);
 
+                // ∫ u dt over the tick, along the relaxation, before u moves
+                const carried = (1 - keep) / D;
+
+                offset[0] += wx * dt + (steady[0] - wx) * carried;
+                offset[1] += wy * dt + (steady[1] - wy) * carried;
+                offset[2] += wz * dt + (steady[2] - wz) * carried;
+
                 steady[0] = wx + (steady[0] - wx) * keep;
                 steady[1] = wy + (steady[1] - wy) * keep;
                 steady[2] = wz + (steady[2] - wz) * keep;
@@ -264,7 +287,16 @@ export class FluidEffectorsSystem extends System {
                 steady[0] = wx;
                 steady[1] = wy;
                 steady[2] = wz;
+
+                offset[0] += wx * dt;
+                offset[1] += wy * dt;
+                offset[2] += wz * dt;
             }
+        } else {
+            // nothing relaxes u: it carries the turbulence as it stands
+            offset[0] += steady[0] * dt;
+            offset[1] += steady[1] * dt;
+            offset[2] += steady[2] * dt;
         }
 
         this.#first_fold_done = true;
@@ -292,9 +324,9 @@ export class FluidEffectorsSystem extends System {
         const atmosphere = this.#atmosphere;
 
         atmosphere[FluidAtmosphere.TIME] += dt;
-        atmosphere[FluidAtmosphere.VELOCITY_X] = steady[0] + gx;
-        atmosphere[FluidAtmosphere.VELOCITY_Y] = steady[1] + gy;
-        atmosphere[FluidAtmosphere.VELOCITY_Z] = steady[2] + gz;
+        atmosphere[FluidAtmosphere.VELOCITY_X] = steady[0];
+        atmosphere[FluidAtmosphere.VELOCITY_Y] = steady[1];
+        atmosphere[FluidAtmosphere.VELOCITY_Z] = steady[2];
         atmosphere[FluidAtmosphere.LAMBDA] += D * dt;
         atmosphere[FluidAtmosphere.FORCED_X] = forced[0];
         atmosphere[FluidAtmosphere.FORCED_Y] = forced[1];
@@ -303,5 +335,16 @@ export class FluidEffectorsSystem extends System {
         atmosphere[FluidAtmosphere.FORCE_Y] = fy;
         atmosphere[FluidAtmosphere.FORCE_Z] = fz;
         atmosphere[FluidAtmosphere.DRAG] = D;
+
+        // no length scale, no tile to lay out: no turbulence
+        const length = this.#turbulence_length;
+        const speed = Math.sqrt(steady[0] * steady[0] + steady[1] * steady[1] + steady[2] * steady[2]);
+        const sigma = length > 0 && this.#turbulence_intensity > 0 ? this.#turbulence_intensity * speed : 0;
+
+        atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_X] = offset[0];
+        atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_Y] = offset[1];
+        atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_Z] = offset[2];
+        atmosphere[FluidAtmosphere.TURBULENCE_SIGMA] = sigma;
+        atmosphere[FluidAtmosphere.TURBULENCE_LENGTH] = length;
     }
 }

package/src/engine/physics/fluid/ecs/FluidObstacle.d.ts

@@ -38,6 +38,22 @@ export class FluidObstacle {
      * @type {number}
      */
     inflation: number;
+    /**
+     * How the obstacle stops the wind, 1/m. `0` (default): it is **solid**, and the air takes its
+     * velocity wherever it is. Above `0`: it is **porous**, the air passes through it and is slowed
+     * toward its velocity by `drag · |u − v| · (u − v)` each second, `u` the air's velocity and `v`
+     * the obstacle's.
+     *
+     * For something made of leaves or blades it is their drag coefficient times their one-sided area
+     * per cubic metre of the volume: a canopy of grass, a crop, the crown of a tree, a hedge. Their drag
+     * is spread through the volume, which is what makes the wind slow inside and fast above, and the
+     * shear at its top roll up into the gusts that run over a field.
+     *
+     * Only the GPU fluid has porous obstacles; the CPU fluid leaves them out.
+     *
+     * @type {number}
+     */
+    drag: number;
     /**
      * True when the previous tick stamped a non-zero wall velocity. A body
      * that stops (or sleeps — the solver zeroes velocities on sleep) must
@@ -58,6 +74,7 @@ export class FluidObstacle {
     hash(): number;
     toJSON(): {
         inflation: number;
+        drag: number;
     };
     fromJSON(json: any): void;
     /**

package/src/engine/physics/fluid/ecs/FluidObstacle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidObstacle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidObstacle.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAEI;;;;;;;;;;;;OAYG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;OAOG;IACH,aAFU,OAAO,CAEG;IAEpB;;;OAGG;IACH,cAHW,aAAa,GACZ,OAAO,CAUlB;IAED;;OAEG;IACH,QAFY,MAAM,CAIjB;IAED;;MAIC;IAED,0BAEC;IASL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CAZtC;;kBAIS,MAAM"}
+{"version":3,"file":"FluidObstacle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidObstacle.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAEI;;;;;;;;;;;;OAYG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;;;;;;;;OAcG;IACH,MAFU,MAAM,CAEP;IAET;;;;;;;OAOG;IACH,aAFU,OAAO,CAEG;IAEpB;;;OAGG;IACH,cAHW,aAAa,GACZ,OAAO,CAUlB;IAED;;OAEG;IACH,QAFY,MAAM,CAIjB;IAED;;;MAKC;IAED,0BAGC;IASL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CAZtC;;kBAIS,MAAM"}

package/src/engine/physics/fluid/ecs/FluidObstacle.js

@@ -1,3 +1,4 @@
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
 import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
 
 /**
@@ -42,6 +43,23 @@ export class FluidObstacle {
      */
     inflation = 0;
 
+    /**
+     * How the obstacle stops the wind, 1/m. `0` (default): it is **solid**, and the air takes its
+     * velocity wherever it is. Above `0`: it is **porous**, the air passes through it and is slowed
+     * toward its velocity by `drag · |u − v| · (u − v)` each second, `u` the air's velocity and `v`
+     * the obstacle's.
+     *
+     * For something made of leaves or blades it is their drag coefficient times their one-sided area
+     * per cubic metre of the volume: a canopy of grass, a crop, the crown of a tree, a hedge. Their drag
+     * is spread through the volume, which is what makes the wind slow inside and fast above, and the
+     * shear at its top roll up into the gusts that run over a field.
+     *
+     * Only the GPU fluid has porous obstacles; the CPU fluid leaves them out.
+     *
+     * @type {number}
+     */
+    drag = 0;
+
     /**
      * True when the previous tick stamped a non-zero wall velocity. A body
      * that stops (or sleeps — the solver zeroes velocities on sleep) must
@@ -63,24 +81,26 @@ export class FluidObstacle {
         if (other === null || other === undefined || other.isFluidObstacle !== true) {
             return false;
         }
-        return this.inflation === other.inflation;
+        return this.inflation === other.inflation && this.drag === other.drag;
     }
 
     /**
      * @return {number}
      */
     hash() {
-        return computeHashFloat(this.inflation);
+        return hash_mix2(computeHashFloat(this.inflation), computeHashFloat(this.drag));
     }
 
     toJSON() {
         return {
             inflation: this.inflation,
+            drag: this.drag,
         };
     }
 
     fromJSON(json) {
         if (json.inflation !== undefined) this.inflation = json.inflation;
+        this.drag = json.drag ?? 0;
     }
 }