@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -1,18 +1,23 @@
+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";
 import { WorkerSystem } from "../../../ecs/async/WorkerSystem.js";
 import { Transform64 } from "../../../ecs/transform/Transform64.js";
+import { FLUID_ATMOSPHERE_WORDS } from "../FluidAtmosphere.js";
 import { FluidSimulator } from "../FluidSimulator.js";
+import { fluid_atmosphere_to_grid } from "../fluid_atmosphere_to_grid.js";
 import { FluidComponent } from "./FluidComponent.js";
 import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
+import { FluidEffectorsSystem } from "./FluidEffectorsSystem.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";
 import {
+    FLUID_COMMAND_FIELD_WORDS,
     FLUID_COMMAND_HEADER_WORDS,
     FluidCommand,
+    FluidCommandField,
     fluid_command_write_simulator
 } from "./fluid_worker_protocol.js";
 
@@ -33,15 +38,20 @@ const DEFAULT_MAX_FIELD_COUNT = 64;
  * 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
@@ -54,9 +64,13 @@ const DEFAULT_MAX_FIELD_COUNT = 64;
  * 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.
@@ -168,6 +182,18 @@ export class WorkerFluidSystem extends WorkerSystem {
     /** @type {AABB3} */
     #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);
+
     /**
      * @param {object} options
      * @param {() => Worker} options.worker_factory spawns the worker. Supplied
@@ -183,7 +209,20 @@ export class WorkerFluidSystem extends WorkerSystem {
         this.#worker_factory = worker_factory;
         this.#max_field_count = max_field_count;
 
-        this.command_word_count = FLUID_COMMAND_HEADER_WORDS + max_field_count;
+        this.command_word_count = FLUID_COMMAND_HEADER_WORDS + max_field_count * FLUID_COMMAND_FIELD_WORDS;
+    }
+
+    /**
+     * @param {EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    async startup(entityManager) {
+        // Before the worker is spawned, so a scene that fails this leaves no thread behind.
+        assert.ok(entityManager.hasSystem(FluidEffectorsSystem), "WorkerFluidSystem 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);
+
+        await super.startup(entityManager);
     }
 
     /**
@@ -287,11 +326,18 @@ export class WorkerFluidSystem extends WorkerSystem {
         //    already correct by the time they start stepping.
         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. Apply effectors per field, and nominate the field for stepping with
+        //    this tick's far field in its grid units. This is phase 1 of
+        //    FluidSimulator.step; the worker brings the field to the far field and
+        //    runs the rest. FluidEffectorsSystem has already synced and advanced
+        //    every effector, and folded the globals.
+        const effectors_system = this.#effectors_system;
+        const atmosphere_world = this.#atmosphere_world;
+
+        if (effectors_system !== null) {
+            effectors_system.read_atmosphere(atmosphere_world, 0);
+        }
 
-        // 3. Apply effectors per field, and nominate the field for stepping.
-        //    This is phase 1 of FluidSimulator.step; the worker runs the rest.
         const world_to_grid = this.#world_to_grid;
         const field_aabb = this.#field_aabb;
         const effector_aabb = this.#effector_aabb;
@@ -342,7 +388,11 @@ export class WorkerFluidSystem extends WorkerSystem {
                 visible[j].apply(component.field, time_delta_seconds, world_to_grid);
             }
 
-            command[FluidCommand.FIELD_IDS + field_count] = registration.id;
+            const record = FluidCommand.FIELDS + field_count * FLUID_COMMAND_FIELD_WORDS;
+
+            command[record + FluidCommandField.ID] = registration.id;
+            fluid_atmosphere_to_grid(command, record + FluidCommandField.ATMOSPHERE, atmosphere_world, 0, world_to_grid);
+
             field_count++;
         });
 

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

@@ -1,6 +1,9 @@
 /**
  * Collect every effector in the dataset whose world-space AABB overlaps
- * `field_aabb` into `out`.
+ * `field_aabb` into `out`, except the {@link GlobalFluidEffector}s: those act on
+ * every field as one, folded by {@link FluidEffectorsSystem} into the far field
+ * that `fluid_apply_atmosphere` brings each field to, and are not applied one by
+ * one.
  *
  * 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

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

@@ -1 +1 @@
-{"version":3,"file":"fluid_gather_visible_effectors.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/fluid_gather_visible_effectors.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oDANW,uBAAuB,yEAIrB,uBAAuB,CAyBnC"}
+{"version":3,"file":"fluid_gather_visible_effectors.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/fluid_gather_visible_effectors.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,oDANW,uBAAuB,yEAIrB,uBAAuB,CA6BnC"}

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

@@ -1,9 +1,13 @@
 import { aabb3_intersects_aabb3 } from "../../../../core/geom/3d/aabb/aabb3_intersects_aabb3.js";
+import { GlobalFluidEffector } from "../effector/GlobalFluidEffector.js";
 import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
 
 /**
  * Collect every effector in the dataset whose world-space AABB overlaps
- * `field_aabb` into `out`.
+ * `field_aabb` into `out`, except the {@link GlobalFluidEffector}s: those act on
+ * every field as one, folded by {@link FluidEffectorsSystem} into the far field
+ * that `fluid_apply_atmosphere` brings each field to, and are not applied one by
+ * one.
  *
  * 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
@@ -30,6 +34,10 @@ export function fluid_gather_visible_effectors(out, ecd, field_aabb, effector_aa
         for (let i = 0; i < effectors.length; i++) {
             const effector = effectors[i];
 
+            if (effector instanceof GlobalFluidEffector) {
+                continue;
+            }
+
             effector.getBoundingBox(effector_aabb);
 
             if (aabb3_intersects_aabb3(

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

@@ -13,6 +13,7 @@
  * advances to a new cell when the raw position has drifted more than
  * `0.5 + hysteresis` cells from it. Crossing the threshold snaps to the new
  * nearest cell, so a single large move still produces a single discrete shift.
+ * That is {@link quantize_hysteretic} in cells, with a step of one cell.
  *
  * First sync (`anchored = false`): snap origin to the desired value, no shift.
  * Subsequent syncs: per-axis hysteretic quantization, then `field.shift` if the

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

@@ -1 +1 @@
-{"version":3,"file":"fluid_reanchor_field.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/fluid_reanchor_field.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8FA4DC"}
+{"version":3,"file":"fluid_reanchor_field.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/fluid_reanchor_field.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,8FA2DC"}

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

@@ -1,3 +1,5 @@
+import { quantize_hysteretic } from "../../../../core/geom/clipmap/quantize_hysteretic.js";
+
 /**
  * Keep a fluid field's grid origin locked to a cell-aligned position near its
  * transform, shifting the field's contents when the alignment changes so the
@@ -13,6 +15,7 @@
  * advances to a new cell when the raw position has drifted more than
  * `0.5 + hysteresis` cells from it. Crossing the threshold snaps to the new
  * nearest cell, so a single large move still produces a single discrete shift.
+ * That is {@link quantize_hysteretic} in cells, with a step of one cell.
  *
  * First sync (`anchored = false`): snap origin to the desired value, no shift.
  * Subsequent syncs: per-axis hysteretic quantization, then `field.shift` if the
@@ -42,9 +45,9 @@ export function fluid_reanchor_field(component, transform) {
     if (!component.anchored) {
         // First sync — adopt the freshly-quantized origin without shifting.
         // Subsequent frames will see integer-cs differences and shift instead.
-        const q_x = Math.round(px / cs);
-        const q_y = Math.round(py / cs);
-        const q_z = Math.round(pz / cs);
+        const q_x = quantize_hysteretic(px / cs, 0, 1, hyst, false);
+        const q_y = quantize_hysteretic(py / cs, 0, 1, hyst, false);
+        const q_z = quantize_hysteretic(pz / cs, 0, 1, hyst, false);
         origin[0] = q_x * cs + offset[0] - half_extent_x;
         origin[1] = q_y * cs + offset[1] - half_extent_y;
         origin[2] = q_z * cs + offset[2] - half_extent_z;
@@ -67,10 +70,9 @@ export function fluid_reanchor_field(component, transform) {
 
     // Hysteretic re-quantize: only adopt a new cell when raw has drifted past
     // 0.5 + hyst from the current one. Snap to the new nearest, not the threshold.
-    const threshold = 0.5 + hyst;
-    const q_new_x = Math.abs(raw_x - q_curr_x) > threshold ? Math.round(raw_x) : q_curr_x;
-    const q_new_y = Math.abs(raw_y - q_curr_y) > threshold ? Math.round(raw_y) : q_curr_y;
-    const q_new_z = Math.abs(raw_z - q_curr_z) > threshold ? Math.round(raw_z) : q_curr_z;
+    const q_new_x = quantize_hysteretic(raw_x, q_curr_x, 1, hyst, true);
+    const q_new_y = quantize_hysteretic(raw_y, q_curr_y, 1, hyst, true);
+    const q_new_z = quantize_hysteretic(raw_z, q_curr_z, 1, hyst, true);
 
     const shift_x = q_new_x - q_curr_x;
     const shift_y = q_new_y - q_curr_y;

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

@@ -1,8 +1,10 @@
 /**
- * Visitor for the (FluidEffectorsComponent, Transform64) traversal — lets every
- * position-bearing effector (wakes, splats) follow its owning entity.
+ * Sync every effector of a component to the `Transform64` on the same entity — lets
+ * every position-bearing effector (wakes, splats) follow its owning entity. Shaped
+ * as a visitor for a (FluidEffectorsComponent, Transform64) traversal.
  *
- * Shared by {@link FluidSystem} and {@link WorkerFluidSystem}.
+ * Called once a tick by {@link FluidEffectorsSystem}, the one place effectors are
+ * synced, so a wake's trail advances once however many fluid systems apply it.
  *
  * @param {FluidEffectorsComponent} effectors_component
  * @param {Transform64} transform

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

@@ -1 +1 @@
-{"version":3,"file":"fluid_sync_effectors_from_transform.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/fluid_sync_effectors_from_transform.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,gIAMC"}
+{"version":3,"file":"fluid_sync_effectors_from_transform.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/fluid_sync_effectors_from_transform.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,gIAMC"}

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

@@ -1,8 +1,10 @@
 /**
- * Visitor for the (FluidEffectorsComponent, Transform64) traversal — lets every
- * position-bearing effector (wakes, splats) follow its owning entity.
+ * Sync every effector of a component to the `Transform64` on the same entity — lets
+ * every position-bearing effector (wakes, splats) follow its owning entity. Shaped
+ * as a visitor for a (FluidEffectorsComponent, Transform64) traversal.
  *
- * Shared by {@link FluidSystem} and {@link WorkerFluidSystem}.
+ * Called once a tick by {@link FluidEffectorsSystem}, the one place effectors are
+ * synced, so a wake's trail advances once however many fluid systems apply it.
  *
  * @param {FluidEffectorsComponent} effectors_component
  * @param {Transform64} transform

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

@@ -25,6 +25,11 @@ export function fluid_command_read_simulator(command: Float64Array, simulator: F
  * `system.simulator.vorticity_confinement = 5` working exactly as it does with
  * the main-thread {@link FluidSystem }, which is the point of a drop-in
  * replacement.
+ *
+ * After the header come the fields to step, {@link FLUID_COMMAND_FIELD_WORDS }
+ * words each: the field's id, then this tick's far field in that field's grid
+ * units (a {@link FluidAtmosphere } record), which the worker brings the field to
+ * before the solve.
  */
 export type FluidCommand = number;
 export namespace FluidCommand {
@@ -41,10 +46,23 @@ export namespace FluidCommand {
     let ADVECTION_SCHEME: number;
     let PRESSURE_SOLVER: number;
     let FIELD_COUNT: number;
-    let FIELD_IDS: number;
+    let FIELDS: number;
+}
+/**
+ * Layout of one field record in the command region, relative to its start.
+ */
+export type FluidCommandField = number;
+export namespace FluidCommandField {
+    let ID: number;
+    let ATMOSPHERE: number;
 }
 /**
- * Command words consumed before the variable-length field id list.
+ * Words in one field record.
+ * @type {number}
+ */
+export const FLUID_COMMAND_FIELD_WORDS: number;
+/**
+ * Command words consumed before the variable-length list of field records.
  * @type {number}
  */
 export const FLUID_COMMAND_HEADER_WORDS: number;

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

@@ -1 +1 @@
-{"version":3,"file":"fluid_worker_protocol.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/fluid_worker_protocol.js"],"names":[],"mappings":"AAwDA;;;;;;GAMG;AACH,uDAJW,YAAY,iDAEZ,MAAM,QAqBhB;AAED;;;;;;;GAOG;AACH,sDAHW,YAAY,mCAqBtB;;;;;;;;;;;;2BAhGS,MAAM;;;;;;;;;;;;;;;;;AA0BhB;;;GAGG;AACH,yCAFU,MAAM,CAEiD"}
+{"version":3,"file":"fluid_worker_protocol.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/fluid_worker_protocol.js"],"names":[],"mappings":"AAoFA;;;;;;GAMG;AACH,uDAJW,YAAY,iDAEZ,MAAM,QAqBhB;AAED;;;;;;;GAOG;AACH,sDAHW,YAAY,mCAqBtB;;;;;;;;;;;;;;;;;2BAtHS,MAAM;;;;;;;;;;;;;;;;;;;;gCAgCN,MAAM;;;;;AAUhB;;;GAGG;AACH,wCAFU,MAAM,CAEoD;AAEpE;;;GAGG;AACH,yCAFU,MAAM,CAE8C"}

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

