@woosh/meep-engine 3.47.0 → 3.50.0

package/src/engine/physics/fluid/effector/record/fluid_record_apply.js

@@ -0,0 +1,151 @@
+import { assert } from "../../../../../core/assert.js";
+import { m4_invert } from "../../../../../core/geom/3d/mat4/m4_invert.js";
+import {
+    FLUID_EFFECTOR_KERNEL_STRIDE,
+    fluid_effector_kernel_bounds,
+    fluid_effector_kernel_deposit,
+    fluid_effector_kernel_prepare
+} from "./fluid_effector_record_deposit.js";
+
+/**
+ * # One effector record applied to a CPU fluid field
+ *
+ * The CPU executor of a {@link FLUID_EFFECTOR_RECORD_STRUCT} record (GPU_FLUID_CASCADES_PROPOSAL §17
+ * D12, one record and two executors; the GPU's is the forcing pass): every face of the field's three
+ * MAC lattices within the record's reach takes the record's deposit at that face's world position,
+ * {@link fluid_effector_kernel_deposit}, turned into the field's grid units. Pinned faces are skipped,
+ * as the effectors' own `apply` skips them.
+ *
+ * The field's cell size is the `world_to_grid` matrix's scale, and it sets the kernel floor: a kernel
+ * narrower than two of the field's cells is evaluated two cells wide, carrying the momentum it would
+ * have had (see `fluid_effector_record_deposit.js`).
+ *
+ * The record is a world one, node 0. One whose node is another transforms row is first brought to the
+ * world with {@link fluid_effector_record_resolve}.
+ *
+ * Allocates nothing.
+ *
+ * @param {FluidField} field
+ * @param {number} dt seconds, > 0
+ * @param {Float32Array|Float64Array|number[]} world_to_grid column-major 4×4 similarity (uniform
+ *   scale, rotation, translation) sending world points into the field's grid space, as
+ *   `fluid_build_world_to_grid` builds it
+ * @param {FluidEffectorRecord} record a world record
+ */
+export function fluid_record_apply(field, dt, world_to_grid, record) {
+    assert.equal(record.node, 0, 'record.node: a record is applied in the world; resolve it first');
+
+    const m = world_to_grid;
+
+    const scale = Math.sqrt(m[0] * m[0] + m[1] * m[1] + m[2] * m[2]);
+
+    const kernel = KERNEL;
+
+    if (!fluid_effector_kernel_prepare(kernel, record, dt, 1 / scale)) {
+        return;
+    }
+
+    const inverse = GRID_TO_WORLD;
+
+    if (!m4_invert(inverse, m)) {
+        return;
+    }
+
+    // The reach in grid space: the world box's two corners mapped, then widened by the box's half
+    // diagonal turned, which bounds a rotated box; for the usual axis-aligned matrix it is exact.
+    const box = BOUNDS;
+    fluid_effector_kernel_bounds(box, kernel);
+
+    const c_x = (box[0] + box[3]) * 0.5;
+    const c_y = (box[1] + box[4]) * 0.5;
+    const c_z = (box[2] + box[5]) * 0.5;
+
+    const h_x = (box[3] - box[0]) * 0.5;
+    const h_y = (box[4] - box[1]) * 0.5;
+    const h_z = (box[5] - box[2]) * 0.5;
+
+    const g_x = m[0] * c_x + m[4] * c_y + m[8] * c_z + m[12];
+    const g_y = m[1] * c_x + m[5] * c_y + m[9] * c_z + m[13];
+    const g_z = m[2] * c_x + m[6] * c_y + m[10] * c_z + m[14];
+
+    const e_x = Math.abs(m[0]) * h_x + Math.abs(m[4]) * h_y + Math.abs(m[8]) * h_z;
+    const e_y = Math.abs(m[1]) * h_x + Math.abs(m[5]) * h_y + Math.abs(m[9]) * h_z;
+    const e_z = Math.abs(m[2]) * h_x + Math.abs(m[6]) * h_y + Math.abs(m[10]) * h_z;
+
+    const resolution = field.getResolution();
+    const res_x = resolution[0];
+    const res_y = resolution[1];
+    const res_z = resolution[2];
+
+    const point = POINT;
+    const deposit = DEPOSIT;
+
+    for (let axis = 0; axis < 3; axis++) {
+        // Lattice `axis` holds the faces normal to it: one more along that axis than there are
+        // cells, each face half a cell back from its cell's centre.
+        const values = axis === 0 ? field.velocity_x : (axis === 1 ? field.velocity_y : field.velocity_z);
+        const pinned = axis === 0 ? field.face_solid_x : (axis === 1 ? field.face_solid_y : field.face_solid_z);
+
+        const o_x = axis === 0 ? 0.5 : 0;
+        const o_y = axis === 1 ? 0.5 : 0;
+        const o_z = axis === 2 ? 0.5 : 0;
+
+        const n_x = axis === 0 ? res_x + 1 : res_x;
+        const n_y = axis === 1 ? res_y + 1 : res_y;
+        const n_z = axis === 2 ? res_z + 1 : res_z;
+
+        const x_min = Math.max(0, Math.floor(g_x - e_x + o_x));
+        const x_max = Math.min(n_x - 1, Math.ceil(g_x + e_x + o_x));
+        const y_min = Math.max(0, Math.floor(g_y - e_y + o_y));
+        const y_max = Math.min(n_y - 1, Math.ceil(g_y + e_y + o_y));
+        const z_min = Math.max(0, Math.floor(g_z - e_z + o_z));
+        const z_max = Math.min(n_z - 1, Math.ceil(g_z + e_z + o_z));
+
+        // the grid component this lattice holds of a world velocity
+        const r_x = m[axis];
+        const r_y = m[4 + axis];
+        const r_z = m[8 + axis];
+
+        for (let z = z_min; z <= z_max; z++) {
+            const q_z = z - o_z;
+
+            for (let y = y_min; y <= y_max; y++) {
+                const q_y = y - o_y;
+
+                const row = (z * n_y + y) * n_x;
+
+                for (let x = x_min; x <= x_max; x++) {
+                    const face = row + x;
+
+                    if (pinned[face] !== 0) {
+                        continue;
+                    }
+
+                    const q_x = x - o_x;
+
+                    point[0] = inverse[0] * q_x + inverse[4] * q_y + inverse[8] * q_z + inverse[12];
+                    point[1] = inverse[1] * q_x + inverse[5] * q_y + inverse[9] * q_z + inverse[13];
+                    point[2] = inverse[2] * q_x + inverse[6] * q_y + inverse[10] * q_z + inverse[14];
+
+                    fluid_effector_kernel_deposit(deposit, 0, kernel, point, 0);
+
+                    const component = r_x * deposit[0] + r_y * deposit[1] + r_z * deposit[2];
+
+                    if (component !== 0) {
+                        values[face] += component;
+                    }
+                }
+            }
+        }
+    }
+}
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const KERNEL = new Float64Array(FLUID_EFFECTOR_KERNEL_STRIDE);
+const GRID_TO_WORLD = new Float64Array(16);
+const BOUNDS = new Float64Array(6);
+const POINT = new Float64Array(3);
+const DEPOSIT = new Float64Array(3);

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

