@woosh/meep-engine 2.138.20 → 2.140.0

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

@@ -0,0 +1,238 @@
+import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+import { FluidField } from "../FluidField.js";
+
+/**
+ * ECS component representing a fluid volume — one {@link FluidField} plus its placement
+ * in world space.
+ *
+ * Behaviour (stepping the simulation, dispatching effectors, re-anchoring on Transform
+ * motion) lives on {@link FluidSystem}, not here. This component is pure data.
+ *
+ * World ↔ grid mapping is uniform and axis-aligned: cell `(0,0,0)`'s center sits at
+ * {@link origin}, and cells are spaced {@link cell_size} world-units apart along each
+ * axis. For non-uniform or oriented volumes, use multiple components.
+ *
+ * **Static placement**: leave the entity without a `Transform`. Set {@link origin}
+ * directly and the system never touches it.
+ *
+ * **Moving placement**: pair the entity with a `Transform`. The system re-anchors the
+ * grid on every fixedUpdate to `quantize(transform.position, cell_size) + offset`, and
+ * when the quantization changes shifts the field by the integer cell delta (carrying
+ * fluid data along with the grid so the fluid appears to stay put in world space) and
+ * patches the newly exposed edges with a Neumann zero-gradient extrapolation. {@link
+ * origin} becomes system-managed in this case.
+ *
+ * NOTE on layout: sibling physics ECS code lives under `engine/ecs/*` (see
+ * `engine/ecs/ik/InverseKinematicsSystem.js`). This component is placed inside the
+ * fluid package because edits to the ECS folder were out-of-scope when it was first
+ * written. Moving it under `engine/ecs/fluid/` later is a pure relocation.
+ */
+export class FluidComponent {
+
+    /**
+     * @type {FluidField}
+     */
+    field = new FluidField();
+
+    /**
+     * World position of grid cell `(0,0,0)`'s center. For static placement (no
+     * `Transform` on the entity) the user sets this directly. For moving placement
+     * (with `Transform`) {@link FluidSystem} owns it — every fixedUpdate it computes
+     * the desired origin from the transform and either snaps on first sync or shifts
+     * the field by the integer cell delta.
+     * @type {[number, number, number]}
+     */
+    origin = [0, 0, 0];
+
+    /**
+     * World-space offset added to the quantized `Transform.position` when computing
+     * the grid centre. Use to place the grid asymmetrically relative to the entity —
+     * e.g. `[-2, 0, 0]` puts the centre 2 world units behind the entity.
+     *
+     * Only consulted when a `Transform` is present (otherwise `origin` is fully
+     * user-controlled).
+     * @type {[number, number, number]}
+     */
+    offset = [0, 0, 0];
+
+    /**
+     * Uniform world-space spacing between adjacent cell centers.
+     * @type {number}
+     */
+    cell_size = 1;
+
+    /**
+     * Half-cell extra margin (in cells) the Transform must cross before the field
+     * re-quantizes to the next cell. Without it, a Transform jittering right on the
+     * boundary between two cells would re-shift every frame, repeatedly clearing the
+     * solid mask and patching velocity edges — visible as flicker in the fluid and
+     * thrashing in any solid-voxelizer downstream of the shift.
+     *
+     * Mechanism: the system keeps the current quantized cell `q` and only re-quantizes
+     * when `|transform.position / cell_size - q| > 0.5 + hysteresis`. Crossing the
+     * threshold snaps to the new nearest cell — not the threshold position — so motion
+     * past the deadband still produces a single discrete shift.
+     *
+     * Range `[0, 0.5)`. `0` disables (snap on any boundary crossing). Default `0.1`
+     * gives a ~10%-of-a-cell deadband on each side, killing jitter while staying
+     * imperceptible at typical cell sizes.
+     *
+     * Only consulted when a `Transform` is present.
+     * @type {number}
+     */
+    hysteresis = 0.1;
+
+    /**
+     * If false, {@link FluidSystem} skips this volume's step. Use to pause fluid for
+     * culled or off-screen volumes.
+     * @type {boolean}
+     */
+    enabled = true;
+
+    /**
+     * Set by {@link FluidSystem} on the first reanchor — distinguishes "snap origin
+     * to the desired position without shifting" (first sync) from "shift the field
+     * by the integer cell delta" (subsequent syncs). User code should not touch this.
+     * @type {boolean}
+     */
+    anchored = false;
+
+    /**
+     * Convert a world-space point to fractional grid coordinates.
+     * @param {Float32Array|number[]} out  length-3 destination
+     * @param {number} wx
+     * @param {number} wy
+     * @param {number} wz
+     * @return {Float32Array|number[]} `out`, for chaining.
+     */
+    worldToGrid(out, wx, wy, wz) {
+        const inv = 1 / this.cell_size;
+        out[0] = (wx - this.origin[0]) * inv;
+        out[1] = (wy - this.origin[1]) * inv;
+        out[2] = (wz - this.origin[2]) * inv;
+        return out;
+    }
+
+    /**
+     * Convert fractional grid coordinates to a world-space point.
+     * @param {Float32Array|number[]} out  length-3 destination
+     * @param {number} gx
+     * @param {number} gy
+     * @param {number} gz
+     * @return {Float32Array|number[]} `out`, for chaining.
+     */
+    gridToWorld(out, gx, gy, gz) {
+        out[0] = this.origin[0] + gx * this.cell_size;
+        out[1] = this.origin[1] + gy * this.cell_size;
+        out[2] = this.origin[2] + gz * this.cell_size;
+        return out;
+    }
+
+    /**
+     * Sample velocity at a world-space point. The velocity values stored in the field
+     * are in "grid cells per second"; this method does NOT rescale them, on the
+     * assumption that callers (vegetation sway, dust drift) interpret the field as a
+     * direction × magnitude wind and want consistent strength regardless of the
+     * underlying cell size.
+     *
+     * If you need world-units-per-second velocity, multiply the result by `cell_size`.
+     *
+     * @param {Float32Array|number[]} out  length-3 destination
+     * @param {number} wx
+     * @param {number} wy
+     * @param {number} wz
+     * @return {Float32Array|number[]} `out`, for chaining.
+     */
+    sampleVelocityAtWorld(out, wx, wy, wz) {
+        const inv = 1 / this.cell_size;
+        const gx = (wx - this.origin[0]) * inv;
+        const gy = (wy - this.origin[1]) * inv;
+        const gz = (wz - this.origin[2]) * inv;
+        return this.field.sampleVelocity(out, gx, gy, gz);
+    }
+
+    /**
+     * Sample a passive scalar at a world-space point.
+     * @param {string} name
+     * @param {number} wx
+     * @param {number} wy
+     * @param {number} wz
+     * @return {number}
+     */
+    sampleScalarAtWorld(name, wx, wy, wz) {
+        const inv = 1 / this.cell_size;
+        const gx = (wx - this.origin[0]) * inv;
+        const gy = (wy - this.origin[1]) * inv;
+        const gz = (wz - this.origin[2]) * inv;
+        return this.field.sampleScalar(name, gx, gy, gz);
+    }
+
+    /**
+     * @param {FluidComponent} other
+     * @return {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+        if (!(other instanceof FluidComponent)) {
+            return false;
+        }
+        return this.enabled === other.enabled
+            && this.anchored === other.anchored
+            && this.cell_size === other.cell_size
+            && this.hysteresis === other.hysteresis
+            && this.origin[0] === other.origin[0]
+            && this.origin[1] === other.origin[1]
+            && this.origin[2] === other.origin[2]
+            && this.offset[0] === other.offset[0]
+            && this.offset[1] === other.offset[1]
+            && this.offset[2] === other.offset[2]
+            && this.field.equals(other.field);
+    }
+
+    /**
+     * @return {number}
+     */
+    hash() {
+        return combine_hash(
+            this.enabled ? 1 : 0,
+            this.anchored ? 1 : 0,
+            computeHashFloat(this.cell_size),
+            computeHashFloat(this.hysteresis),
+            computeHashFloat(this.origin[0]),
+            computeHashFloat(this.origin[1]),
+            computeHashFloat(this.origin[2]),
+            computeHashFloat(this.offset[0]),
+            computeHashFloat(this.offset[1]),
+            computeHashFloat(this.offset[2]),
+            this.field.hash()
+        );
+    }
+
+    /**
+     * Write the field's world-space axis-aligned bounding box into `out`. Used by
+     * {@link FluidSystem} as a broad-phase target when filtering effectors. The box
+     * spans cell `(0, 0, 0)` (centred at `origin`) to cell `(res_x-1, res_y-1, res_z-1)`
+     * plus a `cell_size` margin on the far side, so a point exactly on the field's
+     * boundary cells lies inside the AABB.
+     *
+     * @param {AABB3} out
+     */
+    getBoundingBox(out) {
+        const res = this.field.getResolution();
+        const cs = this.cell_size;
+        const ox = this.origin[0];
+        const oy = this.origin[1];
+        const oz = this.origin[2];
+        out.setBounds(
+            ox, oy, oz,
+            ox + res[0] * cs,
+            oy + res[1] * cs,
+            oz + res[2] * cs
+        );
+    }
+}
+
+FluidComponent.prototype.isFluidComponent = true;

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