@@ -1,3 +1,4 @@
+import { FLUID_ATMOSPHERE_WORDS } from "../FluidAtmosphere.js";
 import { AdvectionScheme, PressureSolver } from "../FluidSimulator.js";
 
 /**
@@ -11,6 +12,11 @@ import { AdvectionScheme, PressureSolver } from "../FluidSimulator.js";
  * the main-thread {@link FluidSystem}, which is the point of a drop-in
  * replacement.
  *
+ * After the header come the fields to step, {@link FLUID_COMMAND_FIELD_WORDS}
+ * words each: the field's id, then this tick's far field in that field's grid
+ * units (a {@link FluidAtmosphere} record), which the worker brings the field to
+ * before the solve.
+ *
  * @readonly
  * @enum {number}
  */
@@ -28,21 +34,43 @@ export const FluidCommand = {
     ADVECTION_SCHEME: 10,
     PRESSURE_SOLVER: 11,
     /**
-     * How many field ids follow.
+     * How many field records follow.
      */
     FIELD_COUNT: 12,
     /**
-     * First of {@link FluidCommand.FIELD_COUNT} field ids, in the order they
-     * should be stepped.
+     * First of {@link FluidCommand.FIELD_COUNT} field records, in the order the
+     * fields should be stepped: {@link FLUID_COMMAND_FIELD_WORDS} words each, the
+     * field's id at {@link FluidCommandField.ID} and its atmosphere from
+     * {@link FluidCommandField.ATMOSPHERE}.
+     */
+    FIELDS: 13
+};
+
+/**
+ * Layout of one field record in the command region, relative to its start.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const FluidCommandField = {
+    ID: 0,
+    /**
+     * First word of the field's {@link FluidAtmosphere} record, in its grid units.
      */