@@ -0,0 +1,42 @@
+/**
+ * Bring a field from the instant it was last brought to the far field (its own record,
+ * {@link FluidField#atmosphere}) to the instant `atmosphere` describes, through the
+ * atmosphere identity, on every unpinned face:
+ *
+ *     v ← v_far(t₁) + (v − v_far(t₀)) · e^(−(Λ(t₁) − Λ(t₀)))
+ *
+ * Air the atmosphere alone acts on relaxes toward the far field at `D` while carrying the
+ * far field's own changes, so its deviation `e = v − v_far` obeys `de/dt = −D·e` whatever
+ * the gust does and however `D` varied: the step is exact over any interval, one tick or
+ * many, and a face equal to the far field stays equal to it.
+ *
+ * The body force is applied exactly in the same linear step, through the forced response
+ * `P` the effectors system integrates: `e` gains `P(t₁) − P(t₀)·e^(−ΔΛ)`, which over one
+ * tick of constant drag is `(F/D)·(1 − e^(−D·dt))` (the terminal velocity
+ * `wind + force / drag`) and with no drag `F·dt`, and over several is exact however `F` and
+ * `D` varied. So each face becomes
+ *
+ *     v ← (v_far(t₁) + P(t₁)) + (v − (v_far(t₀) + P(t₀))) · e^(−ΔΛ)
+ *
+ * The first time a field meets the far field (or after {@link FluidField#clear}) it has no
+ * record, and it takes one step of `time_delta` of this tick's atmosphere from where it
+ * stands: `v ← (v_far + F/D) + (v − (v_far + F/D))·e^(−D·dt)`, or `v += F·dt` with no drag.
+ * A still field therefore starts relaxing toward the far field, as it would under the globals
+ * applied one by one. A record that runs ahead of `atmosphere` (an effectors system replaced
+ * under a living field) is treated the same way, rather than grown by `e^(+ΔΛ)`.
+ *
+ * Pinned faces (either adjacent cell solid) are skipped: they hold the wall's boundary
+ * condition.
+ *
+ * {@link FluidSystem} calls this after the field's effectors and before
+ * {@link FluidSimulator#step}; {@link WorkerFluidSystem}'s worker calls it on the same field
+ * at the same point, so the two agree exactly.
+ *
+ * @param {FluidField} field
+ * @param {number} time_delta seconds, the step about to be taken
+ * @param {Float64Array|number[]} atmosphere a {@link FluidAtmosphere} record in the field's
+ *        grid units (see {@link fluid_atmosphere_to_grid})
+ * @param {number} offset where the record starts in `atmosphere`
+ */
+export function fluid_apply_atmosphere(field: FluidField, time_delta: number, atmosphere: Float64Array | number[], offset: number): void;
+//# sourceMappingURL=fluid_apply_atmosphere.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fluid_apply_atmosphere.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/fluid_apply_atmosphere.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,sEALW,MAAM,cACN,YAAY,GAAC,MAAM,EAAE,UAErB,MAAM,QA2GhB"}

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

