@woosh/meep-engine 3.67.0 → 3.69.0

package/src/shade/renderer/fluid/forcing/shader_fluid_forcing_apply.js

@@ -1,341 +1,367 @@
-import { chunk_fluid_effector_record_resolve } from "../../../../engine/physics/fluid/effector/record/chunk_fluid_effector_record_resolve.js";
-import { FLUID_EFFECTOR_RECORD_STRUCT } from "../../../../engine/physics/fluid/effector/record/FLUID_EFFECTOR_RECORD_STRUCT.js";
-import { FLUID_OBSTACLE_RECORD_STRUCT } from "../../../../engine/physics/fluid/obstacle/FLUID_OBSTACLE_RECORD_STRUCT.js";
-import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
-import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
-import { TRANSFORMS_TABLE } from "../../scene/chunk_scene_database_access.js";
-import { chunk_folded_workgroup_index } from "../../shader/chunk/grid/chunk_folded_workgroup_index.js";
-import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
-import { chunk_grid_tile_window } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
-import { chunk_index_to_grid3d } from "../../shader/chunk/grid/chunk_index_to_grid3d.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { chunk_fluid_forcing_cell } from "./chunk_fluid_forcing_cell.js";
-import {
-    FLUID_EFFECTOR_DESCRIPTOR,
-    FLUID_OBSTACLE_DESCRIPTOR,
-    FLUID_OBSTACLE_PLANE_DESCRIPTOR
-} from "./FLUID_DATABASE_SPEC.js";
-import { FLUID_FORCING_BRICK } from "./FLUID_FORCING.js";
-import { FLUID_FORCING_APPLY_STRUCT } from "./FLUID_FORCING_APPLY_STRUCT.js";
-
-/**
- * Cells of the block a forcing workgroup tests for solids: its brick and the layer before it on every
- * axis, whose cells pin the brick's −faces.
- * @type {number}
- */
-const SOLID_BLOCK = FLUID_FORCING_BRICK + 1;
-
-const resources = new ShaderResourceSetDescriptor();
-
-resources.createGroup()
-    .addUniform("settings", FLUID_FORCING_APPLY_STRUCT)
-    .addStorageBuffer("fluid_database", WebGPUArray.from(u32), false)
-    .addStorageBuffer("scene_database", WebGPUArray.from(u32), false)
-    .addStorageBuffer("list", COLLECTION_U32_STRUCT_READ, false)
-    .addStorageBuffer("survivors", WebGPUArray.from(u32), false)
-    .addStorageBuffer("leaf_rows", WebGPUArray.from(u32), false)
-    // the cascade's solid flags, window-local
-    .addStorageBuffer("solid", WebGPUArray.from(u32), true)
-    // the tick's forcing: u faces, then v from settings.forcing_v, then w from settings.forcing_w
-    .addStorageBuffer("forcing", WebGPUArray.from(f32), true)
-    // the cascade's persistent faces, toroidal, where a pinned face takes its wall's velocity
-    .addStorageTexture("out_u", "r32float", "3d", "write-only")
-    .addStorageTexture("out_v", "r32float", "3d", "write-only")
-    .addStorageTexture("out_w", "r32float", "3d", "write-only");
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-const SOLID_BLOCK: u32 = ${SOLID_BLOCK}u;
-const SOLID_BLOCK_CELLS: u32 = ${SOLID_BLOCK ** 3}u;
-
-var<workgroup> fluid_forcing_obstacles: array<${FLUID_OBSTACLE_RECORD_STRUCT.wgsl_ref}, FLUID_FORCING_OBSTACLE_LIMIT>;
-var<workgroup> fluid_forcing_globals: array<mat4x4<f32>, FLUID_FORCING_OBSTACLE_LIMIT>;
-var<workgroup> fluid_forcing_effectors: array<${FLUID_EFFECTOR_RECORD_STRUCT.wgsl_ref}, FLUID_FORCING_EFFECTOR_LIMIT>;
-// the slot of the obstacle each cell of the block is solid in, or FLUID_FORCING_NONE
-var<workgroup> fluid_forcing_solid_slot: array<u32, SOLID_BLOCK_CELLS>;
-
-fn fluid_forcing_obstacle(slot: u32) -> ${FLUID_OBSTACLE_RECORD_STRUCT.wgsl_ref} {
-    return fluid_forcing_obstacles[slot];
-}
-
-fn fluid_forcing_obstacle_global(slot: u32) -> mat4x4<f32> {
-    return fluid_forcing_globals[slot];
-}
-
-fn fluid_forcing_effector(slot: u32) -> ${FLUID_EFFECTOR_RECORD_STRUCT.wgsl_ref} {
-    return fluid_forcing_effectors[slot];
-}
-
-fn shape_record_plane(index: u32) -> vec4<f32> {
-    return ${FLUID_OBSTACLE_PLANE_DESCRIPTOR.marshalling_method_read_field('plane')}(&fluid_database, index);
-}
-
-// Solid test using the pre-normalised rotation columns stored in fluid_forcing_globals[slot]
-fn fluid_forcing_solid_prenorm(x: vec3<f32>, count: u32) -> u32 {
-    var found = FLUID_FORCING_NONE;
-
-    for (var slot = 0u; slot < FLUID_FORCING_OBSTACLE_LIMIT; slot++) {
-        if (slot >= count) {
-            break;
-        }
-
-        let g = fluid_forcing_globals[slot];
-        let offset = x - g[3].xyz;
-        let node = vec3<f32>(
-            dot(g[0].xyz, offset),
-            dot(g[1].xyz, offset),
-            dot(g[2].xyz, offset),
-        );
-
-        let q = fluid_forcing_obstacles[slot].pose_rotation;
-        let local = quat_rotate_v3(vec4<f32>(-q.xyz, q.w), node - fluid_forcing_obstacles[slot].pose_translation);
-        let d = shape_record_signed_distance(fluid_forcing_obstacles[slot].shape_kind, fluid_forcing_obstacles[slot].shape_parameters, local);
-
-        if (d <= fluid_forcing_obstacles[slot].inflation) {
-            found = slot;
-            break;
-        }
-    }
-
-    return found;
-}
-
-// the slot a brick-local cell (-1 to 3 on each axis) is solid in
-fn fluid_forcing_block_slot(local: vec3<i32>) -> u32 {
-    return fluid_forcing_solid_slot[grid3d_to_index(vec3<u32>(local + vec3<i32>(1)), vec2<u32>(SOLID_BLOCK, SOLID_BLOCK))];
-}
-
-fn fluid_forcing_face_world(face: vec3<f32>) -> vec3<f32> {
-    return fluid_forcing_world(settings.cells.corner, settings.cell_size, face);
-}
-
-// A face between the cells whose solids are minus and plus: pinned when either is solid, and then it
-// takes the wall's velocity in the persistent faces, the solid cell's obstacle's, the + side's when
-// both are; otherwise its forcing is what the effectors deposit there.
-fn fluid_forcing_face_u(face: vec3<i32>, minus: u32, plus: u32, effector_count: u32) {
-    let index = grid3d_to_index(vec3<u32>(face), settings.faces_u.size.xy);
-    let wall = select(minus, plus, plus != FLUID_FORCING_NONE);
-
-    if (wall != FLUID_FORCING_NONE) {
-        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.5, 0.0, 0.0));
-        let velocity = fluid_forcing_wall_velocity(wall, x);
-
-        textureStore(out_u, grid_tile_window_storage(face, settings.faces_u.corner_storage, settings.faces_u.period), vec4<f32>(velocity.x, 0.0, 0.0, 0.0));
-        forcing[index] = 0.0;
-    } else if (effector_count > 0u) {
-        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.5, 0.0, 0.0));
-        forcing[index] = fluid_forcing_deposit(x, settings.dt, settings.cell_size, effector_count).x;
-    } else {
-        forcing[index] = 0.0;
-    }
-}
-
-fn fluid_forcing_face_v(face: vec3<i32>, minus: u32, plus: u32, effector_count: u32) {
-    let index = settings.forcing_v + grid3d_to_index(vec3<u32>(face), settings.faces_v.size.xy);
-    let wall = select(minus, plus, plus != FLUID_FORCING_NONE);
-
-    if (wall != FLUID_FORCING_NONE) {
-        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.0, 0.5, 0.0));
-        let velocity = fluid_forcing_wall_velocity(wall, x);
-
-        textureStore(out_v, grid_tile_window_storage(face, settings.faces_v.corner_storage, settings.faces_v.period), vec4<f32>(velocity.y, 0.0, 0.0, 0.0));
-        forcing[index] = 0.0;
-    } else if (effector_count > 0u) {
-        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.0, 0.5, 0.0));
-        forcing[index] = fluid_forcing_deposit(x, settings.dt, settings.cell_size, effector_count).y;
-    } else {
-        forcing[index] = 0.0;
-    }
-}
-
-fn fluid_forcing_face_w(face: vec3<i32>, minus: u32, plus: u32, effector_count: u32) {
-    let index = settings.forcing_w + grid3d_to_index(vec3<u32>(face), settings.faces_w.size.xy);
-    let wall = select(minus, plus, plus != FLUID_FORCING_NONE);
-
-    if (wall != FLUID_FORCING_NONE) {
-        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.0, 0.0, 0.5));
-        let velocity = fluid_forcing_wall_velocity(wall, x);
-
-        textureStore(out_w, grid_tile_window_storage(face, settings.faces_w.corner_storage, settings.faces_w.period), vec4<f32>(velocity.z, 0.0, 0.0, 0.0));
-        forcing[index] = 0.0;
-    } else if (effector_count > 0u) {
-        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.0, 0.0, 0.5));
-        forcing[index] = fluid_forcing_deposit(x, settings.dt, settings.cell_size, effector_count).z;
-    } else {
-        forcing[index] = 0.0;
-    }
-}
-
-@compute @workgroup_size(${FLUID_FORCING_BRICK}, ${FLUID_FORCING_BRICK}, ${FLUID_FORCING_BRICK})
-fn main(
-    @builtin(workgroup_id) workgroup_id: vec3<u32>,
-    @builtin(local_invocation_id) local: vec3<u32>,
-    @builtin(local_invocation_index) lane: u32,
-) {
-    let entry = folded_workgroup_index(workgroup_id);
-
-    if (entry >= list.count) {
-        return;
-    }
-
-    let query = list.elements[entry];
-    let base = query * FLUID_FORCING_SURVIVOR_STRIDE;
-    let header = survivors[base];
-    let obstacle_count = header & 0xffffu;
-    let effector_count = header >> 16u;
-    let origin = vec3<i32>(index_to_grid3d(query - settings.query_base, settings.bricks.xy) * FLUID_FORCING_BRICK);
-    let brick_local = vec3<i32>(local);
-    let cell = origin + brick_local;
-    let flags = grid3d_to_index(vec3<u32>(cell), settings.cells.size.xy);
-
-    // listed only to clear what an earlier tick left: fluid, and no forcing to read
-    if (obstacle_count + effector_count == 0u) {
-        solid[flags] = 0u;
-
-        return;
-    }
-
-    // the brick's survivors into workgroup memory, posed: obstacles on lanes 0..23, effectors on 32..47
-    if (lane < obstacle_count) {
-        let row = leaf_rows[survivors[base + 1u + lane]];
-        let record = ${FLUID_OBSTACLE_DESCRIPTOR.marshalling_method_read}(&fluid_database, row);
-        let g = ${TRANSFORMS_TABLE.marshalling_method_read_field('global')}(&scene_database, record.node);
-
-        fluid_forcing_obstacles[lane] = record;
-        fluid_forcing_globals[lane] = mat4x4<f32>(
-            vec4<f32>(g[0].xyz * (1.0 / length(g[0].xyz)), 0.0),
-            vec4<f32>(g[1].xyz * (1.0 / length(g[1].xyz)), 0.0),
-            vec4<f32>(g[2].xyz * (1.0 / length(g[2].xyz)), 0.0),
-            g[3]
-        );
-    }
-
-    if (lane >= 32u && lane - 32u < effector_count) {
-        let slot = lane - 32u;
-        let row = leaf_rows[survivors[base + 1u + FLUID_FORCING_OBSTACLE_LIMIT + slot]];
-        let record = ${FLUID_EFFECTOR_DESCRIPTOR.marshalling_method_read}(&fluid_database, row);
-
-        fluid_forcing_effectors[slot] = fluid_effector_record_resolve(
-            record,
-            ${TRANSFORMS_TABLE.marshalling_method_read_field('global')}(&scene_database, record.node),
-            ${TRANSFORMS_TABLE.marshalling_method_read_field('prev_global')}(&scene_database, record.node),
-            settings.inverse_frame_dt
-        );
-    }
-
-    workgroupBarrier();
-
-    var own = FLUID_FORCING_NONE;
-    var minus_x = FLUID_FORCING_NONE;
-    var minus_y = FLUID_FORCING_NONE;
-    var minus_z = FLUID_FORCING_NONE;
-
-    // the solid test at every cell centre of the brick and the layer before it; a cell before the
-    // window is fluid, as every pass of the step reads it
-    if (obstacle_count > 0u) {
-        for (var round = 0u; round < 2u; round++) {
-            let k = round * FLUID_FORCING_BRICK_CELLS + lane;
-
-            if (k < SOLID_BLOCK_CELLS) {
-                let block_cell = origin - vec3<i32>(1) + vec3<i32>(index_to_grid3d(k, vec2<u32>(SOLID_BLOCK, SOLID_BLOCK)));
-
-                var slot = FLUID_FORCING_NONE;
-
-                if (all(block_cell >= vec3<i32>(0))) {
-                    slot = fluid_forcing_solid_prenorm(fluid_forcing_face_world(vec3<f32>(block_cell)), obstacle_count);
-                }
-
-                fluid_forcing_solid_slot[k] = slot;
-            }
-        }
-
-        workgroupBarrier();
-
-        own = fluid_forcing_block_slot(brick_local);
-        minus_x = fluid_forcing_block_slot(brick_local - vec3<i32>(1, 0, 0));
-        minus_y = fluid_forcing_block_slot(brick_local - vec3<i32>(0, 1, 0));
-        minus_z = fluid_forcing_block_slot(brick_local - vec3<i32>(0, 0, 1));
-    }
-
-    solid[flags] = FLUID_FORCED_FLAG | select(0u, FLUID_SOLID_FLAG, own != FLUID_FORCING_NONE);
-
-    // the cell's -x, -y and -z faces
-    fluid_forcing_face_u(cell, minus_x, own, effector_count);
-    fluid_forcing_face_v(cell, minus_y, own, effector_count);
-    fluid_forcing_face_w(cell, minus_z, own, effector_count);
-
-    // the +boundary face planes, owned by the window's last cells; the cell beyond is fluid
-    let last = vec3<i32>(settings.cells.size) - vec3<i32>(1);
-
-    if (cell.x == last.x) {
-        fluid_forcing_face_u(cell + vec3<i32>(1, 0, 0), own, FLUID_FORCING_NONE, effector_count);
-    }
-    if (cell.y == last.y) {
-        fluid_forcing_face_v(cell + vec3<i32>(0, 1, 0), own, FLUID_FORCING_NONE, effector_count);
-    }
-    if (cell.z == last.z) {
-        fluid_forcing_face_w(cell + vec3<i32>(0, 0, 1), own, FLUID_FORCING_NONE, effector_count);
-    }
-}
-`, [
-    chunk_folded_workgroup_index,
-    chunk_index_to_grid3d,
-    chunk_grid3d_to_index,
-    chunk_grid_tile_window,
-    chunk_fluid_forcing_cell,
-    chunk_fluid_effector_record_resolve,
-    FLUID_OBSTACLE_DESCRIPTOR.chunk_read,
-    FLUID_EFFECTOR_DESCRIPTOR.chunk_read,
-    FLUID_OBSTACLE_PLANE_DESCRIPTOR.chunk_read_field('plane'),
-    TRANSFORMS_TABLE.chunk_read_field('global'),
-    TRANSFORMS_TABLE.chunk_read_field('prev_global'),
-]);
-
-body.addExtension(WebGPUExtensionType.Subgroups);
-
-/**
- * Q3 of a tick, the forcing (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10), for one stepping
- * cascade: one workgroup of 4×4×4 for each brick its query listed, dispatched indirectly from Q2's
- * command, the brick found by `folded_workgroup_index`.
- *
- * 1. **The survivors, posed:** the brick's obstacle records with their nodes' `global` (rotation
- *    columns pre-normalised), and its effector records brought to the world
- *    (`fluid_effector_record_resolve` with the node's `global` and `prev_global`), into workgroup
- *    memory; one barrier.
- * 2. **The solid test** (`fluid_forcing_solid_prenorm`) at the centre of every cell of the brick and
- *    the layer before it on each axis (125 cells, two rounds), recording the solid's obstacle; a cell
- *    before the window is fluid, as the step reads it. One barrier.
- * 3. **Per cell:** its solid flags, `FLUID_FORCED_FLAG` with `FLUID_SOLID_FLAG` where solid; then each
- *    of its −x, −y, −z faces, and the window's last cells their +boundary faces: a face with a solid
- *    cell on either side is pinned, as every pass of the step will find it from the flags, and takes
- *    the wall's velocity (`fluid_forcing_wall_velocity`, the solid cell's obstacle, the + side's when
- *    both are) **in the cascade's persistent faces**, before the step reads them, with forcing 0;
- *    any other face's forcing is the effectors' deposit over `dt_c` on `h_c`
- *    (`fluid_forcing_deposit`).
- *
- * Writing the wall's velocity into the persistent faces is what makes a face that just became pinned
- * carry the wall, never the fluid value it held: advection reads it as a boundary value and every pass
- * carries it through. A brick listed only because its flags held an earlier tick's has no survivors
- * and writes its cells' flags to 0, which is also what leaves no reader of this tick's forcing there.
- *
- * Per invocation: two solid tests of at most 24 fields (768 hull planes at worst), three to six faces
- * of at most 16 kernels. Workgroup memory: 24 records and matrices, 16 records, 125 slots, 4,724
- * bytes.
- *
- * Bindings: `settings` ({@link FLUID_FORCING_APPLY_STRUCT}); `fluid_database` and `scene_database`;
- * `list`, `survivors` and `leaf_rows` from the tick's query and the frame's leaf list; `solid`, the
- * cascade's flags; `forcing`, the tick's; `out_u`, `out_v`, `out_w`, the cascade's persistent faces.
- * Seven storage buffers and three storage textures.
- *
- * @type {ComputeShader}
- */
-export const shader_fluid_forcing_apply = ComputeShader.from({
-    label: "Fluid / forcing / apply",
-    resources,
-    body,
-});
+import { chunk_fluid_effector_record_resolve } from "../../../../engine/physics/fluid/effector/record/chunk_fluid_effector_record_resolve.js";
+import { FLUID_EFFECTOR_RECORD_STRUCT } from "../../../../engine/physics/fluid/effector/record/FLUID_EFFECTOR_RECORD_STRUCT.js";
+import { FLUID_OBSTACLE_RECORD_STRUCT } from "../../../../engine/physics/fluid/obstacle/FLUID_OBSTACLE_RECORD_STRUCT.js";
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { TRANSFORMS_TABLE } from "../../scene/chunk_scene_database_access.js";
+import { chunk_folded_workgroup_index } from "../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
+import { chunk_grid_tile_window } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { chunk_index_to_grid3d } from "../../shader/chunk/grid/chunk_index_to_grid3d.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_fluid_forcing_cell } from "./chunk_fluid_forcing_cell.js";
+import {
+    FLUID_EFFECTOR_DESCRIPTOR,
+    FLUID_OBSTACLE_DESCRIPTOR,
+    FLUID_OBSTACLE_PLANE_DESCRIPTOR
+} from "./FLUID_DATABASE_SPEC.js";
+import { FLUID_FORCING_BRICK } from "./FLUID_FORCING.js";
+import { FLUID_FORCING_APPLY_STRUCT } from "./FLUID_FORCING_APPLY_STRUCT.js";
+
+/**
+ * Cells of the block a forcing workgroup tests for solids: its brick and the layer before it on every
+ * axis, whose cells pin the brick's −faces.
+ * @type {number}
+ */
+const SOLID_BLOCK = FLUID_FORCING_BRICK + 1;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("settings", FLUID_FORCING_APPLY_STRUCT)
+    .addStorageBuffer("fluid_database", WebGPUArray.from(u32), false)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32), false)
+    .addStorageBuffer("list", COLLECTION_U32_STRUCT_READ, false)
+    .addStorageBuffer("survivors", WebGPUArray.from(u32), false)
+    .addStorageBuffer("leaf_rows", WebGPUArray.from(u32), false)
+    // the cascade's solid flags, window-local
+    .addStorageBuffer("solid", WebGPUArray.from(u32), true)
+    // the tick's forcing: u faces, then v from settings.forcing_v, then w from settings.forcing_w,
+    // then the cells' drag from settings.forcing_porous
+    .addStorageBuffer("forcing", WebGPUArray.from(f32), true)
+    // the cascade's persistent faces, toroidal, where a pinned face takes its wall's velocity
+    .addStorageTexture("out_u", "r32float", "3d", "write-only")
+    .addStorageTexture("out_v", "r32float", "3d", "write-only")
+    .addStorageTexture("out_w", "r32float", "3d", "write-only");
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const SOLID_BLOCK: u32 = ${SOLID_BLOCK}u;
+const SOLID_BLOCK_CELLS: u32 = ${SOLID_BLOCK ** 3}u;
+
+var<workgroup> fluid_forcing_obstacles: array<${FLUID_OBSTACLE_RECORD_STRUCT.wgsl_ref}, FLUID_FORCING_OBSTACLE_LIMIT>;
+var<workgroup> fluid_forcing_globals: array<mat4x4<f32>, FLUID_FORCING_OBSTACLE_LIMIT>;
+var<workgroup> fluid_forcing_effectors: array<${FLUID_EFFECTOR_RECORD_STRUCT.wgsl_ref}, FLUID_FORCING_EFFECTOR_LIMIT>;
+// the slot of the obstacle each cell of the block is solid in, or FLUID_FORCING_NONE
+var<workgroup> fluid_forcing_solid_slot: array<u32, SOLID_BLOCK_CELLS>;
+
+fn fluid_forcing_obstacle(slot: u32) -> ${FLUID_OBSTACLE_RECORD_STRUCT.wgsl_ref} {
+    return fluid_forcing_obstacles[slot];
+}
+
+fn fluid_forcing_obstacle_global(slot: u32) -> mat4x4<f32> {
+    return fluid_forcing_globals[slot];
+}
+
+fn fluid_forcing_effector(slot: u32) -> ${FLUID_EFFECTOR_RECORD_STRUCT.wgsl_ref} {
+    return fluid_forcing_effectors[slot];
+}
+
+fn shape_record_plane(index: u32) -> vec4<f32> {
+    return ${FLUID_OBSTACLE_PLANE_DESCRIPTOR.marshalling_method_read_field('plane')}(&fluid_database, index);
+}
+
+// Solid test using the pre-normalised rotation columns stored in fluid_forcing_globals[slot]
+fn fluid_forcing_solid_prenorm(x: vec3<f32>, count: u32) -> u32 {
+    var found = FLUID_FORCING_NONE;
+
+    for (var slot = 0u; slot < FLUID_FORCING_OBSTACLE_LIMIT; slot++) {
+        if (slot >= count) {
+            break;
+        }
+
+        if (fluid_forcing_obstacles[slot].drag != 0.0) {
+            continue;
+        }
+
+        let g = fluid_forcing_globals[slot];
+        let offset = x - g[3].xyz;
+        let node = vec3<f32>(
+            dot(g[0].xyz, offset),
+            dot(g[1].xyz, offset),
+            dot(g[2].xyz, offset),
+        );
+
+        let q = fluid_forcing_obstacles[slot].pose_rotation;
+        let local = quat_rotate_v3(vec4<f32>(-q.xyz, q.w), node - fluid_forcing_obstacles[slot].pose_translation);
+        let d = shape_record_signed_distance(fluid_forcing_obstacles[slot].shape_kind, fluid_forcing_obstacles[slot].shape_parameters, local);
+
+        if (d <= fluid_forcing_obstacles[slot].inflation) {
+            found = slot;
+            break;
+        }
+    }
+
+    return found;
+}
+
+// the slot a brick-local cell (-1 to 3 on each axis) is solid in
+fn fluid_forcing_block_slot(local: vec3<i32>) -> u32 {
+    return fluid_forcing_solid_slot[grid3d_to_index(vec3<u32>(local + vec3<i32>(1)), vec2<u32>(SOLID_BLOCK, SOLID_BLOCK))];
+}
+
+fn fluid_forcing_face_world(face: vec3<f32>) -> vec3<f32> {
+    return fluid_forcing_world(settings.cells.corner, settings.cell_size, face);
+}
+
+// A face between the cells whose solids are minus and plus: pinned when either is solid, and then it
+// takes the wall's velocity in the persistent faces, the solid cell's obstacle's, the + side's when
+// both are; otherwise its forcing is what the effectors deposit there.
+fn fluid_forcing_face_u(face: vec3<i32>, minus: u32, plus: u32, effector_count: u32) {
+    let index = grid3d_to_index(vec3<u32>(face), settings.faces_u.size.xy);
+    let wall = select(minus, plus, plus != FLUID_FORCING_NONE);
+
+    if (wall != FLUID_FORCING_NONE) {
+        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.5, 0.0, 0.0));
+        let velocity = fluid_forcing_wall_velocity(wall, x);
+
+        textureStore(out_u, grid_tile_window_storage(face, settings.faces_u.corner_storage, settings.faces_u.period), vec4<f32>(velocity.x, 0.0, 0.0, 0.0));
+        forcing[index] = 0.0;
+    } else if (effector_count > 0u) {
+        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.5, 0.0, 0.0));
+        forcing[index] = fluid_forcing_deposit(x, settings.dt, settings.cell_size, effector_count).x;
+    } else {
+        forcing[index] = 0.0;
+    }
+}
+
+fn fluid_forcing_face_v(face: vec3<i32>, minus: u32, plus: u32, effector_count: u32) {
+    let index = settings.forcing_v + grid3d_to_index(vec3<u32>(face), settings.faces_v.size.xy);
+    let wall = select(minus, plus, plus != FLUID_FORCING_NONE);
+
+    if (wall != FLUID_FORCING_NONE) {
+        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.0, 0.5, 0.0));
+        let velocity = fluid_forcing_wall_velocity(wall, x);
+
+        textureStore(out_v, grid_tile_window_storage(face, settings.faces_v.corner_storage, settings.faces_v.period), vec4<f32>(velocity.y, 0.0, 0.0, 0.0));
+        forcing[index] = 0.0;
+    } else if (effector_count > 0u) {
+        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.0, 0.5, 0.0));
+        forcing[index] = fluid_forcing_deposit(x, settings.dt, settings.cell_size, effector_count).y;
+    } else {
+        forcing[index] = 0.0;
+    }
+}
+
+fn fluid_forcing_face_w(face: vec3<i32>, minus: u32, plus: u32, effector_count: u32) {
+    let index = settings.forcing_w + grid3d_to_index(vec3<u32>(face), settings.faces_w.size.xy);
+    let wall = select(minus, plus, plus != FLUID_FORCING_NONE);
+
+    if (wall != FLUID_FORCING_NONE) {
+        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.0, 0.0, 0.5));
+        let velocity = fluid_forcing_wall_velocity(wall, x);
+
+        textureStore(out_w, grid_tile_window_storage(face, settings.faces_w.corner_storage, settings.faces_w.period), vec4<f32>(velocity.z, 0.0, 0.0, 0.0));
+        forcing[index] = 0.0;
+    } else if (effector_count > 0u) {
+        let x = fluid_forcing_face_world(vec3<f32>(face) - vec3<f32>(0.0, 0.0, 0.5));
+        forcing[index] = fluid_forcing_deposit(x, settings.dt, settings.cell_size, effector_count).z;
+    } else {
+        forcing[index] = 0.0;
+    }
+}
+
+@compute @workgroup_size(${FLUID_FORCING_BRICK}, ${FLUID_FORCING_BRICK}, ${FLUID_FORCING_BRICK})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_id) local: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let entry = folded_workgroup_index(workgroup_id);
+
+    if (entry >= list.count) {
+        return;
+    }
+
+    let query = list.elements[entry];
+    let base = query * FLUID_FORCING_SURVIVOR_STRIDE;
+    let header = survivors[base];
+    let obstacle_count = header & 0xffffu;
+    let effector_count = header >> 16u;
+    let origin = vec3<i32>(index_to_grid3d(query - settings.query_base, settings.bricks.xy) * FLUID_FORCING_BRICK);
+    let brick_local = vec3<i32>(local);
+    let cell = origin + brick_local;
+    let flags = grid3d_to_index(vec3<u32>(cell), settings.cells.size.xy);
+
+    // listed only to clear what an earlier tick left: fluid, and no forcing to read
+    if (obstacle_count + effector_count == 0u) {
+        solid[flags] = 0u;
+
+        return;
+    }
+
+    // the brick's survivors into workgroup memory, posed: obstacles on lanes 0..23, effectors on 32..47
+    if (lane < obstacle_count) {
+        let row = leaf_rows[survivors[base + 1u + lane]];
+        let record = ${FLUID_OBSTACLE_DESCRIPTOR.marshalling_method_read}(&fluid_database, row);
+        let g = ${TRANSFORMS_TABLE.marshalling_method_read_field('global')}(&scene_database, record.node);
+
+        fluid_forcing_obstacles[lane] = record;
+        fluid_forcing_globals[lane] = mat4x4<f32>(
+            vec4<f32>(g[0].xyz * (1.0 / length(g[0].xyz)), 0.0),
+            vec4<f32>(g[1].xyz * (1.0 / length(g[1].xyz)), 0.0),
+            vec4<f32>(g[2].xyz * (1.0 / length(g[2].xyz)), 0.0),
+            g[3]
+        );
+    }
+
+    if (lane >= 32u && lane - 32u < effector_count) {
+        let slot = lane - 32u;
+        let row = leaf_rows[survivors[base + 1u + FLUID_FORCING_OBSTACLE_LIMIT + slot]];
+        let record = ${FLUID_EFFECTOR_DESCRIPTOR.marshalling_method_read}(&fluid_database, row);
+
+        fluid_forcing_effectors[slot] = fluid_effector_record_resolve(
+            record,
+            ${TRANSFORMS_TABLE.marshalling_method_read_field('global')}(&scene_database, record.node),
+            ${TRANSFORMS_TABLE.marshalling_method_read_field('prev_global')}(&scene_database, record.node),
+            settings.inverse_frame_dt
+        );
+    }
+
+    workgroupBarrier();
+
+    var own = FLUID_FORCING_NONE;
+    var minus_x = FLUID_FORCING_NONE;
+    var minus_y = FLUID_FORCING_NONE;
+    var minus_z = FLUID_FORCING_NONE;
+
+    // the solid test at every cell centre of the brick and the layer before it; a cell before the
+    // window is fluid, as every pass of the step reads it
+    if (obstacle_count > 0u) {
+        for (var round = 0u; round < 2u; round++) {
+            let k = round * FLUID_FORCING_BRICK_CELLS + lane;
+
+            if (k < SOLID_BLOCK_CELLS) {
+                let block_cell = origin - vec3<i32>(1) + vec3<i32>(index_to_grid3d(k, vec2<u32>(SOLID_BLOCK, SOLID_BLOCK)));
+
+                var slot = FLUID_FORCING_NONE;
+
+                if (all(block_cell >= vec3<i32>(0))) {
+                    slot = fluid_forcing_solid_prenorm(fluid_forcing_face_world(vec3<f32>(block_cell)), obstacle_count);
+                }
+
+                fluid_forcing_solid_slot[k] = slot;
+            }
+        }
+
+        workgroupBarrier();
+
+        own = fluid_forcing_block_slot(brick_local);
+        minus_x = fluid_forcing_block_slot(brick_local - vec3<i32>(1, 0, 0));
+        minus_y = fluid_forcing_block_slot(brick_local - vec3<i32>(0, 1, 0));
+        minus_z = fluid_forcing_block_slot(brick_local - vec3<i32>(0, 0, 1));
+    }
+
+    // the drag of the porous obstacles on a cell that is not solid, over the step
+    var porous = 0u;
+
+    if (obstacle_count > 0u && own == FLUID_FORCING_NONE) {
+        let drag = fluid_forcing_porous(fluid_forcing_face_world(vec3<f32>(cell)), settings.cell_size, obstacle_count);
+
+        if (drag.x > 0.0) {
+            let at = settings.forcing_porous + flags * FLUID_FORCING_POROUS_WORDS;
+
+            forcing[at] = drag.x * settings.dt;
+            forcing[at + 1u] = drag.y;
+            forcing[at + 2u] = drag.z;
+            forcing[at + 3u] = drag.w;
+
+            porous = FLUID_POROUS_FLAG;
+        }
+    }
+
+    solid[flags] = FLUID_FORCED_FLAG | select(0u, FLUID_SOLID_FLAG, own != FLUID_FORCING_NONE) | porous;
+
+    // the cell's -x, -y and -z faces
+    fluid_forcing_face_u(cell, minus_x, own, effector_count);
+    fluid_forcing_face_v(cell, minus_y, own, effector_count);
+    fluid_forcing_face_w(cell, minus_z, own, effector_count);
+
+    // the +boundary face planes, owned by the window's last cells; the cell beyond is fluid
+    let last = vec3<i32>(settings.cells.size) - vec3<i32>(1);
+
+    if (cell.x == last.x) {
+        fluid_forcing_face_u(cell + vec3<i32>(1, 0, 0), own, FLUID_FORCING_NONE, effector_count);
+    }
+    if (cell.y == last.y) {
+        fluid_forcing_face_v(cell + vec3<i32>(0, 1, 0), own, FLUID_FORCING_NONE, effector_count);
+    }
+    if (cell.z == last.z) {
+        fluid_forcing_face_w(cell + vec3<i32>(0, 0, 1), own, FLUID_FORCING_NONE, effector_count);
+    }
+}
+`, [
+    chunk_folded_workgroup_index,
+    chunk_index_to_grid3d,
+    chunk_grid3d_to_index,
+    chunk_grid_tile_window,
+    chunk_fluid_forcing_cell,
+    chunk_fluid_effector_record_resolve,
+    FLUID_OBSTACLE_DESCRIPTOR.chunk_read,
+    FLUID_EFFECTOR_DESCRIPTOR.chunk_read,
+    FLUID_OBSTACLE_PLANE_DESCRIPTOR.chunk_read_field('plane'),
+    TRANSFORMS_TABLE.chunk_read_field('global'),
+    TRANSFORMS_TABLE.chunk_read_field('prev_global'),
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * Q3 of a tick, the forcing (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10), for one stepping
+ * cascade: one workgroup of 4×4×4 for each brick its query listed, dispatched indirectly from Q2's
+ * command, the brick found by `folded_workgroup_index`.
+ *
+ * 1. **The survivors, posed:** the brick's obstacle records with their nodes' `global` (rotation
+ *    columns pre-normalised), and its effector records brought to the world
+ *    (`fluid_effector_record_resolve` with the node's `global` and `prev_global`), into workgroup
+ *    memory; one barrier.
+ * 2. **The solid test** (`fluid_forcing_solid_prenorm`) at the centre of every cell of the brick and
+ *    the layer before it on each axis (125 cells, two rounds), recording the solid's obstacle; a cell
+ *    before the window is fluid, as the step reads it. One barrier.
+ * 3. **Per cell:** its solid flags, `FLUID_FORCED_FLAG` with `FLUID_SOLID_FLAG` where solid, and
+ *    `FLUID_POROUS_FLAG` where a porous obstacle drags on a cell that is not solid, whose drag over the
+ *    step and the velocity it drags toward go into the forcing buffer's porous block
+ *    (`fluid_forcing_porous`, the drag times `dt_c`); then each
+ *    of its −x, −y, −z faces, and the window's last cells their +boundary faces: a face with a solid
+ *    cell on either side is pinned, as every pass of the step will find it from the flags, and takes
+ *    the wall's velocity (`fluid_forcing_wall_velocity`, the solid cell's obstacle, the + side's when
+ *    both are) **in the cascade's persistent faces**, before the step reads them, with forcing 0;
+ *    any other face's forcing is the effectors' deposit over `dt_c` on `h_c`
+ *    (`fluid_forcing_deposit`).
+ *
+ * Writing the wall's velocity into the persistent faces is what makes a face that just became pinned
+ * carry the wall, never the fluid value it held: advection reads it as a boundary value and every pass
+ * carries it through. A brick listed only because its flags held an earlier tick's has no survivors
+ * and writes its cells' flags to 0, which is also what leaves no reader of this tick's forcing there.
+ *
+ * Per invocation: two solid tests of at most 24 fields (768 hull planes at worst), three to six faces
+ * of at most 16 kernels. Workgroup memory: 24 records and matrices, 16 records, 125 slots, 4,724
+ * bytes.
+ *
+ * Bindings: `settings` ({@link FLUID_FORCING_APPLY_STRUCT}); `fluid_database` and `scene_database`;
+ * `list`, `survivors` and `leaf_rows` from the tick's query and the frame's leaf list; `solid`, the
+ * cascade's flags; `forcing`, the tick's; `out_u`, `out_v`, `out_w`, the cascade's persistent faces.
+ * Seven storage buffers and three storage textures.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_forcing_apply = ComputeShader.from({
+    label: "Fluid / forcing / apply",
+    resources,
+    body,
+});