@woosh/meep-engine 2.138.19 → 2.139.0

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

@@ -0,0 +1,278 @@
+import { AABB3 } from "../../../../core/geom/3d/aabb/AABB3.js";
+import { aabb3_intersects_aabb3 } from "../../../../core/geom/3d/aabb/aabb3_intersects_aabb3.js";
+import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { System } from "../../../ecs/System.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { FluidComponent } from "./FluidComponent.js";
+import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
+import { FluidSimulator } from "../FluidSimulator.js";
+
+/**
+ * ECS system that steps every {@link FluidComponent} on a fixed timestep.
+ *
+ * Effectors live on a separate {@link FluidEffectorsComponent}, decoupled from any
+ * specific fluid field. Each step the system:
+ *
+ *   1. **Re-anchor moving fields.** For every (FluidComponent, Transform) tuple,
+ *      compute the desired grid origin as
+ *          `quantize(transform.position, cell_size) + offset`
+ *      where the grid is then centred at that point. On the first sync this is just
+ *      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, Transform) 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}:
+ *      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)`.
+ *
+ * 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 +
+ * filter happens per field; effectors that overlap multiple fields are evaluated
+ * multiple times — fine for the typical "few fields" case, optimise to a cached
+ * per-effector AABB pass if you find yourself with many fields.
+ *
+ * Uses `fixedUpdate` rather than `update` because fluid stability and the warm-started
+ * pressure solve both depend on consistent dt. Variable timesteps cause visible
+ * pulsing as projection convergence varies.
+ */
+export class FluidSystem extends System {
+
+    dependencies = [FluidComponent];
+
+    /**
+     * 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 Transform sync hooks.
+     *   - `Transform` — read every step (paired with FluidEffectorsComponent) so
+     *     position-bearing effectors can follow their entity.
+     */
+    components_used = [
+        // FluidComponent is also in `dependencies`, but reanchor + step write to it
+        // (origin, anchored, field buffers). Declared again with explicit Write.
+        ResourceAccessSpecification.from(FluidComponent, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(FluidEffectorsComponent, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Transform, ResourceAccessKind.Read),
+    ];
+
+    /**
+     * Single simulator drives every fluid field — it carries only transient scratch,
+     * which {@link FluidSimulator.#ensure_scratch} grows to fit the largest field
+     * encountered.
+     * @type {FluidSimulator}
+     */
+    simulator = new FluidSimulator();
+
+    /**
+     * Per-field filtered effector list, rebuilt at the top of each field's step.
+     * Held as an instance field so we don't allocate per frame.
+     * @type {AbstractFluidEffector[]}
+     */
+    #visible_effectors = [];
+
+    /**
+     * Reusable column-major 4×4 buffer for the world-to-grid matrix; rewritten per
+     * field per step.
+     * @type {Float32Array}
+     */
+    #world_to_grid = new Float32Array(16);
+
+    /**
+     * Reusable AABB scratch for the current field being stepped.
+     * @type {AABB3}
+     */
+    #field_aabb = new AABB3();
+
+    /**
+     * Reusable AABB scratch reused for every effector during broad-phase filtering.
+     * @type {AABB3}
+     */
+    #effector_aabb = new AABB3();
+
+    /**
+     * @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;
+        }
+
+        // 1. Re-anchor moving fields. Field origin tracks quantize(transform) + offset;
+        //    when the quantization changes, the field is shifted to follow the world.
+        ecd.traverseEntities([FluidComponent, Transform], FluidSystem.#reanchor_field);
+
+        // 2. Sync every effector that wants to follow its entity's Transform.
+        ecd.traverseEntities([FluidEffectorsComponent, Transform], FluidSystem.#sync_effectors_from_transform);
+
+        // 2. Step each fluid field, with broad-phase effector filtering per field.
+        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;
+
+        ecd.traverseComponents(FluidComponent, function (component) {
+            if (!component.enabled) {
+                return;
+            }
+
+            component.getBoundingBox(field_aabb);
+            FluidSystem.#build_world_to_grid(world_to_grid, component);
+
+            visible.length = 0;
+            ecd.traverseComponents(FluidEffectorsComponent, function (effectors_component) {
+                const arr = effectors_component.effectors;
+                for (let i = 0; i < arr.length; i++) {
+                    const e = arr[i];
+                    e.getBoundingBox(effector_aabb);
+                    if (aabb3_intersects_aabb3(
+                        effector_aabb.x0, effector_aabb.y0, effector_aabb.z0,
+                        effector_aabb.x1, effector_aabb.y1, effector_aabb.z1,
+                        field_aabb.x0, field_aabb.y0, field_aabb.z0,
+                        field_aabb.x1, field_aabb.y1, field_aabb.z1
+                    )) {
+                        visible.push(e);
+                    }
+                }
+            });
+
+            sim.step(component.field, time_delta_seconds, visible, world_to_grid);
+        });
+    }
+
+    /**
+     * Visitor for the (effectors, transform) traversal — calls syncFromTransform on
+     * every effector in the component.
+     * @param {FluidEffectorsComponent} effectors_component
+     * @param {Transform} transform
+     */
+    static #sync_effectors_from_transform(effectors_component, transform) {
+        const effectors = effectors_component.effectors;
+        for (let i = 0; i < effectors.length; i++) {
+            effectors[i].syncFromTransform(transform);
+        }
+    }
+
+    /**
+     * Visitor for the (FluidComponent, Transform) traversal — keeps the field's
+     * grid origin locked to a cell-aligned position near the transform.
+     *
+     * Centre formula: `q * cell_size + offset`, where `q` is the cell index along
+     * each axis. Origin is then the centre minus half the grid extent so the centre
+     * lands at the geometric middle of the grid.
+     *
+     * Hysteresis: instead of recomputing `q` from the raw position every frame
+     * (which would re-shift on every boundary crossing for a Transform jittering on
+     * a cell edge), we recover the current `q` from the existing origin and only
+     * advance 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.
+     *
+     * First sync (`anchored = false`): snap origin to the desired value, no shift.
+     * Subsequent syncs: per-axis hysteretic quantization, then `field.shift` if the
+     * integer delta is non-zero.
+     *
+     * @param {FluidComponent} component
+     * @param {Transform} transform
+     */
+    static #reanchor_field(component, transform) {
+        const cs = component.cell_size;
+        const p = transform.position;
+        const offset = component.offset;
+        const hyst = component.hysteresis;
+
+        const res = component.field.getResolution();
+        const half_extent_x = (res[0] - 1) * cs * 0.5;
+        const half_extent_y = (res[1] - 1) * cs * 0.5;
+        const half_extent_z = (res[2] - 1) * cs * 0.5;
+
+        const origin = component.origin;
+
+        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(p.x / cs);
+            const q_y = Math.round(p.y / cs);
+            const q_z = Math.round(p.z / cs);
+            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;
+            component.anchored = true;
+            return;
+        }
+
+        // Recover the current quantized cell index per axis from the existing origin.
+        // origin_axis = q_curr * cs + offset - half_extent  →
+        //     q_curr = (origin_axis + half_extent - offset) / cs.
+        // Round defends against floating drift; the value should already be integer.
+        const q_curr_x = Math.round((origin[0] + half_extent_x - offset[0]) / cs);
+        const q_curr_y = Math.round((origin[1] + half_extent_y - offset[1]) / cs);
+        const q_curr_z = Math.round((origin[2] + half_extent_z - offset[2]) / cs);
+
+        // Raw (fractional) cell coordinate the Transform sits at right now.
+        const raw_x = p.x / cs;
+        const raw_y = p.y / cs;
+        const raw_z = p.z / cs;
+
+        // 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 shift_x = q_new_x - q_curr_x;
+        const shift_y = q_new_y - q_curr_y;
+        const shift_z = q_new_z - q_curr_z;
+
+        if (shift_x === 0 && shift_y === 0 && shift_z === 0) {
+            return;
+        }
+
+        component.field.shift(shift_x, shift_y, shift_z);
+        origin[0] = q_new_x * cs + offset[0] - half_extent_x;
+        origin[1] = q_new_y * cs + offset[1] - half_extent_y;
+        origin[2] = q_new_z * cs + offset[2] - half_extent_z;
+    }
+
+    /**
+     * Write the world-to-grid affine for a FluidComponent into `out`. Axis-aligned,
+     * uniform-scale, so the matrix is sparse:
+     *
+     *     [ 1/cs   0     0    -ox/cs ]
+     *     [ 0      1/cs  0    -oy/cs ]
+     *     [ 0      0     1/cs -oz/cs ]
+     *     [ 0      0     0     1     ]
+     *
+     * Stored column-major (matches the convention of {@link v3_matrix4_multiply}).
+     *
+     * @param {Float32Array} out  length-16
+     * @param {FluidComponent} component
+     */
+    static #build_world_to_grid(out, component) {
+        const inv_cs = 1 / component.cell_size;
+        const ox = component.origin[0];
+        const oy = component.origin[1];
+        const oz = component.origin[2];
+
+        out[0]  = inv_cs;  out[1]  = 0;       out[2]  = 0;       out[3]  = 0;
+        out[4]  = 0;       out[5]  = inv_cs;  out[6]  = 0;       out[7]  = 0;
+        out[8]  = 0;       out[9]  = 0;       out[10] = inv_cs;  out[11] = 0;
+        out[12] = -ox * inv_cs;
+        out[13] = -oy * inv_cs;
+        out[14] = -oz * inv_cs;
+        out[15] = 1;
+    }
+}

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

