@woosh/meep-engine 3.69.0 → 3.70.0

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

@@ -8,7 +8,7 @@ import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
  *
  *     dv/dt = force + drag · (wind − v)
  *
- * plus a gust carried on top of the wind.
+ * with turbulence carried on top of the wind.
  *
  * One effector covers the whole family of "push everything" behaviours —
  * pick the regime by which fields you set:
@@ -32,9 +32,9 @@ 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}.
+ *   - **`turbulence_intensity`** — weather on top of the wind: a field of eddies, the
+ *     wind's speed times the intensity in rms, carried along by the wind. See
+ *     {@link turbulence_intensity}.
  *
  * `wind` only enters through the drag term — with `drag = 0` it is inert by
  * construction (the model degenerates to dv/dt = force).
@@ -42,20 +42,21 @@ import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
  * ## The far field
  *
  * 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
+ * every global into one far field — `D = Σ drag`, the drag-weighted means of the
+ * winds, of the turbulence intensities and of the length scales, and the sum of the
+ * forces — and integrates `u`, the far field's mean, toward the mean wind at `D`. The
+ * far field is `u` plus its turbulence, `σ = intensity · |u|` in rms, carried by `u`.
+ * {@link FluidSystem} and {@link WorkerFluidSystem} then bring every field to the mean
+ * once a step through the atmosphere identity (`fluid_apply_atmosphere`); the GPU fluid
+ * brings every cascade to the whole far field, turbulence and all. 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.
  *
  * `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` and `gust` in units/s,
- * `drag` in 1/s. The `world_to_grid` matrix's linear part converts the vectors per
+ * All quantities are WORLD-space: `force` in units/s², `wind` in units/s, `drag` in
+ * 1/s, `turbulence_length` in units. 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.
  *
@@ -92,110 +93,38 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
     drag = 0;
 
     /**
-     * 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.
+     * Turbulence intensity, `σ_u / |U|`: the rms of the far field's eddies on each axis, as a share
+     * of the far field's mean speed `|U|`. 0, the default, is no turbulence. Over grass and crops
+     * the near-ground wind measures 0.15 to 0.2; MIL-F-8785C's low-altitude model gives 0.19 at
+     * 20 ft.
      *
-     * 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.
+     * The eddies are isotropic von Kármán turbulence, frozen and carried by the mean wind
+     * (Taylor's hypothesis), from one repeating tile (`FLUID_TURBULENCE_TILE_RESOLUTION`). The
+     * fluid then shapes them: the ground's shear stretches them into streaks, a canopy's drag
+     * rolls them up. Read through `GPUFluidSystem#far_field_at`; `far_field` is the mean.
      *
      * @type {number}
      */
-    gust = 0;
+    turbulence_intensity = 0;
 
     /**
-     * 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 turbulence's length scale `L`, WORLD units, > 0: the von Kármán spectrum's, whose most
+     * energetic wavelength is about `4.05·L` and whose longitudinal integral scale is `0.747·L`.
+     * The tile repeats every `16·L` across and `4·L` up, and holds wavelengths down to `L/4`.
      *
-     * 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.
+     * The default, 58.6 m, is MIL-F-8785C's low-altitude integral scale at 20 ft (43.8 m),
+     * divided by 0.747. Smaller scales reach down to a canopy's own eddies at the cost of a
+     * shorter repeat.
      *
-     * @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.
+     * Changing it rescales the eddies about the world's origin, so the air there jumps; it is a
+     * property of a scene's weather, set once.
      *
-     * @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`
+     * @type {number}
      */
