@woosh/meep-engine 3.47.0 → 3.50.0

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

@@ -1,28 +1,36 @@
 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_a = new Float32Array(3);
-const scratch_b = new Float32Array(3);
+/**
+ * The record {@link WakeFluidEffector#apply} writes itself into, at the world root.
+ * @type {FluidEffectorRecord}
+ */
+const scratch_record = fluid_effector_record_create();
 
 /**
  * Imparts momentum into the fluid along the swept path of a moving source — the wake
  * 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
@@ -36,15 +44,13 @@ const scratch_b = new Float32Array(3);
  *     {@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]`.
@@ -73,17 +79,15 @@ export class WakeFluidEffector extends AbstractFluidEffector {
     previous_position = [0, 0, 0];
 
     /**
-     * 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 = 1;
 
     /**
-     * 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 = 1;
@@ -99,13 +103,28 @@ export class WakeFluidEffector extends AbstractFluidEffector {
 
     /**
      * True once {@link syncFromTransform} has ever been called — the effector is
-     * driven by an entity Transform64 via {@link FluidSystem}. In this mode the
+     * driven by an entity Transform64 via {@link FluidEffectorsSystem}. In this mode the
      * trail advances in the sync (once per tick) and {@link apply} becomes a pure
      * read, so one instance can serve any number of fluid fields per step.
      * @type {boolean}
      */
     #transform_managed = false;
 