@@ -1,6 +1,67 @@
 /**
- * Base interface for injecting external forces into the simulation
+ * External force source applied to a {@link FluidField} once per simulation step.
+ *
+ * Subclasses override {@link apply} to mutate the field's velocity (and, optionally,
+ * scalar attributes). The simulator calls `apply(field, dt, world_to_grid)` for every
+ * effector at the start of each step, before diffusion / projection / advection.
+ *
+ * Effectors are configured in WORLD coordinates. The `world_to_grid` matrix supplied
+ * to {@link apply} converts a world-space point into the target field's grid space.
+ * The same effector instance can therefore be applied to any number of fluid fields
+ * across a single step — the system iterates fields and re-supplies the matching
+ * matrix each time.
+ *
+ * Effectors should be idempotent given the same `dt`, field state, and
+ * `world_to_grid` — they are pure functions of (their own configured state, field,
+ * dt, matrix). They must not retain references to field buffers between calls (the
+ * field's buffer references are stable, but caching them across resolution changes
+ * would break).
  */
 export class AbstractFluidEffector {
+    /**
+     * @param {FluidField} field
+     * @param {number} dt seconds
+     * @param {Float32Array|number[]} world_to_grid  Column-major 4×4 affine sending
+     *                                               world-space points into the target
+     *                                               field's grid space.
+     */
+    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 `Transform` component. Default: no-op. Effectors that should
+     * follow an entity override this to pull world-space position / orientation /
+     * velocity off the transform.
+     *
+     * @param {Transform} transform
+     */
+    syncFromTransform(transform: Transform): void;
+    /**
+     * Strict value equality. The base implementation collapses to reference equality
+     * — every concrete effector class overrides this to compare its own configured
+     * state.
+     * @param {AbstractFluidEffector} other
+     * @return {boolean}
+     */
+    equals(other: AbstractFluidEffector): boolean;
+    /**
+     * Fast hash. The base implementation returns a constant — concrete effectors
+     * override to hash their own state. Should stay cheap (a few `combine_hash` calls
+     * over scalar fields).
+     * @return {number}
+     */
+    hash(): number;
+    /**
+     * Write the effector's world-space axis-aligned bounding box into `out`. Used by
+     * {@link FluidSystem} as a broad-phase culling primitive: if the effector's box
+     * doesn't intersect a fluid field's box, the effector is skipped for that field
+     * entirely.
+     *
+     * The base implementation writes infinite bounds — i.e. "could affect anything".
+     * Safe (never produces false negatives) but defeats the broad-phase. Concrete
+     * effectors override with tight bounds.
+     *
+     * @param {AABB3} out  destination, mutated in place
+     */
+    getBoundingBox(out: AABB3): void;
 }
 //# 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;;GAEG;AACH;CAEC"}