@@ -0,0 +1,45 @@
+/**
+ * ECS component holding effectors that contribute to fluid fields each simulation step.
+ *
+ * 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.
+ *
+ * Pair this component with a `Transform` 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 Transform before stepping the simulator.
+ */
+export class FluidEffectorsComponent {
+    /**
+     * Effectors applied each simulation step.
+     * @type {AbstractFluidEffector[]}
+     */
+    effectors: AbstractFluidEffector[];
+    /**
+     * Append an effector. The same instance may only be added once; pushing duplicates
+     * causes the effector to fire twice per step.
+     * @param {AbstractFluidEffector} effector
+     */
+    addEffector(effector: AbstractFluidEffector): void;
+    /**
+     * Remove an effector by reference. No-op if not present.
+     * @param {AbstractFluidEffector} effector
+     */
+    removeEffector(effector: AbstractFluidEffector): void;
+    /**
+     * Position-dependent equality: same number of effectors, each pair at the same
+     * index `.equals` each other. Re-ordering counts as a change.
+     * @param {FluidEffectorsComponent} other
+     * @return {boolean}
+     */
+    equals(other: FluidEffectorsComponent): boolean;
+    /**
+     * Order-dependent hash, FNV-like fold over child effector hashes.
+     * @return {number}
+     */
+    hash(): number;
+    isFluidEffectorsComponent: boolean;
+}
+//# sourceMappingURL=FluidEffectorsComponent.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,89 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * ECS component holding effectors that contribute to fluid fields each simulation step.
+ *
+ * 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.
+ *
+ * Pair this component with a `Transform` 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 Transform before stepping the simulator.
+ */
+export class FluidEffectorsComponent {
+
+    /**
+     * Effectors applied each simulation step.
+     * @type {AbstractFluidEffector[]}
+     */
+    effectors = [];
+
+    /**
+     * Append an effector. The same instance may only be added once; pushing duplicates
+     * causes the effector to fire twice per step.
+     * @param {AbstractFluidEffector} effector
+     */
+    addEffector(effector) {
+        assert.defined(effector, "effector");
+        assert.notNull(effector, "effector");
+        this.effectors.push(effector);
+    }
+
+    /**
+     * Remove an effector by reference. No-op if not present.
+     * @param {AbstractFluidEffector} effector
+     */
+    removeEffector(effector) {
+        const i = this.effectors.indexOf(effector);
+        if (i !== -1) {
+            this.effectors.splice(i, 1);
+        }
+    }
+
+    /**
+     * Position-dependent equality: same number of effectors, each pair at the same
+     * index `.equals` each other. Re-ordering counts as a change.
+     * @param {FluidEffectorsComponent} other
+     * @return {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+        if (!(other instanceof FluidEffectorsComponent)) {
+            return false;
+        }
+        const a = this.effectors;
+        const b = other.effectors;
+        const n = a.length;
+        if (n !== b.length) {
+            return false;
+        }
+        for (let i = 0; i < n; i++) {
+            if (!a[i].equals(b[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /**
+     * Order-dependent hash, FNV-like fold over child effector hashes.
+     * @return {number}
+     */
+    hash() {
+        const a = this.effectors;
+        const n = a.length;
+        let h = n;
+        for (let i = 0; i < n; i++) {
+            h = ((h << 5) - h) + a[i].hash();
+            h |= 0;
+        }
+        return h;
+    }
+}
+
+FluidEffectorsComponent.prototype.isFluidEffectorsComponent = true;

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