-    FIELD_IDS: 13
+    ATMOSPHERE: 1
 };
 
 /**
- * Command words consumed before the variable-length field id list.
+ * Words in one field record.
+ * @type {number}
+ */
+export const FLUID_COMMAND_FIELD_WORDS = 1 + FLUID_ATMOSPHERE_WORDS;
+
+/**
+ * Command words consumed before the variable-length list of field records.
  * @type {number}
  */
-export const FLUID_COMMAND_HEADER_WORDS = FluidCommand.FIELD_IDS;
+export const FLUID_COMMAND_HEADER_WORDS = FluidCommand.FIELDS;
 
 /**
  * `AdvectionScheme` is a string enum; the command region is numeric.

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

@@ -17,6 +17,11 @@
  * field's buffer references are stable, but caching them across resolution changes
  * would break).
  *
+ * State an effector carries from one tick to the next changes in its per-tick hooks,
+ * never in `apply`: {@link FluidEffectorsSystem} calls {@link syncFromTransform} and
+ * then {@link advance} exactly once per fixed step, before any fluid system applies
+ * the effector, however many fluid systems there are.
+ *
  * One stated exception: a MANUALLY driven {@link WakeFluidEffector} advances its own
  * trail at the end of `apply`, because a source positioned by hand outside the ECS
  * has nothing else to advance it. That mode hands the segment to whichever field
@@ -35,14 +40,26 @@ export class AbstractFluidEffector {
      */
     apply(field: FluidField, dt: number, world_to_grid: Float32Array | number[]): void;
     /**
-     * Optional hook called by {@link FluidSystem} once per step on each effector whose
-     * entity also has a `Transform64` component. Default: no-op. Effectors that should
-     * follow an entity override this to pull world-space position / orientation /
+     * Optional hook called by {@link FluidEffectorsSystem} once per fixed step on each
+     * effector whose entity also has a `Transform64` component, before {@link advance}
+     * and before any fluid system applies the effector. Default: no-op. Effectors that
+     * should follow an entity override this to pull world-space position / orientation /
      * velocity off the transform.
      *
      * @param {Transform64} transform
      */
     syncFromTransform(transform: Transform64): void;
