@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -3,13 +3,16 @@
  *
  * Effectors here are decoupled from any specific {@link FluidField} — {@link FluidSystem}
  * gathers all effectors across all entities and applies them to every fluid field each
- * step. Effectors that don't overlap a given field self-cull via their radius / position
- * checks, so attachment is implicit rather than configured.
+ * step, the {@link GlobalFluidEffector}s together as one far field. Effectors that don't
+ * overlap a given field self-cull via their radius / position checks, so attachment is
+ * implicit rather than configured.
  *
  * Pair this component with a `Transform64` on the same entity to let position-bearing
  * effectors ({@link WakeFluidEffector}, {@link ImpulseFluidEffector}, ...) follow the
- * entity. The system calls each effector's {@link AbstractFluidEffector.syncFromTransform}
- * with the entity's Transform64 before stepping the simulator.
+ * entity. {@link FluidEffectorsSystem} calls each effector's
+ * {@link AbstractFluidEffector.syncFromTransform} with the entity's Transform64, and
+ * {@link AbstractFluidEffector.advance} on every effector, once per tick before any
+ * fluid system applies them.
  */
 export class FluidEffectorsComponent {
     /**
@@ -42,4 +45,7 @@ export class FluidEffectorsComponent {
     hash(): number;
     isFluidEffectorsComponent: boolean;
 }
+export namespace FluidEffectorsComponent {
+    let typeName: string;
+}
 //# sourceMappingURL=FluidEffectorsComponent.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"FluidEffectorsComponent.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidEffectorsComponent.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH;IAEI;;;OAGG;IACH,WAFU,uBAAuB,CAElB;IAEf;;;;OAIG;IACH,mDAIC;IAED;;;OAGG;IACH,sDAKC;IAED;;;;;OAKG;IACH,cAHW,uBAAuB,GACtB,OAAO,CAqBlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAWjB;IAGL,mCAA2D;CAF1D"}
+{"version":3,"file":"FluidEffectorsComponent.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidEffectorsComponent.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH;IAEI;;;OAGG;IACH,WAFU,uBAAuB,CAElB;IAEf;;;;OAIG;IACH,mDAIC;IAED;;;OAGG;IACH,sDAKC;IAED;;;;;OAKG;IACH,cAHW,uBAAuB,GACtB,OAAO,CAqBlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAWjB;IAGL,mCAA2D;CAF1D;;kBAMS,MAAM"}

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

@@ -5,13 +5,16 @@ import { assert } from "../../../../core/assert.js";
  *
  * Effectors here are decoupled from any specific {@link FluidField} — {@link FluidSystem}
  * gathers all effectors across all entities and applies them to every fluid field each
- * step. Effectors that don't overlap a given field self-cull via their radius / position
- * checks, so attachment is implicit rather than configured.
+ * step, the {@link GlobalFluidEffector}s together as one far field. Effectors that don't
+ * overlap a given field self-cull via their radius / position checks, so attachment is
+ * implicit rather than configured.
  *
  * Pair this component with a `Transform64` on the same entity to let position-bearing
  * effectors ({@link WakeFluidEffector}, {@link ImpulseFluidEffector}, ...) follow the
- * entity. The system calls each effector's {@link AbstractFluidEffector.syncFromTransform}
- * with the entity's Transform64 before stepping the simulator.
+ * entity. {@link FluidEffectorsSystem} calls each effector's
+ * {@link AbstractFluidEffector.syncFromTransform} with the entity's Transform64, and
+ * {@link AbstractFluidEffector.advance} on every effector, once per tick before any
+ * fluid system applies them.
  */
 export class FluidEffectorsComponent {
 
@@ -87,3 +90,9 @@ export class FluidEffectorsComponent {
 }
 
 FluidEffectorsComponent.prototype.isFluidEffectorsComponent = true;
+
+/**
+ * @readonly
+ * @type {string}
+ */
+FluidEffectorsComponent.typeName = "FluidEffectorsComponent";

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

@@ -0,0 +1,47 @@
+/**
+ * Binary serialization for {@link FluidEffectorsComponent}: the count, then each effector in
+ * order through the serializer's object adapter, which writes the effector's `typeName` and
+ * version ahead of its own adapter's data, as `BehaviorComponent`'s behaviours are written.
+ *
+ * Every effector class in a saved component needs its adapter in the same registry: the engine's
+ * are {@link GlobalFluidEffectorSerializationAdapter}, {@link ImpulseFluidEffectorSerializationAdapter},
+ * {@link WakeFluidEffectorSerializationAdapter} and {@link VortexFluidEffectorSerializationAdapter}, and
+ * an effector class of your own needs a `typeName` and an adapter of its own. A global's gust phases
+ * go with it, so a save resumes the gust where it was.
+ *
+ * Like the other physics adapters this is not in `populateEngineSerializationRegistry`; the host
+ * registers it with the effector adapters.
+ *
+ * Version 0: a first version has no predecessor stream to upgrade from.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FluidEffectorsComponentSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof FluidEffectorsComponent;
+    /**
+     * @type {BinaryObjectSerializationAdapter|null}
+     */
+    objectAdapter: BinaryObjectSerializationAdapter | null;
+    /**
+     * @param {*} engine
+     * @param {BinaryObjectSerializationAdapter} objectAdapter
+     */
+    initialize(engine: any, objectAdapter: BinaryObjectSerializationAdapter): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {FluidEffectorsComponent} value
+     */
+    serialize(buffer: BinaryBuffer, value: FluidEffectorsComponent): void;
+    /**
+     * Replaces the component's effectors with the ones read.
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {FluidEffectorsComponent} value
+     */
+    deserialize(buffer: BinaryBuffer, value: FluidEffectorsComponent): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
+//# sourceMappingURL=FluidEffectorsComponentSerializationAdapter.d.ts.map

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

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

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

@@ -0,0 +1,72 @@
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
+
+/**
+ * Binary serialization for {@link FluidEffectorsComponent}: the count, then each effector in
+ * order through the serializer's object adapter, which writes the effector's `typeName` and
+ * version ahead of its own adapter's data, as `BehaviorComponent`'s behaviours are written.
+ *
+ * Every effector class in a saved component needs its adapter in the same registry: the engine's
+ * are {@link GlobalFluidEffectorSerializationAdapter}, {@link ImpulseFluidEffectorSerializationAdapter},
+ * {@link WakeFluidEffectorSerializationAdapter} and {@link VortexFluidEffectorSerializationAdapter}, and
+ * an effector class of your own needs a `typeName` and an adapter of its own. A global's gust phases
+ * go with it, so a save resumes the gust where it was.
+ *
+ * Like the other physics adapters this is not in `populateEngineSerializationRegistry`; the host
+ * registers it with the effector adapters.
+ *
+ * Version 0: a first version has no predecessor stream to upgrade from.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FluidEffectorsComponentSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = FluidEffectorsComponent;
+    version = 0;
+
+    /**
+     * @type {BinaryObjectSerializationAdapter|null}
+     */
+    objectAdapter = null;
+
+    /**
+     * @param {*} engine
+     * @param {BinaryObjectSerializationAdapter} objectAdapter
+     */
+    initialize(engine, objectAdapter) {
+        this.objectAdapter = objectAdapter;
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {FluidEffectorsComponent} value
+     */
+    serialize(buffer, value) {
+        const effectors = value.effectors;
+        const count = effectors.length;
+
+        buffer.writeUintVar(count);
+
+        for (let i = 0; i < count; i++) {
+            this.objectAdapter.serialize(buffer, effectors[i]);
+        }
+    }
+
+    /**
+     * Replaces the component's effectors with the ones read.
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {FluidEffectorsComponent} value
+     */
+    deserialize(buffer, value) {
+        const count = buffer.readUintVar();
+
+        const effectors = value.effectors;
+        effectors.length = 0;
+
+        for (let i = 0; i < count; i++) {
+            effectors.push(this.objectAdapter.deserialize(buffer));
+        }
+    }
+}

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

@@ -0,0 +1,67 @@
+/**
+ * The per-tick life of every fluid effector, and the far field, in one place. Once per fixed
+ * step, for every {@link FluidEffectorsComponent}:
+ *
+ *   1. when its entity has a `Transform64`, each effector's
+ *      {@link AbstractFluidEffector.syncFromTransform}, so position-bearing effectors (wakes,
+ *      impulses) follow their entity;
+ *   2. each effector's {@link AbstractFluidEffector.advance} with the fixed step;
+ *
+ * then, once:
+ *
+ *   3. the fold of every {@link GlobalFluidEffector} into one far field, integrated in f64.
+ *
+ * Effectors carry state across ticks — a wake's trail advances in its sync, a global's gust in
+ * its advance — so this has to happen exactly once a tick however many fluid systems apply the
+ * effectors. It used to be a line in each fluid system, and a scene with two of them advanced
+ * every wake twice.
+ *
+ * ## The far field
+ *
+ * The globals fold into `D = Σ d` (their drags), `W = Σ (d/D)·w` (the drag-weighted mean of their
+ * winds), `g = Σ gust` and `F = Σ force`. The far field is `v_far = u + g`:
+ *
+ *   - `u` relaxes toward `W` exactly, `u ← W + (u − W)·e^(−D·dt)`. Only this system's first fold
+ *     seeds it at `W`, so a scene that starts with its globals starts in steady state; a global
+ *     that arrives later relaxes the air from where it is, at its drag. With `D = 0` — the last
+ *     global gone included — nothing relaxes it and it holds. A scene that never had a global is
+ *     still air; calm is authored as a global with wind 0 and a drag.
+ *   - `g` is added, not drag-filtered: the air carries the authored gust.
+ *   - `Λ += D·dt`, so a field brought from one instant to another keeps `e^(−ΔΛ)` of its deviation
+ *     from the far field however `D` varied in between.
+ *   - `F` is not part of the far field: a world-wide body force would be an unbounded downdraft at
+ *     `D = 0`. CPU fields apply it, in the same step, through its response `P`, integrated here
+ *     exactly tick by tick (`P ← F/D + (P − F/D)·e^(−D·dt)`, or `P += F·dt` with no drag), so a
+ *     field stepping across several ticks takes the force exactly however `F` and `D` varied.
+ *
+ * {@link read_atmosphere} hands the result out as a {@link FluidAtmosphere} record. The sums are
+ * order-independent for two globals and differ only by rounding for more, so several globals act
+ * as one.
+ *
+ * Every fluid system ({@link FluidSystem}, {@link WorkerFluidSystem}) requires this one, and
+ * reads what it writes: it declares `Write` on `FluidEffectorsComponent`, they declare `Read`, so
+ * the order derived from those declarations runs it first.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FluidEffectorsSystem extends System<any> {
+    constructor();
+    components_used: (ResourceAccessSpecification<typeof FluidEffectorsComponent> | ResourceAccessSpecification<typeof Transform64>)[];
+    /**
+     * Copy the far field at the end of the last tick, and the terms CPU fields apply with it,
+     * into `out` at `offset`: a {@link FluidAtmosphere} record, WORLD units. Allocates nothing.
+     *
+     * Before the first tick it is still air at time 0.
+     *
+     * @param {Float64Array|number[]} out
+     * @param {number} offset
+     */
+    read_atmosphere(out: Float64Array | number[], offset: number): void;
+    #private;
+}
+import { System } from "../../../ecs/System.js";
+import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
+//# sourceMappingURL=FluidEffectorsSystem.d.ts.map

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

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

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

@@ -0,0 +1,307 @@
+import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { System } from "../../../ecs/System.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
+import { GlobalFluidEffector } from "../effector/GlobalFluidEffector.js";
+import { FLUID_ATMOSPHERE_WORDS, FluidAtmosphere } from "../FluidAtmosphere.js";
+import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
+import { fluid_sync_effectors_from_transform } from "./fluid_sync_effectors_from_transform.js";
+
+/**
+ * The per-tick life of every fluid effector, and the far field, in one place. Once per fixed
+ * step, for every {@link FluidEffectorsComponent}:
+ *
+ *   1. when its entity has a `Transform64`, each effector's
+ *      {@link AbstractFluidEffector.syncFromTransform}, so position-bearing effectors (wakes,
+ *      impulses) follow their entity;
+ *   2. each effector's {@link AbstractFluidEffector.advance} with the fixed step;
+ *
+ * then, once:
+ *
+ *   3. the fold of every {@link GlobalFluidEffector} into one far field, integrated in f64.
+ *
+ * Effectors carry state across ticks — a wake's trail advances in its sync, a global's gust in
+ * its advance — so this has to happen exactly once a tick however many fluid systems apply the
+ * effectors. It used to be a line in each fluid system, and a scene with two of them advanced
+ * every wake twice.
+ *
+ * ## The far field
+ *
+ * The globals fold into `D = Σ d` (their drags), `W = Σ (d/D)·w` (the drag-weighted mean of their
+ * winds), `g = Σ gust` and `F = Σ force`. The far field is `v_far = u + g`:
+ *
+ *   - `u` relaxes toward `W` exactly, `u ← W + (u − W)·e^(−D·dt)`. Only this system's first fold
+ *     seeds it at `W`, so a scene that starts with its globals starts in steady state; a global
+ *     that arrives later relaxes the air from where it is, at its drag. With `D = 0` — the last
+ *     global gone included — nothing relaxes it and it holds. A scene that never had a global is
+ *     still air; calm is authored as a global with wind 0 and a drag.
+ *   - `g` is added, not drag-filtered: the air carries the authored gust.
+ *   - `Λ += D·dt`, so a field brought from one instant to another keeps `e^(−ΔΛ)` of its deviation
+ *     from the far field however `D` varied in between.
+ *   - `F` is not part of the far field: a world-wide body force would be an unbounded downdraft at
+ *     `D = 0`. CPU fields apply it, in the same step, through its response `P`, integrated here
+ *     exactly tick by tick (`P ← F/D + (P − F/D)·e^(−D·dt)`, or `P += F·dt` with no drag), so a
+ *     field stepping across several ticks takes the force exactly however `F` and `D` varied.
+ *
+ * {@link read_atmosphere} hands the result out as a {@link FluidAtmosphere} record. The sums are
+ * order-independent for two globals and differ only by rounding for more, so several globals act
+ * as one.
+ *
+ * Every fluid system ({@link FluidSystem}, {@link WorkerFluidSystem}) requires this one, and
+ * reads what it writes: it declares `Write` on `FluidEffectorsComponent`, they declare `Read`, so
+ * the order derived from those declarations runs it first.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FluidEffectorsSystem extends System {
+
+    components_used = [
+        // Read to find the effectors; written through them (a wake's trail, an impulse's
+        // position, whatever `advance` moves).
+        ResourceAccessSpecification.from(FluidEffectorsComponent, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        // The pose effectors on the same entity follow.
+        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read),
+    ];
+
+    /**
+     * The step being run, for {@link #visit}: the traversal hands it only the component and
+     * the entity.
+     * @type {number}
+     */
+    #time_delta_seconds = 0;
+
+    /**
+     * `Transform64`'s index in the dataset being traversed, or -1 when it has none.
+     * @type {number}
+     */
+    #transform_index = -1;
+
+    /**
+     * The globals met this tick, in traversal order, the first {@link #global_count} of them.
+     * Written by index and never shortened, so a tick does not reallocate it; entries past the
+     * count are cleared after the fold.
+     * @type {GlobalFluidEffector[]}
+     */
+    #globals = [];
+
+    /**
+     * @type {number}
+     */
+    #global_count = 0;
+
+    /**
+     * Scratch for one global's gust.
+     * @type {Float64Array}
+     */
+    #gust = new Float64Array(3);
+
+    /**
+     * `u`, the far field's steady part, WORLD units per second.
+     * @type {Float64Array}
+     */
+    #steady = new Float64Array(3);
+
+    /**
+     * Whether this system has folded once. Its first fold seeds {@link #steady} at the globals'
+     * mean wind; every later one relaxes it from where it is.
+     * @type {boolean}
+     */
+    #first_fold_done = false;
+
+    /**
+     * `P`, the forced response: the velocity the summed body force has given air the
+     * atmosphere otherwise leaves alone, WORLD units per second. Continuous from the first
+     * tick, never reset, since a field takes only its change over an interval.
+     * @type {Float64Array}
+     */
+    #forced = new Float64Array(3);
+
+    /**
+     * The far field at the end of the last tick, WORLD units.
+     * @type {Float64Array}
+     */
+    #atmosphere = new Float64Array(FLUID_ATMOSPHERE_WORDS);
+
+    /**
+     * Copy the far field at the end of the last tick, and the terms CPU fields apply with it,
+     * into `out` at `offset`: a {@link FluidAtmosphere} record, WORLD units. Allocates nothing.
+     *
+     * Before the first tick it is still air at time 0.
+     *
+     * @param {Float64Array|number[]} out
+     * @param {number} offset
+     */
+    read_atmosphere(out, offset) {
+        const atmosphere = this.#atmosphere;
+
+        for (let i = 0; i < FLUID_ATMOSPHERE_WORDS; i++) {
+            out[offset + i] = atmosphere[i];
+        }
+    }
+
+    /**
+     * @param {number} time_delta_seconds
+     */
+    fixedUpdate(time_delta_seconds) {
+        const em = this.entityManager;
+        if (em === null) {
+            return;
+        }
+        const ecd = em.dataset;
+        if (ecd === null) {
+            return;
+        }
+
+        this.#time_delta_seconds = time_delta_seconds;
+        this.#transform_index = ecd.computeComponentTypeIndex(Transform64);
+
+        const previous_global_count = this.#global_count;
+        this.#global_count = 0;
+
+        ecd.traverseComponents(FluidEffectorsComponent, this.#visit, this);
+
+        this.#fold(time_delta_seconds);
+
+        // Let go of globals that have left since the last tick.
+        const globals = this.#globals;
+        for (let i = this.#global_count; i < previous_global_count; i++) {
+            globals[i] = null;
+        }
+    }
+
+    /**
+     * @param {FluidEffectorsComponent} effectors_component
+     * @param {number} entity
+     */
+    #visit(effectors_component, entity) {
+        const transform_index = this.#transform_index;
+
+        if (transform_index !== -1) {
+            const transform = this.entityManager.dataset.getComponentByIndex(entity, transform_index);
+
+            if (transform !== undefined) {
+                fluid_sync_effectors_from_transform(effectors_component, transform);
+            }
+        }
+
+        const effectors = effectors_component.effectors;
+        const dt = this.#time_delta_seconds;
+
+        for (let i = 0; i < effectors.length; i++) {
+            const effector = effectors[i];
+
+            effector.advance(dt);
+
+            if (effector instanceof GlobalFluidEffector) {
+                this.#globals[this.#global_count++] = effector;
+            }
+        }
+    }
+
+    /**
+     * Fold this tick's globals into the far field and integrate it over `dt`.
+     *
+     * @param {number} dt seconds
+     */
+    #fold(dt) {
+        const globals = this.#globals;
+        const count = this.#global_count;
+        const gust = this.#gust;
+
+        let D = 0;
+        let gx = 0, gy = 0, gz = 0;
+        let fx = 0, fy = 0, fz = 0;
+
+        for (let i = 0; i < count; i++) {
+            const effector = globals[i];
+
+            // A drag that is not positive does not relax.
+            const d = effector.drag > 0 ? effector.drag : 0;
+            D += d;
+
+            const force = effector.force;
+            fx += force[0];
+            fy += force[1];
+            fz += force[2];
+
+            effector.compute_gust(gust);
+            gx += gust[0];
+            gy += gust[1];
+            gz += gust[2];
+        }
+
+        const steady = this.#steady;
+
+        // With no drag (no global at all included) nothing relaxes the air: `u` holds.
+        if (D > 0) {
+            // Weights d/D, so one global's mean wind is its own wind exactly.
+            let wx = 0, wy = 0, wz = 0;
+
+            for (let i = 0; i < count; i++) {
+                const effector = globals[i];
+
+                if (!(effector.drag > 0)) {
+                    continue;
+                }
+
+                const weight = effector.drag / D;
+                const wind = effector.wind;
+
+                wx += weight * wind[0];
+                wy += weight * wind[1];
+                wz += weight * wind[2];
+            }
+
+            if (this.#first_fold_done) {
+                const keep = Math.exp(-D * dt);
+
+                steady[0] = wx + (steady[0] - wx) * keep;
+                steady[1] = wy + (steady[1] - wy) * keep;
+                steady[2] = wz + (steady[2] - wz) * keep;
+            } else {
+                // A scene that starts with its globals starts in steady state.
+                steady[0] = wx;
+                steady[1] = wy;
+                steady[2] = wz;
+            }
+        }
+
+        this.#first_fold_done = true;
+
+        // The force's response, exact over the tick: toward F/D at D, or F·dt with no drag.
+        const forced = this.#forced;
+
+        if (D > 0) {
+            const inv_drag = 1 / D;
+            const keep = Math.exp(-D * dt);
+
+            const terminal_x = fx * inv_drag;
+            const terminal_y = fy * inv_drag;
+            const terminal_z = fz * inv_drag;
+
+            forced[0] = terminal_x + (forced[0] - terminal_x) * keep;
+            forced[1] = terminal_y + (forced[1] - terminal_y) * keep;
+            forced[2] = terminal_z + (forced[2] - terminal_z) * keep;
+        } else {
+            forced[0] += fx * dt;
+            forced[1] += fy * dt;
+            forced[2] += fz * dt;
+        }
+
+        const atmosphere = this.#atmosphere;
+
+        atmosphere[FluidAtmosphere.TIME] += dt;
+        atmosphere[FluidAtmosphere.VELOCITY_X] = steady[0] + gx;
+        atmosphere[FluidAtmosphere.VELOCITY_Y] = steady[1] + gy;
+        atmosphere[FluidAtmosphere.VELOCITY_Z] = steady[2] + gz;
+        atmosphere[FluidAtmosphere.LAMBDA] += D * dt;
+        atmosphere[FluidAtmosphere.FORCED_X] = forced[0];
+        atmosphere[FluidAtmosphere.FORCED_Y] = forced[1];
+        atmosphere[FluidAtmosphere.FORCED_Z] = forced[2];
+        atmosphere[FluidAtmosphere.FORCE_X] = fx;
+        atmosphere[FluidAtmosphere.FORCE_Y] = fy;
+        atmosphere[FluidAtmosphere.FORCE_Z] = fz;
+        atmosphere[FluidAtmosphere.DRAG] = D;
+    }
+}

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

