@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -11,15 +11,22 @@
  *      snapped (no shift), on subsequent syncs the integer cell delta is computed and
  *      the field is shifted to follow — fluid data moves with the world so the volume
  *      appears stationary while the grid hops between cells.
- *   2. Walks every (FluidEffectorsComponent, Transform64) entity and calls
- *      {@link AbstractFluidEffector.syncFromTransform} on each effector so position-
- *      bearing effectors (wakes, splats) follow their owning entity.
- *   3. For each enabled {@link FluidComponent}:
+ *   2. For each enabled {@link FluidComponent}:
  *      a. Builds the world-to-grid matrix from the component's `origin` + `cell_size`.
  *      b. Broad-phase filters effectors via {@link AbstractFluidEffector.getBoundingBox}
  *         vs {@link FluidComponent.getBoundingBox} — only effectors whose world-space
- *         AABB intersects the field's AABB are passed through.
- *      c. Calls the owned simulator's `step(field, dt, visible_effectors, world_to_grid)`.
+ *         AABB intersects the field's AABB are applied.
+ *      c. Brings the field to the far field {@link FluidEffectorsSystem} folded this
+ *         tick, through the atmosphere identity ({@link fluid_apply_atmosphere}). Every
+ *         {@link GlobalFluidEffector} acts here, once, as one: none is applied by itself.
+ *      d. Calls the owned simulator's `step(field, dt, [], world_to_grid)` for the rest.
+ *
+ * Effectors are applied here, but their per-tick life is not: following their
+ * entity's `Transform64`, advancing their own state and folding the globals happen
+ * once a tick in {@link FluidEffectorsSystem}, which this system requires (`startup`
+ * asserts it is registered) and runs after, by the access both declare on
+ * {@link FluidEffectorsComponent}. {@link WorkerFluidSystem} does the same work in the
+ * same order, its solve and atmosphere on a worker, and agrees exactly.
  *
  * The broad-phase is cheap (AABB-AABB intersect, 6 comparisons) and skips the expensive
  * per-cell splat work for effectors that wouldn't have hit anything anyway. Gather +
@@ -38,12 +45,11 @@ export class FluidSystem extends System<any> {
      * Components the system traverses each step but does not own as the linking
      * tuple. Lets the engine validate registration order and schedule reads.
      *
-     *   - `FluidEffectorsComponent` — read every step to gather effectors and to
-     *     deliver Transform64 sync hooks.
-     *   - `Transform64` — read every step (paired with FluidEffectorsComponent) so
-     *     position-bearing effectors can follow their entity.
+     *   - `FluidEffectorsComponent` — read every step to gather and apply effectors.
+     *     {@link FluidEffectorsSystem} writes it, so it runs first.
+     *   - `Transform64` — read every step to re-anchor fields that follow an entity.
      */
-    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidEffectorsComponent>)[];
+    components_used: (ResourceAccessSpecification<typeof FluidEffectorsComponent> | ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof FluidComponent>)[];
     /**
      * Single simulator drives every fluid field — it carries only transient scratch,
      * which {@link FluidSimulator.#ensure_scratch} grows to fit the largest field
@@ -51,12 +57,17 @@ export class FluidSystem extends System<any> {
      * @type {FluidSimulator}
      */
     simulator: FluidSimulator;
