@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -0,0 +1,255 @@
+import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+import { NODE3D_SCENE_ID } from "../../../../shade/renderer/scene/NODE3D_STRUCT.js";
+import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
+import { fluid_effector_record_create } from "./record/fluid_effector_record_create.js";
+import { FluidEffectorRecordKind } from "./record/FluidEffectorRecordKind.js";
+import { fluid_record_apply } from "./record/fluid_record_apply.js";
+
+/**
+ * The record {@link VortexFluidEffector#apply} writes itself into, at the world root.
+ * @type {FluidEffectorRecord}
+ */
+const scratch_record = fluid_effector_record_create();
+
+/**
+ * Turns the air about an axis, along a segment of it: a whirlwind, a dust devil, the swirl behind a
+ * rotor. Each step adds `vortex_swirl` over the step,
+ *
+ *     Δv(x) = strength · dt · (27/4) · (â × r⊥)/R · (1 − d/R)²,   0 from d = R on
+ *
+ * where the segment runs from {@link position} along the unit {@link axis} for {@link length}, `r⊥` is
+ * `x` less the point on the segment closest to it, `d = ‖r⊥‖`, and `R` is {@link radius}. Beside the
+ * segment the push is tangential and right-handed about the axis: zero on the axis, `strength·dt` at
+ * `R/3`, zero at `R` with zero slope. Past an end the swirl fades over a cap of radius `R`, so a
+ * `length` of 0 is a ball of swirl about the axis line through `position`. Finite everywhere.
+ *
+ * Everything is in WORLD units, and `apply` evaluates the effector's GPU record on the field
+ * ({@link fluid_record_apply}), so the CPU fluid and the GPU fluid deposit the same swirl. On a
+ * field whose cells are coarser than half the radius, the swirl is evaluated two cells wide with its
+ * angular momentum kept (the record's kernel floor).
+ *
+ * Synced to a `Transform64`, the segment starts at the entity's position and runs along its local +Y.
+ */
+export class VortexFluidEffector extends AbstractFluidEffector {
+
+    /**
+     * Where the segment starts, on the axis. World coordinates.
+     * @type {[number, number, number]}
+     */
+    position = [0, 0, 0];
+
+    /**
+     * The axis the swirl turns about, right-handed, and the direction the segment runs in. Unit
+     * length, world.
+     * @type {[number, number, number]}
+     */
+    axis = [0, 1, 0];
+
+    /**
+     * How far the segment runs along {@link axis} from {@link position}, metres, ≥ 0. 0 is a point
+     * vortex.
+     * @type {number}
+     */
+    length = 0;
+
+    /**
+     * The swirl's reach from the segment, metres. 0 disables the effector.
+     * @type {number}
+     */
+    radius = 1;
+
+    /**
+     * The swirl's peak, at `radius / 3` beside the segment: m/s added per second, m/s². Negative
+     * turns it the other way.
+     * @type {number}
+     */
+    strength = 1;
+
+    /**
+     * @param {FluidField} field
+     * @param {number} dt
+     * @param {Float32Array|number[]} world_to_grid  Column-major 4×4 affine from world
+     *                                               to the target field's grid space.
+     */
+    apply(field, dt, world_to_grid) {
+        if (dt <= 0) {
+            return;
+        }
+
+        const record = scratch_record;
+
+        record.node = NODE3D_SCENE_ID;
+        this.write_gpu_record(record);
+
+        fluid_record_apply(field, dt, world_to_grid, record);
+    }
+
+    /**
+     * The segment starts at the entity's position and runs along its local +Y.
+     *
+     * @param {Transform64} transform
+     */
+    syncFromTransform(transform) {
+        this.position[0] = transform.translation_x;
+        this.position[1] = transform.translation_y;
+        this.position[2] = transform.translation_z;
+
+        const x = transform.rotation_x;
+        const y = transform.rotation_y;
+        const z = transform.rotation_z;
+        const w = transform.rotation_w;
+
+        // the rotation applied to +Y
+        this.axis[0] = 2 * (x * y - w * z);
+        this.axis[1] = 1 - 2 * (x * x + z * z);
+        this.axis[2] = 2 * (y * z + w * x);
+    }
+
+    /**
+     * A `SWIRL`: the segment's start (the node's origin, or `position` at node 0), the axis (the
+     * node's local +Y, or `axis` at node 0), `length`, `radius` and `strength`.
+     *
+     * @param {FluidEffectorRecord} record `node` already set
+     * @returns {boolean} whether any field changed
+     */
+    write_gpu_record(record) {
+        const world = record.node === NODE3D_SCENE_ID;
+
+        let changed = false;
+
+        if (record.kind !== FluidEffectorRecordKind.SWIRL) {
+            record.kind = FluidEffectorRecordKind.SWIRL;
+            changed = true;
+        }
+
+        const position = record.position;
+
+        const p_x = world ? Math.fround(this.position[0]) : 0;
+        const p_y = world ? Math.fround(this.position[1]) : 0;
+        const p_z = world ? Math.fround(this.position[2]) : 0;
+
+        if (position[0] !== p_x || position[1] !== p_y || position[2] !== p_z) {
+            position[0] = p_x;
+            position[1] = p_y;
+            position[2] = p_z;
+            changed = true;
+        }
+
+        const radius = Math.fround(this.radius);
+
+        if (record.radius !== radius) {
+            record.radius = radius;
+            changed = true;
+        }
+
+        const vector = record.vector;
+
+        const a_x = world ? Math.fround(this.axis[0]) : 0;
+        const a_y = world ? Math.fround(this.axis[1]) : 1;
+        const a_z = world ? Math.fround(this.axis[2]) : 0;
+
+        if (vector[0] !== a_x || vector[1] !== a_y || vector[2] !== a_z) {
+            vector[0] = a_x;
+            vector[1] = a_y;
+            vector[2] = a_z;
+            changed = true;
+        }
+
+        const strength = Math.fround(this.strength);
+
+        if (record.parameter !== strength) {
+            record.parameter = strength;
+            changed = true;
+        }
+
+        const length = Math.fround(this.length);
+
+        if (record.length !== length) {
+            record.length = length;
+            changed = true;
+        }
+
+        return changed;
+    }
+
+    /**
+     * @param {AbstractFluidEffector} other
+     * @return {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+        if (!(other instanceof VortexFluidEffector)) {
+            return false;
+        }
+        return this.length === other.length
+            && this.radius === other.radius
+            && this.strength === other.strength
+            && this.position[0] === other.position[0]
+            && this.position[1] === other.position[1]
+            && this.position[2] === other.position[2]
+            && this.axis[0] === other.axis[0]
+            && this.axis[1] === other.axis[1]
+            && this.axis[2] === other.axis[2];
+    }
+
+    /**
+     * @return {number}
+     */
+    hash() {
+        return hash_mix3(
+            hash_mix3(
+                hash_mix3(
+                    computeHashFloat(this.position[0]),
+                    computeHashFloat(this.position[1]),
+                    computeHashFloat(this.position[2])
+                ),
+                hash_mix3(
+                    computeHashFloat(this.axis[0]),
+                    computeHashFloat(this.axis[1]),
+                    computeHashFloat(this.axis[2])
+                ),
+                computeHashFloat(this.length)
+            ),
+            computeHashFloat(this.radius),
+            computeHashFloat(this.strength)
+        );
+    }
+
+    /**
+     * World-space AABB of the segment, grown by `radius`. Uses the user-supplied radius, not the
+     * kernel floor a coarse field evaluates it at.
+     *
+     * @param {AABB3} out
+     */
+    getBoundingBox(out) {
+        const r = this.radius;
+
+        const a_x = this.position[0];
+        const a_y = this.position[1];
+        const a_z = this.position[2];
+
+        const b_x = a_x + this.axis[0] * this.length;
+        const b_y = a_y + this.axis[1] * this.length;
+        const b_z = a_z + this.axis[2] * this.length;
+
+        out.setBounds(
+            Math.min(a_x, b_x) - r,
+            Math.min(a_y, b_y) - r,
+            Math.min(a_z, b_z) - r,
+            Math.max(a_x, b_x) + r,
+            Math.max(a_y, b_y) + r,
+            Math.max(a_z, b_z) + r
+        );
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+VortexFluidEffector.typeName = "VortexFluidEffector";
+
+VortexFluidEffector.prototype.has_gpu_record = true;

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

@@ -0,0 +1,25 @@
+/**
+ * Binary serialization for {@link VortexFluidEffector}: `position`, `axis`, `length`, `radius` and
+ * `strength`, f64. Version 0; see {@link GlobalFluidEffectorSerializationAdapter} for what a field
+ * added later costs.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VortexFluidEffectorSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof VortexFluidEffector;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {VortexFluidEffector} value
+     */
+    serialize(buffer: BinaryBuffer, value: VortexFluidEffector): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {VortexFluidEffector} value
+     */
+    deserialize(buffer: BinaryBuffer, value: VortexFluidEffector): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { VortexFluidEffector } from "./VortexFluidEffector.js";
+//# sourceMappingURL=VortexFluidEffectorSerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VortexFluidEffectorSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/VortexFluidEffectorSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH;;IAEI,kCAA4B;IAG5B;;;OAGG;IACH,uCAFW,mBAAmB,QAc7B;IAED;;;OAGG;IACH,yCAFW,mBAAmB,QAc7B;CACJ;gDAnD+C,gEAAgE;oCAC5E,0BAA0B"}

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

@@ -0,0 +1,52 @@
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { VortexFluidEffector } from "./VortexFluidEffector.js";
+
+/**
+ * Binary serialization for {@link VortexFluidEffector}: `position`, `axis`, `length`, `radius` and
+ * `strength`, f64. Version 0; see {@link GlobalFluidEffectorSerializationAdapter} for what a field
+ * added later costs.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VortexFluidEffectorSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = VortexFluidEffector;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {VortexFluidEffector} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat64(value.position[0]);
+        buffer.writeFloat64(value.position[1]);
+        buffer.writeFloat64(value.position[2]);
+
+        buffer.writeFloat64(value.axis[0]);
+        buffer.writeFloat64(value.axis[1]);
+        buffer.writeFloat64(value.axis[2]);
+
+        buffer.writeFloat64(value.length);
+        buffer.writeFloat64(value.radius);
+        buffer.writeFloat64(value.strength);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {VortexFluidEffector} value
+     */
+    deserialize(buffer, value) {
+        value.position[0] = buffer.readFloat64();
+        value.position[1] = buffer.readFloat64();
+        value.position[2] = buffer.readFloat64();
+
+        value.axis[0] = buffer.readFloat64();
+        value.axis[1] = buffer.readFloat64();
+        value.axis[2] = buffer.readFloat64();
+
+        value.length = buffer.readFloat64();
+        value.radius = buffer.readFloat64();
+        value.strength = buffer.readFloat64();
+    }
+}

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

@@ -3,17 +3,19 @@
  * left by an agent passing through air or water.
  *
  * Each call to {@link apply} treats the segment from {@link previous_position} to
- * {@link position} (both in WORLD coordinates) as a swept tube. The matrix
- * `world_to_grid` converts both endpoints into the target field's grid space, and the
- * effector splats `(position - previous_position) / dt * strength` into every fluid
- * cell within the kernel of that grid-space segment, weighted by a smooth
- * `(1 - d/R)²` falloff.
+ * {@link position} (both in WORLD coordinates) as a swept tube and deposits along the
+ * source's velocity over it, `v = (position − previous_position) / dt`, weighted by a smooth
+ * `(1 − d/R)²` falloff. The deposit is the effector's GPU record evaluated through
+ * `fluid_record_apply`, so the CPU and GPU fluids deposit the same momentum: a step carries
+ * `v·strength·πR²·|v|·dt`, the volume the source's disc swept taking `v·strength`, so a wake's
+ * momentum per second is `|v|·v·strength·πR²` whatever the step and the cell size. The peak on
+ * the segment is then `v·strength·L/(L/6 + 2R/15)` for a sweep `L = |v|·dt`, not `v·strength`.
  *
  * Trail advancement (copying `position` into `previous_position`) depends on who
  * drives the effector:
  *
- *   - **Transform64-managed** (entity has a `Transform64`; {@link FluidSystem} calls
- *     {@link syncFromTransform} once per fixed update): the trail advances inside
+ *   - **Transform64-managed** (entity has a `Transform64`; {@link FluidEffectorsSystem}
+ *     calls {@link syncFromTransform} once per fixed update): the trail advances inside
  *     the sync, NOT inside {@link apply}. The segment is "movement since the last
  *     tick", and `apply` is a pure read — the same instance can be applied to any
  *     number of overlapping fluid fields in one step and every field receives the
@@ -27,15 +29,13 @@
  *     {@link syncFromTransform}-style bookkeeping yourself by resetting
  *     {@link previous_position} between steps.
  *
- * Works at any user-supplied {@link radius}, including sub-cell. The kernel is
- * internally floored at `1` grid cell — small user radii (bullets, arrows) still
- * produce a roughly 1-cell-wide tube instead of silently missing every cell. The
- * intent: users supply radii in world units without thinking about cell size; the
- * effector picks the smallest physically meaningful footprint when the converted
- * radius is below one cell.
+ * Works at any user-supplied {@link radius}, including sub-cell: a tube narrower than two
+ * of the field's cells is evaluated two cells wide, carrying the momentum the normalisation
+ * gives it (the record's kernel floor) — small radii (bullets, arrows) still push the air,
+ * by as much as their swept disc does.
  *
  * When the entity carrying a {@link FluidEffectorsComponent} also has a Transform64,
- * {@link FluidSystem} calls {@link syncFromTransform} on this effector each step —
+ * {@link FluidEffectorsSystem} calls {@link syncFromTransform} on this effector each step —
  * which pulls the latest world-space position off the transform. On the very first
  * sync `previous_position` is seeded equal to `position` to suppress the spurious
  * wake from `[0, 0, 0]`.
@@ -61,16 +61,14 @@ export class WakeFluidEffector extends AbstractFluidEffector {
      */
     previous_position: [number, number, number];
     /**
-     * Influence radius of the swept tube, in WORLD units. Converted to grid units via
-     * the `world_to_grid` matrix's uniform scale, then internally floored to 1 grid
-     * cell so sub-cell world-radii still hit cells (see class docstring).
+     * Influence radius of the swept tube, in WORLD units. Below two of a field's cells
+     * the tube is evaluated two cells wide, its momentum kept (see class docstring).
      * @type {number}
      */
     radius: number;
     /**
-     * Multiplier on the imparted velocity. `1` means an on-segment cell takes the
-     * source's full grid-space velocity (before falloff weighting). `< 1` softens the
-     * wake; `> 1` exaggerates it.
+     * Multiplier on the imparted momentum: the swept volume takes `v·strength` (see the
+     * class docstring). `< 1` softens the wake; `> 1` exaggerates it.
      * @type {number}
      */
     strength: number;
@@ -81,7 +79,11 @@ export class WakeFluidEffector extends AbstractFluidEffector {
      * across the jump.
      */
     reset_trail(): void;
+    has_gpu_record: boolean;
     #private;
 }
+export namespace WakeFluidEffector {
+    let typeName: string;
+}
 import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
 //# sourceMappingURL=WakeFluidEffector.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"WakeFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/WakeFluidEffector.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IAEI;;;;;OAKG;IACH,UAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEb;IAErB;;;;;;OAMG;IACH,mBAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEJ;IAE9B;;;;;OAKG;IACH,QAFU,MAAM,CAEL;IAEX;;;;;OAKG;IACH,UAFU,MAAM,CAEH;IAoBb;;;;;OAKG;IACH,oBAKC;;CAsSJ;sCAzZqC,4BAA4B"}
+{"version":3,"file":"WakeFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/WakeFluidEffector.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IAEI;;;;;OAKG;IACH,UAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEb;IAErB;;;;;;OAMG;IACH,mBAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEJ;IAE9B;;;;OAIG;IACH,QAFU,MAAM,CAEL;IAEX;;;;OAIG;IACH,UAFU,MAAM,CAEH;IAmCb;;;;;OAKG;IACH,oBAUC;IA0QL,wBAA0C;;CARzC;;kBAIS,MAAM;;sCAjZsB,4BAA4B"}