+    /**
+     * The per-tick hook: called by {@link FluidEffectorsSystem} exactly once per fixed
+     * step for every effector, with or without a `Transform64` on its entity, after
+     * {@link syncFromTransform} and before any fluid system applies it. Default: no-op.
+     * Effectors whose state evolves with time on their own (a gust's phases) override
+     * this to advance it; `apply` then reads that state, and every field stepped this
+     * tick sees the same.
+     *
+     * @param {number} dt seconds, the fixed step
+     */
+    advance(dt: number): void;
     /**
      * Strict value equality. The base implementation collapses to reference equality
      * — every concrete effector class overrides this to compare its own configured
@@ -71,5 +88,31 @@ export class AbstractFluidEffector {
      * @param {AABB3} out  destination, mutated in place
      */
     getBoundingBox(out: AABB3): void;
+    /**
+     * Write this effector into a GPU fluid effector record (`FLUID_EFFECTOR_RECORD_STRUCT`, a
+     * staging object from `fluid_effector_record_create`), comparing each field while assigning it,
+     * and answer whether any field changed: an effector that has not changed writes nothing, and its
+     * row is not uploaded.
+     *
+     * The caller sets `record.node` first, and the effector writes its parameters in that node's
+     * frame: the world's at node 0, its own entity's at any other (see `FLUID_EFFECTOR_RECORD_STRUCT`).
+     * `node` itself is never written here.
+     *
+     * Only effectors whose {@link has_gpu_record} is true have a GPU form. The base implementation
+     * writes nothing and answers false: a `GlobalFluidEffector` is folded into the far field instead,
+     * and an effector class of your own is one the GPU fluid skips.
+     *
+     * @param {FluidEffectorRecord} record
+     * @returns {boolean} whether any field of `record` changed
+     */
+    write_gpu_record(record: FluidEffectorRecord): boolean;
+    /**
+     * Whether {@link AbstractFluidEffector#write_gpu_record} writes a record: true for the effector classes
+     * the GPU fluid deposits per face (impulse, wake, vortex).
+     *
+     * @readonly
+     * @type {boolean}
+     */
+    readonly has_gpu_record: boolean;
 }
 //# sourceMappingURL=AbstractFluidEffector.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"AbstractFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/AbstractFluidEffector.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IACI;;;;;;OAMG;IACH,6BALW,MAAM,iBACN,YAAY,GAAC,MAAM,EAAE,QAO/B;IAED;;;;;;;OAOG;IACH,gDAEC;IAED;;;;;;OAMG;IACH,cAHW,qBAAqB,GACpB,OAAO,CAIlB;IAED;;;;;OAKG;IACH,QAFY,MAAM,CAIjB;IAED;;;;;;;;;;;OAWG;IACH,iCAEC;CACJ"}