+    /**
+     * {@link position} as the last {@link advance} found it, and whether one has: what the GPU
+     * record's velocity is measured from at node 0, where no node's motion carries it. Kept apart
+     * from {@link previous_position}, which a manually driven wake's `apply` advances.
+     * @type {Float64Array}
+     */
+    #advanced_position = new Float64Array(3);
+    #advanced = false;
+
+    /**
+     * World velocity over the last tick, m/s: the GPU record's at node 0.
+     * @type {Float64Array}
+     */
+    #velocity = new Float64Array(3);
+
     /**
      * Snap {@link previous_position} to {@link position} and mark the trail as
      * needing a re-seed. Call after manual initial placement and after any
@@ -117,12 +136,49 @@ export class WakeFluidEffector extends AbstractFluidEffector {
         this.previous_position[1] = this.position[1];
         this.previous_position[2] = this.position[2];
         this.#initialized = false;
+
+        this.#advanced = false;
+        this.#velocity[0] = 0;
+        this.#velocity[1] = 0;
+        this.#velocity[2] = 0;
+    }
+
+    /**
+     * Measure the velocity over the tick: {@link position} now against where the last call found it,
+     * over `dt`. The first call after construction or {@link reset_trail} measures none. Only the GPU
+     * record of a wake without a `Transform64` reads it ({@link write_gpu_record}); `apply` sweeps the
+     * trail, as it always has.
+     *
+     * @param {number} dt seconds, the fixed step
+     */
+    advance(dt) {
+        const p = this.position;
+        const was = this.#advanced_position;
+        const velocity = this.#velocity;
+
+        if (this.#advanced && dt > 0) {
+            const inverse_dt = 1 / dt;
+
+            velocity[0] = (p[0] - was[0]) * inverse_dt;
+            velocity[1] = (p[1] - was[1]) * inverse_dt;
+            velocity[2] = (p[2] - was[2]) * inverse_dt;
+        } else {
+            velocity[0] = 0;
+            velocity[1] = 0;
+            velocity[2] = 0;
+        }
+
+        was[0] = p[0];
+        was[1] = p[1];
+        was[2] = p[2];
+
+        this.#advanced = true;
     }
 
     /**
      * Pull world-space position off the entity Transform64 and advance the trail:
      * `previous_position` takes the position adopted on the LAST sync, `position`
-     * takes the transform's current one. Called by {@link FluidSystem} once per
+     * takes the transform's current one. Called by {@link FluidEffectorsSystem} once per
      * fixed update, before any field is stepped — so every field stepped this
      * tick sees the same one-tick segment.
      *
@@ -154,177 +210,38 @@ export class WakeFluidEffector extends AbstractFluidEffector {
     }
 
     /**
+     * Push the field along the segment the source swept, `previous_position` → `position`: the
+     * effector's record at the world root, its velocity that segment over `dt`, evaluated on every
+     * unpinned face in its reach by {@link fluid_record_apply}, so the CPU fluid deposits what the GPU
+     * fluid does. The step's momentum is `v·strength·πR²·|v|·dt`, the volume the source's disc swept
+     * taking `v·strength`, however the field's cells are sized; narrower than two cells the tube is
+     * evaluated two cells wide with that momentum kept.
+     *
+     * A manually driven source's trail then advances (see the class docstring).
+     *
      * @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 (dt <= 0 || this.strength === 0 || this.radius <= 0) {
+        if (!(dt > 0) || this.strength === 0 || this.radius <= 0) {
             return;
         }
 
-        const m = world_to_grid;
-
-        // World radius → grid radius via uniform scale (length of the matrix's
-        // first basis vector). For axis-aligned uniform-scale matrices this is
-        // exactly 1/cell_size. Effective kernel is then floored to 1 grid cell so
-        // sub-cell radii still hit cells regardless of where the segment falls.
-        // `radius <= 0` is handled separately as a no-op so users can explicitly
-        // disable.
-        const scale = Math.sqrt(m[0] * m[0] + m[1] * m[1] + m[2] * m[2]);
-        const r = Math.max(1, this.radius * scale);
-
-        // Convert both segment endpoints into grid space.
-        v3_matrix4_multiply(scratch_a, 0, this.previous_position, 0, world_to_grid);
-        v3_matrix4_multiply(scratch_b, 0, this.position, 0, world_to_grid);
-
-        const ax = scratch_a[0];
-        const ay = scratch_a[1];
-        const az = scratch_a[2];
-        const bx = scratch_b[0];
-        const by = scratch_b[1];
-        const bz = scratch_b[2];
-
-        const seg_dx = bx - ax;
-        const seg_dy = by - ay;
-        const seg_dz = bz - az;
-
-        const seg_len_sq = seg_dx * seg_dx + seg_dy * seg_dy + seg_dz * seg_dz;
-        if (seg_len_sq === 0) {
-            // Source didn't move in grid space — no wake. previous_position is already
-            // equal to position (or maps to the same grid cell), leave it alone.
-            return;
-        }
+        const record = scratch_record;
 
-        // Source velocity * strength = impulse per step (added directly to velocity).
-        const inv_dt = 1 / dt;
-        const impulse_x = seg_dx * inv_dt * this.strength;
-        const impulse_y = seg_dy * inv_dt * this.strength;
-        const impulse_z = seg_dz * inv_dt * this.strength;
-
-        const res = field.getResolution();
-        const res_x = res[0];
-        const res_y = res[1];
-        const res_z = res[2];
-
-        const r_inv = 1 / r;
-        const inv_seg_len_sq = 1 / seg_len_sq;
-
-        // Conservative AABB of the swept tube in cell coordinates; each face
-        // lattice clips it to its own index range below.
-        const box_x_min = Math.min(ax, bx) - r;
-        const box_x_max = Math.max(ax, bx) + r;
-        const box_y_min = Math.min(ay, by) - r;
-        const box_y_max = Math.max(ay, by) + r;
-        const box_z_min = Math.min(az, bz) - r;
-        const box_z_max = Math.max(az, bz) + r;
-
-        if (Math.max(0, Math.floor(box_x_min)) > Math.min(res_x, Math.ceil(box_x_max))
-            || Math.max(0, Math.floor(box_y_min)) > Math.min(res_y, Math.ceil(box_y_max))
-            || Math.max(0, Math.floor(box_z_min)) > Math.min(res_z, Math.ceil(box_z_max))) {
-            // Swept tube doesn't intersect the field at all.
-            this.#advance_trail_if_manual();
-            return;
-        }
+        record.node = NODE3D_SCENE_ID;
+        this.write_gpu_record(record);
 
-        // Weight of the (1 − d/R)² falloff at a query position, or 0 outside
-        // the tube.
-        const tube_weight = (qx, qy, qz) => {
-            const dx = qx - ax;
-            const dy = qy - ay;
-            const dz = qz - az;
-            let t = (dx * seg_dx + dy * seg_dy + dz * seg_dz) * inv_seg_len_sq;
-            if (t < 0) t = 0;
-            else if (t > 1) t = 1;
-            const ndx = dx - t * seg_dx;
-            const ndy = dy - t * seg_dy;
-            const ndz = dz - t * seg_dz;
-            const tt = Math.sqrt(ndx * ndx + ndy * ndy + ndz * ndz) * r_inv;
-            if (tt >= 1) return 0;
-            const fall = 1 - tt;
-            return fall * fall;
-        };
-
-        // Each component deposits onto its own face lattice at face positions
-        // (offset −0.5 on its own axis). Pinned faces are skipped.
-
-        // u (x-faces).
-        {
-            const vu = field.velocity_x;
-            const pin = field.face_solid_x;
-            const sx = res_x + 1;
-            const x_min = Math.max(0, Math.floor(box_x_min + 0.5));
-            const x_max = Math.min(res_x, Math.ceil(box_x_max + 0.5));
-            const y_min = Math.max(0, Math.floor(box_y_min));
-            const y_max = Math.min(res_y - 1, Math.ceil(box_y_max));
-            const z_min = Math.max(0, Math.floor(box_z_min));
-            const z_max = Math.min(res_z - 1, Math.ceil(box_z_max));
-            for (let z = z_min; z <= z_max; z++) {
-                const z_off = z * sx * res_y;
-                for (let y = y_min; y <= y_max; y++) {
-                    const y_off = z_off + y * sx;
-                    for (let x = x_min; x <= x_max; x++) {
-                        const w = tube_weight(x - 0.5, y, z);
-                        if (w === 0) continue;
-                        const f = y_off + x;
-                        if (pin[f] !== 0) continue;
-                        vu[f] += impulse_x * w;
-                    }
-                }
-            }
-        }
+        // the segment's velocity: the swept capsule [p − v·dt, p] is the segment itself
+        const inverse_dt = 1 / dt;
 
-        // v (y-faces).
-        {
-            const vv = field.velocity_y;
-            const pin = field.face_solid_y;
-            const x_min = Math.max(0, Math.floor(box_x_min));
-            const x_max = Math.min(res_x - 1, Math.ceil(box_x_max));
-            const y_min = Math.max(0, Math.floor(box_y_min + 0.5));
-            const y_max = Math.min(res_y, Math.ceil(box_y_max + 0.5));
-            const z_min = Math.max(0, Math.floor(box_z_min));
-            const z_max = Math.min(res_z - 1, Math.ceil(box_z_max));
-            for (let z = z_min; z <= z_max; z++) {
-                const z_off = z * res_x * (res_y + 1);
-                for (let y = y_min; y <= y_max; y++) {
-                    const y_off = z_off + y * res_x;
-                    for (let x = x_min; x <= x_max; x++) {
-                        const w = tube_weight(x, y - 0.5, z);
-                        if (w === 0) continue;
-                        const f = y_off + x;
-                        if (pin[f] !== 0) continue;
-                        vv[f] += impulse_y * w;
-                    }
-                }
-            }
-        }
+        record.vector[0] = (this.position[0] - this.previous_position[0]) * inverse_dt;
+        record.vector[1] = (this.position[1] - this.previous_position[1]) * inverse_dt;
+        record.vector[2] = (this.position[2] - this.previous_position[2]) * inverse_dt;
 
-        // w (z-faces).
-        {
-            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(box_x_min));
-            const x_max = Math.min(res_x - 1, Math.ceil(box_x_max));
-            const y_min = Math.max(0, Math.floor(box_y_min));
-            const y_max = Math.min(res_y - 1, Math.ceil(box_y_max));
-            const z_min = Math.max(0, Math.floor(box_z_min + 0.5));
-            const z_max = Math.min(res_z, Math.ceil(box_z_max + 0.5));
-            for (let z = z_min; z <= z_max; z++) {
-                const z_off = z * slice;
-                for (let y = y_min; y <= y_max; y++) {
-                    const y_off = z_off + y * res_x;
-                    for (let x = x_min; x <= x_max; x++) {
-                        const w = tube_weight(x, y, z - 0.5);
-                        if (w === 0) continue;
-                        const f = y_off + x;
-                        if (pin[f] !== 0) continue;
-                        vw[f] += impulse_z * w;
-                    }
-                }
-            }
-        }
+        fluid_record_apply(field, dt, world_to_grid, record);
 
         this.#advance_trail_if_manual();
     }
@@ -387,6 +304,77 @@ export class WakeFluidEffector extends AbstractFluidEffector {
         );
     }
 
+    /**
+     * A `SWEPT_CAPSULE`: the source (the node's origin, or `position` at node 0), `radius`,
+     * `strength`, and the wake's own velocity: at node 0 the velocity over the last tick that
+     * {@link advance} measured, and at any other node 0, the node's motion being the wake's.
+     *
+     * On the GPU the capsule swept over a step of `dt_c` is `[p − v·dt_c, p]`, `v` the record's
+     * velocity plus its node's, and its momentum per second is `|v|·v·strength·πR²` on every
+     * cascade, and `apply` on a CPU field deposits through the same record.
+     *
+     * @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.SWEPT_CAPSULE) {
+            record.kind = FluidEffectorRecordKind.SWEPT_CAPSULE;
+            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 velocity = this.#velocity;
+
+        const v_x = world ? Math.fround(velocity[0]) : 0;
+        const v_y = world ? Math.fround(velocity[1]) : 0;
+        const v_z = world ? Math.fround(velocity[2]) : 0;
+
+        if (vector[0] !== v_x || vector[1] !== v_y || vector[2] !== v_z) {
+            vector[0] = v_x;
+            vector[1] = v_y;
+            vector[2] = v_z;
+            changed = true;
+        }
+
+        const strength = Math.fround(this.strength);
+
+        if (record.parameter !== strength) {
+            record.parameter = strength;
+            changed = true;
+        }
+
+        if (record.length !== 0) {
+            record.length = 0;
+            changed = true;
+        }
+
+        return changed;
+    }
+
     /**
      * World-space AABB of the swept segment, grown by `radius` in each direction.
      * Uses the user-supplied radius (in world units), not the internal min-radius
@@ -412,3 +400,11 @@ export class WakeFluidEffector extends AbstractFluidEffector {
         );
     }
 }
+
+/**
+ * @readonly
+ * @type {string}
+ */
+WakeFluidEffector.typeName = "WakeFluidEffector";
+
+WakeFluidEffector.prototype.has_gpu_record = true;

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

