@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,405 +1,405 @@
-import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
-import { v3_matrix4_multiply } from "../../../../core/geom/vec3/v3_matrix4_multiply.js";
-import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
-import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
-
-const scratch_a = new Float32Array(3);
-const scratch_b = new Float32Array(3);
-
-/**
- * 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.
- *
- * Trail advancement (copying `position` into `previous_position`) depends on who
- * drives the effector:
- *
- *   - **Transform-managed** (entity has a `Transform`; {@link FluidSystem} 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
- *     same wake. (Advancing in `apply` would hand the whole segment to whichever
- *     field stepped first and a zero segment to the rest.)
- *
- *   - **Manually driven** (user code sets {@link position} directly; no sync):
- *     `apply` advances the trail after splatting, so consecutive applies follow
- *     the moving source. With multiple fields this mode gives the segment to the
- *     first field only — pair manual driving with a single field, or call
- *     {@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.
- *
- * When the entity carrying a {@link FluidEffectorsComponent} also has a Transform,
- * {@link FluidSystem} 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]`.
- *
- * For sources you position manually (no Transform on the entity, or no entity at
- * all), call {@link reset_trail} once after the initial placement and after any
- * teleport so the next apply doesn't splat a wake across the jump.
- */
-export class WakeFluidEffector extends AbstractFluidEffector {
-
-    /**
-     * Current world-space position of the source. Updated each step from the entity
-     * Transform (via {@link syncFromTransform}) when one is available, otherwise set
-     * by user code before each step.
-     * @type {[number, number, number]}
-     */
-    position = [0, 0, 0];
-
-    /**
-     * Position at the start of the swept segment, world space. Advanced to
-     * `position` by {@link syncFromTransform} (transform-managed mode) or at the
-     * end of {@link apply} (manual mode) — see the class docstring. Caller
-     * normally doesn't touch it directly.
-     * @type {[number, number, number]}
-     */
-    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).
-     * @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.
-     * @type {number}
-     */
-    strength = 1;
-
-    /**
-     * True when a sync has adopted a position since construction / the last
-     * {@link reset_trail}. While false, the next {@link syncFromTransform} seeds
-     * `previous_position = position` instead of advancing the trail — suppressing
-     * a spurious wake from the origin or across a teleport.
-     * @type {boolean}
-     */
-    #initialized = false;
-
-    /**
-     * True once {@link syncFromTransform} has ever been called — the effector is
-     * driven by an entity Transform via {@link FluidSystem}. 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;
-
-    /**
-     * Snap {@link previous_position} to {@link position} and mark the trail as
-     * needing a re-seed. Call after manual initial placement and after any
-     * teleport (in either driving mode) so the next splat doesn't sweep a wake
-     * across the jump.
-     */
-    reset_trail() {
-        this.previous_position[0] = this.position[0];
-        this.previous_position[1] = this.position[1];
-        this.previous_position[2] = this.position[2];
-        this.#initialized = false;
-    }
-
-    /**
-     * Pull world-space position off the entity Transform 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
-     * fixed update, before any field is stepped — so every field stepped this
-     * tick sees the same one-tick segment.
-     *
-     * The first call (and the first after {@link reset_trail}) seeds
-     * `previous_position = position` instead, suppressing a wake from the origin
-     * or across a teleport.
-     *
-     * @param {Transform} transform
-     */
-    syncFromTransform(transform) {
-        const p = transform.position;
-        this.#transform_managed = true;
-        if (this.#initialized) {
-            this.previous_position[0] = this.position[0];
-            this.previous_position[1] = this.position[1];
-            this.previous_position[2] = this.position[2];
-        }
-        this.position[0] = p.x;
-        this.position[1] = p.y;
-        this.position[2] = p.z;
-        if (!this.#initialized) {
-            this.previous_position[0] = p.x;
-            this.previous_position[1] = p.y;
-            this.previous_position[2] = p.z;
-            this.#initialized = true;
-        }
-    }
-
-    /**
-     * @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 || 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;
-        }
-
-        // 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;
-        }
-
-        // 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;
-                    }
-                }
-            }
-        }
-
-        // 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;
-                    }
-                }
-            }
-        }
-
-        // 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;
-                    }
-                }
-            }
-        }
-
-        this.#advance_trail_if_manual();
-    }
-
-    /**
-     * Manual-mode trail bookkeeping: shift `previous_position` to `position` so
-     * the next apply() picks up where this one left off. Transform-managed
-     * effectors skip this — their trail advances in {@link syncFromTransform},
-     * keeping apply() pure so the same segment serves every field in the step.
-     */
-    #advance_trail_if_manual() {
-        if (this.#transform_managed) {
-            return;
-        }
-        this.previous_position[0] = this.position[0];
-        this.previous_position[1] = this.position[1];
-        this.previous_position[2] = this.position[2];
-    }
-
-    /**
-     * @param {AbstractFluidEffector} other
-     * @return {boolean}
-     */
-    equals(other) {
-        if (other === this) {
-            return true;
-        }
-        if (!(other instanceof WakeFluidEffector)) {
-            return false;
-        }
-        return 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.previous_position[0] === other.previous_position[0]
-            && this.previous_position[1] === other.previous_position[1]
-            && this.previous_position[2] === other.previous_position[2];
-    }
-
-    /**
-     * @return {number}
-     */
-    hash() {
-        return combine_hash(
-            computeHashFloat(this.position[0]),
-            computeHashFloat(this.position[1]),
-            computeHashFloat(this.position[2]),
-            computeHashFloat(this.previous_position[0]),
-            computeHashFloat(this.previous_position[1]),
-            computeHashFloat(this.previous_position[2]),
-            computeHashFloat(this.radius),
-            computeHashFloat(this.strength)
-        );
-    }
-
-    /**
-     * 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
-     * clamp.
-     *
-     * @param {AABB3} out
-     */
-    getBoundingBox(out) {
-        const r = this.radius;
-        const px = this.position[0];
-        const py = this.position[1];
-        const pz = this.position[2];
-        const ppx = this.previous_position[0];
-        const ppy = this.previous_position[1];
-        const ppz = this.previous_position[2];
-        out.setBounds(
-            Math.min(px, ppx) - r,
-            Math.min(py, ppy) - r,
-            Math.min(pz, ppz) - r,
-            Math.max(px, ppx) + r,
-            Math.max(py, ppy) + r,
-            Math.max(pz, ppz) + r
-        );
-    }
-}
+import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import { v3_matrix4_multiply } from "../../../../core/geom/vec3/v3_matrix4_multiply.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
+
+const scratch_a = new Float32Array(3);
+const scratch_b = new Float32Array(3);
+
+/**
+ * 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.
+ *
+ * Trail advancement (copying `position` into `previous_position`) depends on who
+ * drives the effector:
+ *
+ *   - **Transform-managed** (entity has a `Transform`; {@link FluidSystem} 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
+ *     same wake. (Advancing in `apply` would hand the whole segment to whichever
+ *     field stepped first and a zero segment to the rest.)
+ *
+ *   - **Manually driven** (user code sets {@link position} directly; no sync):
+ *     `apply` advances the trail after splatting, so consecutive applies follow
+ *     the moving source. With multiple fields this mode gives the segment to the
+ *     first field only — pair manual driving with a single field, or call
+ *     {@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.
+ *
+ * When the entity carrying a {@link FluidEffectorsComponent} also has a Transform,
+ * {@link FluidSystem} 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]`.
+ *
+ * For sources you position manually (no Transform on the entity, or no entity at
+ * all), call {@link reset_trail} once after the initial placement and after any
+ * teleport so the next apply doesn't splat a wake across the jump.
+ */
+export class WakeFluidEffector extends AbstractFluidEffector {
+
+    /**
+     * Current world-space position of the source. Updated each step from the entity
+     * Transform (via {@link syncFromTransform}) when one is available, otherwise set
+     * by user code before each step.
+     * @type {[number, number, number]}
+     */
+    position = [0, 0, 0];
+
+    /**
+     * Position at the start of the swept segment, world space. Advanced to
+     * `position` by {@link syncFromTransform} (transform-managed mode) or at the
+     * end of {@link apply} (manual mode) — see the class docstring. Caller
+     * normally doesn't touch it directly.
+     * @type {[number, number, number]}
+     */
+    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).
+     * @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.
+     * @type {number}
+     */
+    strength = 1;
+
+    /**
+     * True when a sync has adopted a position since construction / the last
+     * {@link reset_trail}. While false, the next {@link syncFromTransform} seeds
+     * `previous_position = position` instead of advancing the trail — suppressing
+     * a spurious wake from the origin or across a teleport.
+     * @type {boolean}
+     */
+    #initialized = false;
+
+    /**
+     * True once {@link syncFromTransform} has ever been called — the effector is
+     * driven by an entity Transform via {@link FluidSystem}. 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;
+
+    /**
+     * Snap {@link previous_position} to {@link position} and mark the trail as
+     * needing a re-seed. Call after manual initial placement and after any
+     * teleport (in either driving mode) so the next splat doesn't sweep a wake
+     * across the jump.
+     */
+    reset_trail() {
+        this.previous_position[0] = this.position[0];
+        this.previous_position[1] = this.position[1];
+        this.previous_position[2] = this.position[2];
+        this.#initialized = false;
+    }
+
+    /**
+     * Pull world-space position off the entity Transform 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
+     * fixed update, before any field is stepped — so every field stepped this
+     * tick sees the same one-tick segment.
+     *
+     * The first call (and the first after {@link reset_trail}) seeds
+     * `previous_position = position` instead, suppressing a wake from the origin
+     * or across a teleport.
+     *
+     * @param {Transform} transform
+     */
+    syncFromTransform(transform) {
+        const p = transform.position;
+        this.#transform_managed = true;
+        if (this.#initialized) {
+            this.previous_position[0] = this.position[0];
+            this.previous_position[1] = this.position[1];
+            this.previous_position[2] = this.position[2];
+        }
+        this.position[0] = p.x;
+        this.position[1] = p.y;
+        this.position[2] = p.z;
+        if (!this.#initialized) {
+            this.previous_position[0] = p.x;
+            this.previous_position[1] = p.y;
+            this.previous_position[2] = p.z;
+            this.#initialized = true;
+        }
+    }
+
+    /**
+     * @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 || 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;
+        }
+
+        // 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;
+        }
+
+        // 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;
+                    }
+                }
+            }
+        }
+
+        // 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;
+                    }
+                }
+            }
+        }
+
+        // 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;
+                    }
+                }
+            }
+        }
+
+        this.#advance_trail_if_manual();
+    }
+
+    /**
+     * Manual-mode trail bookkeeping: shift `previous_position` to `position` so
+     * the next apply() picks up where this one left off. Transform-managed
+     * effectors skip this — their trail advances in {@link syncFromTransform},
+     * keeping apply() pure so the same segment serves every field in the step.
+     */
+    #advance_trail_if_manual() {
+        if (this.#transform_managed) {
+            return;
+        }
+        this.previous_position[0] = this.position[0];
+        this.previous_position[1] = this.position[1];
+        this.previous_position[2] = this.position[2];
+    }
+
+    /**
+     * @param {AbstractFluidEffector} other
+     * @return {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+        if (!(other instanceof WakeFluidEffector)) {
+            return false;
+        }
+        return 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.previous_position[0] === other.previous_position[0]
+            && this.previous_position[1] === other.previous_position[1]
+            && this.previous_position[2] === other.previous_position[2];
+    }
+
+    /**
+     * @return {number}
+     */
+    hash() {
+        return combine_hash(
+            computeHashFloat(this.position[0]),
+            computeHashFloat(this.position[1]),
+            computeHashFloat(this.position[2]),
+            computeHashFloat(this.previous_position[0]),
+            computeHashFloat(this.previous_position[1]),
+            computeHashFloat(this.previous_position[2]),
+            computeHashFloat(this.radius),
+            computeHashFloat(this.strength)
+        );
+    }
+
+    /**
+     * 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
+     * clamp.
+     *
+     * @param {AABB3} out
+     */
+    getBoundingBox(out) {
+        const r = this.radius;
+        const px = this.position[0];
+        const py = this.position[1];
+        const pz = this.position[2];
+        const ppx = this.previous_position[0];
+        const ppy = this.previous_position[1];
+        const ppz = this.previous_position[2];
+        out.setBounds(
+            Math.min(px, ppx) - r,
+            Math.min(py, ppy) - r,
+            Math.min(pz, ppz) - r,
+            Math.max(px, ppx) + r,
+            Math.max(py, ppy) + r,
+            Math.max(pz, ppz) + r
+        );
+    }
+}