+{"version":3,"file":"AbstractFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/AbstractFluidEffector.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IACI;;;;;;OAMG;IACH,6BALW,MAAM,iBACN,YAAY,GAAC,MAAM,EAAE,QAO/B;IAED;;;;;;;OAOG;IACH,8CAEC;IAED;;;;;;OAMG;IACH,cAHW,qBAAqB,GACpB,OAAO,CAIlB;IAED;;;;;OAKG;IACH,QAFY,MAAM,CAIjB;IAED;;;;;;;;;;;OAWG;IACH,iCAEC;CACJ"}

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

@@ -1,6 +1,81 @@
-/**
- * Base interface for injecting external forces into the simulation
- */
-export class AbstractFluidEffector {
-
-}
+/**
+ * External force source applied to a {@link FluidField} once per simulation step.
+ *
+ * Subclasses override {@link apply} to mutate the field's velocity (and, optionally,
+ * scalar attributes). The simulator calls `apply(field, dt, world_to_grid)` for every
+ * effector at the start of each step, before diffusion / projection / advection.
+ *
+ * Effectors are configured in WORLD coordinates. The `world_to_grid` matrix supplied
+ * to {@link apply} converts a world-space point into the target field's grid space.
+ * The same effector instance can therefore be applied to any number of fluid fields
+ * across a single step — the system iterates fields and re-supplies the matching
+ * matrix each time.
+ *
+ * Effectors should be idempotent given the same `dt`, field state, and
+ * `world_to_grid` — they are pure functions of (their own configured state, field,
+ * dt, matrix). They must not retain references to field buffers between calls (the
+ * field's buffer references are stable, but caching them across resolution changes
+ * would break).
+ */
+export class AbstractFluidEffector {
+    /**
+     * @param {FluidField} field
+     * @param {number} dt seconds
+     * @param {Float32Array|number[]} world_to_grid  Column-major 4×4 affine sending
+     *                                               world-space points into the target
+     *                                               field's grid space.
+     */
+    apply(field, dt, world_to_grid) {
+        // Default no-op so a partially-built effector doesn't crash the sim. Subclasses
+        // must override to do useful work.
+    }
+
+    /**
+     * Optional hook called by {@link FluidSystem} once per step on each effector whose
+     * entity also has a `Transform` component. Default: no-op. Effectors that should
+     * follow an entity override this to pull world-space position / orientation /
+     * velocity off the transform.
+     *
+     * @param {Transform} transform
+     */
+    syncFromTransform(transform) {
+        // override as needed
+    }
+
+    /**
+     * Strict value equality. The base implementation collapses to reference equality
+     * — every concrete effector class overrides this to compare its own configured
+     * state.
+     * @param {AbstractFluidEffector} other
+     * @return {boolean}
+     */
+    equals(other) {
+        return other === this;
+    }
+
+    /**
+     * Fast hash. The base implementation returns a constant — concrete effectors
+     * override to hash their own state. Should stay cheap (a few `combine_hash` calls
+     * over scalar fields).
+     * @return {number}
+     */
+    hash() {
+        return 0;
+    }
+
+    /**
+     * Write the effector's world-space axis-aligned bounding box into `out`. Used by
+     * {@link FluidSystem} as a broad-phase culling primitive: if the effector's box
+     * doesn't intersect a fluid field's box, the effector is skipped for that field
+     * entirely.
+     *
+     * The base implementation writes infinite bounds — i.e. "could affect anything".
+     * Safe (never produces false negatives) but defeats the broad-phase. Concrete
+     * effectors override with tight bounds.
+     *
+     * @param {AABB3} out  destination, mutated in place
+     */
+    getBoundingBox(out) {
+        out.setInfiniteBounds();
+    }
+}

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