@@ -0,0 +1,148 @@
+import { FluidAtmosphere, FluidFieldAtmosphere } from "./FluidAtmosphere.js";
+
+/**
+ * Bring a field from the instant it was last brought to the far field (its own record,
+ * {@link FluidField#atmosphere}) to the instant `atmosphere` describes, through the
+ * atmosphere identity, on every unpinned face:
+ *
+ *     v ← v_far(t₁) + (v − v_far(t₀)) · e^(−(Λ(t₁) − Λ(t₀)))
+ *
+ * Air the atmosphere alone acts on relaxes toward the far field at `D` while carrying the
+ * far field's own changes, so its deviation `e = v − v_far` obeys `de/dt = −D·e` whatever
+ * the gust does and however `D` varied: the step is exact over any interval, one tick or
+ * many, and a face equal to the far field stays equal to it.
+ *
+ * The body force is applied exactly in the same linear step, through the forced response
+ * `P` the effectors system integrates: `e` gains `P(t₁) − P(t₀)·e^(−ΔΛ)`, which over one
+ * tick of constant drag is `(F/D)·(1 − e^(−D·dt))` (the terminal velocity
+ * `wind + force / drag`) and with no drag `F·dt`, and over several is exact however `F` and
+ * `D` varied. So each face becomes
+ *
+ *     v ← (v_far(t₁) + P(t₁)) + (v − (v_far(t₀) + P(t₀))) · e^(−ΔΛ)
+ *
+ * The first time a field meets the far field (or after {@link FluidField#clear}) it has no
+ * record, and it takes one step of `time_delta` of this tick's atmosphere from where it
+ * stands: `v ← (v_far + F/D) + (v − (v_far + F/D))·e^(−D·dt)`, or `v += F·dt` with no drag.
+ * A still field therefore starts relaxing toward the far field, as it would under the globals
+ * applied one by one. A record that runs ahead of `atmosphere` (an effectors system replaced
+ * under a living field) is treated the same way, rather than grown by `e^(+ΔΛ)`.
+ *
+ * Pinned faces (either adjacent cell solid) are skipped: they hold the wall's boundary
+ * condition.
+ *
+ * {@link FluidSystem} calls this after the field's effectors and before
+ * {@link FluidSimulator#step}; {@link WorkerFluidSystem}'s worker calls it on the same field
+ * at the same point, so the two agree exactly.
+ *
+ * @param {FluidField} field
+ * @param {number} time_delta seconds, the step about to be taken
+ * @param {Float64Array|number[]} atmosphere a {@link FluidAtmosphere} record in the field's
+ *        grid units (see {@link fluid_atmosphere_to_grid})
+ * @param {number} offset where the record starts in `atmosphere`
+ */
+export function fluid_apply_atmosphere(field, time_delta, atmosphere, offset) {
+    const record = field.atmosphere;
+
+    const time_1 = atmosphere[offset + FluidAtmosphere.TIME];
+    const lambda_1 = atmosphere[offset + FluidAtmosphere.LAMBDA];
+
+    // The far field as the field stores it.
+    const far_1_x = Math.fround(atmosphere[offset + FluidAtmosphere.VELOCITY_X]);
+    const far_1_y = Math.fround(atmosphere[offset + FluidAtmosphere.VELOCITY_Y]);
+    const far_1_z = Math.fround(atmosphere[offset + FluidAtmosphere.VELOCITY_Z]);
+
+    const forced_1_x = atmosphere[offset + FluidAtmosphere.FORCED_X];
+    const forced_1_y = atmosphere[offset + FluidAtmosphere.FORCED_Y];
+    const forced_1_z = atmosphere[offset + FluidAtmosphere.FORCED_Z];
+
+    // Each face becomes `to + (v − from) · keep`.
+    let keep, to_x, to_y, to_z, from_x, from_y, from_z;
+
+    if (record[FluidFieldAtmosphere.SEEDED] !== 0
+        && record[FluidFieldAtmosphere.TIME] <= time_1
+        && record[FluidFieldAtmosphere.LAMBDA] <= lambda_1) {
+
+        keep = Math.exp(record[FluidFieldAtmosphere.LAMBDA] - lambda_1);
+
+        to_x = far_1_x + forced_1_x;
+        to_y = far_1_y + forced_1_y;
+        to_z = far_1_z + forced_1_z;
+
+        from_x = record[FluidFieldAtmosphere.VELOCITY_X] + record[FluidFieldAtmosphere.FORCED_X];
+        from_y = record[FluidFieldAtmosphere.VELOCITY_Y] + record[FluidFieldAtmosphere.FORCED_Y];
+        from_z = record[FluidFieldAtmosphere.VELOCITY_Z] + record[FluidFieldAtmosphere.FORCED_Z];
+    } else {
+        // First meeting: one step of this tick's atmosphere, from the far field now.
+        const drag = atmosphere[offset + FluidAtmosphere.DRAG];
+
+        const force_x = atmosphere[offset + FluidAtmosphere.FORCE_X];
+        const force_y = atmosphere[offset + FluidAtmosphere.FORCE_Y];
+        const force_z = atmosphere[offset + FluidAtmosphere.FORCE_Z];
+
+        if (drag > 0) {
+            const inv_drag = 1 / drag;
+
+            keep = Math.exp(-drag * time_delta);
+
+            to_x = far_1_x + force_x * inv_drag;
+            to_y = far_1_y + force_y * inv_drag;
+            to_z = far_1_z + force_z * inv_drag;
+
+            from_x = to_x;
+            from_y = to_y;
+            from_z = to_z;
+        } else {
+            keep = 1;
+
+            to_x = far_1_x + force_x * time_delta;
+            to_y = far_1_y + force_y * time_delta;
+            to_z = far_1_z + force_z * time_delta;
+
+            from_x = far_1_x;
+            from_y = far_1_y;
+            from_z = far_1_z;
+        }
+    }
+
+    record[FluidFieldAtmosphere.SEEDED] = 1;
+    record[FluidFieldAtmosphere.TIME] = time_1;
+    record[FluidFieldAtmosphere.VELOCITY_X] = far_1_x;
+    record[FluidFieldAtmosphere.VELOCITY_Y] = far_1_y;
+    record[FluidFieldAtmosphere.VELOCITY_Z] = far_1_z;
+    record[FluidFieldAtmosphere.LAMBDA] = lambda_1;
+    record[FluidFieldAtmosphere.FORCED_X] = forced_1_x;
+    record[FluidFieldAtmosphere.FORCED_Y] = forced_1_y;
+    record[FluidFieldAtmosphere.FORCED_Z] = forced_1_z;
+
+    // An axis the identity leaves where it is is not walked: with no global in the scene,
+    // that is every axis.
+    if (keep !== 1 || to_x !== from_x) {
+        const v = field.velocity_x;
+        const pinned = field.face_solid_x;
+        const n = v.length;
+
+        for (let i = 0; i < n; i++) {
+            if (pinned[i] === 0) v[i] = to_x + (v[i] - from_x) * keep;
+        }
+    }
+
+    if (keep !== 1 || to_y !== from_y) {
+        const v = field.velocity_y;
+        const pinned = field.face_solid_y;
+        const n = v.length;
+
+        for (let i = 0; i < n; i++) {
+            if (pinned[i] === 0) v[i] = to_y + (v[i] - from_y) * keep;
+        }
+    }
+
+    if (keep !== 1 || to_z !== from_z) {
+        const v = field.velocity_z;
+        const pinned = field.face_solid_z;
+        const n = v.length;
+
+        for (let i = 0; i < n; i++) {
+            if (pinned[i] === 0) v[i] = to_z + (v[i] - from_z) * keep;
+        }
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Convert a {@link FluidAtmosphere} record from WORLD units into one field's grid units:
+ * the far-field velocity, the forced response and the force through the linear
+ * (upper-left 3×3) part of `world_to_grid`, since all three are directions; time, `Λ` and
+ * the drag unchanged.
+ *
+ * Reads and writes `(array, offset)` records, so `out` may be a worker command region.
+ *
+ * @param {Float64Array|number[]} out
+ * @param {number} out_offset
+ * @param {Float64Array|number[]} atmosphere WORLD units
+ * @param {number} offset
+ * @param {Float32Array|number[]} world_to_grid column-major 4×4 affine
+ */
+export function fluid_atmosphere_to_grid(out: Float64Array | number[], out_offset: number, atmosphere: Float64Array | number[], offset: number, world_to_grid: Float32Array | number[]): void;
+//# sourceMappingURL=fluid_atmosphere_to_grid.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fluid_atmosphere_to_grid.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/fluid_atmosphere_to_grid.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,8CANW,YAAY,GAAC,MAAM,EAAE,cACrB,MAAM,cACN,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,iBACN,YAAY,GAAC,MAAM,EAAE,QAgC/B"}

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

@@ -0,0 +1,47 @@
+import { FluidAtmosphere } from "./FluidAtmosphere.js";
+
+/**
+ * Convert a {@link FluidAtmosphere} record from WORLD units into one field's grid units:
+ * the far-field velocity, the forced response and the force through the linear
+ * (upper-left 3×3) part of `world_to_grid`, since all three are directions; time, `Λ` and
+ * the drag unchanged.
+ *
+ * Reads and writes `(array, offset)` records, so `out` may be a worker command region.
+ *
+ * @param {Float64Array|number[]} out
+ * @param {number} out_offset
+ * @param {Float64Array|number[]} atmosphere WORLD units
+ * @param {number} offset
+ * @param {Float32Array|number[]} world_to_grid column-major 4×4 affine
+ */
+export function fluid_atmosphere_to_grid(out, out_offset, atmosphere, offset, world_to_grid) {
+    const m = world_to_grid;
+
+    const vx = atmosphere[offset + FluidAtmosphere.VELOCITY_X];
+    const vy = atmosphere[offset + FluidAtmosphere.VELOCITY_Y];
+    const vz = atmosphere[offset + FluidAtmosphere.VELOCITY_Z];
+
+    const px = atmosphere[offset + FluidAtmosphere.FORCED_X];
+    const py = atmosphere[offset + FluidAtmosphere.FORCED_Y];
+    const pz = atmosphere[offset + FluidAtmosphere.FORCED_Z];
+
+    const fx = atmosphere[offset + FluidAtmosphere.FORCE_X];
+    const fy = atmosphere[offset + FluidAtmosphere.FORCE_Y];
+    const fz = atmosphere[offset + FluidAtmosphere.FORCE_Z];
+
+    out[out_offset + FluidAtmosphere.TIME] = atmosphere[offset + FluidAtmosphere.TIME];
+    out[out_offset + FluidAtmosphere.LAMBDA] = atmosphere[offset + FluidAtmosphere.LAMBDA];
+    out[out_offset + FluidAtmosphere.DRAG] = atmosphere[offset + FluidAtmosphere.DRAG];
+
+    out[out_offset + FluidAtmosphere.VELOCITY_X] = m[0] * vx + m[4] * vy + m[8] * vz;
+    out[out_offset + FluidAtmosphere.VELOCITY_Y] = m[1] * vx + m[5] * vy + m[9] * vz;
+    out[out_offset + FluidAtmosphere.VELOCITY_Z] = m[2] * vx + m[6] * vy + m[10] * vz;
+
+    out[out_offset + FluidAtmosphere.FORCED_X] = m[0] * px + m[4] * py + m[8] * pz;
+    out[out_offset + FluidAtmosphere.FORCED_Y] = m[1] * px + m[5] * py + m[9] * pz;
+    out[out_offset + FluidAtmosphere.FORCED_Z] = m[2] * px + m[6] * py + m[10] * pz;
+
+    out[out_offset + FluidAtmosphere.FORCE_X] = m[0] * fx + m[4] * fy + m[8] * fz;
+    out[out_offset + FluidAtmosphere.FORCE_Y] = m[1] * fx + m[5] * fy + m[9] * fz;
+    out[out_offset + FluidAtmosphere.FORCE_Z] = m[2] * fx + m[6] * fy + m[10] * fz;
+}

package/src/engine/physics/fluid/obstacle/FLUID_OBSTACLE_RECORD_STRUCT.d.ts

@@ -0,0 +1,32 @@
+/**
+ * # One record of a fluid obstacle, as the GPU fluid holds it
+ *
+ * A row of the `fluid_obstacles` table (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10): one core shape
+ * record (`core/geom/3d/shape/record/`) of a `FluidObstacle`'s collider, its frame within the
+ * collider's, the obstacle's inflation and its body's motion, and the transforms row it is posed by.
+ * A collider whose shape is a run of records (a rigid `TransformedShape3D`, a `UnionShape3D`) is a run
+ * of rows; one with no record of its own (a mesh, a heightmap, a scaled wrapper) is one row, its
+ * oriented box (`shape_record_pack_bounding_box`), until the SDF stage. A hull's planes are rows of a
+ * plane table, `vec4<f32>` each in core's `(n, offset)` layout, from `shape_parameters.x` for
+ * `shape_parameters.y` planes. 80 bytes.
+ *
+ * Written field by field in two halves: {@link fluid_obstacle_write_gpu_shape} when the collider's
+ * shape changes, {@link fluid_obstacle_write_gpu_motion} every frame, so an obstacle whose inflation
+ * and motion have not changed (a sleeping body, a static wall) writes nothing.
+ *
+ * ## What a consumer supplies
+ *
+ * The node's `global` (its `transforms` row; node 0 is the world). The collider is posed rigidly, as
+ * the physics narrowphase and the CPU fluid pose it: the node's translation and the rotation of its
+ * matrix with each column normalised, scale ignored. A point `x` is in the record's frame at
+ * `q⁻¹·(Rᵀ·(x − t) − pose_translation)`, `q = pose_rotation`; there it is solid when
+ * `shape_record_signed_distance(shape_kind, shape_parameters, ·) ≤ inflation`, and the wall moves at
+ * `rigid_velocity_at_point(linear_velocity, angular_velocity, t, x)`.
+ * `fluid_obstacle_record_signed_distance` and `fluid_obstacle_record_wall_velocity`
+ * (`chunk_fluid_obstacle_record`) are those, with CPU twins.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_OBSTACLE_RECORD_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../../shade/renderer/shader/type/WebGPUStruct.js";
+//# sourceMappingURL=FLUID_OBSTACLE_RECORD_STRUCT.d.ts.map

package/src/engine/physics/fluid/obstacle/FLUID_OBSTACLE_RECORD_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_OBSTACLE_RECORD_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/obstacle/FLUID_OBSTACLE_RECORD_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,2CAFU,YAAY,CAmBI;6BAhDG,wDAAwD"}

package/src/engine/physics/fluid/obstacle/FLUID_OBSTACLE_RECORD_STRUCT.js

@@ -0,0 +1,50 @@
+import { f32, u32, vec3f, vec4f } from "../../../../shade/renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../../shade/renderer/shader/type/WebGPUStruct.js";
+
+/**
+ * # One record of a fluid obstacle, as the GPU fluid holds it
+ *
+ * A row of the `fluid_obstacles` table (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10): one core shape
+ * record (`core/geom/3d/shape/record/`) of a `FluidObstacle`'s collider, its frame within the
+ * collider's, the obstacle's inflation and its body's motion, and the transforms row it is posed by.
+ * A collider whose shape is a run of records (a rigid `TransformedShape3D`, a `UnionShape3D`) is a run
+ * of rows; one with no record of its own (a mesh, a heightmap, a scaled wrapper) is one row, its
+ * oriented box (`shape_record_pack_bounding_box`), until the SDF stage. A hull's planes are rows of a
+ * plane table, `vec4<f32>` each in core's `(n, offset)` layout, from `shape_parameters.x` for
+ * `shape_parameters.y` planes. 80 bytes.
+ *
+ * Written field by field in two halves: {@link fluid_obstacle_write_gpu_shape} when the collider's
+ * shape changes, {@link fluid_obstacle_write_gpu_motion} every frame, so an obstacle whose inflation
+ * and motion have not changed (a sleeping body, a static wall) writes nothing.
+ *
+ * ## What a consumer supplies
+ *
+ * The node's `global` (its `transforms` row; node 0 is the world). The collider is posed rigidly, as
+ * the physics narrowphase and the CPU fluid pose it: the node's translation and the rotation of its
+ * matrix with each column normalised, scale ignored. A point `x` is in the record's frame at
+ * `q⁻¹·(Rᵀ·(x − t) − pose_translation)`, `q = pose_rotation`; there it is solid when
+ * `shape_record_signed_distance(shape_kind, shape_parameters, ·) ≤ inflation`, and the wall moves at
+ * `rigid_velocity_at_point(linear_velocity, angular_velocity, t, x)`.
+ * `fluid_obstacle_record_signed_distance` and `fluid_obstacle_record_wall_velocity`
+ * (`chunk_fluid_obstacle_record`) are those, with CPU twins.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_OBSTACLE_RECORD_STRUCT = WebGPUStruct.from({
+    /** The core shape record's `SHAPE_RECORD_PARAM_0..3`. */
+    shape_parameters: vec4f,
+    /** Where the record's frame sits in the collider's: a translation. */
+    pose_translation: vec3f,
+    /** The core shape record's `ShapeRecordKind`. */
+    shape_kind: u32,
+    /** Where the record's frame sits in the collider's: a unit quaternion `(x, y, z, w)`. */
+    pose_rotation: vec4f,
+    /** The body's velocity at the node's translation, world m/s: `RigidBody.linearVelocity`. */
+    linear_velocity: vec3f,
+    /** `FluidObstacle.inflation`, metres: a point is solid within it of the surface. */
+    inflation: f32,
+    /** The body's spin about the node's translation, world rad/s: `RigidBody.angularVelocity`. */
+    angular_velocity: vec3f,
+    /** The transforms row that poses the record; `NODE3D_SCENE_ID` (0) for the world. */
+    node: u32,
+}, "FluidObstacleRecord");

