@woosh/meep-engine 3.47.0 → 3.50.0

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

@@ -1 +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;CAkNd;sCAhQqC,4BAA4B"}
+{"version":3,"file":"ImpulseFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/ImpulseFluidEffector.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;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;;;;;OAKG;IACH,QAFU,MAAM,CAEL;IAEX;;;;;;;;;;;;;OAaG;IACH,QAFU,MAAM,CAEL;IA0Kf,wBAA6C;CAR5C;;kBAIS,MAAM;;sCAhPsB,4BAA4B"}

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

@@ -1,9 +1,17 @@
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
 import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
-import { v3_matrix4_multiply } from "../../../../core/geom/vec3/v3_matrix4_multiply.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";
 
-const scratch_grid_pos = new Float32Array(3);
+/**
+ * The record {@link ImpulseFluidEffector#apply} writes itself into, at the world root.
+ * @type {FluidEffectorRecord}
+ */
+const scratch_record = fluid_effector_record_create();
 
 /**
  * Splats a velocity impulse into a spherical region around a world-space position
@@ -15,11 +23,17 @@ const scratch_grid_pos = new Float32Array(3);
  * 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.
+ * vector), {@link radius} (scalar length). {@link apply} evaluates the effector's GPU record
+ * ({@link write_gpu_record}) on the field through `fluid_record_apply`, so the CPU fluid and the
+ * GPU fluid deposit the same push. Works at any radius, sub-cell included: a push narrower than
+ * two of the field's cells is evaluated two cells wide with its amplitude scaled by `(R/R_eff)³`,
+ * so it carries the momentum it would have had (the record's kernel floor). From two cells up the
+ * deposit is the kernel itself.
+ *
+ * {@link spread} widens the push from a jet into a cone, and at π into a burst: each face
+ * takes `|force|·dt·w` along the direction from the centre to the face, clamped into the cone
+ * of half-angle `spread` about `force` (`v3_clamp_to_cone`). At 0 every face is pushed along
+ * `force`, exactly as before the field existed.
  *
  * For moving sources that should leave a trail, see {@link WakeFluidEffector}.
  */