+{"version":3,"file":"AbstractFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/AbstractFluidEffector.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH;IACI;;;;;;OAMG;IACH,6BALW,MAAM,iBACN,YAAY,GAAC,MAAM,EAAE,QAO/B;IAED;;;;;;;;OAQG;IACH,gDAEC;IAED;;;;;;;;;OASG;IACH,YAFW,MAAM,QAIhB;IAED;;;;;;OAMG;IACH,cAHW,qBAAqB,GACpB,OAAO,CAIlB;IAED;;;;;OAKG;IACH,QAFY,MAAM,CAIjB;IAED;;;;;;;;;;;OAWG;IACH,iCAEC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,+CAFa,OAAO,CAInB;IAGL;;;;;;OAMG;IACH,yBAFU,OAAO,CAE6B;CAT7C"}

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

@@ -17,6 +17,11 @@
  * field's buffer references are stable, but caching them across resolution changes
  * would break).
  *
+ * State an effector carries from one tick to the next changes in its per-tick hooks,
+ * never in `apply`: {@link FluidEffectorsSystem} calls {@link syncFromTransform} and
+ * then {@link advance} exactly once per fixed step, before any fluid system applies
+ * the effector, however many fluid systems there are.
+ *
  * One stated exception: a MANUALLY driven {@link WakeFluidEffector} advances its own
  * trail at the end of `apply`, because a source positioned by hand outside the ECS
  * has nothing else to advance it. That mode hands the segment to whichever field