@@ -0,0 +1,107 @@
+/**
+ * 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<any, any, any, any, any> {
+    /**
+     * Visitor for the (effectors, transform) traversal — calls syncFromTransform on
+     * every effector in the component.
+     * @param {FluidEffectorsComponent} effectors_component
+     * @param {Transform} transform
+     */
+    static "__#135@#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.
+     *
+     * 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 "__#135@#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:
+     *
+     *     [ 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 "__#135@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
+    constructor();
+    dependencies: (typeof 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: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidEffectorsComponent>)[];
+    /**
+     * 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: FluidSimulator;
+    #private;
+}
+import { System } from "../../../ecs/System.js";
+import { FluidComponent } from "./FluidComponent.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
+import { FluidSimulator } from "../FluidSimulator.js";
+//# sourceMappingURL=FluidSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FluidSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IA+GI;;;;;OAKG;IACH,oEAHW,uBAAuB,aACvB,SAAS,QAOnB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,2CAHW,cAAc,aACd,SAAS,QA4DnB;IAED;;;;;;;;;;;;;OAaG;IACH,0CAHW,YAAY,aACZ,cAAc,QAexB;IAlRe,cAAmB;IA2CnC,wCAAgC;IAEhC;;;;;;;;OAQG;IACH,sLAME;IAEF;;;;;OAKG;IACH,WAFU,cAAc,CAES;;CA+MpC;uBAjRsB,wBAAwB;+BAEhB,qBAAqB;0BAD1B,qCAAqC;4CAFnB,uDAAuD;wCAI3D,8BAA8B;+BACvC,sBAAsB"}