@@ -33,7 +47,7 @@ export class ImpulseFluidEffector extends AbstractFluidEffector {
 
     /**
      * Acceleration vector in WORLD units per second squared. Per-step deposit is
-     * `world_to_grid · force × dt × falloff_weight`. Same world-units convention as
+     * `force × dt × falloff_weight`, turned into the field's grid units. Same world-units convention as
      * {@link GlobalFluidEffector.force} — gravity stays gravity across fields with
      * different `cell_size`.
      * @type {[number, number, number]}
@@ -41,154 +55,52 @@ export class ImpulseFluidEffector extends AbstractFluidEffector {
     force = [0, 0, 0];
 
     /**
-     * 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).
+     * Influence radius in WORLD units. Faces past `radius` from the splat point are
+     * unaffected by the falloff. Below two of a field's cells the push is evaluated two cells
+     * wide with its momentum kept (see the class docstring). 0 or less disables it.
      * @type {number}
      */
     radius = 1;
 
     /**
+     * Half-angle, in radians, of the cone the push fans into, in [0, π].
+     *
+     * - `0` (default): every face is pushed along {@link force}.
+     * - Between: a face is pushed along the direction from {@link position} to it, turned toward
+     *   `force` just far enough to lie in the cone of this half-angle about it. Inside the cone a
+     *   face is pushed straight outward.
+     * - `π`: every direction is inside the cone, so every face is pushed straight outward — an
+     *   omnidirectional burst, with `force`'s length as its strength.
+     *
+     * A face at the centre itself has no direction from it and is pushed along `force`.
+     *
+     * @type {number}
+     */
+    spread = 0;
+
+    /**
+     * Push the field: the effector's record ({@link write_gpu_record}, at the world root) evaluated on
+     * every unpinned face in its reach by {@link fluid_record_apply}, so the CPU fluid deposits what the
+     * GPU fluid does. Each face takes `|force|·dt·w·v3_clamp_to_cone(r̂, f̂, spread)` at its own
+     * position, `f·dt·w` at spread 0, `w = (1 − |r|/R)²`. Narrower than two of the field's cells, the
+     * push is evaluated two cells wide with its momentum kept (the record's kernel floor).
+     *
      * @param {FluidField} field
-     * @param {number} dt
-     * @param {Float32Array|number[]} world_to_grid  Column-major 4×4 affine from world
+     * @param {number} dt seconds; 0 or less deposits nothing
+     * @param {Float32Array|number[]} world_to_grid  Column-major 4×4 similarity from world
      *                                               to the target field's grid space.
      */
     apply(field, dt, world_to_grid) {
-        if (this.radius <= 0) {
-            // Explicit no-op so callers can disable per-frame without zeroing force.
+        if (!(dt > 0)) {
             return;
         }
 
-        const wfx = this.force[0];
-        const wfy = this.force[1];
-        const wfz = this.force[2];
-
-        if (wfx === 0 && wfy === 0 && wfz === 0) {
-            return;
-        }
+        const record = scratch_record;
 
-        const m = world_to_grid;
+        record.node = NODE3D_SCENE_ID;
+        this.write_gpu_record(record);
 
-        // Direction-transform the world force into grid units, then scale by dt.
-        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;
-
-        // Point-transform position into grid coords.
-        v3_matrix4_multiply(scratch_grid_pos, 0, this.position, 0, world_to_grid);
-        const px = scratch_grid_pos[0];
-        const py = scratch_grid_pos[1];
-        const pz = scratch_grid_pos[2];
-
-        // World radius → grid radius via the uniform-scale factor (length of the
-        // matrix's first basis vector). For non-uniform scale this assumes the user
-        // is OK with the x-axis scale standing in for all three.
-        const scale = Math.sqrt(m[0] * m[0] + m[1] * m[1] + m[2] * m[2]);
-        // Internal min-radius clamp: see class docstring.
-        const r = Math.max(1, this.radius * scale);
-
-        const res = field.getResolution();
-        const res_x = res[0];
-        const res_y = res[1];
-        const res_z = res[2];
-
-        const r_inv = 1 / r;
-
-        // Each velocity component deposits onto its own face lattice, with the
-        // falloff evaluated at the face position (the lattice is offset by
-        // −0.5 on its own axis relative to cell centers). Pinned faces
-        // (adjacent solid) are skipped.
-
-        // u (x-faces) — face (x, y, z) sits at (x − 0.5, y, z).
-        {
-            const vu = field.velocity_x;
-            const pin = field.face_solid_x;
-            const sx = res_x + 1;
-            const x_min = Math.max(0, Math.floor(px + 0.5 - r));
-            const x_max = Math.min(res_x, Math.ceil(px + 0.5 + r));
-            const y_min = Math.max(0, Math.floor(py - r));
-            const y_max = Math.min(res_y - 1, Math.ceil(py + r));
-            const z_min = Math.max(0, Math.floor(pz - r));
-            const z_max = Math.min(res_z - 1, Math.ceil(pz + r));
-            for (let z = z_min; z <= z_max; z++) {
-                const dz = z - pz;
-                const z_off = z * sx * res_y;
-                for (let y = y_min; y <= y_max; y++) {
-                    const dy = y - py;
-                    const y_off = z_off + y * sx;
-                    for (let x = x_min; x <= x_max; x++) {
-                        const dx = x - 0.5 - px;
-                        const t = Math.sqrt(dx * dx + dy * dy + dz * dz) * r_inv;
-                        if (t >= 1) continue;
-                        const f = y_off + x;
-                        if (pin[f] !== 0) continue;
-                        const w = (1 - t) * (1 - t);
-                        vu[f] += fx * w;
-                    }
-                }
-            }
-        }
-
-        // v (y-faces) — face (x, y, z) sits at (x, y − 0.5, z).
-        {
-            const vv = field.velocity_y;
-            const pin = field.face_solid_y;
-            const x_min = Math.max(0, Math.floor(px - r));
-            const x_max = Math.min(res_x - 1, Math.ceil(px + r));
-            const y_min = Math.max(0, Math.floor(py + 0.5 - r));
-            const y_max = Math.min(res_y, Math.ceil(py + 0.5 + r));
-            const z_min = Math.max(0, Math.floor(pz - r));
-            const z_max = Math.min(res_z - 1, Math.ceil(pz + r));
-            for (let z = z_min; z <= z_max; z++) {
-                const dz = z - pz;
-                const z_off = z * res_x * (res_y + 1);
-                for (let y = y_min; y <= y_max; y++) {
-                    const dy = y - 0.5 - py;
-                    const y_off = z_off + y * res_x;
-                    for (let x = x_min; x <= x_max; x++) {
-                        const dx = x - px;
-                        const t = Math.sqrt(dx * dx + dy * dy + dz * dz) * r_inv;
-                        if (t >= 1) continue;
-                        const f = y_off + x;
-                        if (pin[f] !== 0) continue;
-                        const w = (1 - t) * (1 - t);
-                        vv[f] += fy * w;
-                    }
-                }
-            }
-        }
-
-        // w (z-faces) — face (x, y, z) sits at (x, y, z − 0.5).
-        {
-            const vw = field.velocity_z;
-            const pin = field.face_solid_z;
-            const slice = res_x * res_y;
-            const x_min = Math.max(0, Math.floor(px - r));
-            const x_max = Math.min(res_x - 1, Math.ceil(px + r));
-            const y_min = Math.max(0, Math.floor(py - r));
-            const y_max = Math.min(res_y - 1, Math.ceil(py + r));
-            const z_min = Math.max(0, Math.floor(pz + 0.5 - r));
-            const z_max = Math.min(res_z, Math.ceil(pz + 0.5 + r));
-            for (let z = z_min; z <= z_max; z++) {
-                const dz = z - 0.5 - pz;
-                const z_off = z * slice;
-                for (let y = y_min; y <= y_max; y++) {
-                    const dy = y - py;
-                    const y_off = z_off + y * res_x;
-                    for (let x = x_min; x <= x_max; x++) {
-                        const dx = x - px;
-                        const t = Math.sqrt(dx * dx + dy * dy + dz * dz) * r_inv;
-                        if (t >= 1) continue;
-                        const f = y_off + x;
-                        if (pin[f] !== 0) continue;
-                        const w = (1 - t) * (1 - t);
-                        vw[f] += fz * w;
-                    }
-                }
-            }
-        }
+        fluid_record_apply(field, dt, world_to_grid, record);
     }
 
     /**
@@ -213,6 +125,7 @@ export class ImpulseFluidEffector extends AbstractFluidEffector {
             return false;
         }
         return this.radius === other.radius
+            && this.spread === other.spread
             && this.position[0] === other.position[0]
             && this.position[1] === other.position[1]
             && this.position[2] === other.position[2]
@@ -225,21 +138,89 @@ export class ImpulseFluidEffector extends AbstractFluidEffector {
      * @return {number}
      */
     hash() {
-        return hash_mix3(
+        return hash_mix2(
             hash_mix3(
                 hash_mix3(
-                    computeHashFloat(this.position[0]),
-                    computeHashFloat(this.position[1]),
-                    computeHashFloat(this.position[2])
+                    hash_mix3(
+                        computeHashFloat(this.position[0]),
+                        computeHashFloat(this.position[1]),
+                        computeHashFloat(this.position[2])
+                    ),
+                    computeHashFloat(this.force[0]),
+                    computeHashFloat(this.force[1])
                 ),
-                computeHashFloat(this.force[0]),
-                computeHashFloat(this.force[1])
+                computeHashFloat(this.force[2]),
+                computeHashFloat(this.radius)
             ),
-            computeHashFloat(this.force[2]),
-            computeHashFloat(this.radius)
+            computeHashFloat(this.spread)
         );
     }
 
+    /**
+     * A `SPHERE_PUSH`: the centre (the node's origin, or `position` at node 0), `radius`, `force` as
+     * a world vector on either (this effector's sync takes the translation alone), and `spread`.
+     *
+     * @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.SPHERE_PUSH) {
+            record.kind = FluidEffectorRecordKind.SPHERE_PUSH;
+            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 f_x = Math.fround(this.force[0]);
+        const f_y = Math.fround(this.force[1]);
+        const f_z = Math.fround(this.force[2]);
+
+        if (vector[0] !== f_x || vector[1] !== f_y || vector[2] !== f_z) {
+            vector[0] = f_x;
+            vector[1] = f_y;
+            vector[2] = f_z;
+            changed = true;
+        }
+
+        const spread = Math.fround(this.spread);
+
+        if (record.parameter !== spread) {
+            record.parameter = spread;
+            changed = true;
+        }
+
+        if (record.length !== 0) {
+            record.length = 0;
+            changed = true;
+        }
+
+        return changed;
+    }
+
     /**
      * World-space box around `position` expanded by `radius`. Uses the user-supplied
      * radius (in world units), not the internal min-radius clamp — broad-phase rejects
@@ -258,3 +239,11 @@ export class ImpulseFluidEffector extends AbstractFluidEffector {
         );
     }
 }
+
+/**
+ * @readonly
+ * @type {string}
+ */
+ImpulseFluidEffector.typeName = "ImpulseFluidEffector";
+
+ImpulseFluidEffector.prototype.has_gpu_record = true;

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"ImpulseFluidEffectorSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/ImpulseFluidEffectorSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH;;IAEI,mCAA6B;IAG7B;;;OAGG;IACH,uCAFW,oBAAoB,QAa9B;IAED;;;OAGG;IACH,yCAFW,oBAAoB,QAa9B;CACJ;gDAlD+C,gEAAgE;qCAC3E,2BAA2B"}

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

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

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

@@ -0,0 +1,55 @@
+/**
+ * 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: [number, number, number];
+    /**
+     * The axis the swirl turns about, right-handed, and the direction the segment runs in. Unit
+     * length, world.
+     * @type {[number, number, number]}
+     */
+    axis: [number, number, number];
+    /**
+     * How far the segment runs along {@link axis} from {@link position}, metres, ≥ 0. 0 is a point
+     * vortex.
+     * @type {number}
+     */
+    length: number;
+    /**
+     * The swirl's reach from the segment, metres. 0 disables the effector.
+     * @type {number}
+     */
+    radius: number;
+    /**
+     * 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: number;
+    has_gpu_record: boolean;
+}
+export namespace VortexFluidEffector {
+    let typeName: string;
+}
+import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
+//# sourceMappingURL=VortexFluidEffector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VortexFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/VortexFluidEffector.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAEI;;;OAGG;IACH,UAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEb;IAErB;;;;OAIG;IACH,MAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEjB;IAEjB;;;;OAIG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;;OAIG;IACH,UAFU,MAAM,CAEH;IA4LjB,wBAA4C;CAR3C;;kBAIS,MAAM;;sCAvPsB,4BAA4B"}