@@ -1,12 +1,25 @@
 /**
- * Affects fluid everywhere inside the field uniformly
+ * Adds the same acceleration to every fluid cell each step (gravity, ambient wind).
+ *
+ * `force` is in WORLD units per second squared. The `world_to_grid` matrix is applied
+ * (as a direction transform — translation ignored) inside {@link apply} to convert
+ * the force into the target field's grid-cell units before depositing. The same
+ * GlobalFluidEffector applied to fields with different `cell_size` therefore produces
+ * the same world-space acceleration on each — gravity stays gravity.
+ *
+ * Solid cells are left untouched — the projection step would zero them anyway, but
+ * skipping the write is slightly cheaper and keeps the solid mask authoritative for
+ * effectors as well as the solver.
  */
 export class GlobalFluidEffector extends AbstractFluidEffector {
     /**
-     * 3d force vector
-     * @type {number[]}
+     * Acceleration vector in WORLD units per second squared (e.g. `[0, -9.8, 0]` for
+     * Earth gravity in metres-and-seconds). Per-step deposit into the velocity field
+     * is `world_to_grid · force × dt`.
+     *
+     * @type {[number, number, number]}
      */
-    force: number[];
+    force: [number, number, number];
 }
 import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
 //# sourceMappingURL=GlobalFluidEffector.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GlobalFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/GlobalFluidEffector.js"],"names":[],"mappings":"AAEA;;GAEG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,EAAE,CAEA;CACrB;sCAXqC,4BAA4B"}