-    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;
-    }
+    turbulence_length = 58.6;
 
     /**
-     * Every field, the gust's phases included: two globals are equal when they make the
-     * same air from now on.
+     * Every field: two globals are equal when they make the same air.
      *
      * @param {AbstractFluidEffector} other
      * @return {boolean}
@@ -214,11 +143,8 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
             && this.wind[0] === other.wind[0]
             && this.wind[1] === other.wind[1]
             && 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];
+            && this.turbulence_intensity === other.turbulence_intensity
+            && this.turbulence_length === other.turbulence_length;
     }
 
     /**
@@ -238,17 +164,9 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
             hash_mix3(
                 computeHashFloat(this.wind[2]),
                 computeHashFloat(this.drag),
-                computeHashFloat(this.gust)
+                computeHashFloat(this.turbulence_intensity)
             ),
-            hash_mix3(
-                computeHashFloat(this.gust_period),
-                computeHashFloat(this.gust_phase[0]),
-                hash_mix3(
-                    computeHashFloat(this.gust_phase[1]),
-                    computeHashFloat(this.gust_phase[2]),
-                    0
-                )
-            )
+            computeHashFloat(this.turbulence_length)
         );
     }
 
@@ -267,59 +185,3 @@ export class GlobalFluidEffector extends AbstractFluidEffector {
  * @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

@@ -1,17 +1,14 @@
 /**
- * Binary serialization for {@link GlobalFluidEffector}: `force`, `wind`, `drag`, `gust`,
- * `gust_period`, and the gust's three phases, every one an f64.
+ * Binary serialization for {@link GlobalFluidEffector}: `force`, `wind`, `drag`,
+ * `turbulence_intensity` and `turbulence_length`, 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 1
  *
- * ## 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.
+ * Version 0 carried a gust (`gust`, `gust_period` and three phases) where version 1 carries the
+ * turbulence; {@link GlobalFluidEffectorSerializationUpgrader_0_1} reads a version-0 stream as
+ * version 1, the gust dropped (it has no turbulence equivalent) and no turbulence. A host that
+ * loads version-0 saves registers it beside this adapter. The spec's exact byte count is what makes
+ * a field added without a bump fail rather than shift every component after this one.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

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

@@ -1 +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"}
+{"version":3,"file":"GlobalFluidEffectorSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/GlobalFluidEffectorSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH;;IAEI,kCAA4B;IAG5B;;;OAGG;IACH,uCAFW,mBAAmB,QAe7B;IAED;;;OAGG;IACH,yCAFW,mBAAmB,QAe7B;CACJ;gDA5D+C,gEAAgE;oCAC5E,0BAA0B"}

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

@@ -2,19 +2,16 @@ import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/Bin
 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.
+ * Binary serialization for {@link GlobalFluidEffector}: `force`, `wind`, `drag`,
+ * `turbulence_intensity` and `turbulence_length`, 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 1
  *
- * ## 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.
+ * Version 0 carried a gust (`gust`, `gust_period` and three phases) where version 1 carries the
+ * turbulence; {@link GlobalFluidEffectorSerializationUpgrader_0_1} reads a version-0 stream as
+ * version 1, the gust dropped (it has no turbulence equivalent) and no turbulence. A host that
+ * loads version-0 saves registers it beside this adapter. The spec's exact byte count is what makes
+ * a field added without a bump fail rather than shift every component after this one.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -22,7 +19,7 @@ import { GlobalFluidEffector } from "./GlobalFluidEffector.js";
 export class GlobalFluidEffectorSerializationAdapter extends BinaryClassSerializationAdapter {
 
     klass = GlobalFluidEffector;
-    version = 0;
+    version = 1;
 
     /**
      * @param {BinaryBuffer} buffer
@@ -39,12 +36,8 @@ export class GlobalFluidEffectorSerializationAdapter extends BinaryClassSerializ
 
         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]);
+        buffer.writeFloat64(value.turbulence_intensity);
+        buffer.writeFloat64(value.turbulence_length);
     }
 
     /**
@@ -62,11 +55,7 @@ export class GlobalFluidEffectorSerializationAdapter extends BinaryClassSerializ
 
         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();
+        value.turbulence_intensity = buffer.readFloat64();
+        value.turbulence_length = buffer.readFloat64();
     }
 }

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

@@ -0,0 +1,16 @@
+/**
+ * Reads a version-0 {@link GlobalFluidEffector} stream as version 1: `force`, `wind` and `drag` as
+ * they were; the gust (`gust`, `gust_period`, three phases), which version 1 no longer has, dropped;
+ * then no turbulence, at the default length scale.
+ *
+ * Every value an f64, in and out.
+ */
+export class GlobalFluidEffectorSerializationUpgrader_0_1 extends BinaryClassUpgrader {
+    /**
+     * @param {BinaryBuffer} source
+     * @param {BinaryBuffer} target
+     */
+    upgrade(source: BinaryBuffer, target: BinaryBuffer): void;
+}
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+//# sourceMappingURL=GlobalFluidEffectorSerializationUpgrader_0_1.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GlobalFluidEffectorSerializationUpgrader_0_1.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/GlobalFluidEffectorSerializationUpgrader_0_1.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH;IAII;;;OAGG;IACH,0DAeC;CACJ;oCAlCmC,oDAAoD"}

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