@@ -39,9 +44,10 @@ export class AbstractFluidEffector {
     }
 
     /**
-     * Optional hook called by {@link FluidSystem} once per step on each effector whose
-     * entity also has a `Transform64` component. Default: no-op. Effectors that should
-     * follow an entity override this to pull world-space position / orientation /
+     * Optional hook called by {@link FluidEffectorsSystem} once per fixed step on each
+     * effector whose entity also has a `Transform64` component, before {@link advance}
+     * and before any fluid system applies the effector. Default: no-op. Effectors that
+     * should follow an entity override this to pull world-space position / orientation /
      * velocity off the transform.
      *
      * @param {Transform64} transform
@@ -50,6 +56,20 @@ export class AbstractFluidEffector {
         // override as needed
     }
 
+    /**
+     * The per-tick hook: called by {@link FluidEffectorsSystem} exactly once per fixed
+     * step for every effector, with or without a `Transform64` on its entity, after
+     * {@link syncFromTransform} and before any fluid system applies it. Default: no-op.
+     * Effectors whose state evolves with time on their own (a gust's phases) override
+     * this to advance it; `apply` then reads that state, and every field stepped this
+     * tick sees the same.
+     *
+     * @param {number} dt seconds, the fixed step
+     */
+    advance(dt) {
+        // override as needed
+    }
+
     /**
      * Strict value equality. The base implementation collapses to reference equality
      * — every concrete effector class overrides this to compare its own configured
@@ -86,4 +106,34 @@ export class AbstractFluidEffector {
     getBoundingBox(out) {
         out.setInfiniteBounds();
     }
+
+    /**
+     * Write this effector into a GPU fluid effector record (`FLUID_EFFECTOR_RECORD_STRUCT`, a
+     * staging object from `fluid_effector_record_create`), comparing each field while assigning it,
+     * and answer whether any field changed: an effector that has not changed writes nothing, and its
+     * row is not uploaded.
+     *
+     * The caller sets `record.node` first, and the effector writes its parameters in that node's
+     * frame: the world's at node 0, its own entity's at any other (see `FLUID_EFFECTOR_RECORD_STRUCT`).
+     * `node` itself is never written here.
+     *
+     * Only effectors whose {@link has_gpu_record} is true have a GPU form. The base implementation
+     * writes nothing and answers false: a `GlobalFluidEffector` is folded into the far field instead,
+     * and an effector class of your own is one the GPU fluid skips.
+     *
+     * @param {FluidEffectorRecord} record
+     * @returns {boolean} whether any field of `record` changed
+     */
+    write_gpu_record(record) {
+        return false;
+    }
 }
+
+/**
+ * Whether {@link AbstractFluidEffector#write_gpu_record} writes a record: true for the effector classes
+ * the GPU fluid deposits per face (impulse, wake, vortex).
+ *
+ * @readonly
+ * @type {boolean}
+ */
+AbstractFluidEffector.prototype.has_gpu_record = false;