@@ -0,0 +1,31 @@
+/**
+ * Binary serialization for {@link WakeFluidEffector}: `position`, `previous_position`, `radius`
+ * and `strength`, f64. Version 0; see {@link GlobalFluidEffectorSerializationAdapter} for what a
+ * field added later costs.
+ *
+ * The trail's private bookkeeping (whether it has been seeded, whether a `Transform64` drives
+ * it) is not written: a loaded wake is a fresh one at the saved segment. Driven by a transform,
+ * its first sync seeds the trail, so the load sweeps no wake from wherever the entity was saved
+ * to wherever it is loaded; driven by hand, its next apply splats the saved segment, which is
+ * the one it was about to splat.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WakeFluidEffectorSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof WakeFluidEffector;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {WakeFluidEffector} value
+     */
+    serialize(buffer: BinaryBuffer, value: WakeFluidEffector): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {WakeFluidEffector} value
+     */
+    deserialize(buffer: BinaryBuffer, value: WakeFluidEffector): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { WakeFluidEffector } from "./WakeFluidEffector.js";
+//# sourceMappingURL=WakeFluidEffectorSerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WakeFluidEffectorSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/WakeFluidEffectorSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH;;IAEI,gCAA0B;IAG1B;;;OAGG;IACH,uCAFW,iBAAiB,QAa3B;IAED;;;OAGG;IACH,yCAFW,iBAAiB,QAa3B;CACJ;gDAvD+C,gEAAgE;kCAC9E,wBAAwB"}

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