@@ -0,0 +1,35 @@
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+import { GlobalFluidEffector } from "./GlobalFluidEffector.js";
+
+/**
+ * Reads a version-0 {@link GlobalFluidEffector} stream as version 1: `force`, `wind` and `drag` as
+ * they were; the gust (`gust`, `gust_period`, three phases), which version 1 no longer has, dropped;
+ * then no turbulence, at the default length scale.
+ *
+ * Every value an f64, in and out.
+ */
+export class GlobalFluidEffectorSerializationUpgrader_0_1 extends BinaryClassUpgrader {
+    __startVersion = 0;
+    __targetVersion = 1;
+
+    /**
+     * @param {BinaryBuffer} source
+     * @param {BinaryBuffer} target
+     */
+    upgrade(source, target) {
+        // force, wind, drag
+        for (let i = 0; i < 7; i++) {
+            target.writeFloat64(source.readFloat64());
+        }
+
+        // the gust, its period and its three phases
+        for (let i = 0; i < 5; i++) {
+            source.readFloat64();
+        }
+
+        const defaults = new GlobalFluidEffector();
+
+        target.writeFloat64(defaults.turbulence_intensity);
+        target.writeFloat64(defaults.turbulence_length);
+    }
+}

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

@@ -7,7 +7,7 @@
  *
  * Air the atmosphere alone acts on relaxes toward the far field at `D` while carrying the
  * far field's own changes, so its deviation `e = v − v_far` obeys `de/dt = −D·e` whatever
- * the gust does and however `D` varied: the step is exact over any interval, one tick or
+ * the mean does and however `D` varied: the step is exact over any interval, one tick or
  * many, and a face equal to the far field stays equal to it.
  *
  * The body force is applied exactly in the same linear step, through the forced response

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

@@ -9,7 +9,7 @@ import { FluidAtmosphere, FluidFieldAtmosphere } from "./FluidAtmosphere.js";
  *
  * Air the atmosphere alone acts on relaxes toward the far field at `D` while carrying the
  * far field's own changes, so its deviation `e = v − v_far` obeys `de/dt = −D·e` whatever
- * the gust does and however `D` varied: the step is exact over any interval, one tick or
+ * the mean does and however `D` varied: the step is exact over any interval, one tick or
  * many, and a face equal to the far field stays equal to it.
  *
  * The body force is applied exactly in the same linear step, through the forced response

package/src/engine/physics/fluid/turbulence/FLUID_TURBULENCE_TILE.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Texels of the far field's turbulence tile on x, y and z: 128 × 32 × 128, y up.
+ *
+ * The tile repeats, so the far field's turbulence repeats every `16·L` across the wind and `4·L`
+ * up, `L` the length scale: four of the spectrum's most energetic wavelength (`≈ 4.05·L`) across,
+ * one up. 4 MiB as `rgba16float`.
+ *
+ * @type {ReadonlyArray<number>}
+ */
+export const FLUID_TURBULENCE_TILE_RESOLUTION: ReadonlyArray<number>;
+/**
+ * Texels of the turbulence tile per length scale `L`: the tile's spacing is `L/8`.
+ *
+ * The von Kármán spectrum is a function of `k·L` alone, so a tile laid out in units of `L` is the same
+ * tile for every `L`: the length scale is only how far apart its texels are in the world, and changing
+ * it regenerates nothing. Eight a length keeps the spectrum's peak (`≈ 4·L`) at 32 texels and resolves
+ * wavelengths down to `L` at 8 texels each, the fewest a trilinear read and the solver's advection
+ * carry without visible loss; shorter ones, down to the tile's Nyquist `L/4`, are in it too.
+ *
+ * @type {number}
+ */
+export const FLUID_TURBULENCE_TEXELS_PER_LENGTH: number;
+/**
+ * The seed the engine's turbulence tile is generated from: one tile, the same on every machine.
+ * @type {number}
+ */
+export const FLUID_TURBULENCE_TILE_SEED: number;
+//# sourceMappingURL=FLUID_TURBULENCE_TILE.d.ts.map

