@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,348 +1,348 @@
-import { PosedShape3D } from "../../../../core/geom/3d/shape/PosedShape3D.js";
-import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
-import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
-import { System } from "../../../ecs/System.js";
-import { Transform } from "../../../ecs/transform/Transform.js";
-import { Collider } from "../../ecs/Collider.js";
-import { RigidBody } from "../../ecs/RigidBody.js";
-import { FluidComponent } from "./FluidComponent.js";
-import { FluidObstacle } from "./FluidObstacle.js";
-
-/**
- * ECS system that voxelizes collider geometry into fluid solid masks and
- * stamps rigid-body velocities onto the walls as moving-wall boundary
- * conditions.
- *
- * Every fixed update, each entity carrying ({@link FluidObstacle},
- * {@link Collider}, {@link RigidBody}, {@link Transform}) — the same tuple
- * {@link PhysicsSystem} simulates, plus the marker — is swept against every
- * {@link FluidComponent}: the collider's shape — posed rigidly at the
- * transform's position/rotation via {@link PosedShape3D} — is sampled at the
- * centre of every fluid cell inside its world AABB, and cells whose signed
- * distance is `<= obstacle.inflation` become solid. The fluid then treats
- * those cells exactly like hand-authored walls: faces pinned, pressure
- * Neumann, traces clipped.
- *
- * **Ownership contract**: while at least one obstacle exists, this system
- * OWNS the solid mask of every fluid field — masks are cleared and rebuilt
- * from scratch each tick, so moving obstacles leave no stale walls behind.
- * Hand-written `setSolidAt` state will be wiped; mix the two styles only by
- * expressing the static geometry as obstacle entities too (a `BoxShape3D`
- * collider is cheaper to author than a splat loop anyway). With NO obstacles
- * present the system leaves every mask untouched.
- *
- * **Moving walls — the wall-velocity specification**:
- *
- *   - The velocity source is `RigidBody.linearVelocity` (world m/s) — the
- *     SAME value the contact solver resolves against, so air and contacts
- *     always agree on how fast a wall moves. It is stamped onto every face
- *     of every cell the obstacle voxelized (converted to grid units per
- *     field); the projection's divergence reads pinned faces at face value,
- *     so a moving collider genuinely pushes and drags the air around it.
- *   - Pose is still read from `Transform`; velocity is NOT derived from
- *     pose deltas. A teleported body (spawn snap, network correction)
- *     relocates its walls but stamps no velocity — no one-tick air blast.
- *     This mirrors the engine's own contact-solver rule: see
- *     {@link BodyKind}.KinematicPosition, deferred for exactly this reason.
- *     Consequently pose-animated colliders read as stationary walls that
- *     teleport, for air just as for contacts — drive movers through
- *     `BodyKind.KinematicVelocity` (or Dynamic) to displace air.
- *   - `BodyKind.Static` bodies have zero velocity and stamp nothing.
- *     Sleeping bodies stamp nothing either — the solver zeroes velocities
- *     on sleep.
- *   - A body that stops stamps ONE extra pass of zeros
- *     (`FluidObstacle._was_moving`): pinned faces preserve their values
- *     across mask recomputes by design, so without it a stale moving BC
- *     would drive phantom inflow forever.
- *   - A retreating wall leaves its velocity behind on unpinned faces as the
- *     wake seed for the fluid that takes its place.
- *   - Rotation-induced surface velocity (ω × r from
- *     `RigidBody.angularVelocity`) is not modelled yet — fast spinners read
- *     as translating walls only (follow-up in REVIEW_02_PLAN.md).
- *
- * **Ordering**: register AFTER {@link PhysicsSystem} (so this tick's solved
- * velocities and integrated poses are read) and BEFORE {@link FluidSystem}
- * (so the simulation step sees this tick's walls and wall velocities).
- * Engine systems run in registration order.
- *
- * Cost: clearing is O(cells) per field; voxelization is one
- * `signed_distance_at_point` per cell inside each obstacle's AABB ∩ field.
- * Static scenes pay the same as moving ones — change detection is a
- * follow-up (REVIEW_02_PLAN.md) if profiling ever points here.
- */
-export class FluidObstacleSystem extends System {
-
-    dependencies = [FluidObstacle];
-
-    components_used = [
-        ResourceAccessSpecification.from(FluidObstacle, ResourceAccessKind.Read),
-        ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read),
-        ResourceAccessSpecification.from(RigidBody, ResourceAccessKind.Read),
-        ResourceAccessSpecification.from(Transform, ResourceAccessKind.Read),
-        // Solid masks are rewritten each tick.
-        ResourceAccessSpecification.from(FluidComponent, ResourceAccessKind.Read | ResourceAccessKind.Write),
-    ];
-
-    /**
-     * Reusable rigid-pose adapter, rebound per obstacle per tick.
-     * @type {PosedShape3D}
-     */
-    #posed = new PosedShape3D();
-
-    /**
-     * World AABB scratch for the current posed shape (x0,y0,z0,x1,y1,z1).
-     * @type {Float64Array}
-     */
-    #aabb = new Float64Array(6);
-
-    /**
-     * World-space point scratch for per-cell SDF queries.
-     * @type {Float64Array}
-     */
-    #point = new Float64Array(3);
-
-    /**
-     * @param {number} time_delta_seconds
-     */
-    fixedUpdate(time_delta_seconds) {
-        const em = this.entityManager;
-        if (em === null) {
-            return;
-        }
-        const ecd = em.dataset;
-        if (ecd === null) {
-            return;
-        }
-
-        // With no obstacles the system must not touch any mask — fields with
-        // hand-authored solids keep them.
-        let obstacle_count = 0;
-        ecd.traverseEntities([FluidObstacle, Collider, RigidBody, Transform], function () {
-            obstacle_count++;
-        });
-        if (obstacle_count === 0) {
-            return;
-        }
-
-        // Clear every field's mask, then accumulate every obstacle into every
-        // overlapping field. Solids are world-anchored; rebuilding from
-        // scratch each tick is what keeps moving obstacles honest.
-        ecd.traverseComponents(FluidComponent, FluidObstacleSystem.#clear_field);
-
-        const posed = this.#posed;
-        const aabb = this.#aabb;
-        const point = this.#point;
-
-        ecd.traverseEntities([FluidObstacle, Collider, RigidBody, Transform], function (obstacle, collider, body, transform) {
-            posed.setup(collider.shape, transform.position, transform.rotation);
-            posed.compute_bounding_box(aabb);
-
-            ecd.traverseComponents(FluidComponent, function (fluid) {
-                FluidObstacleSystem.#voxelize(fluid, posed, aabb, obstacle.inflation, point);
-            });
-        });
-
-        // Refresh each field's derived masks NOW so the unpinned→pinned
-        // transitions are consumed here (zeroing those faces to the static
-        // default). The moving-wall velocities written below then survive the
-        // simulator's own per-step refresh — already-pinned faces keep their
-        // values (see v3_mac_compute_face_solid).
-        ecd.traverseComponents(FluidComponent, FluidObstacleSystem.#refresh_masks);
-
-        // Second pass: moving bodies stamp their velocity onto the faces of
-        // the cells they voxelized — the MAC moving-wall boundary condition.
-        // The divergence reads these values, so the wall genuinely pushes
-        // (and pulls) the surrounding fluid. The source is the solver's own
-        // linearVelocity, NOT a pose delta — teleports stamp nothing.
-        ecd.traverseEntities([FluidObstacle, Collider, RigidBody, Transform], function (obstacle, collider, body, transform) {
-            const lv = body.linearVelocity;
-            const vx = lv.x;
-            const vy = lv.y;
-            const vz = lv.z;
-
-            const moving = vx !== 0 || vy !== 0 || vz !== 0;
-
-            // Stamp while moving, plus ONE extra pass on the tick the body
-            // stops (or falls asleep — the solver zeroes velocities on
-            // sleep): pinned faces preserve their values across mask
-            // recomputes, so a stopped wall must overwrite its stale moving
-            // BC with zeros or the projection keeps seeing phantom inflow.
-            // Bodies that never move never pay for this pass.
-            if (moving || obstacle._was_moving) {
-                posed.setup(collider.shape, transform.position, transform.rotation);
-                posed.compute_bounding_box(aabb);
-                ecd.traverseComponents(FluidComponent, function (fluid) {
-                    FluidObstacleSystem.#stamp_wall_velocity(
-                        fluid, posed, aabb, obstacle.inflation, point, vx, vy, vz);
-                });
-            }
-
-            obstacle._was_moving = moving;
-        });
-    }
-
-    /**
-     * @param {FluidComponent} fluid
-     */
-    static #refresh_masks(fluid) {
-        fluid.field.recomputeSolidNeighbourMask();
-    }
-
-    /**
-     * @param {FluidComponent} fluid
-     */
-    static #clear_field(fluid) {
-        const solid = fluid.field.solid;
-        if (solid !== null) {
-            solid.fill(0);
-        }
-    }
-
-    /**
-     * Mark every cell of `fluid` whose centre lies within `inflation` of the
-     * posed shape as solid. Iteration is clipped to the shape's world AABB
-     * (grown by `inflation`), so far-away obstacles cost nothing.
-     *
-     * @param {FluidComponent} fluid
-     * @param {PosedShape3D} posed
-     * @param {Float64Array} aabb      world AABB of the posed shape
-     * @param {number} inflation       world-units SDF threshold
-     * @param {Float64Array} point     length-3 scratch
-     */
-    static #voxelize(fluid, posed, aabb, inflation, point) {
-        const field = fluid.field;
-        const solid = field.solid;
-        if (solid === null) {
-            return; // field not built yet
-        }
-
-        const res = field.getResolution();
-        const cs = fluid.cell_size;
-        const inv_cs = 1 / cs;
-        const origin = fluid.origin;
-
-        // Index range of cell centres inside the inflated AABB, clamped.
-        let x_min = Math.ceil((aabb[0] - inflation - origin[0]) * inv_cs);
-        let y_min = Math.ceil((aabb[1] - inflation - origin[1]) * inv_cs);
-        let z_min = Math.ceil((aabb[2] - inflation - origin[2]) * inv_cs);
-        let x_max = Math.floor((aabb[3] + inflation - origin[0]) * inv_cs);
-        let y_max = Math.floor((aabb[4] + inflation - origin[1]) * inv_cs);
-        let z_max = Math.floor((aabb[5] + inflation - origin[2]) * inv_cs);
-
-        if (x_min < 0) x_min = 0;
-        if (y_min < 0) y_min = 0;
-        if (z_min < 0) z_min = 0;
-        if (x_max >= res[0]) x_max = res[0] - 1;
-        if (y_max >= res[1]) y_max = res[1] - 1;
-        if (z_max >= res[2]) z_max = res[2] - 1;
-
-        if (x_min > x_max || y_min > y_max || z_min > z_max) {
-            return; // no overlap with this field
-        }
-
-        const slice = res[0] * res[1];
-
-        for (let z = z_min; z <= z_max; z++) {
-            const z_off = z * slice;
-            point[2] = origin[2] + z * cs;
-            for (let y = y_min; y <= y_max; y++) {
-                const y_off = z_off + y * res[0];
-                point[1] = origin[1] + y * cs;
-                for (let x = x_min; x <= x_max; x++) {
-                    point[0] = origin[0] + x * cs;
-                    if (posed.signed_distance_at_point(point) <= inflation) {
-                        solid[y_off + x] = 1;
-                    }
-                }
-            }
-        }
-    }
-
-    /**
-     * Write the obstacle's translation velocity onto every face of every cell
-     * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
-     * refresh, so the values stick (already-pinned faces keep their stored
-     * velocity through subsequent recomputes).
-     *
-     * Velocity is converted to grid units (cells/second) per field. Where
-     * obstacles overlap, the later-visited one wins on shared faces — both
-     * claims are walls, the disagreement is sub-cell.
-     *
-     * @param {FluidComponent} fluid
-     * @param {PosedShape3D} posed
-     * @param {Float64Array} aabb
-     * @param {number} inflation
-     * @param {Float64Array} point
-     * @param {number} wvx  world-units-per-second obstacle velocity
-     * @param {number} wvy
-     * @param {number} wvz
-     */
-    static #stamp_wall_velocity(fluid, posed, aabb, inflation, point, wvx, wvy, wvz) {
-        const field = fluid.field;
-        const solid = field.solid;
-        if (solid === null) {
-            return;
-        }
-
-        const res = field.getResolution();
-        const cs = fluid.cell_size;
-        const inv_cs = 1 / cs;
-        const origin = fluid.origin;
-
-        // Grid-units wall velocity (cells per second).
-        const gvx = wvx * inv_cs;
-        const gvy = wvy * inv_cs;
-        const gvz = wvz * inv_cs;
-
-        let x_min = Math.ceil((aabb[0] - inflation - origin[0]) * inv_cs);
-        let y_min = Math.ceil((aabb[1] - inflation - origin[1]) * inv_cs);
-        let z_min = Math.ceil((aabb[2] - inflation - origin[2]) * inv_cs);
-        let x_max = Math.floor((aabb[3] + inflation - origin[0]) * inv_cs);
-        let y_max = Math.floor((aabb[4] + inflation - origin[1]) * inv_cs);
-        let z_max = Math.floor((aabb[5] + inflation - origin[2]) * inv_cs);
-
-        if (x_min < 0) x_min = 0;
-        if (y_min < 0) y_min = 0;
-        if (z_min < 0) z_min = 0;
-        if (x_max >= res[0]) x_max = res[0] - 1;
-        if (y_max >= res[1]) y_max = res[1] - 1;
-        if (z_max >= res[2]) z_max = res[2] - 1;
-
-        if (x_min > x_max || y_min > y_max || z_min > z_max) {
-            return;
-        }
-
-        const rx = res[0];
-        const ry = res[1];
-        const slice = rx * ry;
-        const sx = rx + 1;
-        const vel_u = field.velocity_x;
-        const vel_v = field.velocity_y;
-        const vel_w = field.velocity_z;
-
-        for (let z = z_min; z <= z_max; z++) {
-            point[2] = origin[2] + z * cs;
-            for (let y = y_min; y <= y_max; y++) {
-                point[1] = origin[1] + y * cs;
-                for (let x = x_min; x <= x_max; x++) {
-                    point[0] = origin[0] + x * cs;
-                    // Re-test ownership: only this obstacle's own cells get
-                    // its velocity (the solid mask may contain other walls).
-                    if (posed.signed_distance_at_point(point) > inflation) {
-                        continue;
-                    }
-                    // All six faces of a solid cell are pinned by definition.
-                    const u = z * sx * ry + y * sx + x;
-                    vel_u[u] = gvx;
-                    vel_u[u + 1] = gvx;
-                    const v = z * rx * (ry + 1) + y * rx + x;
-                    vel_v[v] = gvy;
-                    vel_v[v + rx] = gvy;
-                    const w = z * slice + y * rx + x;
-                    vel_w[w] = gvz;
-                    vel_w[w + slice] = gvz;
-                }
-            }
-        }
-    }
-}
+import { PosedShape3D } from "../../../../core/geom/3d/shape/PosedShape3D.js";
+import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { System } from "../../../ecs/System.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { Collider } from "../../ecs/Collider.js";
+import { RigidBody } from "../../ecs/RigidBody.js";
+import { FluidComponent } from "./FluidComponent.js";
+import { FluidObstacle } from "./FluidObstacle.js";
+
+/**
+ * ECS system that voxelizes collider geometry into fluid solid masks and
+ * stamps rigid-body velocities onto the walls as moving-wall boundary
+ * conditions.
+ *
+ * Every fixed update, each entity carrying ({@link FluidObstacle},
+ * {@link Collider}, {@link RigidBody}, {@link Transform}) — the same tuple
+ * {@link PhysicsSystem} simulates, plus the marker — is swept against every
+ * {@link FluidComponent}: the collider's shape — posed rigidly at the
+ * transform's position/rotation via {@link PosedShape3D} — is sampled at the
+ * centre of every fluid cell inside its world AABB, and cells whose signed
+ * distance is `<= obstacle.inflation` become solid. The fluid then treats
+ * those cells exactly like hand-authored walls: faces pinned, pressure
+ * Neumann, traces clipped.
+ *
+ * **Ownership contract**: while at least one obstacle exists, this system
+ * OWNS the solid mask of every fluid field — masks are cleared and rebuilt
+ * from scratch each tick, so moving obstacles leave no stale walls behind.
+ * Hand-written `setSolidAt` state will be wiped; mix the two styles only by
+ * expressing the static geometry as obstacle entities too (a `BoxShape3D`
+ * collider is cheaper to author than a splat loop anyway). With NO obstacles
+ * present the system leaves every mask untouched.
+ *
+ * **Moving walls — the wall-velocity specification**:
+ *
+ *   - The velocity source is `RigidBody.linearVelocity` (world m/s) — the
+ *     SAME value the contact solver resolves against, so air and contacts
+ *     always agree on how fast a wall moves. It is stamped onto every face
+ *     of every cell the obstacle voxelized (converted to grid units per
+ *     field); the projection's divergence reads pinned faces at face value,
+ *     so a moving collider genuinely pushes and drags the air around it.
+ *   - Pose is still read from `Transform`; velocity is NOT derived from
+ *     pose deltas. A teleported body (spawn snap, network correction)
+ *     relocates its walls but stamps no velocity — no one-tick air blast.
+ *     This mirrors the engine's own contact-solver rule: see
+ *     {@link BodyKind}.KinematicPosition, deferred for exactly this reason.
+ *     Consequently pose-animated colliders read as stationary walls that
+ *     teleport, for air just as for contacts — drive movers through
+ *     `BodyKind.KinematicVelocity` (or Dynamic) to displace air.
+ *   - `BodyKind.Static` bodies have zero velocity and stamp nothing.
+ *     Sleeping bodies stamp nothing either — the solver zeroes velocities
+ *     on sleep.
+ *   - A body that stops stamps ONE extra pass of zeros
+ *     (`FluidObstacle._was_moving`): pinned faces preserve their values
+ *     across mask recomputes by design, so without it a stale moving BC
+ *     would drive phantom inflow forever.
+ *   - A retreating wall leaves its velocity behind on unpinned faces as the
+ *     wake seed for the fluid that takes its place.
+ *   - Rotation-induced surface velocity (ω × r from
+ *     `RigidBody.angularVelocity`) is not modelled yet — fast spinners read
+ *     as translating walls only (follow-up in REVIEW_02_PLAN.md).
+ *
+ * **Ordering**: register AFTER {@link PhysicsSystem} (so this tick's solved
+ * velocities and integrated poses are read) and BEFORE {@link FluidSystem}
+ * (so the simulation step sees this tick's walls and wall velocities).
+ * Engine systems run in registration order.
+ *
+ * Cost: clearing is O(cells) per field; voxelization is one
+ * `signed_distance_at_point` per cell inside each obstacle's AABB ∩ field.
+ * Static scenes pay the same as moving ones — change detection is a
+ * follow-up (REVIEW_02_PLAN.md) if profiling ever points here.
+ */
+export class FluidObstacleSystem extends System {
+
+    dependencies = [FluidObstacle];
+
+    components_used = [
+        ResourceAccessSpecification.from(FluidObstacle, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(RigidBody, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Transform, ResourceAccessKind.Read),
+        // Solid masks are rewritten each tick.
+        ResourceAccessSpecification.from(FluidComponent, ResourceAccessKind.Read | ResourceAccessKind.Write),
+    ];
+
+    /**
+     * Reusable rigid-pose adapter, rebound per obstacle per tick.
+     * @type {PosedShape3D}
+     */
+    #posed = new PosedShape3D();
+
+    /**
+     * World AABB scratch for the current posed shape (x0,y0,z0,x1,y1,z1).
+     * @type {Float64Array}
+     */
+    #aabb = new Float64Array(6);
+
+    /**
+     * World-space point scratch for per-cell SDF queries.
+     * @type {Float64Array}
+     */
+    #point = new Float64Array(3);
+
+    /**
+     * @param {number} time_delta_seconds
+     */
+    fixedUpdate(time_delta_seconds) {
+        const em = this.entityManager;
+        if (em === null) {
+            return;
+        }
+        const ecd = em.dataset;
+        if (ecd === null) {
+            return;
+        }
+
+        // With no obstacles the system must not touch any mask — fields with
+        // hand-authored solids keep them.
+        let obstacle_count = 0;
+        ecd.traverseEntities([FluidObstacle, Collider, RigidBody, Transform], function () {
+            obstacle_count++;
+        });
+        if (obstacle_count === 0) {
+            return;
+        }
+
+        // Clear every field's mask, then accumulate every obstacle into every
+        // overlapping field. Solids are world-anchored; rebuilding from
+        // scratch each tick is what keeps moving obstacles honest.
+        ecd.traverseComponents(FluidComponent, FluidObstacleSystem.#clear_field);
+
+        const posed = this.#posed;
+        const aabb = this.#aabb;
+        const point = this.#point;
+
+        ecd.traverseEntities([FluidObstacle, Collider, RigidBody, Transform], function (obstacle, collider, body, transform) {
+            posed.setup(collider.shape, transform.position, transform.rotation);
+            posed.compute_bounding_box(aabb);
+
+            ecd.traverseComponents(FluidComponent, function (fluid) {
+                FluidObstacleSystem.#voxelize(fluid, posed, aabb, obstacle.inflation, point);
+            });
+        });
+
+        // Refresh each field's derived masks NOW so the unpinned→pinned
+        // transitions are consumed here (zeroing those faces to the static
+        // default). The moving-wall velocities written below then survive the
+        // simulator's own per-step refresh — already-pinned faces keep their
+        // values (see v3_mac_compute_face_solid).
+        ecd.traverseComponents(FluidComponent, FluidObstacleSystem.#refresh_masks);
+
+        // Second pass: moving bodies stamp their velocity onto the faces of
+        // the cells they voxelized — the MAC moving-wall boundary condition.
+        // The divergence reads these values, so the wall genuinely pushes
+        // (and pulls) the surrounding fluid. The source is the solver's own
+        // linearVelocity, NOT a pose delta — teleports stamp nothing.
+        ecd.traverseEntities([FluidObstacle, Collider, RigidBody, Transform], function (obstacle, collider, body, transform) {
+            const lv = body.linearVelocity;
+            const vx = lv.x;
+            const vy = lv.y;
+            const vz = lv.z;
+
+            const moving = vx !== 0 || vy !== 0 || vz !== 0;
+
+            // Stamp while moving, plus ONE extra pass on the tick the body
+            // stops (or falls asleep — the solver zeroes velocities on
+            // sleep): pinned faces preserve their values across mask
+            // recomputes, so a stopped wall must overwrite its stale moving
+            // BC with zeros or the projection keeps seeing phantom inflow.
+            // Bodies that never move never pay for this pass.
+            if (moving || obstacle._was_moving) {
+                posed.setup(collider.shape, transform.position, transform.rotation);
+                posed.compute_bounding_box(aabb);
+                ecd.traverseComponents(FluidComponent, function (fluid) {
+                    FluidObstacleSystem.#stamp_wall_velocity(
+                        fluid, posed, aabb, obstacle.inflation, point, vx, vy, vz);
+                });
+            }
+
+            obstacle._was_moving = moving;
+        });
+    }
+
+    /**
+     * @param {FluidComponent} fluid
+     */
+    static #refresh_masks(fluid) {
+        fluid.field.recomputeSolidNeighbourMask();
+    }
+
+    /**
+     * @param {FluidComponent} fluid
+     */
+    static #clear_field(fluid) {
+        const solid = fluid.field.solid;
+        if (solid !== null) {
+            solid.fill(0);
+        }
+    }
+
+    /**
+     * Mark every cell of `fluid` whose centre lies within `inflation` of the
+     * posed shape as solid. Iteration is clipped to the shape's world AABB
+     * (grown by `inflation`), so far-away obstacles cost nothing.
+     *
+     * @param {FluidComponent} fluid
+     * @param {PosedShape3D} posed
+     * @param {Float64Array} aabb      world AABB of the posed shape
+     * @param {number} inflation       world-units SDF threshold
+     * @param {Float64Array} point     length-3 scratch
+     */
+    static #voxelize(fluid, posed, aabb, inflation, point) {
+        const field = fluid.field;
+        const solid = field.solid;
+        if (solid === null) {
+            return; // field not built yet
+        }
+
+        const res = field.getResolution();
+        const cs = fluid.cell_size;
+        const inv_cs = 1 / cs;
+        const origin = fluid.origin;
+
+        // Index range of cell centres inside the inflated AABB, clamped.
+        let x_min = Math.ceil((aabb[0] - inflation - origin[0]) * inv_cs);
+        let y_min = Math.ceil((aabb[1] - inflation - origin[1]) * inv_cs);
+        let z_min = Math.ceil((aabb[2] - inflation - origin[2]) * inv_cs);
+        let x_max = Math.floor((aabb[3] + inflation - origin[0]) * inv_cs);
+        let y_max = Math.floor((aabb[4] + inflation - origin[1]) * inv_cs);
+        let z_max = Math.floor((aabb[5] + inflation - origin[2]) * inv_cs);
+
+        if (x_min < 0) x_min = 0;
+        if (y_min < 0) y_min = 0;
+        if (z_min < 0) z_min = 0;
+        if (x_max >= res[0]) x_max = res[0] - 1;
+        if (y_max >= res[1]) y_max = res[1] - 1;
+        if (z_max >= res[2]) z_max = res[2] - 1;
+
+        if (x_min > x_max || y_min > y_max || z_min > z_max) {
+            return; // no overlap with this field
+        }
+
+        const slice = res[0] * res[1];
+
+        for (let z = z_min; z <= z_max; z++) {
+            const z_off = z * slice;
+            point[2] = origin[2] + z * cs;
+            for (let y = y_min; y <= y_max; y++) {
+                const y_off = z_off + y * res[0];
+                point[1] = origin[1] + y * cs;
+                for (let x = x_min; x <= x_max; x++) {
+                    point[0] = origin[0] + x * cs;
+                    if (posed.signed_distance_at_point(point) <= inflation) {
+                        solid[y_off + x] = 1;
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Write the obstacle's translation velocity onto every face of every cell
+     * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
+     * refresh, so the values stick (already-pinned faces keep their stored
+     * velocity through subsequent recomputes).
+     *
+     * Velocity is converted to grid units (cells/second) per field. Where
+     * obstacles overlap, the later-visited one wins on shared faces — both
+     * claims are walls, the disagreement is sub-cell.
+     *
+     * @param {FluidComponent} fluid
+     * @param {PosedShape3D} posed
+     * @param {Float64Array} aabb
+     * @param {number} inflation
+     * @param {Float64Array} point
+     * @param {number} wvx  world-units-per-second obstacle velocity
+     * @param {number} wvy
+     * @param {number} wvz
+     */
+    static #stamp_wall_velocity(fluid, posed, aabb, inflation, point, wvx, wvy, wvz) {
+        const field = fluid.field;
+        const solid = field.solid;
+        if (solid === null) {
+            return;
+        }
+
+        const res = field.getResolution();
+        const cs = fluid.cell_size;
+        const inv_cs = 1 / cs;
+        const origin = fluid.origin;
+
+        // Grid-units wall velocity (cells per second).
+        const gvx = wvx * inv_cs;
+        const gvy = wvy * inv_cs;
+        const gvz = wvz * inv_cs;
+
+        let x_min = Math.ceil((aabb[0] - inflation - origin[0]) * inv_cs);
+        let y_min = Math.ceil((aabb[1] - inflation - origin[1]) * inv_cs);
+        let z_min = Math.ceil((aabb[2] - inflation - origin[2]) * inv_cs);
+        let x_max = Math.floor((aabb[3] + inflation - origin[0]) * inv_cs);
+        let y_max = Math.floor((aabb[4] + inflation - origin[1]) * inv_cs);
+        let z_max = Math.floor((aabb[5] + inflation - origin[2]) * inv_cs);
+
+        if (x_min < 0) x_min = 0;
+        if (y_min < 0) y_min = 0;
+        if (z_min < 0) z_min = 0;
+        if (x_max >= res[0]) x_max = res[0] - 1;
+        if (y_max >= res[1]) y_max = res[1] - 1;
+        if (z_max >= res[2]) z_max = res[2] - 1;
+
+        if (x_min > x_max || y_min > y_max || z_min > z_max) {
+            return;
+        }
+
+        const rx = res[0];
+        const ry = res[1];
+        const slice = rx * ry;
+        const sx = rx + 1;
+        const vel_u = field.velocity_x;
+        const vel_v = field.velocity_y;
+        const vel_w = field.velocity_z;
+
+        for (let z = z_min; z <= z_max; z++) {
+            point[2] = origin[2] + z * cs;
+            for (let y = y_min; y <= y_max; y++) {
+                point[1] = origin[1] + y * cs;
+                for (let x = x_min; x <= x_max; x++) {
+                    point[0] = origin[0] + x * cs;
+                    // Re-test ownership: only this obstacle's own cells get
+                    // its velocity (the solid mask may contain other walls).
+                    if (posed.signed_distance_at_point(point) > inflation) {
+                        continue;
+                    }
+                    // All six faces of a solid cell are pinned by definition.
+                    const u = z * sx * ry + y * sx + x;
+                    vel_u[u] = gvx;
+                    vel_u[u + 1] = gvx;
+                    const v = z * rx * (ry + 1) + y * rx + x;
+                    vel_v[v] = gvy;
+                    vel_v[v + rx] = gvy;
+                    const w = z * slice + y * rx + x;
+                    vel_w[w] = gvz;
+                    vel_w[w + slice] = gvz;
+                }
+            }
+        }
+    }
+}