@@ -0,0 +1,56 @@
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { WakeFluidEffector } from "./WakeFluidEffector.js";
+
+/**
+ * Binary serialization for {@link WakeFluidEffector}: `position`, `previous_position`, `radius`
+ * and `strength`, f64. Version 0; see {@link GlobalFluidEffectorSerializationAdapter} for what a
+ * field added later costs.
+ *
+ * The trail's private bookkeeping (whether it has been seeded, whether a `Transform64` drives
+ * it) is not written: a loaded wake is a fresh one at the saved segment. Driven by a transform,
+ * its first sync seeds the trail, so the load sweeps no wake from wherever the entity was saved
+ * to wherever it is loaded; driven by hand, its next apply splats the saved segment, which is
+ * the one it was about to splat.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WakeFluidEffectorSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = WakeFluidEffector;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {WakeFluidEffector} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat64(value.position[0]);
+        buffer.writeFloat64(value.position[1]);
+        buffer.writeFloat64(value.position[2]);
+
+        buffer.writeFloat64(value.previous_position[0]);
+        buffer.writeFloat64(value.previous_position[1]);
+        buffer.writeFloat64(value.previous_position[2]);
+
+        buffer.writeFloat64(value.radius);
+        buffer.writeFloat64(value.strength);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {WakeFluidEffector} value
+     */
+    deserialize(buffer, value) {
+        value.position[0] = buffer.readFloat64();
+        value.position[1] = buffer.readFloat64();
+        value.position[2] = buffer.readFloat64();
+
+        value.previous_position[0] = buffer.readFloat64();
+        value.previous_position[1] = buffer.readFloat64();
+        value.previous_position[2] = buffer.readFloat64();
+
+        value.radius = buffer.readFloat64();
+        value.strength = buffer.readFloat64();
+    }
+}

