@woosh/meep-engine 2.157.0 → 2.158.0

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

@@ -0,0 +1,348 @@
+import { PosedShape3D } from "../../../../core/geom/3d/shape/PosedShape3D.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 { Collider } from "../../ecs/Collider.js";
+import { RigidBody } from "../../ecs/RigidBody.js";
+import { FluidComponent } from "./FluidComponent.js";
+import { FluidObstacle } from "./FluidObstacle.js";
+
+/**
+ * ECS system that voxelizes collider geometry into fluid solid masks and
+ * stamps rigid-body velocities onto the walls as moving-wall boundary
+ * conditions.
+ *
+ * Every fixed update, each entity carrying ({@link FluidObstacle},
+ * {@link Collider}, {@link RigidBody}, {@link Transform}) — the same tuple
+ * {@link PhysicsSystem} simulates, plus the marker — is swept against every
+ * {@link FluidComponent}: the collider's shape — posed rigidly at the
+ * transform's position/rotation via {@link PosedShape3D} — is sampled at the
+ * centre of every fluid cell inside its world AABB, and cells whose signed
+ * distance is `<= obstacle.inflation` become solid. The fluid then treats
+ * those cells exactly like hand-authored walls: faces pinned, pressure
+ * Neumann, traces clipped.
+ *
+ * **Ownership contract**: while at least one obstacle exists, this system
+ * OWNS the solid mask of every fluid field — masks are cleared and rebuilt
+ * from scratch each tick, so moving obstacles leave no stale walls behind.
+ * Hand-written `setSolidAt` state will be wiped; mix the two styles only by
+ * expressing the static geometry as obstacle entities too (a `BoxShape3D`
+ * collider is cheaper to author than a splat loop anyway). With NO obstacles
+ * present the system leaves every mask untouched.
+ *
+ * **Moving walls — the wall-velocity specification**:
+ *
+ *   - The velocity source is `RigidBody.linearVelocity` (world m/s) — the
+ *     SAME value the contact solver resolves against, so air and contacts
+ *     always agree on how fast a wall moves. It is stamped onto every face
+ *     of every cell the obstacle voxelized (converted to grid units per
+ *     field); the projection's divergence reads pinned faces at face value,
+ *     so a moving collider genuinely pushes and drags the air around it.
+ *   - Pose is still read from `Transform`; velocity is NOT derived from
+ *     pose deltas. A teleported body (spawn snap, network correction)
+ *     relocates its walls but stamps no velocity — no one-tick air blast.
+ *     This mirrors the engine's own contact-solver rule: see
+ *     {@link BodyKind}.KinematicPosition, deferred for exactly this reason.
+ *     Consequently pose-animated colliders read as stationary walls that
+ *     teleport, for air just as for contacts — drive movers through
+ *     `BodyKind.KinematicVelocity` (or Dynamic) to displace air.
+ *   - `BodyKind.Static` bodies have zero velocity and stamp nothing.
+ *     Sleeping bodies stamp nothing either — the solver zeroes velocities
+ *     on sleep.
+ *   - A body that stops stamps ONE extra pass of zeros
+ *     (`FluidObstacle._was_moving`): pinned faces preserve their values
+ *     across mask recomputes by design, so without it a stale moving BC
+ *     would drive phantom inflow forever.
+ *   - A retreating wall leaves its velocity behind on unpinned faces as the
+ *     wake seed for the fluid that takes its place.
+ *   - Rotation-induced surface velocity (ω × r from
+ *     `RigidBody.angularVelocity`) is not modelled yet — fast spinners read
+ *     as translating walls only (follow-up in REVIEW_02_PLAN.md).
+ *
+ * **Ordering**: register AFTER {@link PhysicsSystem} (so this tick's solved
+ * velocities and integrated poses are read) and BEFORE {@link FluidSystem}
+ * (so the simulation step sees this tick's walls and wall velocities).
+ * Engine systems run in registration order.
+ *
+ * Cost: clearing is O(cells) per field; voxelization is one
+ * `signed_distance_at_point` per cell inside each obstacle's AABB ∩ field.
+ * Static scenes pay the same as moving ones — change detection is a
+ * follow-up (REVIEW_02_PLAN.md) if profiling ever points here.
+ */
+export class FluidObstacleSystem extends System {
+
+    dependencies = [FluidObstacle];
+
+    components_used = [
+        ResourceAccessSpecification.from(FluidObstacle, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(RigidBody, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Transform, ResourceAccessKind.Read),
+        // Solid masks are rewritten each tick.
+        ResourceAccessSpecification.from(FluidComponent, ResourceAccessKind.Read | ResourceAccessKind.Write),
+    ];
+
+    /**
+     * Reusable rigid-pose adapter, rebound per obstacle per tick.
+     * @type {PosedShape3D}
+     */
+    #posed = new PosedShape3D();
+
+    /**
+     * World AABB scratch for the current posed shape (x0,y0,z0,x1,y1,z1).
+     * @type {Float64Array}
+     */
+    #aabb = new Float64Array(6);
+
+    /**
+     * World-space point scratch for per-cell SDF queries.
+     * @type {Float64Array}
+     */
+    #point = new Float64Array(3);
+
+    /**
+     * @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;
+        }
+
+        // With no obstacles the system must not touch any mask — fields with
+        // hand-authored solids keep them.
+        let obstacle_count = 0;
+        ecd.traverseEntities([FluidObstacle, Collider, RigidBody, Transform], function () {
+            obstacle_count++;
+        });
+        if (obstacle_count === 0) {
+            return;
+        }
+
+        // Clear every field's mask, then accumulate every obstacle into every
+        // overlapping field. Solids are world-anchored; rebuilding from
+        // scratch each tick is what keeps moving obstacles honest.
+        ecd.traverseComponents(FluidComponent, FluidObstacleSystem.#clear_field);
+
+        const posed = this.#posed;
+        const aabb = this.#aabb;
+        const point = this.#point;
+
+        ecd.traverseEntities([FluidObstacle, Collider, RigidBody, Transform], function (obstacle, collider, body, transform) {
+            posed.setup(collider.shape, transform.position, transform.rotation);
+            posed.compute_bounding_box(aabb);
+
+            ecd.traverseComponents(FluidComponent, function (fluid) {
+                FluidObstacleSystem.#voxelize(fluid, posed, aabb, obstacle.inflation, point);
+            });
+        });
+
+        // Refresh each field's derived masks NOW so the unpinned→pinned
+        // transitions are consumed here (zeroing those faces to the static
+        // default). The moving-wall velocities written below then survive the
+        // simulator's own per-step refresh — already-pinned faces keep their
+        // values (see v3_mac_compute_face_solid).
+        ecd.traverseComponents(FluidComponent, FluidObstacleSystem.#refresh_masks);
+
+        // Second pass: moving bodies stamp their velocity onto the faces of
+        // the cells they voxelized — the MAC moving-wall boundary condition.
+        // The divergence reads these values, so the wall genuinely pushes
+        // (and pulls) the surrounding fluid. The source is the solver's own
+        // linearVelocity, NOT a pose delta — teleports stamp nothing.
+        ecd.traverseEntities([FluidObstacle, Collider, RigidBody, Transform], function (obstacle, collider, body, transform) {
+            const lv = body.linearVelocity;
+            const vx = lv.x;
+            const vy = lv.y;
+            const vz = lv.z;
+
+            const moving = vx !== 0 || vy !== 0 || vz !== 0;
+
+            // Stamp while moving, plus ONE extra pass on the tick the body
+            // stops (or falls asleep — the solver zeroes velocities on
+            // sleep): pinned faces preserve their values across mask
+            // recomputes, so a stopped wall must overwrite its stale moving
+            // BC with zeros or the projection keeps seeing phantom inflow.
+            // Bodies that never move never pay for this pass.
+            if (moving || obstacle._was_moving) {
+                posed.setup(collider.shape, transform.position, transform.rotation);
+                posed.compute_bounding_box(aabb);
+                ecd.traverseComponents(FluidComponent, function (fluid) {
+                    FluidObstacleSystem.#stamp_wall_velocity(
+                        fluid, posed, aabb, obstacle.inflation, point, vx, vy, vz);
+                });
+            }
+
+            obstacle._was_moving = moving;
+        });
+    }
+
+    /**
+     * @param {FluidComponent} fluid
+     */
+    static #refresh_masks(fluid) {
+        fluid.field.recomputeSolidNeighbourMask();
+    }
+
+    /**
+     * @param {FluidComponent} fluid
+     */
+    static #clear_field(fluid) {
+        const solid = fluid.field.solid;
+        if (solid !== null) {
+            solid.fill(0);
+        }
+    }
+
+    /**
+     * 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
+     * (grown by `inflation`), so far-away obstacles cost nothing.
+     *
+     * @param {FluidComponent} fluid
+     * @param {PosedShape3D} posed
+     * @param {Float64Array} aabb      world AABB of the posed shape
+     * @param {number} inflation       world-units SDF threshold
+     * @param {Float64Array} point     length-3 scratch
+     */
+    static #voxelize(fluid, posed, aabb, inflation, point) {
+        const field = fluid.field;
+        const solid = field.solid;
+        if (solid === null) {
+            return; // field not built yet
+        }
+
+        const res = field.getResolution();
+        const cs = fluid.cell_size;
+        const inv_cs = 1 / cs;
+        const origin = fluid.origin;
+
+        // Index range of cell centres inside the inflated AABB, clamped.
+        let x_min = Math.ceil((aabb[0] - inflation - origin[0]) * inv_cs);
+        let y_min = Math.ceil((aabb[1] - inflation - origin[1]) * inv_cs);
+        let z_min = Math.ceil((aabb[2] - inflation - origin[2]) * inv_cs);
+        let x_max = Math.floor((aabb[3] + inflation - origin[0]) * inv_cs);
+        let y_max = Math.floor((aabb[4] + inflation - origin[1]) * inv_cs);
+        let z_max = Math.floor((aabb[5] + inflation - origin[2]) * inv_cs);
+
+        if (x_min < 0) x_min = 0;
+        if (y_min < 0) y_min = 0;
+        if (z_min < 0) z_min = 0;
+        if (x_max >= res[0]) x_max = res[0] - 1;
+        if (y_max >= res[1]) y_max = res[1] - 1;
+        if (z_max >= res[2]) z_max = res[2] - 1;
+
+        if (x_min > x_max || y_min > y_max || z_min > z_max) {
+            return; // no overlap with this field
+        }
+
+        const slice = res[0] * res[1];
+
+        for (let z = z_min; z <= z_max; z++) {
+            const z_off = z * slice;
+            point[2] = origin[2] + z * cs;
+            for (let y = y_min; y <= y_max; y++) {
+                const y_off = z_off + y * res[0];
+                point[1] = origin[1] + y * cs;
+                for (let x = x_min; x <= x_max; x++) {
+                    point[0] = origin[0] + x * cs;
+                    if (posed.signed_distance_at_point(point) <= inflation) {
+                        solid[y_off + x] = 1;
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Write the obstacle's translation velocity onto every face of every cell
+     * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
+     * refresh, so the values stick (already-pinned faces keep their stored
+     * velocity through subsequent recomputes).
+     *
+     * Velocity is converted to grid units (cells/second) per field. Where
+     * obstacles overlap, the later-visited one wins on shared faces — both
+     * claims are walls, the disagreement is sub-cell.
+     *
+     * @param {FluidComponent} fluid
+     * @param {PosedShape3D} posed
+     * @param {Float64Array} aabb
+     * @param {number} inflation
+     * @param {Float64Array} point
+     * @param {number} wvx  world-units-per-second obstacle velocity
+     * @param {number} wvy
+     * @param {number} wvz
+     */
+    static #stamp_wall_velocity(fluid, posed, aabb, inflation, point, wvx, wvy, wvz) {
+        const field = fluid.field;
+        const solid = field.solid;
+        if (solid === null) {
+            return;
+        }
+
+        const res = field.getResolution();
+        const cs = fluid.cell_size;
+        const inv_cs = 1 / cs;
+        const origin = fluid.origin;
+
+        // Grid-units wall velocity (cells per second).
+        const gvx = wvx * inv_cs;
+        const gvy = wvy * inv_cs;
+        const gvz = wvz * inv_cs;
+
+        let x_min = Math.ceil((aabb[0] - inflation - origin[0]) * inv_cs);
+        let y_min = Math.ceil((aabb[1] - inflation - origin[1]) * inv_cs);
+        let z_min = Math.ceil((aabb[2] - inflation - origin[2]) * inv_cs);
+        let x_max = Math.floor((aabb[3] + inflation - origin[0]) * inv_cs);
+        let y_max = Math.floor((aabb[4] + inflation - origin[1]) * inv_cs);
+        let z_max = Math.floor((aabb[5] + inflation - origin[2]) * inv_cs);
+
+        if (x_min < 0) x_min = 0;
+        if (y_min < 0) y_min = 0;
+        if (z_min < 0) z_min = 0;
+        if (x_max >= res[0]) x_max = res[0] - 1;
+        if (y_max >= res[1]) y_max = res[1] - 1;
+        if (z_max >= res[2]) z_max = res[2] - 1;
+
+        if (x_min > x_max || y_min > y_max || z_min > z_max) {
+            return;
+        }
+
+        const rx = res[0];
+        const ry = res[1];
+        const slice = rx * ry;
+        const sx = rx + 1;
+        const vel_u = field.velocity_x;
+        const vel_v = field.velocity_y;
+        const vel_w = field.velocity_z;
+
+        for (let z = z_min; z <= z_max; z++) {
+            point[2] = origin[2] + z * cs;
+            for (let y = y_min; y <= y_max; y++) {
+                point[1] = origin[1] + y * cs;
+                for (let x = x_min; x <= x_max; x++) {
+                    point[0] = origin[0] + x * cs;
+                    // Re-test ownership: only this obstacle's own cells get
+                    // its velocity (the solid mask may contain other walls).
+                    if (posed.signed_distance_at_point(point) > inflation) {
+                        continue;
+                    }
+                    // All six faces of a solid cell are pinned by definition.
+                    const u = z * sx * ry + y * sx + x;
+                    vel_u[u] = gvx;
+                    vel_u[u + 1] = gvx;
+                    const v = z * rx * (ry + 1) + y * rx + x;
+                    vel_v[v] = gvy;
+                    vel_v[v + rx] = gvy;
+                    const w = z * slice + y * rx + x;
+                    vel_w[w] = gvz;
+                    vel_w[w + slice] = gvz;
+                }
+            }
+        }
+    }
+}

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

@@ -38,7 +38,7 @@ export class FluidSystem extends System<any, any, any, any, any> {
      * @param {FluidEffectorsComponent} effectors_component
      * @param {Transform} transform
      */
-    static "__#141@#sync_effectors_from_transform"(effectors_component: FluidEffectorsComponent, transform: Transform): void;
+    static "__#142@#sync_effectors_from_transform"(effectors_component: FluidEffectorsComponent, transform: Transform): void;
     /**
      * Visitor for the (FluidComponent, Transform) traversal — keeps the field's
      * grid origin locked to a cell-aligned position near the transform.
@@ -61,7 +61,7 @@ export class FluidSystem extends System<any, any, any, any, any> {
      * @param {FluidComponent} component
      * @param {Transform} transform
      */
-    static "__#141@#reanchor_field"(component: FluidComponent, transform: Transform): void;
+    static "__#142@#reanchor_field"(component: FluidComponent, transform: Transform): void;
     /**
      * Write the world-to-grid affine for a FluidComponent into `out`. Axis-aligned,
      * uniform-scale, so the matrix is sparse:
@@ -76,7 +76,7 @@ export class FluidSystem extends System<any, any, any, any, any> {
      * @param {Float32Array} out  length-16
      * @param {FluidComponent} component
      */
-    static "__#141@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
+    static "__#142@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
     constructor();
     dependencies: (typeof FluidComponent)[];
     /**

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

@@ -1,25 +1,75 @@
 /**
- * Adds the same acceleration to every fluid cell each step (gravity, ambient wind).
+ * The global atmosphere: every fluid face in every field integrates the same
+ * linear flow model each step,
  *
- * `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.
+ *     dv/dt = force + drag · (wind − v)
  *
- * 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.
+ * One effector covers the whole family of "push everything" behaviours —
+ * pick the regime by which fields you set:
+ *
+ *   - **`force` alone** — constant body force (gravity, buoyancy). NOTE:
+ *     incompressible projection cannot oppose a uniform force (a uniform
+ *     field is divergence-free), so without `drag`, a sealed container, or
+ *     {@link FluidSimulator#velocity_damping}, the velocity grows without
+ *     bound. This is the legacy GlobalFluidEffector behaviour.
+ *
+ *   - **`wind` + `drag`** — prevailing wind: the air relaxes toward the wind
+ *     velocity at `drag` per second; gusts, wakes and splats decay back to
+ *     the ambient flow. The fixed point is exactly `wind`.
+ *
+ *   - **`force` + `drag` (+ `wind`)** — bounded forcing with a terminal
+ *     velocity of `wind + force / drag`: falling smoke, drifting ash, rain
+ *     sheets in a breeze.
+ *
+ *   - **`drag` alone** — pure exponential calming toward still air. (The
+ *     scene-content twin of {@link FluidSimulator#velocity_damping}, which
+ *     is the solver-level stability knob that exists even when no effectors
+ *     are wired.)
+ *
+ * `wind` only enters through the drag term — with `drag = 0` it is inert by
+ * construction (the model degenerates to dv/dt = force).
+ *
+ * The step uses the EXACT solution of the linear ODE, not an Euler step:
+ *
+ *     v ← v∞ + (v − v∞) · e^(−drag·dt),   v∞ = wind + force / drag
+ *
+ * (and plain `v += force·dt`, also exact, when `drag = 0`). Exactness makes
+ * the effector frame-rate independent — two half-steps land exactly where
+ * one full step does, including with both terms active.
+ *
+ * All quantities are WORLD-space: `force` in units/s², `wind` in units/s,
+ * `drag` in 1/s. The `world_to_grid` matrix's linear part converts the two
+ * vectors at apply time, so one instance produces the same world-space
+ * atmosphere on fields of any `cell_size` — gravity stays gravity.
+ *
+ * Pinned faces (either adjacent cell solid) are skipped — the projection
+ * owns those as boundary conditions, and skipping 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`.
+     * Body-force acceleration in WORLD units per second squared (e.g.
+     * `[0, -9.8, 0]` for Earth gravity in metres-and-seconds).
      *
      * @type {[number, number, number]}
      */
     force: [number, number, number];
+    /**
+     * Ambient wind velocity in WORLD units per second — the velocity the air
+     * relaxes toward. Only effective when {@link drag} is non-zero.
+     *
+     * @type {[number, number, number]}
+     */
+    wind: [number, number, number];
+    /**
+     * Relaxation rate toward the ambient flow, per second. Higher = stiffer
+     * atmosphere that re-asserts itself quickly after disturbances; lower =
+     * gusts and wakes linger. A disturbance decays to ~37% in `1/drag`
+     * seconds. `0` disables the relaxation term entirely.
+     *
+     * @type {number}
+     */
+    drag: 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":"AAIA;;;;;;;;;;;;GAYG;AACH;IAEI;;;;;;OAMG;IACH,OAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEhB;CA8ErB;sCAtGqC,4BAA4B"}
+{"version":3,"file":"GlobalFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/GlobalFluidEffector.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IAEI;;;;;OAKG;IACH,OAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEhB;IAElB;;;;;OAKG;IACH,MAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEjB;IAEjB;;;;;;;OAOG;IACH,MAFU,MAAM,CAEP;CA2HZ;sCAvMqC,4BAA4B"}