package/src/engine/physics/fluid/obstacle/chunk_fluid_obstacle_record.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A `FluidObstacleRecord` at a world point, under its node's world matrix `global`:
+ *
+ * - `fluid_obstacle_record_signed_distance(record, global, x) -> f32`: signed distance to its
+ *   surface, negative inside; the point is solid when it is at most `record.inflation`;
+ * - `fluid_obstacle_record_wall_velocity(record, global, x) -> vec3<f32>`: the wall's velocity there,
+ *   `rigid_velocity_at_point(v, ω, t, x)` with `t` the node's translation.
+ *
+ * The node poses the record rigidly: its translation, and its matrix's rotation with each column
+ * normalised, scale ignored, as the physics narrowphase and the CPU fluid pose a collider; then the
+ * record's own pose within the collider; then `shape_record_signed_distance`. The twins of
+ * `fluid_obstacle_record_signed_distance` and `fluid_obstacle_record_wall_velocity`
+ * (`fluid_obstacle_record_evaluate.js`).
+ *
+ * ## Seam
+ *
+ * A hull's planes come through `shape_record_plane(index)`, which the enclosing shader defines over
+ * the obstacle plane table it binds (see `chunk_shape_record_signed_distance`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_obstacle_record: CodeChunk;
+import { CodeChunk } from "../../../../shade/renderer/shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_fluid_obstacle_record.d.ts.map

package/src/engine/physics/fluid/obstacle/chunk_fluid_obstacle_record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_fluid_obstacle_record.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/obstacle/chunk_fluid_obstacle_record.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,0CAFU,SAAS,CAmCjB;0BAzDwB,yDAAyD"}

package/src/engine/physics/fluid/obstacle/chunk_fluid_obstacle_record.js

@@ -0,0 +1,61 @@
+import { chunk_quat_rotate_v3 } from "../../../../shade/renderer/shader/chunk/geometry/quaternion/chunk_v3_apply_quat.js";
+import { chunk_rigid_velocity_at_point } from "../../../../shade/renderer/shader/chunk/physics/kinematics/chunk_rigid_velocity_at_point.js";
+import { chunk_shape_record_signed_distance } from "../../../../shade/renderer/shader/chunk/sdf/chunk_shape_record_signed_distance.js";
+import { CodeChunk } from "../../../../shade/renderer/shader/compiler/CodeChunk.js";
+import { FLUID_OBSTACLE_RECORD_STRUCT } from "./FLUID_OBSTACLE_RECORD_STRUCT.js";
+
+/**
+ * A `FluidObstacleRecord` at a world point, under its node's world matrix `global`:
+ *
+ * - `fluid_obstacle_record_signed_distance(record, global, x) -> f32`: signed distance to its
+ *   surface, negative inside; the point is solid when it is at most `record.inflation`;
+ * - `fluid_obstacle_record_wall_velocity(record, global, x) -> vec3<f32>`: the wall's velocity there,
+ *   `rigid_velocity_at_point(v, ω, t, x)` with `t` the node's translation.
+ *
+ * The node poses the record rigidly: its translation, and its matrix's rotation with each column
+ * normalised, scale ignored, as the physics narrowphase and the CPU fluid pose a collider; then the
+ * record's own pose within the collider; then `shape_record_signed_distance`. The twins of
+ * `fluid_obstacle_record_signed_distance` and `fluid_obstacle_record_wall_velocity`
+ * (`fluid_obstacle_record_evaluate.js`).
+ *
+ * ## Seam
+ *
+ * A hull's planes come through `shape_record_plane(index)`, which the enclosing shader defines over
+ * the obstacle plane table it binds (see `chunk_shape_record_signed_distance`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_obstacle_record = CodeChunk.from(
+    //language=WGSL
+    `
+fn fluid_obstacle_record_signed_distance(
+    record: ${FLUID_OBSTACLE_RECORD_STRUCT.wgsl_ref}, global: mat4x4<f32>, x: vec3<f32>
+) -> f32 {
+    let offset = x - global[3].xyz;
+
+    // the node's rotation: its columns normalised, so its scale is ignored
+    let node = vec3<f32>(
+        dot(global[0].xyz, offset) * (1.0 / length(global[0].xyz)),
+        dot(global[1].xyz, offset) * (1.0 / length(global[1].xyz)),
+        dot(global[2].xyz, offset) * (1.0 / length(global[2].xyz)),
+    );
+
+    // the record's own pose within the collider, inverted
+    let q = record.pose_rotation;
+    let local = quat_rotate_v3(vec4<f32>(-q.xyz, q.w), node - record.pose_translation);
+
+    return shape_record_signed_distance(record.shape_kind, record.shape_parameters, local);
+}
+
+fn fluid_obstacle_record_wall_velocity(
+    record: ${FLUID_OBSTACLE_RECORD_STRUCT.wgsl_ref}, global: mat4x4<f32>, x: vec3<f32>
+) -> vec3<f32> {
+    return rigid_velocity_at_point(record.linear_velocity, record.angular_velocity, global[3].xyz, x);
+}
+`, [
+        FLUID_OBSTACLE_RECORD_STRUCT.declaration_chunk,
+        chunk_quat_rotate_v3,
+        chunk_rigid_velocity_at_point,
+        chunk_shape_record_signed_distance,
+    ]
+);

package/src/engine/physics/fluid/obstacle/fluid_obstacle_record_create.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @typedef {object} FluidObstacleRecord
+ * @property {Float32Array} shape_parameters `[p0, p1, p2, p3]`, the core shape record's parameters
+ * @property {Float32Array} pose_translation `[x, y, z]`, the record's frame in the collider's
+ * @property {number} shape_kind a `ShapeRecordKind`
+ * @property {Float32Array} pose_rotation `[x, y, z, w]`, the record's frame in the collider's
+ * @property {Float32Array} linear_velocity `[x, y, z]`, world m/s
+ * @property {number} inflation metres
+ * @property {Float32Array} angular_velocity `[x, y, z]`, world rad/s
+ * @property {number} node the transforms row that poses the record
+ */
+/**
+ * A staging record for one row of {@link FLUID_OBSTACLE_RECORD_STRUCT}: what
+ * {@link fluid_obstacle_write_gpu_shape} and {@link fluid_obstacle_write_gpu_motion} assign into and
+ * `generate_record_writer` reads. A sphere
+ * of radius 0 at the identity, not moving, at the world root.
+ *
+ * Vector fields are `Float32Array`s and scalars hold f32 values, so a record compares as the GPU
+ * holds it. Retain one per row; this allocates.
+ *
+ * @returns {FluidObstacleRecord}
+ */
+export function fluid_obstacle_record_create(): FluidObstacleRecord;
+export type FluidObstacleRecord = {
+    /**
+     * `[p0, p1, p2, p3]`, the core shape record's parameters
+     */
+    shape_parameters: Float32Array;
+    /**
+     * `[x, y, z]`, the record's frame in the collider's
+     */
+    pose_translation: Float32Array;
+    /**
+     * a `ShapeRecordKind`
+     */
+    shape_kind: number;
+    /**
+     * `[x, y, z, w]`, the record's frame in the collider's
+     */
+    pose_rotation: Float32Array;
+    /**
+     * `[x, y, z]`, world m/s
+     */
+    linear_velocity: Float32Array;
+    /**
+     * metres
+     */
+    inflation: number;
+    /**
+     * `[x, y, z]`, world rad/s
+     */
+    angular_velocity: Float32Array;
+    /**
+     * the transforms row that poses the record
+     */
+    node: number;
+};
+//# sourceMappingURL=fluid_obstacle_record_create.d.ts.map

package/src/engine/physics/fluid/obstacle/fluid_obstacle_record_create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fluid_obstacle_record_create.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/obstacle/fluid_obstacle_record_create.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;GAUG;AACH,gDAFa,mBAAmB,CAa/B;;;;;sBAhCa,YAAY;;;;sBACZ,YAAY;;;;gBACZ,MAAM;;;;mBACN,YAAY;;;;qBACZ,YAAY;;;;eACZ,MAAM;;;;sBACN,YAAY;;;;UACZ,MAAM"}