package/src/engine/physics/fluid/turbulence/FLUID_TURBULENCE_TILE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_TURBULENCE_TILE.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/turbulence/FLUID_TURBULENCE_TILE.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,+CAFU,cAAc,MAAM,CAAC,CAE+C;AAE9E;;;;;;;;;;GAUG;AACH,iDAFU,MAAM,CAEoC;AAEpD;;;GAGG;AACH,yCAFU,MAAM,CAEmC"}

package/src/engine/physics/fluid/turbulence/FLUID_TURBULENCE_TILE.js

@@ -0,0 +1,29 @@
+/**
+ * Texels of the far field's turbulence tile on x, y and z: 128 × 32 × 128, y up.
+ *
+ * The tile repeats, so the far field's turbulence repeats every `16·L` across the wind and `4·L`
+ * up, `L` the length scale: four of the spectrum's most energetic wavelength (`≈ 4.05·L`) across,
+ * one up. 4 MiB as `rgba16float`.
+ *
+ * @type {ReadonlyArray<number>}
+ */
+export const FLUID_TURBULENCE_TILE_RESOLUTION = Object.freeze([128, 32, 128]);
+
+/**
+ * Texels of the turbulence tile per length scale `L`: the tile's spacing is `L/8`.
+ *
+ * The von Kármán spectrum is a function of `k·L` alone, so a tile laid out in units of `L` is the same
+ * tile for every `L`: the length scale is only how far apart its texels are in the world, and changing
+ * it regenerates nothing. Eight a length keeps the spectrum's peak (`≈ 4·L`) at 32 texels and resolves
+ * wavelengths down to `L` at 8 texels each, the fewest a trilinear read and the solver's advection
+ * carry without visible loss; shorter ones, down to the tile's Nyquist `L/4`, are in it too.
+ *
+ * @type {number}
+ */
+export const FLUID_TURBULENCE_TEXELS_PER_LENGTH = 8;
+
+/**
+ * The seed the engine's turbulence tile is generated from: one tile, the same on every machine.
+ * @type {number}
+ */
+export const FLUID_TURBULENCE_TILE_SEED = 0x6b6172;

package/src/engine/physics/fluid/turbulence/fluid_atmosphere_velocity_at.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The far field a {@link FluidAtmosphere} record describes, at a WORLD point: its mean `u`, plus
+ * `σ·T((x − o) ⊙ S⁻¹)` when it has turbulence, `T` the engine's tile read trilinearly
+ * ({@link fluid_turbulence_tile_sample}), as every GPU reader of the far field reads it.
+ *
+ * With `σ = 0` it is `u`, and the tile is never made. Allocates nothing once the tile exists.
+ *
+ * @param {Float64Array|Float32Array|number[]} out receives `[x, y, z]`, WORLD units per second
+ * @param {Float64Array|number[]} atmosphere
+ * @param {number} offset where the record starts
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ */
+export function fluid_atmosphere_velocity_at(out: Float64Array | Float32Array | number[], atmosphere: Float64Array | number[], offset: number, x: number, y: number, z: number): void;
+//# sourceMappingURL=fluid_atmosphere_velocity_at.d.ts.map

package/src/engine/physics/fluid/turbulence/fluid_atmosphere_velocity_at.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fluid_atmosphere_velocity_at.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/turbulence/fluid_atmosphere_velocity_at.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AACH,kDAPW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QA4BhB"}

package/src/engine/physics/fluid/turbulence/fluid_atmosphere_velocity_at.js

