@woosh/meep-engine 3.0.2 → 3.2.0

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

@@ -1,239 +1,239 @@
-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, sloshing every buffer
-     * back and forth and re-extrapolating the exposed edges each time — 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;
+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, sloshing every buffer
+     * back and forth and re-extrapolating the exposed edges each time — 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.js

@@ -1,89 +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;
+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;