+    /**
+     * @param {EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    startup(entityManager: EntityManager): Promise<void>;
     #private;
 }
 import { System } from "../../../ecs/System.js";
 import { FluidComponent } from "./FluidComponent.js";
-import { Transform64 } from "../../../ecs/transform/Transform64.js";
-import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
 import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
 import { FluidSimulator } from "../FluidSimulator.js";
 //# sourceMappingURL=FluidSystem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"FluidSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidSystem.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;;IAEI,wCAAgC;IAEhC;;;;;;;;OAQG;IACH,wLAME;IAEF;;;;;OAKG;IACH,WAFU,cAAc,CAES;;CAoEpC;uBA1IsB,wBAAwB;+BAEhB,qBAAqB;4BADxB,uCAAuC;4CAFvB,uDAAuD;wCAI3D,8BAA8B;+BACvC,sBAAsB"}
+{"version":3,"file":"FluidSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidSystem.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH;;IAEI,wCAAgC;IAEhC;;;;;;;OAOG;IACH,wLAME;IAEF;;;;;OAKG;IACH,WAFU,cAAc,CAES;IA8CjC;;;OAGG;IACH,uCAFa,QAAQ,IAAI,CAAC,CAMzB;;CA6DJ;uBAzMsB,wBAAwB;+BAEhB,qBAAqB;wCACZ,8BAA8B;4CAJ1B,uDAAuD;4BAEvE,uCAAuC;+BAKpC,sBAAsB"}

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

@@ -1,3 +1,4 @@
+import { assert } from "../../../../core/assert.js";
 import { AABB3 } from "../../../../core/geom/3d/aabb/AABB3.js";
 import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
@@ -5,11 +6,21 @@ import { System } from "../../../ecs/System.js";
 import { Transform64 } from "../../../ecs/transform/Transform64.js";
 import { FluidComponent } from "./FluidComponent.js";
 import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
+import { FluidEffectorsSystem } from "./FluidEffectorsSystem.js";
+import { FLUID_ATMOSPHERE_WORDS } from "../FluidAtmosphere.js";
 import { FluidSimulator } from "../FluidSimulator.js";
+import { fluid_apply_atmosphere } from "../fluid_apply_atmosphere.js";
+import { fluid_atmosphere_to_grid } from "../fluid_atmosphere_to_grid.js";
 import { fluid_build_world_to_grid } from "./fluid_build_world_to_grid.js";
 import { fluid_gather_visible_effectors } from "./fluid_gather_visible_effectors.js";
 import { fluid_reanchor_field } from "./fluid_reanchor_field.js";
-import { fluid_sync_effectors_from_transform } from "./fluid_sync_effectors_from_transform.js";
+
+/**
+ * The effectors handed to {@link FluidSimulator#step}: none, since this system applies them
+ * itself, before the atmosphere. Module-static because `step` only ever iterates it.
+ * @type {AbstractFluidEffector[]}
+ */
+const NO_EFFECTORS = [];
 
 /**
  * ECS system that steps every {@link FluidComponent} on a fixed timestep.
@@ -24,15 +35,22 @@ import { fluid_sync_effectors_from_transform } from "./fluid_sync_effectors_from
  *      snapped (no shift), on subsequent syncs the integer cell delta is computed and
  *      the field is shifted to follow — fluid data moves with the world so the volume
  *      appears stationary while the grid hops between cells.
- *   2. Walks every (FluidEffectorsComponent, Transform64) entity and calls
- *      {@link AbstractFluidEffector.syncFromTransform} on each effector so position-
- *      bearing effectors (wakes, splats) follow their owning entity.
- *   3. For each enabled {@link FluidComponent}:
+ *   2. For each enabled {@link FluidComponent}:
  *      a. Builds the world-to-grid matrix from the component's `origin` + `cell_size`.
  *      b. Broad-phase filters effectors via {@link AbstractFluidEffector.getBoundingBox}
  *         vs {@link FluidComponent.getBoundingBox} — only effectors whose world-space
- *         AABB intersects the field's AABB are passed through.
- *      c. Calls the owned simulator's `step(field, dt, visible_effectors, world_to_grid)`.
+ *         AABB intersects the field's AABB are applied.
+ *      c. Brings the field to the far field {@link FluidEffectorsSystem} folded this
+ *         tick, through the atmosphere identity ({@link fluid_apply_atmosphere}). Every
+ *         {@link GlobalFluidEffector} acts here, once, as one: none is applied by itself.
+ *      d. Calls the owned simulator's `step(field, dt, [], world_to_grid)` for the rest.
+ *
+ * Effectors are applied here, but their per-tick life is not: following their
+ * entity's `Transform64`, advancing their own state and folding the globals happen
+ * once a tick in {@link FluidEffectorsSystem}, which this system requires (`startup`
+ * asserts it is registered) and runs after, by the access both declare on
+ * {@link FluidEffectorsComponent}. {@link WorkerFluidSystem} does the same work in the
+ * same order, its solve and atmosphere on a worker, and agrees exactly.
  *
  * The broad-phase is cheap (AABB-AABB intersect, 6 comparisons) and skips the expensive
  * per-cell splat work for effectors that wouldn't have hit anything anyway. Gather +
@@ -52,10 +70,9 @@ export class FluidSystem extends System {
      * Components the system traverses each step but does not own as the linking
      * tuple. Lets the engine validate registration order and schedule reads.
      *
-     *   - `FluidEffectorsComponent` — read every step to gather effectors and to
-     *     deliver Transform64 sync hooks.
-     *   - `Transform64` — read every step (paired with FluidEffectorsComponent) so
-     *     position-bearing effectors can follow their entity.
+     *   - `FluidEffectorsComponent` — read every step to gather and apply effectors.
+     *     {@link FluidEffectorsSystem} writes it, so it runs first.
+     *   - `Transform64` — read every step to re-anchor fields that follow an entity.
      */
     components_used = [
         // FluidComponent is also in `dependencies`, but reanchor + step write to it
@@ -99,6 +116,34 @@ export class FluidSystem extends System {
      */
     #effector_aabb = new AABB3();
 
+    /**
+     * The system that folds the far field, found at startup.
+     * @type {FluidEffectorsSystem|null}
+     */
+    #effectors_system = null;
+
+    /**
+     * This tick's far field, WORLD units. Still air while there is no effectors system.
+     * @type {Float64Array}
+     */
+    #atmosphere_world = new Float64Array(FLUID_ATMOSPHERE_WORDS);
+
+    /**
+     * The far field in the grid units of the field being stepped.
+     * @type {Float64Array}
+     */
+    #atmosphere_grid = new Float64Array(FLUID_ATMOSPHERE_WORDS);
+
+    /**
+     * @param {EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    async startup(entityManager) {
+        assert.ok(entityManager.hasSystem(FluidEffectorsSystem), "FluidSystem requires a FluidEffectorsSystem: without one, effectors on an entity with a Transform64 no longer follow it and the globals make no atmosphere. Register both, FluidEffectorsSystem first if the EntityManager is already running.");
+
+        this.#effectors_system = entityManager.getSystem(FluidEffectorsSystem);
+    }
+
     /**
      * @param {number} time_delta_seconds
      */
@@ -116,27 +161,46 @@ export class FluidSystem extends System {
         //    when the quantization changes, the field is shifted to follow the world.
         ecd.traverseEntities([FluidComponent, Transform64], fluid_reanchor_field);
 
-        // 2. Sync every effector that wants to follow its entity's Transform64.
-        ecd.traverseEntities([FluidEffectorsComponent, Transform64], fluid_sync_effectors_from_transform);
-
         // 2. Step each fluid field, with broad-phase effector filtering per field.
+        //    FluidEffectorsSystem has already synced and advanced every effector, and
+        //    folded the globals into this tick's far field.
+        const effectors_system = this.#effectors_system;
+        const atmosphere_world = this.#atmosphere_world;
+
+        if (effectors_system !== null) {
+            effectors_system.read_atmosphere(atmosphere_world, 0);
+        }
+
         const sim = this.simulator;
         const world_to_grid = this.#world_to_grid;
         const field_aabb = this.#field_aabb;
         const effector_aabb = this.#effector_aabb;
         const visible = this.#visible_effectors;
+        const atmosphere_grid = this.#atmosphere_grid;
 
         ecd.traverseComponents(FluidComponent, function (component) {
             if (!component.enabled) {
                 return;
             }
 
+            const field = component.field;
+
             component.getBoundingBox(field_aabb);
             fluid_build_world_to_grid(world_to_grid, component);
 
             fluid_gather_visible_effectors(visible, ecd, field_aabb, effector_aabb);
 
-            sim.step(component.field, time_delta_seconds, visible, world_to_grid);
+            // Phase 1 of FluidSimulator.step, done here so the atmosphere can follow it: the
+            // order WorkerFluidSystem has, with its effectors on this thread and the rest on
+            // the worker.
+            for (let i = 0; i < visible.length; i++) {
+                visible[i].apply(field, time_delta_seconds, world_to_grid);
+            }
+
+            fluid_atmosphere_to_grid(atmosphere_grid, 0, atmosphere_world, 0, world_to_grid);
+            fluid_apply_atmosphere(field, time_delta_seconds, atmosphere_grid, 0);
+
+            sim.step(field, time_delta_seconds, NO_EFFECTORS, world_to_grid);
         });
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"FluidWorkerCore.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidWorkerCore.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;GAeG;AACH;IAEI;;;;;OAKG;IACH,WAFU,cAAc,CAES;IAQjC;;OAEG;IACH,+BAcC;IAED;;OAEG;IACH,0BAEC;IAED;;;;;OAKG;IACH,WAHW,MAAM,WACN,YAAY,QAkCtB;;CACJ;+BAzH8B,sBAAsB"}
+{"version":3,"file":"FluidWorkerCore.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidWorkerCore.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;GAeG;AACH;IAEI;;;;;OAKG;IACH,WAFU,cAAc,CAES;IAQjC;;OAEG;IACH,+BAcC;IAED;;OAEG;IACH,0BAEC;IAED;;;;;OAKG;IACH,WAHW,MAAM,WACN,YAAY,QAuCtB;;CACJ;+BArI8B,sBAAsB"}

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

@@ -1,6 +1,12 @@
 import { FluidField } from "../FluidField.js";
 import { FluidSimulator } from "../FluidSimulator.js";
-import { FluidCommand, fluid_command_read_simulator } from "./fluid_worker_protocol.js";
+import { fluid_apply_atmosphere } from "../fluid_apply_atmosphere.js";
+import {
+    FLUID_COMMAND_FIELD_WORDS,
+    FluidCommand,
+    FluidCommandField,
+    fluid_command_read_simulator
+} from "./fluid_worker_protocol.js";
 
 /**
  * Effectors have already been applied on the main thread by
@@ -12,8 +18,9 @@ const NO_EFFECTORS = [];
 
 /**
  * `world_to_grid` is only ever read by effectors. With none present the value is
- * unused, but `step` requires a non-null length-16 affine, so hand it the
- * identity rather than something that would read as meaningful.
+ * unused (the atmosphere arrives already in the field's grid units), but `step`
+ * requires a non-null length-16 affine, so hand it the identity rather than
+ * something that would read as meaningful.
  * @type {Float32Array}
  */
 const IDENTITY_4X4 = new Float32Array([
@@ -96,7 +103,9 @@ export class FluidWorkerCore {
         const field_count = command[FluidCommand.FIELD_COUNT];
 
         for (let i = 0; i < field_count; i++) {
-            const id = command[FluidCommand.FIELD_IDS + i];
+            const record = FluidCommand.FIELDS + i * FLUID_COMMAND_FIELD_WORDS;
+
+            const id = command[record + FluidCommandField.ID];
 
             const field = this.#fields.get(id);
 
@@ -116,7 +125,10 @@ export class FluidWorkerCore {
             }
 
             // Phase 1 of FluidSimulator.step (effectors) already ran on the main
-            // thread; passing none leaves exactly phases 2-6 — the solve.
+            // thread. The atmosphere comes next, as in FluidSystem; then passing no
+            // effectors leaves exactly phases 2-6 — the solve.
+            fluid_apply_atmosphere(field, time_delta_seconds, command, record + FluidCommandField.ATMOSPHERE);
+
             simulator.step(field, time_delta_seconds, NO_EFFECTORS, IDENTITY_4X4);
         }
     }

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

@@ -0,0 +1,82 @@
+/**
+ * The GPU wind fluid's domain (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §5): nested, scrolling
+ * cascades of air around an entity, which `GPUFluidSystem` steps on the device and publishes as the
+ * scene's wind field. Add one to an entity with a `Transform64` and the scene has GPU wind; the
+ * domain follows that entity (§17 D1), its windows centred on the entity's translation.
+ *
+ * Cascade `c` has cells of `cell_size·2^c` at one {@link resolution}, so the finest covers
+ * `resolution·cell_size` metres and each coarser one twice that on every axis; beyond the coarsest
+ * the far field, `GlobalFluidEffector`s folded by `FluidEffectorsSystem`, takes over.
+ *
+ * There is no velocity damping: relaxing toward still air would fight the far field, which is what
+ * the air relaxes toward. Nothing of the fluid's state is here, and nothing of it is saved: a load
+ * or a device restart seeds the cascades at the far field and they warm up (§6).
+ *
+ * This component is pure data; the behaviour lives on `GPUFluidSystem`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUFluidComponent {
+    /**
+     * Cells of every cascade along x, y and z: each a power of two in
+     * [{@link GPU_FLUID_COMPONENT_RESOLUTION_MIN}, {@link GPU_FLUID_COMPONENT_RESOLUTION_MAX}].
+     * @type {[number, number, number]}
+     */
+    resolution: [number, number, number];
+    /**
+     * The finest cascade's cell, metres, > 0.
+     * @type {number}
+     */
+    cell_size: number;
+    /**
+     * How many cascades, 1 to {@link GPU_FLUID_COMPONENT_CASCADE_LIMIT}.
+     * @type {number}
+     */
+    cascade_count: number;
+    /**
+     * The strength of vorticity confinement, ≥ 0, as `FluidSimulator#vorticity_confinement` reads it.
+     * 0 turns it off. Authored and saved; the GPU cascades have no confinement pass yet (§14's curl),
+     * so nothing reads it until they do.
+     * @type {number}
+     */
+    vorticity_confinement: number;
+    /**
+     * Whether the domain exists. A disabled component holds nothing on the device.
+     * @type {boolean}
+     */
+    enabled: boolean;
+    /**
+     * @param {GPUFluidComponent} other
+     * @returns {boolean}
+     */
+    equals(other: GPUFluidComponent): boolean;
+    /**
+     * @returns {number}
+     */
+    hash(): number;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isGPUFluidComponent: boolean;
+}
+export namespace GPUFluidComponent {
+    let typeName: string;
+}
+/**
+ * The fewest cells a cascade has along an axis: the cascades nest from 32.
+ * @type {number}
+ */
+export const GPU_FLUID_COMPONENT_RESOLUTION_MIN: number;
+/**
+ * The most cells a cascade has along an axis.
+ * @type {number}
+ */
+export const GPU_FLUID_COMPONENT_RESOLUTION_MAX: number;
+/**
+ * The most cascades a domain has.
+ * @type {number}
+ */
+export const GPU_FLUID_COMPONENT_CASCADE_LIMIT: number;
+//# sourceMappingURL=GPUFluidComponent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUFluidComponent.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/GPUFluidComponent.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAEI;;;;OAIG;IACH,YAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAER;IAE1B;;;OAGG;IACH,WAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;OAKG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;OAGG;IACH,SAFU,OAAO,CAEF;IAEf;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAkBnB;IAED;;OAEG;IACH,QAFa,MAAM,CAalB;IA2BL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;CA9B9C;;kBAsBS,MAAM;;AApBhB;;;GAGG;AACH,iDAFU,MAAM,CAEqC;AAErD;;;GAGG;AACH,iDAFU,MAAM,CAEsC;AAEtD;;;GAGG;AACH,gDAFU,MAAM,CAEmC"}

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

@@ -0,0 +1,124 @@
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+
+/**
+ * The GPU wind fluid's domain (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §5): nested, scrolling
+ * cascades of air around an entity, which `GPUFluidSystem` steps on the device and publishes as the
+ * scene's wind field. Add one to an entity with a `Transform64` and the scene has GPU wind; the
+ * domain follows that entity (§17 D1), its windows centred on the entity's translation.
+ *
+ * Cascade `c` has cells of `cell_size·2^c` at one {@link resolution}, so the finest covers
+ * `resolution·cell_size` metres and each coarser one twice that on every axis; beyond the coarsest
+ * the far field, `GlobalFluidEffector`s folded by `FluidEffectorsSystem`, takes over.
+ *
+ * There is no velocity damping: relaxing toward still air would fight the far field, which is what
+ * the air relaxes toward. Nothing of the fluid's state is here, and nothing of it is saved: a load
+ * or a device restart seeds the cascades at the far field and they warm up (§6).
+ *
+ * This component is pure data; the behaviour lives on `GPUFluidSystem`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUFluidComponent {
+
+    /**
+     * Cells of every cascade along x, y and z: each a power of two in
+     * [{@link GPU_FLUID_COMPONENT_RESOLUTION_MIN}, {@link GPU_FLUID_COMPONENT_RESOLUTION_MAX}].
+     * @type {[number, number, number]}
+     */
+    resolution = [64, 32, 64];
+
+    /**
+     * The finest cascade's cell, metres, > 0.
+     * @type {number}
+     */
+    cell_size = 0.5;
+
+    /**
+     * How many cascades, 1 to {@link GPU_FLUID_COMPONENT_CASCADE_LIMIT}.
+     * @type {number}
+     */
+    cascade_count = 4;
+
+    /**
+     * The strength of vorticity confinement, ≥ 0, as `FluidSimulator#vorticity_confinement` reads it.
+     * 0 turns it off. Authored and saved; the GPU cascades have no confinement pass yet (§14's curl),
+     * so nothing reads it until they do.
+     * @type {number}
+     */
+    vorticity_confinement = 0;
+
+    /**
+     * Whether the domain exists. A disabled component holds nothing on the device.
+     * @type {boolean}
+     */
+    enabled = true;
+
+    /**
+     * @param {GPUFluidComponent} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+
+        if (other === null || other === undefined || other.isGPUFluidComponent !== true) {
+            return false;
+        }
+
+        return this.resolution[0] === other.resolution[0]
+            && this.resolution[1] === other.resolution[1]
+            && this.resolution[2] === other.resolution[2]
+            && this.cell_size === other.cell_size
+            && this.cascade_count === other.cascade_count
+            && this.vorticity_confinement === other.vorticity_confinement
+            && this.enabled === other.enabled;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        let h = this.resolution[0];
+
+        h = (h * 31 + this.resolution[1]) | 0;
+        h = (h * 31 + this.resolution[2]) | 0;
+        h = (h * 31 + this.cascade_count) | 0;
+        h = (h * 31 + computeHashFloat(this.cell_size)) | 0;
+        h = (h * 31 + computeHashFloat(this.vorticity_confinement)) | 0;
+        h = (h * 31 + (this.enabled ? 1 : 0)) | 0;
+
+        return h;
+    }
+}
+
+/**
+ * The fewest cells a cascade has along an axis: the cascades nest from 32.
+ * @type {number}
+ */
+export const GPU_FLUID_COMPONENT_RESOLUTION_MIN = 32;
+
+/**
+ * The most cells a cascade has along an axis.
+ * @type {number}
+ */
+export const GPU_FLUID_COMPONENT_RESOLUTION_MAX = 256;
+
+/**
+ * The most cascades a domain has.
+ * @type {number}
+ */
+export const GPU_FLUID_COMPONENT_CASCADE_LIMIT = 8;
+
+/**
+ * @readonly
+ * @type {string}
+ */
+GPUFluidComponent.typeName = "GPUFluidComponent";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+GPUFluidComponent.prototype.isGPUFluidComponent = true;

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

@@ -0,0 +1,30 @@
+/**
+ * Binary serialization for {@link GPUFluidComponent}: `resolution` (three u16), `cell_size` (f64),
+ * `cascade_count` (u8), `vorticity_confinement` (f64) and `enabled` (u8), 24 bytes. Nothing of the
+ * fluid's state is saved: a load seeds the cascades at the far field (GPU_FLUID_CASCADES_PROPOSAL §6).
+ *
+ * Like the other physics adapters this is not in `populateEngineSerializationRegistry`; the host
+ * registers it.
+ *
+ * Version 0: a first version has no predecessor stream to upgrade from.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUFluidComponentSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof GPUFluidComponent;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {GPUFluidComponent} value
+     */
+    serialize(buffer: BinaryBuffer, value: GPUFluidComponent): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {GPUFluidComponent} value
+     */
+    deserialize(buffer: BinaryBuffer, value: GPUFluidComponent): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { GPUFluidComponent } from "./GPUFluidComponent.js";
+//# sourceMappingURL=GPUFluidComponentSerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUFluidComponentSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/GPUFluidComponentSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH;;IAEI,gCAA0B;IAG1B;;;OAGG;IACH,uCAFW,iBAAiB,QAW3B;IAED;;;OAGG;IACH,yCAFW,iBAAiB,QAW3B;CACJ;gDAlD+C,gEAAgE;kCAC9E,wBAAwB"}

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

@@ -0,0 +1,51 @@
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { GPUFluidComponent } from "./GPUFluidComponent.js";
+
+/**
+ * Binary serialization for {@link GPUFluidComponent}: `resolution` (three u16), `cell_size` (f64),
+ * `cascade_count` (u8), `vorticity_confinement` (f64) and `enabled` (u8), 24 bytes. Nothing of the
+ * fluid's state is saved: a load seeds the cascades at the far field (GPU_FLUID_CASCADES_PROPOSAL §6).
+ *
+ * Like the other physics adapters this is not in `populateEngineSerializationRegistry`; the host
+ * registers it.
+ *
+ * Version 0: a first version has no predecessor stream to upgrade from.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUFluidComponentSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = GPUFluidComponent;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {GPUFluidComponent} value
+     */
+    serialize(buffer, value) {
+        buffer.writeUint16(value.resolution[0]);
+        buffer.writeUint16(value.resolution[1]);
+        buffer.writeUint16(value.resolution[2]);
+
+        buffer.writeFloat64(value.cell_size);
+        buffer.writeUint8(value.cascade_count);
+        buffer.writeFloat64(value.vorticity_confinement);
+        buffer.writeUint8(value.enabled ? 1 : 0);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {GPUFluidComponent} value
+     */
+    deserialize(buffer, value) {
+        value.resolution[0] = buffer.readUint16();
+        value.resolution[1] = buffer.readUint16();
+        value.resolution[2] = buffer.readUint16();
+
+        value.cell_size = buffer.readFloat64();
+        value.cascade_count = buffer.readUint8();
+        value.vorticity_confinement = buffer.readFloat64();
+        value.enabled = buffer.readUint8() !== 0;
+    }
+}

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

@@ -8,15 +8,20 @@
  * projection, transport, scalars), and the solve — pressure above all — is the
  * expensive part. So the split is:
  *
- *   - **main thread**: re-anchoring, effector Transform64 sync, the AABB
- *     broad-phase, and `effector.apply(...)`. Effectors stay here because they
- *     are arbitrary user-authored classes; keeping them on this side is what
- *     makes the swap transparent rather than a porting exercise.
- *   - **worker**: `simulator.step(field, dt, [], identity)` — the *same* method
- *     with an empty effector list, which is exactly the remaining phases.
+ *   - **main thread**: re-anchoring, the AABB broad-phase, and
+ *     `effector.apply(...)`. Effectors stay here because they are arbitrary
+ *     user-authored classes; keeping them on this side is what makes the swap
+ *     transparent rather than a porting exercise. This tick's far field, from
+ *     {@link FluidEffectorsSystem}, goes into the command region in each field's
+ *     grid units.
+ *   - **worker**: `fluid_apply_atmosphere(field, dt, ...)`, which brings the field
+ *     to that far field against the field's own record (it lives in the field's
+ *     shared memory), then `simulator.step(field, dt, [], identity)` — the *same*
+ *     method with an empty effector list, which is exactly the remaining phases.
  *
  * Identical code over identical data in an identical order, so results are
- * bit-for-bit equal to {@link FluidSystem}'s (`WorkerFluidSystem.spec.js` holds
+ * bit-for-bit equal to {@link FluidSystem}'s, which applies the effectors, the
+ * atmosphere and the solve in the same order (`WorkerFluidSystem.spec.js` holds
  * that as a standing gate).
  *
  * Nothing is copied. The field's buffers live in a {@link SharedArrayBuffer} and
@@ -29,9 +34,13 @@
  * component.field.shared_memory = true;   // before build()
  * component.field.build();
  *
+ * entityManager.addSystem(new FluidEffectorsSystem());
  * entityManager.addSystem(new WorkerFluidSystem({ worker_factory: makeFluidWorker }));
  * ```
  *
+ * Like {@link FluidSystem} it requires a {@link FluidEffectorsSystem}, which
+ * syncs and advances every effector once a tick before this system applies them.
+ *
  * Requires a cross-origin isolated page (`Cross-Origin-Opener-Policy:
  * same-origin` + `Cross-Origin-Embedder-Policy: require-corp`) — without it
  * `SharedArrayBuffer` does not exist and startup throws.
@@ -84,7 +93,7 @@ export class WorkerFluidSystem extends WorkerSystem {
         max_field_count?: number;
     });
     dependencies: (typeof FluidComponent)[];
-    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidEffectorsComponent>)[];
+    components_used: (ResourceAccessSpecification<typeof FluidEffectorsComponent> | ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof FluidComponent>)[];
     /**
      * Tuning knobs, mirrored to the worker in full on every dispatch. Its
      * scratch buffers are never used on this side — the solve happens over
@@ -112,8 +121,8 @@ export class WorkerFluidSystem extends WorkerSystem {
 }
 import { WorkerSystem } from "../../../ecs/async/WorkerSystem.js";
 import { FluidComponent } from "./FluidComponent.js";
-import { Transform64 } from "../../../ecs/transform/Transform64.js";
-import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
 import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
 import { FluidSimulator } from "../FluidSimulator.js";
 //# sourceMappingURL=WorkerFluidSystem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"WorkerFluidSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/WorkerFluidSystem.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH;IA0EI;;;;;;;;OAQG;IACH;QAPiC,cAAc,EAApC,MAAM,MAAM;QAIK,eAAe,GAAhC,MAAM;OAUhB;IAxFD,wCAAgC;IAEhC,wLAME;IAEF;;;;;;OAMG;IACH,WAFU,cAAc,CAES;IAyEjC;;;OAGG;IACH,iCAEC;IAgBD;;;OAGG;IACH,gBAHW,cAAc,UACd,MAAM,QA0BhB;IAED;;;OAGG;IACH,kBAHW,cAAc,UACd,MAAM,QAqBhB;;CAmIJ;6BAvY4B,oCAAoC;+BAGlC,qBAAqB;4BAFxB,uCAAuC;4CAFvB,uDAAuD;wCAK3D,8BAA8B;+BAFvC,sBAAsB"}
+{"version":3,"file":"WorkerFluidSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/WorkerFluidSystem.js"],"names":[],"mappings":"AA8BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH;IAsFI;;;;;;;;OAQG;IACH;QAPiC,cAAc,EAApC,MAAM,MAAM;QAIK,eAAe,GAAhC,MAAM;OAUhB;IApGD,wCAAgC;IAEhC,wLAME;IAEF;;;;;;OAMG;IACH,WAFU,cAAc,CAES;IAkGjC;;;OAGG;IACH,iCAEC;IAgBD;;;OAGG;IACH,gBAHW,cAAc,UACd,MAAM,QA0BhB;IAED;;;OAGG;IACH,kBAHW,cAAc,UACd,MAAM,QAqBhB;;CA8IJ;6BAxb4B,oCAAoC;+BAKlC,qBAAqB;wCACZ,8BAA8B;4CAP1B,uDAAuD;4BAEvE,uCAAuC;+BAEpC,sBAAsB"}