+{"version":3,"file":"GlobalFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/GlobalFluidEffector.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH;IAEI;;;;;;OAMG;IACH,OAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEhB;CA8ErB;sCAtGqC,4BAA4B"}

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

@@ -1,12 +1,105 @@
-import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
-
-/**
- * Affects fluid everywhere inside the field uniformly
- */
-export class GlobalFluidEffector extends AbstractFluidEffector{
-    /**
-     * 3d force vector
-     * @type {number[]}
-     */
-    force = [0, 0, 0];
-}
+import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
+
+/**
+ * Adds the same acceleration to every fluid cell each step (gravity, ambient wind).
+ *
+ * `force` is in WORLD units per second squared. The `world_to_grid` matrix is applied
+ * (as a direction transform — translation ignored) inside {@link apply} to convert
+ * the force into the target field's grid-cell units before depositing. The same
+ * GlobalFluidEffector applied to fields with different `cell_size` therefore produces
+ * the same world-space acceleration on each — gravity stays gravity.
+ *
+ * Solid cells are left untouched — the projection step would zero them anyway, but
+ * skipping the write is slightly cheaper and keeps the solid mask authoritative for
+ * effectors as well as the solver.
+ */
+export class GlobalFluidEffector extends AbstractFluidEffector {
+
+    /**
+     * Acceleration vector in WORLD units per second squared (e.g. `[0, -9.8, 0]` for
+     * Earth gravity in metres-and-seconds). Per-step deposit into the velocity field
+     * is `world_to_grid · force × dt`.
+     *
+     * @type {[number, number, number]}
+     */
+    force = [0, 0, 0];
+
+    /**
+     * @param {FluidField} field
+     * @param {number} dt
+     * @param {Float32Array|number[]} world_to_grid  Column-major 4×4 affine; only the
+     *                                               linear (upper-left 3×3) part is
+     *                                               used since force is a direction.
+     */
+    apply(field, dt, world_to_grid) {
+        const wfx = this.force[0];
+        const wfy = this.force[1];
+        const wfz = this.force[2];
+
+        if (wfx === 0 && wfy === 0 && wfz === 0) {
+            return;
+        }
+
+        // Direction-transform: apply the linear part of world_to_grid (translation in
+        // m[12..14] is for points, not directions). For the axis-aligned uniform-scale
+        // matrices built by FluidSystem this collapses to division by cell_size, so
+        // world m/s² becomes grid cells/s².
+        const m = world_to_grid;
+        const fx = (m[0] * wfx + m[4] * wfy + m[8]  * wfz) * dt;
+        const fy = (m[1] * wfx + m[5] * wfy + m[9]  * wfz) * dt;
+        const fz = (m[2] * wfx + m[6] * wfy + m[10] * wfz) * dt;
+
+        const vx = field.velocity_x;
+        const vy = field.velocity_y;
+        const vz = field.velocity_z;
+        const solid = field.solid;
+        const n = vx.length;
+
+        for (let i = 0; i < n; i++) {
+            if (solid[i] !== 0) {
+                continue;
+            }
+            vx[i] += fx;
+            vy[i] += fy;
+            vz[i] += fz;
+        }
+    }
+
+    /**
+     * @param {AbstractFluidEffector} other
+     * @return {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+        if (!(other instanceof GlobalFluidEffector)) {
+            return false;
+        }
+        return this.force[0] === other.force[0]
+            && this.force[1] === other.force[1]
+            && this.force[2] === other.force[2];
+    }
+
+    /**
+     * @return {number}
+     */
+    hash() {
+        return combine_hash(
+            computeHashFloat(this.force[0]),
+            computeHashFloat(this.force[1]),
+            computeHashFloat(this.force[2])
+        );
+    }
+
+    /**
+     * Position-free — applies to every cell of any field. Infinite bounds means the
+     * broad-phase will never cull this effector.
+     * @param {AABB3} out
+     */
+    getBoundingBox(out) {
+        out.setInfiniteBounds();
+    }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Splats a velocity impulse into a spherical region around a world-space position
+ * each step. Useful for fans, jets, point explosions, and unit-testing the projection
+ * step.
+ *
+ * Falloff is quadratic in the normalized distance — `(1 - r/R)²` — giving a smooth
+ * brush profile with zero gradient at the boundary, which projects more cleanly than a
+ * hard sphere.
+ *
+ * Everything is in WORLD units: {@link position} (point), {@link force} (direction
+ * vector), {@link radius} (scalar length). The `world_to_grid` matrix supplied to
+ * {@link apply} converts them at splat time. Works at any user-supplied radius
+ * including sub-cell: the effective kernel radius is internally floored at 1 grid
+ * cell so a small world-space radius still produces a roughly one-cell-wide splat
+ * instead of silently missing every cell.
+ *
+ * For moving sources that should leave a trail, see {@link WakeFluidEffector}.
+ */
+export class ImpulseFluidEffector extends AbstractFluidEffector {
+    /**
+     * Position in world coordinates.
+     * @type {[number, number, number]}
+     */
+    position: [number, number, number];
+    /**
+     * Acceleration vector in WORLD units per second squared. Per-step deposit is
+     * `world_to_grid · force × dt × falloff_weight`. Same world-units convention as
+     * {@link GlobalFluidEffector.force} — gravity stays gravity across fields with
+     * different `cell_size`.
+     * @type {[number, number, number]}
+     */
+    force: [number, number, number];
+    /**
+     * Influence radius in WORLD units. Cells past `radius` from the splat point are
+     * unaffected by the falloff. Internally floored to 1 grid cell so sub-cell
+     * world-radii still hit cells (the alternative is silently dropping the splat
+     * at fractional positions — see class docstring).
+     * @type {number}
+     */
+    radius: number;
+}
+import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
+//# sourceMappingURL=ImpulseFluidEffector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ImpulseFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/ImpulseFluidEffector.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAEI;;;OAGG;IACH,UAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEb;IAErB;;;;;;OAMG;IACH,OAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEhB;IAElB;;;;;;OAMG;IACH,QAFU,MAAM,CAEL;CAgKd;sCA9MqC,4BAA4B"}