@@ -0,0 +1,49 @@
+import { FluidAtmosphere } from "../FluidAtmosphere.js";
+import { fluid_turbulence_inverse_tile_size } from "./fluid_turbulence_inverse_tile_size.js";
+import { fluid_turbulence_tile_data } from "./fluid_turbulence_tile_data.js";
+import { fluid_turbulence_tile_sample } from "./fluid_turbulence_tile_sample.js";
+
+const inverse_size = new Float64Array(3);
+const coordinate = new Float64Array(3);
+
+/**
+ * The far field a {@link FluidAtmosphere} record describes, at a WORLD point: its mean `u`, plus
+ * `σ·T((x − o) ⊙ S⁻¹)` when it has turbulence, `T` the engine's tile read trilinearly
+ * ({@link fluid_turbulence_tile_sample}), as every GPU reader of the far field reads it.
+ *
+ * With `σ = 0` it is `u`, and the tile is never made. Allocates nothing once the tile exists.
+ *
+ * @param {Float64Array|Float32Array|number[]} out receives `[x, y, z]`, WORLD units per second
+ * @param {Float64Array|number[]} atmosphere
+ * @param {number} offset where the record starts
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ */
+export function fluid_atmosphere_velocity_at(out, atmosphere, offset, x, y, z) {
+    const sigma = atmosphere[offset + FluidAtmosphere.TURBULENCE_SIGMA];
+
+    const ux = atmosphere[offset + FluidAtmosphere.VELOCITY_X];
+    const uy = atmosphere[offset + FluidAtmosphere.VELOCITY_Y];
+    const uz = atmosphere[offset + FluidAtmosphere.VELOCITY_Z];
+
+    if (sigma === 0) {
+        out[0] = ux;
+        out[1] = uy;
+        out[2] = uz;
+
+        return;
+    }
+
+    fluid_turbulence_inverse_tile_size(inverse_size, atmosphere[offset + FluidAtmosphere.TURBULENCE_LENGTH]);
+
+    coordinate[0] = (x - atmosphere[offset + FluidAtmosphere.TURBULENCE_OFFSET_X]) * inverse_size[0];
+    coordinate[1] = (y - atmosphere[offset + FluidAtmosphere.TURBULENCE_OFFSET_Y]) * inverse_size[1];
+    coordinate[2] = (z - atmosphere[offset + FluidAtmosphere.TURBULENCE_OFFSET_Z]) * inverse_size[2];
+
+    fluid_turbulence_tile_sample(out, fluid_turbulence_tile_data(), coordinate);
+
+    out[0] = ux + sigma * out[0];
+    out[1] = uy + sigma * out[1];
+    out[2] = uz + sigma * out[2];
+}

package/src/engine/physics/fluid/turbulence/fluid_turbulence_inverse_tile_size.d.ts

@@ -0,0 +1,11 @@
+/**
+ * One over the turbulence tile's size in the world on each axis, for a length scale `L`: a world
+ * distance times it is a distance in tiles. The tile is `n·L / FLUID_TURBULENCE_TEXELS_PER_LENGTH`
+ * on an axis of `n` texels.
+ *
+ * @param {Float64Array|Float32Array|number[]} out receives x, y, z
+ * @param {number} length `L`, WORLD units, > 0
+ * @returns {Float64Array|Float32Array|number[]} `out`
+ */
+export function fluid_turbulence_inverse_tile_size(out: Float64Array | Float32Array | number[], length: number): Float64Array | Float32Array | number[];
+//# sourceMappingURL=fluid_turbulence_inverse_tile_size.d.ts.map

package/src/engine/physics/fluid/turbulence/fluid_turbulence_inverse_tile_size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fluid_turbulence_inverse_tile_size.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/turbulence/fluid_turbulence_inverse_tile_size.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wDAJW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,UAClC,MAAM,GACJ,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,CAQ9C"}

package/src/engine/physics/fluid/turbulence/fluid_turbulence_inverse_tile_size.js

@@ -0,0 +1,18 @@
+import { FLUID_TURBULENCE_TEXELS_PER_LENGTH, FLUID_TURBULENCE_TILE_RESOLUTION } from "./FLUID_TURBULENCE_TILE.js";
+
+/**
+ * One over the turbulence tile's size in the world on each axis, for a length scale `L`: a world
+ * distance times it is a distance in tiles. The tile is `n·L / FLUID_TURBULENCE_TEXELS_PER_LENGTH`
+ * on an axis of `n` texels.
+ *
+ * @param {Float64Array|Float32Array|number[]} out receives x, y, z
+ * @param {number} length `L`, WORLD units, > 0
+ * @returns {Float64Array|Float32Array|number[]} `out`
+ */
+export function fluid_turbulence_inverse_tile_size(out, length) {
+    for (let axis = 0; axis < 3; axis++) {
+        out[axis] = FLUID_TURBULENCE_TEXELS_PER_LENGTH / (FLUID_TURBULENCE_TILE_RESOLUTION[axis] * length);
+    }
+
+    return out;
+}