@woosh/meep-engine 3.49.0 → 3.50.0

package/src/engine/graphics3/ParticipatingMedia.d.ts

@@ -110,6 +110,12 @@ export class ParticipatingMedia {
     noise_velocity: number[];
     /**
      * How much of the scene's wind this medium feels. 1 is all of it, 0 is none.
+     *
+     * The wind is the scene's: its far field, `GPUFluidSystem.far_field`, folded into the noise's
+     * scroll by {@link ParticipatingMediaSystem}, and where the scene's fluid departs from it, the
+     * departure, which the shaders sample from the published wind field wherever they evaluate the
+     * noise. A scene without a `GPUFluidSystem` is still air.
+     *
      * @type {number}
      */
     noise_wind_factor: number;

package/src/engine/graphics3/ParticipatingMedia.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticipatingMedia.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMedia.js"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;GAGG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;GAGG;AACH,iCAFU,MAAM,CAEsB;AAEtC;;;GAGG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;GAGG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAuHI;;;OAGG;IACH,4BAFa,kBAAkB,CAQ9B;IA/HD;;;;;;;;OAQG;IACH,SAFU,MAAM,CAEU;IAE1B;;;;;;;;OAQG;IACH,eAFU,uBAAuB,CAE8C;IAE/E;;;;;;;;OAQG;IACH,eAFU,MAAM,CAEsB;IAEtC;;;;;;;;;;OAUG;IACH,gBAFU,MAAM,CAEwB;IAExC;;;;OAIG;IACH,aAFU,MAAM,CAEkB;IAElC;;;;OAIG;IACH,YAFU,MAAM,CAEgB;IAEhC;;;;OAIG;IACH,gBAFU,MAAM,EAAE,CAES;IAE3B;;;OAGG;IACH,mBAFU,MAAM,CAE8B;IAE9C;;;OAGG;IACH,eAFU,MAAM,CAEsB;IAmBtC;;OAEG;IACH,qCAgBC;IApCD;;;;;;;;;;;;OAYG;IACH,gCAEC;IAmCD;;;;;;;;;;;;;;;MAmBC;IAED;;;;;;;;;;;;;OAaG;IACH;QAZ4B,OAAO,GAAxB,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,aAAa,GAA9B,MAAM;QAGW,cAAc,GAA/B,MAAM;QACW,WAAW,GAA5B,MAAM;QACW,UAAU,GAA3B,MAAM;QACa,cAAc,GAAjC,MAAM,EAAE;QACS,iBAAiB,GAAlC,MAAM;QACW,aAAa,GAA9B,MAAM;aAkDhB;IAED;;;;;;;OAOG;IACH,QAFa,MAAM,CAsBlB;IAED;;;OAGG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAYnB;CACJ;;kBAIS,MAAM;;wCAvUT,8DAA8D"}
+{"version":3,"file":"ParticipatingMedia.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMedia.js"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;GAGG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;GAGG;AACH,iCAFU,MAAM,CAEsB;AAEtC;;;GAGG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;GAGG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA6HI;;;OAGG;IACH,4BAFa,kBAAkB,CAQ9B;IArID;;;;;;;;OAQG;IACH,SAFU,MAAM,CAEU;IAE1B;;;;;;;;OAQG;IACH,eAFU,uBAAuB,CAE8C;IAE/E;;;;;;;;OAQG;IACH,eAFU,MAAM,CAEsB;IAEtC;;;;;;;;;;OAUG;IACH,gBAFU,MAAM,CAEwB;IAExC;;;;OAIG;IACH,aAFU,MAAM,CAEkB;IAElC;;;;OAIG;IACH,YAFU,MAAM,CAEgB;IAEhC;;;;OAIG;IACH,gBAFU,MAAM,EAAE,CAES;IAE3B;;;;;;;;;OASG;IACH,mBAFU,MAAM,CAE8B;IAE9C;;;OAGG;IACH,eAFU,MAAM,CAEsB;IAmBtC;;OAEG;IACH,qCAgBC;IApCD;;;;;;;;;;;;OAYG;IACH,gCAEC;IAmCD;;;;;;;;;;;;;;;MAmBC;IAED;;;;;;;;;;;;;OAaG;IACH;QAZ4B,OAAO,GAAxB,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,aAAa,GAA9B,MAAM;QAGW,cAAc,GAA/B,MAAM;QACW,WAAW,GAA5B,MAAM;QACW,UAAU,GAA3B,MAAM;QACa,cAAc,GAAjC,MAAM,EAAE;QACS,iBAAiB,GAAlC,MAAM;QACW,aAAa,GAA9B,MAAM;aAkDhB;IAED;;;;;;;OAOG;IACH,QAFa,MAAM,CAsBlB;IAED;;;OAGG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAYnB;CACJ;;kBAIS,MAAM;;wCA7UT,8DAA8D"}

package/src/engine/graphics3/ParticipatingMedia.js

@@ -139,6 +139,12 @@ export class ParticipatingMedia {
 
     /**
      * How much of the scene's wind this medium feels. 1 is all of it, 0 is none.
+     *
+     * The wind is the scene's: its far field, `GPUFluidSystem.far_field`, folded into the noise's
+     * scroll by {@link ParticipatingMediaSystem}, and where the scene's fluid departs from it, the
+     * departure, which the shaders sample from the published wind field wherever they evaluate the
+     * noise. A scene without a `GPUFluidSystem` is still air.
+     *
      * @type {number}
      */
     noise_wind_factor = DEFAULT_NOISE_WIND_FACTOR;

package/src/engine/graphics3/ParticipatingMediaSystem.d.ts

@@ -1,31 +1,29 @@
 /**
- * Copy what the component and its transform say onto the volume Shade will render.
+ * Copy what the component and its transform say onto the volume Shade will render, field by field,
+ * comparing while assigning, and say whether anything differed — which is whether the GPU table
+ * has to be repacked.
  *
  * The particle spec is **copied, not referenced**: two entities are routinely built from the same
  * blueprint and would otherwise share one spec, so tuning one volume's particle would silently
- * retune the other's.
+ * retune the other's. The scroll and flow phases are the volume's own state and are not touched
+ * here; `noise_wind_factor` is a setting, and the shaders read it.
+ *
+ * **The transform is compared and copied by its matrix**, element by element straight off the
+ * `Transform64` — its first sixteen elements — and never through its `matrix` getter, which makes a
+ * view per read. The matrix is the entire transform the GPU is given, so this is exactly the question
+ * "would the upload differ", and it catches a transform posed by writing its matrix, which comparing
+ * position, rotation and scale would not. `fromMatrix` copies the sixteen and then decomposes them,
+ * leaving the matrix bit-identical, so the volume carries the authored matrix exactly.
  *
  * @param {ParticipatingMediaVolume} volume Shade's
  * @param {ParticipatingMedia} component meep's
  * @param {Transform64} transform where the box is
+ * @returns {boolean} whether the volume differed from what the component and transform say
  */
-export function participating_media_volume_write(volume: ParticipatingMediaVolume, component: ParticipatingMedia, transform: Transform64): void;
+export function participating_media_volume_write(volume: ParticipatingMediaVolume, component: ParticipatingMedia, transform: Transform64): boolean;
 /**
- * Whether the volume already says what the component and transform say.
- *
- * True on all but a handful of frames, which is the point of asking: a `false` here costs the whole
- * scene's volumetrics table a trip to the GPU.
- *
- * **The transform is compared by its matrix rather than by its components**, because the matrix is
- * the entire transform the GPU is given — the volume's position, rotation and scale are never read
- * on their own. That makes this exactly the question worth asking, "would the upload differ", and it
- * catches a transform posed by writing its matrix, which comparing position, rotation and scale
- * would not.
- *
- * The volume's matrix is a `Float64Array` and the component's is a `Float32Array`, and the strict
- * comparison across the two still holds: {@link participating_media_volume_write} copies the matrix
- * across element by element, and every f32 value widens to f64 exactly. It is a recomposed matrix
- * that would not compare equal, which is why the write does not recompose.
+ * Whether the volume already says what the component and transform say: the question
+ * {@link participating_media_volume_write} answers while it assigns, asked without assigning.
  *
  * @param {ParticipatingMediaVolume} volume
  * @param {ParticipatingMedia} component
@@ -54,10 +52,22 @@ export function participating_media_volume_is_current(volume: ParticipatingMedia
  * tens, so the comparison is cheaper than the signal plumbing it replaces. The price is latency: a
  * change is visible within a frame rather than instantly.
  *
- * **Nothing is uploaded unless something actually changed.** The GPU table is repacked whole
- * whenever {@link SceneVolumetrics.version} moves, so an unconditional copy every frame would
- * re-upload every volume in the scene forever. The comparison is what decides, and on almost every
- * frame it decides nothing has to happen.
+ * **Nothing is uploaded unless something actually changed**, and what is uploaded is what changed.
+ * A change to anything but the noise phases moves {@link SceneVolumetrics#version}, and the GPU
+ * table is repacked whole; a scroll of the noise moves only {@link SceneVolumetrics#noise_version},
+ * and the rows get their phase words. The comparison, made while assigning, is what decides, and on
+ * almost every frame it decides nothing but the scroll has to happen.
+ *
+ * **The wind: the far field here, the rest on the GPU.** A noisy volume scrolls with the scene's far
+ * field `v_far(t)` × `noise_wind_factor` + `noise_velocity`, folded into its phases on the host: the
+ * far field is {@link GPUFluidSystem#far_field}, the `GlobalFluidEffector`s as `FluidEffectorsSystem`
+ * folds them — synchronous and deterministic, nothing read back. Where the scene's fluid differs from
+ * its far field, the shaders that evaluate the noise sample the published wind field there and carry
+ * the noise by the difference, flow-map style, on the volume's flow clock, which the advance moves on
+ * for every volume that feels the wind (`chunk_participating_media_noise`); uniform air costs and
+ * looks as a scroll alone does. Without a `GPUFluidSystem` in the entity manager the air is still.
+ *
+ * Allocates nothing per frame.
  *
  * @see ParticipatingMedia the component
  * @see SceneVolumetrics what the volumes are handed to

package/src/engine/graphics3/ParticipatingMediaSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticipatingMediaSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMediaSystem.js"],"names":[],"mappings":"AAwKA;;;;;;;;;;GAUG;AACH,yDAJW,wBAAwB,aACxB,kBAAkB,aAClB,WAAW,QAwBrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8DALW,wBAAwB,aACxB,kBAAkB,aAClB,WAAW,GACT,OAAO,CAWnB;AAhOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAmBI;;;OAGG;IACH,oDASC;IA9BD,iEAAiD;IAgCjD,2CAIC;IAED,4CAIC;IAED;;;;OAIG;IACH,gBAJW,kBAAkB,aAClB,WAAW,UACX,MAAM,QAUhB;IAED;;;;OAIG;IACH,kBAJW,kBAAkB,aAClB,WAAW,UACX,MAAM,QAIhB;;CA2DJ;yCAjKM,8DAA8D;mCAGlC,yBAAyB;4BADhC,iCAAiC;uBADtC,kBAAkB"}
+{"version":3,"file":"ParticipatingMediaSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMediaSystem.js"],"names":[],"mappings":"AAyRA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yDALW,wBAAwB,aACxB,kBAAkB,aAClB,WAAW,GACT,OAAO,CAmDnB;AAED;;;;;;;;GAQG;AACH,8DALW,wBAAwB,aACxB,kBAAkB,aAClB,WAAW,GACT,OAAO,CAYnB;AA/UD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;IA+BI;;;OAGG;IACH,oDASC;IA1CD,iEAAiD;IA4CjD,2CAIC;IAED,4CAIC;IAED;;;;OAIG;IACH,gBAJW,kBAAkB,aAClB,WAAW,UACX,MAAM,QAehB;IAED;;;;OAIG;IACH,kBAJW,kBAAkB,aAClB,WAAW,UACX,MAAM,QAIhB;;CAmHJ;yCAnRM,8DAA8D;mCAIlC,yBAAyB;4BAFL,iCAAiC;uBADjE,kBAAkB"}

package/src/engine/graphics3/ParticipatingMediaSystem.js

@@ -1,13 +1,41 @@
 import { assert } from "../../core/assert.js";
-import { isArrayEqualStrict } from "../../core/collection/array/isArrayEqualStrict.js";
 import {
     participating_media_volume_advance_noise,
     ParticipatingMediaVolume
 } from "../../shade/renderer/volumetrics/ParticipatingMediaVolume.js";
 import { System } from "../ecs/System.js";
-import { Transform64 } from "../ecs/transform/Transform64.js";
+import { Transform64, TRANSFORM64_MATRIX_OFFSET } from "../ecs/transform/Transform64.js";
+import { GPUFluidSystem } from "./GPUFluidSystem.js";
 import { ParticipatingMedia } from "./ParticipatingMedia.js";
 
+/**
+ * One linked entity: its component, its transform, and the renderer's volume made for it.
+ */
+class MediaEntry {
+    /** @type {ParticipatingMedia} */
+    component;
+
+    /** @type {Transform64} */
+    transform;
+
+    /** @type {ParticipatingMediaVolume} */
+    volume;
+
+    /** Where the entry sits in the system's list. */
+    index = -1;
+
+    /**
+     * @param {ParticipatingMedia} component
+     * @param {Transform64} transform
+     * @param {ParticipatingMediaVolume} volume
+     */
+    constructor(component, transform, volume) {
+        this.component = component;
+        this.transform = transform;
+        this.volume = volume;
+    }
+}
+
 /**
  * Mirrors fog, smoke and cloud entities into Shade's volumetrics.
  *
@@ -29,10 +57,22 @@ import { ParticipatingMedia } from "./ParticipatingMedia.js";
  * tens, so the comparison is cheaper than the signal plumbing it replaces. The price is latency: a
  * change is visible within a frame rather than instantly.
  *
- * **Nothing is uploaded unless something actually changed.** The GPU table is repacked whole
- * whenever {@link SceneVolumetrics.version} moves, so an unconditional copy every frame would
- * re-upload every volume in the scene forever. The comparison is what decides, and on almost every
- * frame it decides nothing has to happen.
+ * **Nothing is uploaded unless something actually changed**, and what is uploaded is what changed.
+ * A change to anything but the noise phases moves {@link SceneVolumetrics#version}, and the GPU
+ * table is repacked whole; a scroll of the noise moves only {@link SceneVolumetrics#noise_version},
+ * and the rows get their phase words. The comparison, made while assigning, is what decides, and on
+ * almost every frame it decides nothing but the scroll has to happen.
+ *
+ * **The wind: the far field here, the rest on the GPU.** A noisy volume scrolls with the scene's far
+ * field `v_far(t)` × `noise_wind_factor` + `noise_velocity`, folded into its phases on the host: the
+ * far field is {@link GPUFluidSystem#far_field}, the `GlobalFluidEffector`s as `FluidEffectorsSystem`
+ * folds them — synchronous and deterministic, nothing read back. Where the scene's fluid differs from
+ * its far field, the shaders that evaluate the noise sample the published wind field there and carry
+ * the noise by the difference, flow-map style, on the volume's flow clock, which the advance moves on
+ * for every volume that feels the wind (`chunk_participating_media_noise`); uniform air costs and
+ * looks as a scroll alone does. Without a `GPUFluidSystem` in the entity manager the air is still.
+ *
+ * Allocates nothing per frame.
  *
  * @see ParticipatingMedia the component
  * @see SceneVolumetrics what the volumes are handed to
@@ -52,10 +92,22 @@ export class ParticipatingMediaSystem extends System {
     #scene;
 
     /**
-     * @type {Map<number, {component: ParticipatingMedia, transform: Transform, volume: ParticipatingMediaVolume}>}
+     * @type {Map<number, MediaEntry>}
      */
     #entries = new Map();
 
+    /**
+     * The same entries as {@link #entries}, in a list a frame walks without an iterator.
+     * @type {MediaEntry[]}
+     */
+    #list = [];
+
+    /** The far field this frame, read at most once a frame. */
+    #far = new Float64Array(3);
+
+    /** The wind a medium feels plus its own motion, for one call of the advance; never kept. */
+    #velocity = new Float64Array(3);
+
     /**
      * @param {GraphicsEngine} graphics
      * @param {Scene} scene
@@ -95,7 +147,12 @@ export class ParticipatingMediaSystem extends System {
 
         this.#scene.volumetrics.add(volume);
 
-        this.#entries.set(entity, { component, transform, volume });
+        const entry = new MediaEntry(component, transform, volume);
+
+        entry.index = this.#list.length;
+
+        this.#list.push(entry);
+        this.#entries.set(entity, entry);
     }
 
     /**
@@ -108,46 +165,91 @@ export class ParticipatingMediaSystem extends System {
     }
 
     /**
-     * One frame: every volume's noise scrolls on by the wind it feels plus its own motion, and
-     * whatever changed — that, or anything the component or transform now says differently —
-     * reaches the renderer's volume and moves the volumetrics version.
+     * One frame: whatever the component or transform now says differently reaches the renderer's
+     * volume and moves the volumetrics version, and every noisy volume's noise scrolls on by the far
+     * field it feels plus its own motion, which moves only the noise version.
      *
-     * The wind is the scene's (`SceneVolumetrics.wind`), felt through each medium's
-     * `noise_wind_factor`; the fold to a scroll phase happens on the volume, in f64, wrapped, so a
-     * long session never grows a number and a change of wind never jumps the field. A medium with
-     * no noise, or none that moves, costs the comparison it always did.
+     * The far field is felt through each medium's `noise_wind_factor`; the fold to a scroll phase
+     * happens on the volume, in f64, wrapped, so a long session never grows a number and a change of
+     * wind never jumps the field. A medium with no noise, or none that moves, costs the comparison it
+     * always did.
      *
      * @param {number} time_delta_seconds
      */
     update(time_delta_seconds) {
         const volumetrics = this.#scene.volumetrics;
-        const wind = volumetrics.wind;
 
-        for (const entry of this.#entries.values()) {
+        const list = this.#list;
+        const count = list.length;
+
+        const velocity = this.#velocity;
+        const far = this.#far;
+
+        let far_read = false;
+        let changed = false;
+        let scrolled = false;
+
+        for (let i = 0; i < count; i++) {
+            const entry = list[i];
             const volume = entry.volume;
             const component = entry.component;
 
-            let moved = false;
+            if (participating_media_volume_write(volume, component, entry.transform)) {
+                changed = true;
+            }
 
-            if (component.noise_strength > 0) {
-                const factor = component.noise_wind_factor;
-                const own = component.noise_velocity;
+            if (component.noise_strength <= 0) {
+                continue;
+            }
 
-                scratch_velocity[0] = wind[0] * factor + own[0];
-                scratch_velocity[1] = wind[1] * factor + own[1];
-                scratch_velocity[2] = wind[2] * factor + own[2];
+            const factor = component.noise_wind_factor;
+            const own = component.noise_velocity;
 
-                moved = participating_media_volume_advance_noise(volume, scratch_velocity, time_delta_seconds);
+            if (factor !== 0 && !far_read) {
+                this.#read_far_field(far);
+                far_read = true;
             }
 
-            if (!moved && participating_media_volume_is_current(volume, component, entry.transform)) {
-                continue;
+            if (factor !== 0) {
+                velocity[0] = far[0] * factor + own[0];
+                velocity[1] = far[1] * factor + own[1];
+                velocity[2] = far[2] * factor + own[2];
+            } else {
+                velocity[0] = own[0];
+                velocity[1] = own[1];
+                velocity[2] = own[2];
             }
 
-            participating_media_volume_write(volume, component, entry.transform);
+            if (participating_media_volume_advance_noise(volume, velocity, time_delta_seconds)) {
+                scrolled = true;
+            }
+        }
 
+        if (changed) {
             volumetrics.invalidate();
         }
+
+        if (scrolled) {
+            volumetrics.invalidate_noise();
+        }
+    }
+
+    /**
+     * The entity manager's {@link GPUFluidSystem}'s far field now, or still air without one.
+     *
+     * @param {Float64Array} out
+     */
+    #read_far_field(out) {
+        const manager = this.entityManager;
+        const fluid = manager === null || manager === undefined ? null : manager.getSystem(GPUFluidSystem);
+
+        if (fluid === null) {
+            out[0] = 0;
+            out[1] = 0;
+            out[2] = 0;
+        } else {
+            fluid.far_field(out);
+        }
     }
 
     /**
@@ -163,60 +265,96 @@ export class ParticipatingMediaSystem extends System {
         this.#scene.volumetrics.remove(entry.volume);
 
         this.#entries.delete(entity);
+
+        // swap the last entry into the gap
+        const list = this.#list;
+        const last = list.pop();
+
+        if (last !== entry) {
+            list[entry.index] = last;
+            last.index = entry.index;
+        }
+
+        entry.index = -1;
     }
 }
 
 /**
- * Copy what the component and its transform say onto the volume Shade will render.
+ * Copy what the component and its transform say onto the volume Shade will render, field by field,
+ * comparing while assigning, and say whether anything differed — which is whether the GPU table
+ * has to be repacked.
  *
  * The particle spec is **copied, not referenced**: two entities are routinely built from the same
  * blueprint and would otherwise share one spec, so tuning one volume's particle would silently
- * retune the other's.
+ * retune the other's. The scroll and flow phases are the volume's own state and are not touched
+ * here; `noise_wind_factor` is a setting, and the shaders read it.
+ *
+ * **The transform is compared and copied by its matrix**, element by element straight off the
+ * `Transform64` — its first sixteen elements — and never through its `matrix` getter, which makes a
+ * view per read. The matrix is the entire transform the GPU is given, so this is exactly the question
+ * "would the upload differ", and it catches a transform posed by writing its matrix, which comparing
+ * position, rotation and scale would not. `fromMatrix` copies the sixteen and then decomposes them,
+ * leaving the matrix bit-identical, so the volume carries the authored matrix exactly.
  *
  * @param {ParticipatingMediaVolume} volume Shade's
  * @param {ParticipatingMedia} component meep's
  * @param {Transform64} transform where the box is
+ * @returns {boolean} whether the volume differed from what the component and transform say
  */
 export function participating_media_volume_write(volume, component, transform) {
-    volume.density = component.density;
-    volume.fade_distance = component.fade_distance;
-
-    // the settings; the scroll phases are the volume's own state and are not touched here
-    volume.noise_strength = component.noise_strength;
-    volume.noise_scale = component.noise_scale;
-    volume.noise_warp = component.noise_warp;
-    volume.noise_slot = component.noise_texture;
-
-    volume.particle_spec.copy(component.particle_spec);
-
-    // By the MATRIX, not by the components. The volume is defined by the matrix the GPU is
-    // handed, and a transform can be posed by writing that matrix directly - with automatic change
-    // detection off, position, rotation and scale know nothing about it. `fromMatrix` copies the
-    // sixteen elements and then decomposes them, leaving the matrix bit-identical, so the volume
-    // carries the authored matrix exactly and gets usable components besides.
-    //
-    // Nothing is gained by recomposing in f64 here, the way t64_copy_from_transform would: the
-    // source matrix is f32, and precision the input never had cannot be recovered. This becomes a
-    // plain buffer copy, f64 end to end, once the entity's own transform is a Transform64.
-    volume.transform.fromMatrix(transform.matrix);
+    let changed = false;
+
+    if (volume.density !== component.density) {
+        volume.density = component.density;
+        changed = true;
+    }
+
+    if (volume.fade_distance !== component.fade_distance) {
+        volume.fade_distance = component.fade_distance;
+        changed = true;
+    }
+
+    if (volume.noise_strength !== component.noise_strength) {
+        volume.noise_strength = component.noise_strength;
+        changed = true;
+    }
+
+    if (volume.noise_scale !== component.noise_scale) {
+        volume.noise_scale = component.noise_scale;
+        changed = true;
+    }
+
+    if (volume.noise_warp !== component.noise_warp) {
+        volume.noise_warp = component.noise_warp;
+        changed = true;
+    }
+
+    if (volume.noise_slot !== component.noise_texture) {
+        volume.noise_slot = component.noise_texture;
+        changed = true;
+    }
+
+    if (volume.noise_wind_factor !== component.noise_wind_factor) {
+        volume.noise_wind_factor = component.noise_wind_factor;
+        changed = true;
+    }
+
+    if (!volume.particle_spec.equals(component.particle_spec)) {
+        volume.particle_spec.copy(component.particle_spec);
+        changed = true;
+    }
+
+    if (!participating_media_matrix_equals(volume.transform, transform)) {
+        volume.transform.fromMatrix(transform);
+        changed = true;
+    }
+
+    return changed;
 }
 
 /**
- * Whether the volume already says what the component and transform say.
- *
- * True on all but a handful of frames, which is the point of asking: a `false` here costs the whole
- * scene's volumetrics table a trip to the GPU.
- *
- * **The transform is compared by its matrix rather than by its components**, because the matrix is
- * the entire transform the GPU is given — the volume's position, rotation and scale are never read
- * on their own. That makes this exactly the question worth asking, "would the upload differ", and it
- * catches a transform posed by writing its matrix, which comparing position, rotation and scale
- * would not.
- *
- * The volume's matrix is a `Float64Array` and the component's is a `Float32Array`, and the strict
- * comparison across the two still holds: {@link participating_media_volume_write} copies the matrix
- * across element by element, and every f32 value widens to f64 exactly. It is a recomposed matrix
- * that would not compare equal, which is why the write does not recompose.
+ * Whether the volume already says what the component and transform say: the question
+ * {@link participating_media_volume_write} answers while it assigns, asked without assigning.
  *
  * @param {ParticipatingMediaVolume} volume
  * @param {ParticipatingMedia} component
@@ -230,12 +368,22 @@ export function participating_media_volume_is_current(volume, component, transfo
         && volume.noise_scale === component.noise_scale
         && volume.noise_warp === component.noise_warp
         && volume.noise_slot === component.noise_texture
-        && isArrayEqualStrict(volume.transform.matrix, transform.matrix)
+        && volume.noise_wind_factor === component.noise_wind_factor
+        && participating_media_matrix_equals(volume.transform, transform)
         && volume.particle_spec.equals(component.particle_spec);
 }
 
 /**
- * The wind a medium feels plus its own motion, for one call of the advance; never kept.
- * @type {Float64Array}
+ * @param {Transform64} a
+ * @param {Transform64} b
+ * @returns {boolean} whether the two matrices are the same sixteen numbers
  */
-const scratch_velocity = new Float64Array(3);
+function participating_media_matrix_equals(a, b) {
+    for (let i = TRANSFORM64_MATRIX_OFFSET; i < TRANSFORM64_MATRIX_OFFSET + 16; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+
+    return true;
+}

package/src/engine/graphics3/WaterSystem.d.ts

@@ -3,15 +3,21 @@
  * edits queue writes; idle frames never walk bodies. Transform rows follow the same change events
  * and GPU hierarchy as shaded geometry. Water does not enter the opaque mesh table or its TLAS.
  *
- * Every body has a surface row (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1): its wind from an
+ * Every body has a surface row (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1): its fetch and shore from an
  * optional {@link WaterWaves}, its queued splashes, and what the GPU derives from them each frame. The GPU culls
  * every body against the frame's view before simulating; a hidden body is paused unless
  * {@link Water#simulateWhenHidden} (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3).
+ *
+ * **The wind is the scene's** (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6, the Water row): the culling pass
+ * samples the published wind field 10 m above each body's origin and low-passes it per body, on the GPU. What the
+ * system decides on the CPU is only whether that field can hold wind at all ({@link GPUWaterSurface#windy}, which
+ * animates the shared bands): while any enabled {@link GPUFluidComponent} steps a fluid, or the far field
+ * ({@link GPUFluidSystem#far_field}) is not still. Asked every update, allocating nothing.
  */
 export class WaterSystem extends System<any> {
     constructor(graphics: any, scene: any);
     dependencies: (typeof Transform64 | typeof MeshletGeometry | typeof Water)[];
-    components_used: ResourceAccessSpecification<typeof WaterWaves>[];
+    components_used: (ResourceAccessSpecification<typeof WaterWaves> | ResourceAccessSpecification<typeof GPUFluidComponent>)[];
     get settings(): {
         enabled: boolean;
         max_distance: number;
@@ -61,6 +67,7 @@ import { MeshletGeometry } from "../../shade/renderer/geometry/MeshletGeometry.j
 import Water from "../graphics/ecs/water/Water.js";
 import WaterWaves from "../graphics/ecs/water/WaterWaves.js";
 import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
+import { GPUFluidComponent } from "../physics/fluid/ecs/GPUFluidComponent.js";
 import { GPUWaterSurface } from "../../shade/renderer/water/surface/GPUWaterSurface.js";
 import { GPUWaterRenderer } from "../../shade/renderer/water/GPUWaterRenderer.js";
 import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";

package/src/engine/graphics3/WaterSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WaterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/WaterSystem.js"],"names":[],"mappings":"AA+BA;;;;;;;;;GASG;AACH;IA2BI,uCAaC;IAvCD,6EAAqD;IACrD,kEAA0F;IAc1F;;;;;;;;;;;MAAkD;IAClD,6BAAmC;IACnC,6CAAqD;IACrD,iBAAmC;IACnC,qCAA8D;IAE9D,0BAGC;IAJD,mBAAiC;IAqBjC,2CAOC;IAED,0BAMC;IAED,mEAsBC;IAQD,qEAkBC;IAED,sBAoBC;IAqDD;;;;OAIG;IACH,qEASC;IAED,iCAMC;IACD,yBAGC;;CACJ;AAED;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAA4C;CAC/C;AACD;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAAoD;CACvD;uBAlQsB,kBAAkB;4BAEb,iCAAiC;gCAI7B,kDAAkD;kBARhE,gCAAgC;uBACe,qCAAqC;4CAS1D,iDAAiD;gCAG7D,uDAAuD;iCAFtD,gDAAgD;gCAIjD,mDAAmD"}
+{"version":3,"file":"WaterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/WaterSystem.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;GAeG;AACH;IAoCI,uCAaC;IAhDD,6EAAqD;IACrD,4HAEkF;IAqBlF;;;;;;;;;;;MAAkD;IAClD,6BAAmC;IACnC,6CAAqD;IACrD,iBAAmC;IACnC,qCAA8D;IAE9D,0BAGC;IAJD,mBAAiC;IAqBjC,2CAOC;IAED,0BAMC;IAED,mEAsBC;IAQD,qEAiBC;IAED,sBAqBC;IA0ED;;;;OAIG;IACH,qEASC;IAED,iCAMC;IACD,yBAGC;;CACJ;AAED;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAA4C;CAC/C;AACD;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAAoD;CACvD;uBAxSsB,kBAAkB;4BAEb,iCAAiC;gCAI7B,kDAAkD;kBARhE,gCAAgC;uBACe,qCAAqC;4CAS1D,iDAAiD;kCAW3D,2CAA2C;gCAR7C,uDAAuD;iCAFtD,gDAAgD;gCAIjD,mDAAmD"}