@@ -66,11 +66,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#445@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#461@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#445@#clear_field"(fluid: FluidComponent): void;
+    static "__#461@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -82,7 +82,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#445@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#461@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -102,18 +102,18 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#445@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#461@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
-    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];
+    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof FluidObstacle> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof FluidComponent>)[];
     #private;
 }
 import { System } from "../../../ecs/System.js";
 import { FluidObstacle } from "./FluidObstacle.js";
 import { Transform64 } from "../../../ecs/transform/Transform64.js";
 import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
-import { RigidBody } from "../../ecs/RigidBody.js";
 import { Collider } from "../../ecs/Collider.js";
+import { RigidBody } from "../../ecs/RigidBody.js";
 import { FluidComponent } from "./FluidComponent.js";
 import { PosedShape3D } from "../../../../core/geom/3d/shape/PosedShape3D.js";
 //# sourceMappingURL=FluidObstacleSystem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"FluidObstacleSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidObstacleSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH;IAuHI;;OAEG;IACH,sCAFW,cAAc,QAIxB;IAED;;OAEG;IACH,oCAFW,cAAc,QAOxB;IAED;;;;;;;;;;OAUG;IACH,iCANW,cAAc,SACd,YAAY,QACZ,YAAY,aACZ,MAAM,SACN,YAAY,QAiDtB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,4CATW,cAAc,SACd,YAAY,QACZ,YAAY,aACZ,MAAM,SACN,YAAY,OACZ,MAAM,OACN,MAAM,OACN,MAAM,QAqEhB;;IAxRD,uCAA+B;IAE/B,6QAOE;;CAgRL;uBAlWsB,wBAAwB;8BAKjB,oBAAoB;4BAJtB,uCAAuC;4CAFvB,uDAAuD;0BAIzE,wBAAwB;yBADzB,uBAAuB;+BAEjB,qBAAqB;6BAPvB,gDAAgD"}
+{"version":3,"file":"FluidObstacleSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidObstacleSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH;IAuHI;;OAEG;IACH,sCAFW,cAAc,QAIxB;IAED;;OAEG;IACH,oCAFW,cAAc,QAOxB;IAED;;;;;;;;;;OAUG;IACH,iCANW,cAAc,SACd,YAAY,QACZ,YAAY,aACZ,MAAM,SACN,YAAY,QAiDtB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,4CATW,cAAc,SACd,YAAY,QACZ,YAAY,aACZ,MAAM,SACN,YAAY,OACZ,MAAM,OACN,MAAM,OACN,MAAM,QAqEhB;;IAxRD,uCAA+B;IAE/B,6QAOE;;CAgRL;uBAlWsB,wBAAwB;8BAKjB,oBAAoB;4BAJtB,uCAAuC;4CAFvB,uDAAuD;yBAG1E,uBAAuB;0BACtB,wBAAwB;+BACnB,qBAAqB;6BAPvB,gDAAgD"}