package/src/engine/physics/fluid/effector/record/FLUID_EFFECTOR_RECORD_STRUCT.d.ts

@@ -0,0 +1,52 @@
+/**
+ * # One local fluid effector, as the GPU fluid holds it
+ *
+ * A row of the `fluid_effectors` table (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10): a
+ * {@link FluidEffectorRecordKind}, the kind's parameters, and the transforms row its frame is. One
+ * layout for every kind; {@link FluidEffectorRecordKind} says which field means what. 48 bytes.
+ *
+ * One record, two executors (§17 D12): the GPU's forcing pass evaluates it per face with
+ * `fluid_effector_record_deposit` (`chunk_fluid_effector_record_deposit`), and the CPU with
+ * {@link fluid_record_apply}, from the same per-point maths.
+ *
+ * ## Written by the effector, field by field
+ *
+ * Each effector class with a GPU form writes its own record, `write_gpu_record(record)`, comparing
+ * every field while it assigns it and answering whether anything changed, so an unchanged effector
+ * writes nothing (the particle emitter's pattern). A staging record is
+ * {@link fluid_effector_record_create}'s; the table takes it through
+ * `generate_record_writer(FLUID_EFFECTOR_RECORD_STRUCT)`.
+ *
+ * ## The node, and what the pose comes from
+ *
+ * `node` is a row of the scene's `transforms` table. The system linking the record sets it before the
+ * effector writes: `NODE3D_SCENE_ID` (0, the world root) for an effector on an entity with no
+ * `Transform64`, or `row_of_entity(entity)` for one with. The effector then writes its parameters in
+ * that node's frame:
+ *
+ * - **node 0:** the world's — its own `position`, its axis, and (a wake) its velocity;
+ * - **any other:** its entity's — an effector there is placed by its node, so `position` is the
+ *   origin and a vortex's axis is local +Y (`syncFromTransform` takes both from the transform), and a
+ *   wake's own velocity is 0, its motion being the node's.
+ *
+ * So the pose is never in the record, and an effector that only moves writes nothing. An impulse's
+ * force stays world-frame on either: its `syncFromTransform` takes the translation alone.
+ *
+ * **What a consumer supplies per node** to bring a record to the world, which
+ * {@link fluid_effector_record_resolve} (`chunk_fluid_effector_record_resolve`) does, and every node-0
+ * record already is:
+ *
+ * - `global` and `prev_global`, the node's world matrix this frame and last (node 0: identity both);
+ * - `1 / (frame_dt · fixedStepTimeScale)`: the game seconds the node took to move from
+ *   `prev_global` to `global`, inverted; 0 on a frame no game time passed.
+ *
+ * The world position is `global · (position, 1)`; a swirl's axis `normalize(global · (axis, 0))`; a
+ * wake's velocity `vector + ((global − prev_global) · (position, 1)) / (frame_dt ·
+ * fixedStepTimeScale)`. A teleport reports no motion, because `GPUSceneRows` seeds `prev_global =
+ * global` on `TRANSFORM64_EVENT_PLACED`.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_EFFECTOR_RECORD_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../../../shade/renderer/shader/type/WebGPUStruct.js";
+//# sourceMappingURL=FLUID_EFFECTOR_RECORD_STRUCT.d.ts.map

package/src/engine/physics/fluid/effector/record/FLUID_EFFECTOR_RECORD_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_EFFECTOR_RECORD_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/fluid/effector/record/FLUID_EFFECTOR_RECORD_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,2CAFU,YAAY,CAiBI;6BAlEG,2DAA2D"}