@woosh/meep-engine 2.169.6 → 2.170.0

package/src/engine/physics/fluid/FluidField.d.ts

@@ -27,6 +27,22 @@
  *      effector-driven design pattern this package is moving toward.
  */
 export class FluidField {
+    /**
+     * Build a field whose buffers view the memory described by `descriptor` —
+     * the counterpart to {@link getSharedDescriptor}, used on the worker side.
+     *
+     * The result is not a copy: writing through it is writing through the
+     * original.
+     *
+     * @param {{buffer: SharedArrayBuffer, resolution: number[], scalars: string[], half_precision_pressure: boolean}} descriptor
+     * @returns {FluidField}
+     */
+    static fromSharedDescriptor(descriptor: {
+        buffer: SharedArrayBuffer;
+        resolution: number[];
+        scalars: string[];
+        half_precision_pressure: boolean;
+    }): FluidField;
     /**
      * Velocity X component on x-faces. Length `(res_x+1) * res_y * res_z`,
      * indexed by `z * (res_x+1) * res_y + y * (res_x+1) + x` with
@@ -170,6 +186,27 @@ export class FluidField {
      * @type {boolean}
      */
     half_precision_pressure: boolean;
+    /**
+     * Back every buffer with a single {@link SharedArrayBuffer} instead of
+     * separate private allocations, so the field can be stepped by a worker
+     * thread in place — see {@link WorkerFluidSystem}.
+     *
+     * Must be set before {@link build}. Requires a cross-origin isolated page
+     * (`Cross-Origin-Opener-Policy: same-origin` +
+     * `Cross-Origin-Embedder-Policy: require-corp`); {@link build} throws
+     * otherwise rather than quietly falling back to private memory, which for a
+     * worker bridge would mean each thread mutating a copy the other never sees.
+     *
+     * One buffer rather than one per lattice so the whole field travels to the
+     * worker as a single object, and so the layout is described by
+     * {@link getSharedDescriptor} rather than a dozen handles.
+     *
+     * Has no effect on the field's semantics: the same buffers, the same
+     * contents, the same stable references.
+     *
+     * @type {boolean}
+     */
+    shared_memory: boolean;
     /**
      * Set the grid dimensions in cells. Must be called before {@link build}; throws if
      * the field is already built.
@@ -222,6 +259,23 @@ export class FluidField {
      * resolution and attribute set are frozen.
      */
     build(): void;
+    /**
+     * @returns {boolean} whether this field's buffers live in shared memory.
+     */
+    isSharedMemory(): boolean;
+    /**
+     * Everything another thread needs to attach to this exact field. Structured-
+     * cloneable, and cheap — the buffer is shared, not copied.
+     *
+     * @returns {{buffer: SharedArrayBuffer, resolution: number[], scalars: string[], half_precision_pressure: boolean}}
+     * @throws {Error} if the field is not shared-memory backed
+     */
+    getSharedDescriptor(): {
+        buffer: SharedArrayBuffer;
+        resolution: number[];
+        scalars: string[];
+        half_precision_pressure: boolean;
+    };
     /**
      * Linear cell index for integer grid coordinates.
      * @param {number} x integer in [0, res_x)

package/src/engine/physics/fluid/FluidField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidField.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidField.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAQI;;;;;;;OAOG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;OAIG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;;OAKG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;;;OAMG;IACH,OAFU,UAAU,GAAC,IAAI,CAEZ;IAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,sBAFU,UAAU,GAAC,IAAI,CAEG;IAE5B;;;;;;;OAOG;IACH,cAFU,UAAU,GAAC,IAAI,CAEL;IAEpB;;;OAGG;IACH,cAFU,UAAU,GAAC,IAAI,CAEL;IAEpB;;;OAGG;IACH,cAFU,UAAU,GAAC,IAAI,CAEL;IAEpB;;;;;;;;;;;;;;;;OAgBG;IACH,eAFU,UAAU,GAAC,IAAI,CAEJ;IAErB;;;;;;;;;;;;;OAaG;IACH,UAFU,YAAY,kBAAc,IAAI,CAExB;IAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,yBAFU,OAAO,CAEe;IAShC;;;;;;OAMG;IACH,qBAJW,MAAM,SACN,MAAM,SACN,MAAM,QAWhB;IAED;;;OAGG;IACH,iBAHY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAKnC;IAED;;;OAGG;IACH,aAHY,MAAM,CAKjB;IAED;;;;;;;;;OASG;IACH,gBAHW,MAAM,GACL,MAAM,CAejB;IAED;;;OAGG;IACH,kBAHW,MAAM,GACL,MAAM,CAIjB;IAED;;;;OAIG;IACH,oBAJW,MAAM,GACL,YAAY,GAAC,IAAI,CAM5B;IAED;;OAEG;IACH,uBAFY;QAAE,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE,CAIjD;IAED;;;OAGG;IACH,cA6BC;IAED;;;;;;OAMG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAajB;IAED;;;;;;;;;;;;OAYG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAgBhB;IAED;;;;;;;;;;OAUG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,QAgBhB;IAED;;;;;;OAMG;IACH,kCANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,SACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,cALW,MAAM,KACN,MAAM,KACN,MAAM,YACN,OAAO,QAIjB;IAED;;;;;OAKG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,OAAO,CAIlB;IAED;;;;;;;;;;;OAWG;IACH,oBANW,YAAY,GAAC,MAAM,EAAE,KACrB,MAAM,KACN,MAAM,KACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAUhC;IAED;;;;;;;OAOG;IACH,mBANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAMjB;IAED;;;;;;;;;;OAUG;IACH,cAHW,UAAU,GACT,OAAO,CAqDlB;IAED;;;;;;;;;;;OAWG;IACH,QAFY,MAAM,CAajB;IAED;;;;;;;;;;OAUG;IACH,oCAgBC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,eAJW,MAAM,WACN,MAAM,WACN,MAAM,QA0ChB;IAED;;;;OAIG;IACH,cASC;;CACJ"}
+{"version":3,"file":"FluidField.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidField.js"],"names":[],"mappings":"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"}

package/src/engine/physics/fluid/FluidField.js

@@ -199,6 +199,34 @@ export class FluidField {
      */
     half_precision_pressure = false;
 
+    /**
+     * Back every buffer with a single {@link SharedArrayBuffer} instead of
+     * separate private allocations, so the field can be stepped by a worker
+     * thread in place — see {@link WorkerFluidSystem}.
+     *
+     * Must be set before {@link build}. Requires a cross-origin isolated page
+     * (`Cross-Origin-Opener-Policy: same-origin` +
+     * `Cross-Origin-Embedder-Policy: require-corp`); {@link build} throws
+     * otherwise rather than quietly falling back to private memory, which for a
+     * worker bridge would mean each thread mutating a copy the other never sees.
+     *
+     * One buffer rather than one per lattice so the whole field travels to the
+     * worker as a single object, and so the layout is described by
+     * {@link getSharedDescriptor} rather than a dozen handles.
+     *
+     * Has no effect on the field's semantics: the same buffers, the same
+     * contents, the same stable references.
+     *
+     * @type {boolean}
+     */
+    shared_memory = false;
+
+    /**
+     * The backing buffer when {@link shared_memory} is set, else null.
+     * @type {SharedArrayBuffer|null}
+     */
+    #buffer = null;
+
     /**
      * @type {{ name: string, data: Float32Array }[]}
      */
@@ -298,31 +326,186 @@ export class FluidField {
         assert.notOk(this.#built, "build() called twice");
         assert.greaterThanOrEqual(this.#resolution[0], 1, "setResolution(...) must be called before build()");
 
-        const cell_count = this.cellCount();
+        if (!this.shared_memory) {
+            this.#allocate(null);
+            this.#built = true;
+
+            return;
+        }
+
+        if (typeof SharedArrayBuffer !== "function") {
+            throw new Error(
+                "FluidField.shared_memory requires SharedArrayBuffer, which needs a cross-origin isolated page:"
+                + " serve with 'Cross-Origin-Opener-Policy: same-origin' and 'Cross-Origin-Embedder-Policy: require-corp'."
+            );
+        }
+
+        this.#buffer = new SharedArrayBuffer(this.#computeSharedByteLength());
+        this.#allocate(this.#buffer);
+        this.#built = true;
+    }
+
+    /**
+     * Describe every buffer this field owns, in allocation order.
+     *
+     * The order matters for the shared layout: the 4-byte lattices come first,
+     * then pressure (which may be 2-byte under
+     * {@link half_precision_pressure}), then the 1-byte masks — so each view's
+     * offset lands on its own alignment with no padding in the common case.
+     *
+     * Both {@link build} and {@link fromSharedDescriptor} derive the layout from
+     * this same table, which is why a descriptor only has to carry the
+     * resolution, the scalar names and the pressure precision — never an offset
+     * table that could drift from the allocation code.
+     *
+     * @private
+     * @returns {{key: string, ctor: Function, length: number, scalar_index: number}[]}
+     */
+    #bufferSpecs() {
         const rx = this.#resolution[0];
         const ry = this.#resolution[1];
         const rz = this.#resolution[2];
+
+        const cell_count = rx * ry * rz;
         const face_count_x = (rx + 1) * ry * rz;
         const face_count_y = rx * (ry + 1) * rz;
         const face_count_z = rx * ry * (rz + 1);
 
-        this.velocity_x = new Float32Array(face_count_x);
-        this.velocity_y = new Float32Array(face_count_y);
-        this.velocity_z = new Float32Array(face_count_z);
-        this.face_solid_x = new Uint8Array(face_count_x);
-        this.face_solid_y = new Uint8Array(face_count_y);
-        this.face_solid_z = new Uint8Array(face_count_z);
-        this.solid = new Uint8Array(cell_count);
-        this.solid_neighbour_mask = new Uint8Array(cell_count);
-        this.pressure_diag = new Uint8Array(cell_count);
-        const PressureCtor = this.half_precision_pressure ? Float16Array : Float32Array;
-        this.pressure = new PressureCtor(cell_count);
+        const specs = [
+            { key: "velocity_x", ctor: Float32Array, length: face_count_x, scalar_index: -1 },
+            { key: "velocity_y", ctor: Float32Array, length: face_count_y, scalar_index: -1 },
+            { key: "velocity_z", ctor: Float32Array, length: face_count_z, scalar_index: -1 }
+        ];
 
-        for (const attr of this.#scalar_attributes) {
-            attr.data = new Float32Array(cell_count);
+        for (let i = 0; i < this.#scalar_attributes.length; i++) {
+            specs.push({ key: "", ctor: Float32Array, length: cell_count, scalar_index: i });
         }
 
-        this.#built = true;
+        specs.push({
+            key: "pressure",
+            ctor: this.half_precision_pressure ? Float16Array : Float32Array,
+            length: cell_count,
+            scalar_index: -1
+        });
+
+        specs.push({ key: "solid", ctor: Uint8Array, length: cell_count, scalar_index: -1 });
+        specs.push({ key: "solid_neighbour_mask", ctor: Uint8Array, length: cell_count, scalar_index: -1 });
+        specs.push({ key: "pressure_diag", ctor: Uint8Array, length: cell_count, scalar_index: -1 });
+        specs.push({ key: "face_solid_x", ctor: Uint8Array, length: face_count_x, scalar_index: -1 });
+        specs.push({ key: "face_solid_y", ctor: Uint8Array, length: face_count_y, scalar_index: -1 });
+        specs.push({ key: "face_solid_z", ctor: Uint8Array, length: face_count_z, scalar_index: -1 });
+
+        return specs;
+    }
+
+    /**
+     * @private
+     * @returns {number} bytes needed to hold every buffer in one allocation
+     */
+    #computeSharedByteLength() {
+        const specs = this.#bufferSpecs();
+
+        let offset = 0;
+
+        for (let i = 0; i < specs.length; i++) {
+            const spec = specs[i];
+            const alignment = spec.ctor.BYTES_PER_ELEMENT;
+
+            offset = Math.ceil(offset / alignment) * alignment;
+            offset += spec.length * alignment;
+        }
+
+        return offset;
+    }
+
+    /**
+     * Point every buffer at fresh storage — private arrays when `buffer` is
+     * null, sub-views of a single allocation otherwise.
+     *
+     * @private
+     * @param {SharedArrayBuffer|null} buffer
+     */
+    #allocate(buffer) {
+        const specs = this.#bufferSpecs();
+
+        let offset = 0;
+
+        for (let i = 0; i < specs.length; i++) {
+            const spec = specs[i];
+
+            let array;
+
+            if (buffer === null) {
+                array = new spec.ctor(spec.length);
+            } else {
+                const alignment = spec.ctor.BYTES_PER_ELEMENT;
+
+                offset = Math.ceil(offset / alignment) * alignment;
+                array = new spec.ctor(buffer, offset, spec.length);
+                offset += spec.length * alignment;
+            }
+
+            if (spec.scalar_index === -1) {
+                this[spec.key] = array;
+            } else {
+                this.#scalar_attributes[spec.scalar_index].data = array;
+            }
+        }
+    }
+
+    /**
+     * @returns {boolean} whether this field's buffers live in shared memory.
+     */
+    isSharedMemory() {
+        return this.#buffer !== null;
+    }
+
+    /**
+     * Everything another thread needs to attach to this exact field. Structured-
+     * cloneable, and cheap — the buffer is shared, not copied.
+     *
+     * @returns {{buffer: SharedArrayBuffer, resolution: number[], scalars: string[], half_precision_pressure: boolean}}
+     * @throws {Error} if the field is not shared-memory backed
+     */
+    getSharedDescriptor() {
+        if (this.#buffer === null) {
+            throw new Error("field is not shared-memory backed; set shared_memory = true before build()");
+        }
+
+        return {
+            buffer: this.#buffer,
+            resolution: [this.#resolution[0], this.#resolution[1], this.#resolution[2]],
+            scalars: this.#scalar_attributes.map(a => a.name),
+            half_precision_pressure: this.half_precision_pressure
+        };
+    }
+
+    /**
+     * Build a field whose buffers view the memory described by `descriptor` —
+     * the counterpart to {@link getSharedDescriptor}, used on the worker side.
+     *
+     * The result is not a copy: writing through it is writing through the
+     * original.
+     *
+     * @param {{buffer: SharedArrayBuffer, resolution: number[], scalars: string[], half_precision_pressure: boolean}} descriptor
+     * @returns {FluidField}
+     */
+    static fromSharedDescriptor(descriptor) {
+        const field = new FluidField();
+
+        field.setResolution(descriptor.resolution[0], descriptor.resolution[1], descriptor.resolution[2]);
+
+        for (let i = 0; i < descriptor.scalars.length; i++) {
+            field.addScalar(descriptor.scalars[i]);
+        }
+
+        field.half_precision_pressure = descriptor.half_precision_pressure;
+        field.shared_memory = true;
+        field.#buffer = descriptor.buffer;
+        field.#allocate(descriptor.buffer);
+        field.#built = true;
+
+        return field;
     }
 
     /**

package/src/engine/physics/fluid/FluidSimulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidSimulator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidSimulator.js"],"names":[],"mappings":";;;;;;;;;;;;;;;6BA2BU,MAAM;;;;;;;;;;;;;;;;;;;;;;8BAwBN,MAAM;;;;;AAOhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;;;;;;;;;GASG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;;;;;;;;;;;;;GAgBG;AACH,qCAFU,MAAM,CAE2B;AAE3C;IAEI;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,+BAFU,MAAM,CAEkB;IAElC;;;;;OAKG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,6BAFU,MAAM,CAEgB;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;;;;;;;;;;OAeG;IACH,iBAFU,MAAM,CAEqB;IAErC;;;;;;;;;;;;;;OAcG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;;;;;;;;OAgBG;IACH,kBAFU,MAAM,CAE8B;IAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,sBAFU,OAAO,CAEY;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,0BAFU,OAAO,CAEe;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,0BAFU,MAAM,CAEgB;IAuKhC;;;;;;;;;;;;OAYG;IACH,iCALW,MAAM,SACN,MAAM,SACN,MAAM,GACL,MAAM,CAUjB;IAED;;;;;;;;;;;;OAYG;IACH,iCAGC;IAwFD;;;;;;;;;;;;;OAaG;IACH,oCAVW,MAAM,aAEN,uBAAuB,iBACvB,YAAY,GAAC,MAAM,EAAE,QA4L/B;;CACJ"}
+{"version":3,"file":"FluidSimulator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidSimulator.js"],"names":[],"mappings":";;;;;;;;;;;;;;;6BA2BU,MAAM;;;;;;;;;;;;;;;;;;;;;;8BAwBN,MAAM;;;;;AAOhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;;;;;;;;;GASG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;;;;;;;;;;;;;GAgBG;AACH,qCAFU,MAAM,CAE2B;AAE3C;IAEI;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,+BAFU,MAAM,CAEkB;IAElC;;;;;OAKG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,6BAFU,MAAM,CAEgB;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;;;;;;;;;;OAeG;IACH,iBAFU,MAAM,CAEqB;IAErC;;;;;;;;;;;;;;OAcG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;;;;;;;;OAgBG;IACH,kBAFU,MAAM,CAE8B;IAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,sBAFU,OAAO,CAEY;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,0BAFU,OAAO,CAEe;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,0BAFU,MAAM,CAEgB;IAuKhC;;;;;;;;;;;;OAYG;IACH,iCALW,MAAM,SACN,MAAM,SACN,MAAM,GACL,MAAM,CAUjB;IAED;;;;;;;;;;;;OAYG;IACH,iCAGC;IAwFD;;;;;;;;;;;;;OAaG;IACH,oCAVW,MAAM,aAEN,uBAAuB,iBACvB,YAAY,GAAC,MAAM,EAAE,QAsM/B;;CACJ"}

package/src/engine/physics/fluid/FluidSimulator.js

@@ -787,18 +787,28 @@ export class FluidSimulator {
 
         // 6. Transport each passive scalar by the now-finalized velocity field.
         const scalars = field.getScalarAttributes();
+
+        // Scratch is grown to the LARGEST field this simulator has stepped and
+        // never shrinks, so on a smaller field it is longer than a cell buffer.
+        // The kernels accept oversized inputs, but their whole-buffer seeding
+        // copies (`output.set(source)`) do not — a longer source overflows the
+        // destination. Both scratch views therefore have to be exact-length.
+        const scalar_source = this.#scalar_scratch.length === cell_count
+            ? this.#scalar_scratch
+            : this.#scalar_scratch.subarray(0, cell_count);
+
         for (let i = 0; i < scalars.length; i++) {
             const attr = scalars[i];
 
             if (this.scalar_diffusion_rate > 0 && this.scalar_diffusion_iterations > 0) {
-                this.#scalar_scratch.set(attr.data);
+                scalar_source.set(attr.data);
                 // The diffusion scratch is face-lattice sized; the kernel's
                 // internal whole-buffer copies need an exact cell-count view.
                 const ping_pong = this.#diffusion_scratch.length === cell_count
                     ? this.#diffusion_scratch
                     : this.#diffusion_scratch.subarray(0, cell_count);
                 v3_grid_apply_diffusion(
-                    attr.data, this.#scalar_scratch, ping_pong,
+                    attr.data, scalar_source, ping_pong,
                     res[0], res[1], res[2],
                     this.scalar_diffusion_rate,
                     this.scalar_diffusion_iterations,
@@ -806,12 +816,12 @@ export class FluidSimulator {
                 );
             }
 
-            this.#scalar_scratch.set(attr.data);
+            scalar_source.set(attr.data);
             // Scalars are ALWAYS semi-Lagrangian, independent of
             // advection_scheme — gather-MacCormack is non-conservative (see
             // the AdvectionScheme docstring).
             v3_mac_advect_sl_scalar(
-                attr.data, this.#scalar_scratch,
+                attr.data, scalar_source,
                 field.velocity_x, field.velocity_y, field.velocity_z,
                 res[0], res[1], res[2],
                 time_delta,

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#191@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#200@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#191@#clear_field"(fluid: FluidComponent): void;
+    static "__#200@#clear_field"(fluid: FluidComponent): void;
     /**
      * 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
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#191@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#200@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#191@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#200@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/engine/physics/fluid/ecs/FluidSystem.d.ts

@@ -32,51 +32,6 @@
  * pulsing as projection convergence varies.
  */
 export class FluidSystem extends System<any> {
-    /**
-     * Visitor for the (effectors, transform) traversal — calls syncFromTransform on
-     * every effector in the component.
-     * @param {FluidEffectorsComponent} effectors_component
-     * @param {Transform} transform
-     */
-    static "__#190@#sync_effectors_from_transform"(effectors_component: FluidEffectorsComponent, transform: Transform): void;
-    /**
-     * Visitor for the (FluidComponent, Transform) traversal — keeps the field's
-     * grid origin locked to a cell-aligned position near the transform.
-     *
-     * Centre formula: `q * cell_size + offset`, where `q` is the cell index along
-     * each axis. Origin is then the centre minus half the grid extent so the centre
-     * lands at the geometric middle of the grid.
-     *
-     * Hysteresis: instead of recomputing `q` from the raw position every frame
-     * (which would re-shift on every boundary crossing for a Transform jittering on
-     * a cell edge), we recover the current `q` from the existing origin and only
-     * advance to a new cell when the raw position has drifted more than
-     * `0.5 + hysteresis` cells from it. Crossing the threshold snaps to the new
-     * nearest cell, so a single large move still produces a single discrete shift.
-     *
-     * First sync (`anchored = false`): snap origin to the desired value, no shift.
-     * Subsequent syncs: per-axis hysteretic quantization, then `field.shift` if the
-     * integer delta is non-zero.
-     *
-     * @param {FluidComponent} component
-     * @param {Transform} transform
-     */
-    static "__#190@#reanchor_field"(component: FluidComponent, transform: Transform): void;
-    /**
-     * Write the world-to-grid affine for a FluidComponent into `out`. Axis-aligned,
-     * uniform-scale, so the matrix is sparse:
-     *
-     *     [ 1/cs   0     0    -ox/cs ]
-     *     [ 0      1/cs  0    -oy/cs ]
-     *     [ 0      0     1/cs -oz/cs ]
-     *     [ 0      0     0     1     ]
-     *
-     * Stored column-major (matches the convention of {@link v3_matrix4_multiply}).
-     *
-     * @param {Float32Array} out  length-16
-     * @param {FluidComponent} component
-     */
-    static "__#190@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
     constructor();
     dependencies: (typeof FluidComponent)[];
     /**

package/src/engine/physics/fluid/ecs/FluidSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IA+GI;;;;;OAKG;IACH,oEAHW,uBAAuB,aACvB,SAAS,QAOnB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,2CAHW,cAAc,aACd,SAAS,QA4DnB;IAED;;;;;;;;;;;;;OAaG;IACH,0CAHW,YAAY,aACZ,cAAc,QAexB;;IAvOD,wCAAgC;IAEhC;;;;;;;;OAQG;IACH,sLAME;IAEF;;;;;OAKG;IACH,WAFU,cAAc,CAES;;CA+MpC;uBAjRsB,wBAAwB;+BAEhB,qBAAqB;0BAD1B,qCAAqC;4CAFnB,uDAAuD;wCAI3D,8BAA8B;+BACvC,sBAAsB"}
+{"version":3,"file":"FluidSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidSystem.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;;IAEI,wCAAgC;IAEhC;;;;;;;;OAQG;IACH,sLAME;IAEF;;;;;OAKG;IACH,WAFU,cAAc,CAES;;CAoEpC;uBA1IsB,wBAAwB;+BAEhB,qBAAqB;0BAD1B,qCAAqC;4CAFnB,uDAAuD;wCAI3D,8BAA8B;+BACvC,sBAAsB"}

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

@@ -1,5 +1,4 @@
 import { AABB3 } from "../../../../core/geom/3d/aabb/AABB3.js";
-import { aabb3_intersects_aabb3 } from "../../../../core/geom/3d/aabb/aabb3_intersects_aabb3.js";
 import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
 import { System } from "../../../ecs/System.js";
@@ -7,6 +6,10 @@ import { Transform } from "../../../ecs/transform/Transform.js";
 import { FluidComponent } from "./FluidComponent.js";
 import { FluidEffectorsComponent } from "./FluidEffectorsComponent.js";
 import { FluidSimulator } from "../FluidSimulator.js";
+import { fluid_build_world_to_grid } from "./fluid_build_world_to_grid.js";
+import { fluid_gather_visible_effectors } from "./fluid_gather_visible_effectors.js";
+import { fluid_reanchor_field } from "./fluid_reanchor_field.js";
+import { fluid_sync_effectors_from_transform } from "./fluid_sync_effectors_from_transform.js";
 
 /**
  * ECS system that steps every {@link FluidComponent} on a fixed timestep.
@@ -111,10 +114,10 @@ export class FluidSystem extends System {
 
         // 1. Re-anchor moving fields. Field origin tracks quantize(transform) + offset;
         //    when the quantization changes, the field is shifted to follow the world.
-        ecd.traverseEntities([FluidComponent, Transform], FluidSystem.#reanchor_field);
+        ecd.traverseEntities([FluidComponent, Transform], fluid_reanchor_field);
 
         // 2. Sync every effector that wants to follow its entity's Transform.
-        ecd.traverseEntities([FluidEffectorsComponent, Transform], FluidSystem.#sync_effectors_from_transform);
+        ecd.traverseEntities([FluidEffectorsComponent, Transform], fluid_sync_effectors_from_transform);
 
         // 2. Step each fluid field, with broad-phase effector filtering per field.
         const sim = this.simulator;
@@ -129,150 +132,11 @@ export class FluidSystem extends System {
             }
 
             component.getBoundingBox(field_aabb);
-            FluidSystem.#build_world_to_grid(world_to_grid, component);
+            fluid_build_world_to_grid(world_to_grid, component);
 
-            visible.length = 0;
-            ecd.traverseComponents(FluidEffectorsComponent, function (effectors_component) {
-                const arr = effectors_component.effectors;
-                for (let i = 0; i < arr.length; i++) {
-                    const e = arr[i];
-                    e.getBoundingBox(effector_aabb);
-                    if (aabb3_intersects_aabb3(
-                        effector_aabb.x0, effector_aabb.y0, effector_aabb.z0,
-                        effector_aabb.x1, effector_aabb.y1, effector_aabb.z1,
-                        field_aabb.x0, field_aabb.y0, field_aabb.z0,
-                        field_aabb.x1, field_aabb.y1, field_aabb.z1
-                    )) {
-                        visible.push(e);
-                    }
-                }
-            });
+            fluid_gather_visible_effectors(visible, ecd, field_aabb, effector_aabb);
 
             sim.step(component.field, time_delta_seconds, visible, world_to_grid);
         });
     }
-
-    /**
-     * Visitor for the (effectors, transform) traversal — calls syncFromTransform on
-     * every effector in the component.
-     * @param {FluidEffectorsComponent} effectors_component
-     * @param {Transform} transform
-     */
-    static #sync_effectors_from_transform(effectors_component, transform) {
-        const effectors = effectors_component.effectors;
-        for (let i = 0; i < effectors.length; i++) {
-            effectors[i].syncFromTransform(transform);
-        }
-    }
-
-    /**
-     * Visitor for the (FluidComponent, Transform) traversal — keeps the field's
-     * grid origin locked to a cell-aligned position near the transform.
-     *
-     * Centre formula: `q * cell_size + offset`, where `q` is the cell index along
-     * each axis. Origin is then the centre minus half the grid extent so the centre
-     * lands at the geometric middle of the grid.
-     *
-     * Hysteresis: instead of recomputing `q` from the raw position every frame
-     * (which would re-shift on every boundary crossing for a Transform jittering on
-     * a cell edge), we recover the current `q` from the existing origin and only
-     * advance to a new cell when the raw position has drifted more than
-     * `0.5 + hysteresis` cells from it. Crossing the threshold snaps to the new
-     * nearest cell, so a single large move still produces a single discrete shift.
-     *
-     * First sync (`anchored = false`): snap origin to the desired value, no shift.
-     * Subsequent syncs: per-axis hysteretic quantization, then `field.shift` if the
-     * integer delta is non-zero.
-     *
-     * @param {FluidComponent} component
-     * @param {Transform} transform
-     */
-    static #reanchor_field(component, transform) {
-        const cs = component.cell_size;
-        const p = transform.position;
-        const offset = component.offset;
-        const hyst = component.hysteresis;
-
-        const res = component.field.getResolution();
-        const half_extent_x = (res[0] - 1) * cs * 0.5;
-        const half_extent_y = (res[1] - 1) * cs * 0.5;
-        const half_extent_z = (res[2] - 1) * cs * 0.5;
-
-        const origin = component.origin;
-
-        if (!component.anchored) {
-            // First sync — adopt the freshly-quantized origin without shifting.
-            // Subsequent frames will see integer-cs differences and shift instead.
-            const q_x = Math.round(p.x / cs);
-            const q_y = Math.round(p.y / cs);
-            const q_z = Math.round(p.z / cs);
-            origin[0] = q_x * cs + offset[0] - half_extent_x;
-            origin[1] = q_y * cs + offset[1] - half_extent_y;
-            origin[2] = q_z * cs + offset[2] - half_extent_z;
-            component.anchored = true;
-            return;
-        }
-
-        // Recover the current quantized cell index per axis from the existing origin.
-        // origin_axis = q_curr * cs + offset - half_extent  →
-        //     q_curr = (origin_axis + half_extent - offset) / cs.
-        // Round defends against floating drift; the value should already be integer.
-        const q_curr_x = Math.round((origin[0] + half_extent_x - offset[0]) / cs);
-        const q_curr_y = Math.round((origin[1] + half_extent_y - offset[1]) / cs);
-        const q_curr_z = Math.round((origin[2] + half_extent_z - offset[2]) / cs);
-
-        // Raw (fractional) cell coordinate the Transform sits at right now.
-        const raw_x = p.x / cs;
-        const raw_y = p.y / cs;
-        const raw_z = p.z / cs;
-
-        // Hysteretic re-quantize: only adopt a new cell when raw has drifted past
-        // 0.5 + hyst from the current one. Snap to the new nearest, not the threshold.
-        const threshold = 0.5 + hyst;
-        const q_new_x = Math.abs(raw_x - q_curr_x) > threshold ? Math.round(raw_x) : q_curr_x;
-        const q_new_y = Math.abs(raw_y - q_curr_y) > threshold ? Math.round(raw_y) : q_curr_y;
-        const q_new_z = Math.abs(raw_z - q_curr_z) > threshold ? Math.round(raw_z) : q_curr_z;
-
-        const shift_x = q_new_x - q_curr_x;
-        const shift_y = q_new_y - q_curr_y;
-        const shift_z = q_new_z - q_curr_z;
-
-        if (shift_x === 0 && shift_y === 0 && shift_z === 0) {
-            return;
-        }
-
-        component.field.shift(shift_x, shift_y, shift_z);
-        origin[0] = q_new_x * cs + offset[0] - half_extent_x;
-        origin[1] = q_new_y * cs + offset[1] - half_extent_y;
-        origin[2] = q_new_z * cs + offset[2] - half_extent_z;
-    }
-
-    /**
-     * Write the world-to-grid affine for a FluidComponent into `out`. Axis-aligned,
-     * uniform-scale, so the matrix is sparse:
-     *
-     *     [ 1/cs   0     0    -ox/cs ]
-     *     [ 0      1/cs  0    -oy/cs ]
-     *     [ 0      0     1/cs -oz/cs ]
-     *     [ 0      0     0     1     ]
-     *
-     * Stored column-major (matches the convention of {@link v3_matrix4_multiply}).
-     *
-     * @param {Float32Array} out  length-16
-     * @param {FluidComponent} component
-     */
-    static #build_world_to_grid(out, component) {
-        const inv_cs = 1 / component.cell_size;
-        const ox = component.origin[0];
-        const oy = component.origin[1];
-        const oz = component.origin[2];
-
-        out[0]  = inv_cs;  out[1]  = 0;       out[2]  = 0;       out[3]  = 0;
-        out[4]  = 0;       out[5]  = inv_cs;  out[6]  = 0;       out[7]  = 0;
-        out[8]  = 0;       out[9]  = 0;       out[10] = inv_cs;  out[11] = 0;
-        out[12] = -ox * inv_cs;
-        out[13] = -oy * inv_cs;
-        out[14] = -oz * inv_cs;
-        out[15] = 1;
-    }
 }