@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/fluid/coupling/shader_fluid_cascade_restrict.js

@@ -0,0 +1,126 @@
+import { chunk_grid_tile_window, GRID_TILE_SIZE } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { FLUID_CASCADE_RESTRICT_STRUCT } from "./FLUID_CASCADE_RESTRICT_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("restriction", FLUID_CASCADE_RESTRICT_STRUCT)
+    .addTexture("child_u", "unfilterable-float", "3d")
+    .addTexture("child_v", "unfilterable-float", "3d")
+    .addTexture("child_w", "unfilterable-float", "3d")
+    .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
+    `
+// a child face's deviation from the far field at the child's record
+fn fluid_restrict_child_u(face: vec3<i32>) -> f32 {
+    let storage = grid_tile_window_storage(face, restriction.child_u.corner_storage, restriction.child_u.period);
+    return textureLoad(child_u, storage, 0).r - restriction.child_far_velocity.x;
+}
+
+fn fluid_restrict_child_v(face: vec3<i32>) -> f32 {
+    let storage = grid_tile_window_storage(face, restriction.child_v.corner_storage, restriction.child_v.period);
+    return textureLoad(child_v, storage, 0).r - restriction.child_far_velocity.y;
+}
+
+fn fluid_restrict_child_w(face: vec3<i32>) -> f32 {
+    let storage = grid_tile_window_storage(face, restriction.child_w.corner_storage, restriction.child_w.period);
+    return textureLoad(child_w, storage, 0).r - restriction.child_far_velocity.z;
+}
+
+// parent face P of each component: the mean of the four child faces on it, as of the parent's record
+fn fluid_restrict_u(face: vec3<i32>) {
+    let c = 2 * face + restriction.child_offset;
+    let sum = (fluid_restrict_child_u(c) + fluid_restrict_child_u(c + vec3<i32>(0, 1, 0)))
+        + (fluid_restrict_child_u(c + vec3<i32>(0, 0, 1)) + fluid_restrict_child_u(c + vec3<i32>(0, 1, 1)));
+    let value = restriction.far_velocity.x + (0.25 * sum) * restriction.keep;
+
+    textureStore(out_u, grid_tile_window_storage(face, restriction.faces_u.corner_storage, restriction.faces_u.period), vec4<f32>(value, 0.0, 0.0, 0.0));
+}
+
+fn fluid_restrict_v(face: vec3<i32>) {
+    let c = 2 * face + restriction.child_offset;
+    let sum = (fluid_restrict_child_v(c) + fluid_restrict_child_v(c + vec3<i32>(1, 0, 0)))
+        + (fluid_restrict_child_v(c + vec3<i32>(0, 0, 1)) + fluid_restrict_child_v(c + vec3<i32>(1, 0, 1)));
+    let value = restriction.far_velocity.y + (0.25 * sum) * restriction.keep;
+
+    textureStore(out_v, grid_tile_window_storage(face, restriction.faces_v.corner_storage, restriction.faces_v.period), vec4<f32>(value, 0.0, 0.0, 0.0));
+}
+
+fn fluid_restrict_w(face: vec3<i32>) {
+    let c = 2 * face + restriction.child_offset;
+    let sum = (fluid_restrict_child_w(c) + fluid_restrict_child_w(c + vec3<i32>(1, 0, 0)))
+        + (fluid_restrict_child_w(c + vec3<i32>(0, 1, 0)) + fluid_restrict_child_w(c + vec3<i32>(1, 1, 0)));
+    let value = restriction.far_velocity.z + (0.25 * sum) * restriction.keep;
+
+    textureStore(out_w, grid_tile_window_storage(face, restriction.faces_w.corner_storage, restriction.faces_w.period), vec4<f32>(value, 0.0, 0.0, 0.0));
+}
+
+@compute @workgroup_size(${GRID_TILE_SIZE.join(', ')})
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    if (any(id >= restriction.box_size)) {
+        return;
+    }
+
+    let cell = restriction.box + vec3<i32>(id);
+    let last = restriction.box + vec3<i32>(restriction.box_size) - vec3<i32>(1);
+
+    // each cell's -x, -y and -z faces, and the box's +faces from its last cells
+    fluid_restrict_u(cell);
+    fluid_restrict_v(cell);
+    fluid_restrict_w(cell);
+
+    if (cell.x == last.x) {
+        fluid_restrict_u(cell + vec3<i32>(1, 0, 0));
+    }
+    if (cell.y == last.y) {
+        fluid_restrict_v(cell + vec3<i32>(0, 1, 0));
+    }
+    if (cell.z == last.z) {
+        fluid_restrict_w(cell + vec3<i32>(0, 0, 1));
+    }
+}
+`, [
+        chunk_grid_tile_window,
+    ]
+);
+
+/**
+ * Two-way feedback (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8 pass 7, §9): before a parent steps, the
+ * parent faces over its child's interior take the mean of the four child faces each covers.
+ *
+ * On a ratio-2 MAC lattice a parent cell's six faces cover the boundary of its eight children, and
+ * the sum of the means is a quarter of the sum of the children's divergences, the children's shared
+ * faces cancelling: a divergence-free child restricts to a divergence-free parent, exactly. The
+ * parent's own projection then removes the divergence at the interface, where a parent cell has some
+ * faces from the child and some of its own.
+ *
+ * The box is the parent cells whose children lie {@link FLUID_CASCADE_FEEDBACK_MARGIN} child cells or
+ * more inside the child's window: the child's edge row and relaxation band are not fed back.
+ *
+ * Frames: the child's faces are deviations from `v_far` at its record and the parent's from `v_far`
+ * at its own, which is older (the parent is about to step); the mean deviation is carried to the
+ * parent's record by `keep`.
+ *
+ * One invocation a parent cell of the box, 8 × 8 × 4 a workgroup, dispatched over the box. A cell
+ * writes its −x, −y, −z faces, and the box's last cell on an axis its + face there. Reads 12 child
+ * texels a cell; no storage buffer, three storage textures.
+ *
+ * Bindings:
+ * - `restriction`: {@link FLUID_CASCADE_RESTRICT_STRUCT};
+ * - `child_u`, `child_v`, `child_w`: the child's persistent faces;
+ * - `out_u`, `out_v`, `out_w`: written, the parent's persistent faces.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_cascade_restrict = ComputeShader.from({
+    label: "Fluid / cascade restrict",
+    body,
+    resources,
+});

package/src/shade/renderer/fluid/fluid_cascade_ruler.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The coarse cascade a tick steps (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8, Berger–Oliger on a
+ * ruler): cascade `c ≥ 1` steps on ticks with `t mod 2^c = 2^(c−1)`, with `dt_c = dt·2^c`, and cascade
+ * 0 on every tick. The `c` a tick names is one more than its lowest set bit, so a tick steps cascade 0
+ * and at most one other: odd ticks cascade 1, ticks 2 mod 4 cascade 2, and so on; tick 0, and a tick
+ * whose `c` is past the coarsest, steps cascade 0 alone (with four cascades, one tick in eight).
+ *
+ * Over any `2^c` consecutive ticks cascade `c` steps exactly once.
+ *
+ * @param {number} tick a non-negative integer
+ * @param {number} cascade_count 1 to 8
+ * @returns {number} the coarse cascade the tick steps, or -1 for none
+ */
+export function fluid_cascade_ruler(tick: number, cascade_count: number): number;
+//# sourceMappingURL=fluid_cascade_ruler.d.ts.map

package/src/shade/renderer/fluid/fluid_cascade_ruler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fluid_cascade_ruler.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fluid/fluid_cascade_ruler.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,0CAJW,MAAM,iBACN,MAAM,GACJ,MAAM,CAwBlB"}

package/src/shade/renderer/fluid/fluid_cascade_ruler.js

@@ -0,0 +1,38 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * The coarse cascade a tick steps (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8, Berger–Oliger on a
+ * ruler): cascade `c ≥ 1` steps on ticks with `t mod 2^c = 2^(c−1)`, with `dt_c = dt·2^c`, and cascade
+ * 0 on every tick. The `c` a tick names is one more than its lowest set bit, so a tick steps cascade 0
+ * and at most one other: odd ticks cascade 1, ticks 2 mod 4 cascade 2, and so on; tick 0, and a tick
+ * whose `c` is past the coarsest, steps cascade 0 alone (with four cascades, one tick in eight).
+ *
+ * Over any `2^c` consecutive ticks cascade `c` steps exactly once.
+ *
+ * @param {number} tick a non-negative integer
+ * @param {number} cascade_count 1 to 8
+ * @returns {number} the coarse cascade the tick steps, or -1 for none
+ */
+export function fluid_cascade_ruler(tick, cascade_count) {
+    assert.isNonNegativeInteger(tick, 'tick');
+    assert.isPositiveInteger(cascade_count, 'cascade_count');
+
+    if (tick === 0) {
+        return -1;
+    }
+
+    let t = tick;
+    let cascade = 1;
+
+    // the lowest set bit, counted without 32-bit operators so that any safe integer works
+    while (t % 2 === 0) {
+        t /= 2;
+        cascade++;
+
+        if (cascade >= cascade_count) {
+            return -1;
+        }
+    }
+
+    return cascade < cascade_count ? cascade : -1;
+}

package/src/shade/renderer/fluid/fluid_cascade_window.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A {@link GRID_TILE_WINDOW_STRUCT} value, to be filled in place.
+ *
+ * @returns {{corner: Int32Array, corner_storage: Uint32Array, size: Uint32Array, period: Uint32Array}}
+ */
+export function fluid_cascade_window_value(): {
+    corner: Int32Array;
+    corner_storage: Uint32Array;
+    size: Uint32Array;
+    period: Uint32Array;
+};
+/**
+ * Where one of a cascade window's grids is stored (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7):
+ * `corner` at window-local 0, a size and a period of the window's cells, plus one along `axis` for the
+ * faces of that axis's component (−1 for the cells, the pressure). The storage corner is the corner
+ * modulo the period, so a window that moves keeps every value still inside it where it is.
+ *
+ * @param {{corner: Int32Array, corner_storage: Uint32Array, size: Uint32Array, period: Uint32Array}} out
+ * @param {ArrayLike<number>} corner the world cell at window-local (0, 0, 0)
+ * @param {ArrayLike<number>} resolution the window's cells on each axis
+ * @param {number} axis 0, 1 or 2 for the u, v or w faces; -1 for the cells
+ */
+export function fluid_cascade_window_place(out: {
+    corner: Int32Array;
+    corner_storage: Uint32Array;
+    size: Uint32Array;
+    period: Uint32Array;
+}, corner: ArrayLike<number>, resolution: ArrayLike<number>, axis: number): void;
+/**
+ * A window that holds nothing: size 0 on every axis, so every cell lies beyond it. The far field, as
+ * a cascade's parent, is one (`FLUID_CASCADE_PARENT_STRUCT`).
+ *
+ * @param {{corner: Int32Array, corner_storage: Uint32Array, size: Uint32Array, period: Uint32Array}} out
+ */
+export function fluid_cascade_window_empty(out: {
+    corner: Int32Array;
+    corner_storage: Uint32Array;
+    size: Uint32Array;
+    period: Uint32Array;
+}): void;
+//# sourceMappingURL=fluid_cascade_window.d.ts.map

package/src/shade/renderer/fluid/fluid_cascade_window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fluid_cascade_window.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fluid/fluid_cascade_window.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,8CAFa;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,cAAc,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAC,CASrG;AAED;;;;;;;;;;GAUG;AACH,gDALW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,cAAc,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAC,UACzF,UAAU,MAAM,CAAC,cACjB,UAAU,MAAM,CAAC,QACjB,MAAM,QAYhB;AAED;;;;;GAKG;AACH,gDAFW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,cAAc,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAC,QAOnG"}

package/src/shade/renderer/fluid/fluid_cascade_window.js

@@ -0,0 +1,49 @@
+/**
+ * A {@link GRID_TILE_WINDOW_STRUCT} value, to be filled in place.
+ *
+ * @returns {{corner: Int32Array, corner_storage: Uint32Array, size: Uint32Array, period: Uint32Array}}
+ */
+export function fluid_cascade_window_value() {
+    return {
+        corner: new Int32Array(3),
+        corner_storage: new Uint32Array(3),
+        size: new Uint32Array(3),
+        period: new Uint32Array(3),
+    };
+}
+
+/**
+ * Where one of a cascade window's grids is stored (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7):
+ * `corner` at window-local 0, a size and a period of the window's cells, plus one along `axis` for the
+ * faces of that axis's component (−1 for the cells, the pressure). The storage corner is the corner
+ * modulo the period, so a window that moves keeps every value still inside it where it is.
+ *
+ * @param {{corner: Int32Array, corner_storage: Uint32Array, size: Uint32Array, period: Uint32Array}} out
+ * @param {ArrayLike<number>} corner the world cell at window-local (0, 0, 0)
+ * @param {ArrayLike<number>} resolution the window's cells on each axis
+ * @param {number} axis 0, 1 or 2 for the u, v or w faces; -1 for the cells
+ */
+export function fluid_cascade_window_place(out, corner, resolution, axis) {
+    for (let i = 0; i < 3; i++) {
+        const size = resolution[i] + (i === axis ? 1 : 0);
+        const c = corner[i];
+
+        out.corner[i] = c;
+        out.corner_storage[i] = ((c % size) + size) % size;
+        out.size[i] = size;
+        out.period[i] = size;
+    }
+}
+
+/**
+ * A window that holds nothing: size 0 on every axis, so every cell lies beyond it. The far field, as
+ * a cascade's parent, is one (`FLUID_CASCADE_PARENT_STRUCT`).
+ *
+ * @param {{corner: Int32Array, corner_storage: Uint32Array, size: Uint32Array, period: Uint32Array}} out
+ */
+export function fluid_cascade_window_empty(out) {
+    out.corner.fill(0);
+    out.corner_storage.fill(0);
+    out.size.fill(0);
+    out.period.fill(1);
+}

package/src/shade/renderer/fluid/forcing/FLUID_DATABASE_SPEC.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Effectors and obstacles are counted in tens to thousands, not millions, so the engine's default
+ * page (128 KB) would reserve far more than most scenes fill. A 16 KB page holds 341 effectors, 204
+ * obstacle records or 1,024 hull planes, and a table grows a page at a time past that.
+ *
+ * @type {number}
+ */
+export const FLUID_DATABASE_PAGE_SIZE: number;
+/**
+ * How big a fluid database's buffer starts out: the page address table (three tables of
+ * `GPU_DATABASE_PAGE_LIMIT` u32 slots, 48 KB) and a page of each table, before the database grows
+ * itself.
+ *
+ * @type {number}
+ */
+export const FLUID_DATABASE_INITIAL_SIZE: number;
+/** Name of the effector table within {@link FLUID_DATABASE_SPEC}. */
+export const FLUID_EFFECTOR_TABLE: "fluid_effectors";
+/** Name of the obstacle table within {@link FLUID_DATABASE_SPEC}. */
+export const FLUID_OBSTACLE_TABLE: "fluid_obstacles";
+/** Name of the hull plane table within {@link FLUID_DATABASE_SPEC}. */
+export const FLUID_OBSTACLE_PLANE_TABLE: "fluid_obstacle_planes";
+/**
+ * # The GPU fluid's database
+ *
+ * The rows the GPU fluid's forcing reads (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10), one buffer
+ * for every table so a pass binds them as one:
+ *
+ * | Table | Row | Lifecycle |
+ * |---|---|---|
+ * | `fluid_effectors` | one {@link FLUID_EFFECTOR_RECORD_STRUCT} per local effector (globals fold on the CPU) | stable; written when `write_gpu_record` answers that a field changed |
+ * | `fluid_obstacles` | one {@link FLUID_OBSTACLE_RECORD_STRUCT} per shape record of a `FluidObstacle`'s collider; a `Union` or a rigid wrapper is a run, through `add_run` | stable; the shape half written when the collider's shape changes, the motion half when inflation or velocity does |
+ * | `fluid_obstacle_planes` | one hull plane, {@link FLUID_OBSTACLE_PLANE_STRUCT} | a run per collider, through `add_run`, named by its records |
+ *
+ * **The node links** are cross-database, to the scene's `transforms` rows: `node` of both record
+ * tables names the row that poses the record, `NODE3D_SCENE_ID` (0, the world root) for a record
+ * with no transform. Like the particle emitters', they neither own nor null: the system that links a
+ * record holds its row through the scene's rows.
+ *
+ * **The planes are not a schema range.** A hull record names its run where core's shape record keeps
+ * it, as `shape_parameters.x` (the first row) and `.y` (the count), f32, which is the layout
+ * `chunk_shape_record_signed_distance` reads; a range is declared over two u32 words of a record, and
+ * the 80-byte record has none to spare. So the run is the caller's to free with its records
+ * (`GPUFluidForcing#remove_planes`).
+ *
+ * The query tables of the read API (§12, `fluid_query`, `fluid_query_sample`) join this schema at S5;
+ * nothing here depends on the table count or order.
+ *
+ * @type {GPUDatabaseDefinition}
+ */
+export const FLUID_DATABASE_SPEC: GPUDatabaseDefinition;
+/**
+ * The effector table's descriptor: the source of the WGSL reader a forcing pass pulls in.
+ * @type {GPUTypedTableDescriptor}
+ */
+export const FLUID_EFFECTOR_DESCRIPTOR: GPUTypedTableDescriptor;
+/**
+ * The obstacle table's descriptor.
+ * @type {GPUTypedTableDescriptor}
+ */
+export const FLUID_OBSTACLE_DESCRIPTOR: GPUTypedTableDescriptor;
+/**
+ * The hull plane table's descriptor.
+ * @type {GPUTypedTableDescriptor}
+ */
+export const FLUID_OBSTACLE_PLANE_DESCRIPTOR: GPUTypedTableDescriptor;
+import { GPUDatabaseDefinition } from "../../buffer/table/GPUDatabaseDefinition.js";
+//# sourceMappingURL=FLUID_DATABASE_SPEC.d.ts.map

package/src/shade/renderer/fluid/forcing/FLUID_DATABASE_SPEC.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/FLUID_DATABASE_SPEC.js"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,uCAFU,MAAM,CAEsC;AAEtD;;;;;;GAMG;AACH,0CAFU,MAAM,CAEyC;AAEzD,qEAAqE;AACrE,qDAAsD;AAEtD,qEAAqE;AACrE,qDAAsD;AAEtD,uEAAuE;AACvE,iEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,kCAFU,qBAAqB,CAMF;AAoB7B;;;GAGG;AACH,gEAAuF;AAEvF;;;GAGG;AACH,gEAAuF;AAEvF;;;GAGG;AACH,sEAAmG;sCAnG7D,6CAA6C"}

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

@@ -0,0 +1,103 @@
+import { KILOBYTE } from "../../../../core/science/units/memory/KILOBYTE.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 { GPUDatabaseDefinition } from "../../buffer/table/GPUDatabaseDefinition.js";
+import { SCENE_DATABASE_SPEC } from "../../scene/SCENE_DATABASE_SPEC.js";
+import { FLUID_OBSTACLE_PLANE_STRUCT } from "./FLUID_OBSTACLE_PLANE_STRUCT.js";
+
+/**
+ * Effectors and obstacles are counted in tens to thousands, not millions, so the engine's default
+ * page (128 KB) would reserve far more than most scenes fill. A 16 KB page holds 341 effectors, 204
+ * obstacle records or 1,024 hull planes, and a table grows a page at a time past that.
+ *
+ * @type {number}
+ */
+export const FLUID_DATABASE_PAGE_SIZE = 16 * KILOBYTE;
+
+/**
+ * How big a fluid database's buffer starts out: the page address table (three tables of
+ * `GPU_DATABASE_PAGE_LIMIT` u32 slots, 48 KB) and a page of each table, before the database grows
+ * itself.
+ *
+ * @type {number}
+ */
+export const FLUID_DATABASE_INITIAL_SIZE = 96 * KILOBYTE;
+
+/** Name of the effector table within {@link FLUID_DATABASE_SPEC}. */
+export const FLUID_EFFECTOR_TABLE = "fluid_effectors";
+
+/** Name of the obstacle table within {@link FLUID_DATABASE_SPEC}. */
+export const FLUID_OBSTACLE_TABLE = "fluid_obstacles";
+
+/** Name of the hull plane table within {@link FLUID_DATABASE_SPEC}. */
+export const FLUID_OBSTACLE_PLANE_TABLE = "fluid_obstacle_planes";
+
+/**
+ * # The GPU fluid's database
+ *
+ * The rows the GPU fluid's forcing reads (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10), one buffer
+ * for every table so a pass binds them as one:
+ *
+ * | Table | Row | Lifecycle |
+ * |---|---|---|
+ * | `fluid_effectors` | one {@link FLUID_EFFECTOR_RECORD_STRUCT} per local effector (globals fold on the CPU) | stable; written when `write_gpu_record` answers that a field changed |
+ * | `fluid_obstacles` | one {@link FLUID_OBSTACLE_RECORD_STRUCT} per shape record of a `FluidObstacle`'s collider; a `Union` or a rigid wrapper is a run, through `add_run` | stable; the shape half written when the collider's shape changes, the motion half when inflation or velocity does |
+ * | `fluid_obstacle_planes` | one hull plane, {@link FLUID_OBSTACLE_PLANE_STRUCT} | a run per collider, through `add_run`, named by its records |
+ *
+ * **The node links** are cross-database, to the scene's `transforms` rows: `node` of both record
+ * tables names the row that poses the record, `NODE3D_SCENE_ID` (0, the world root) for a record
+ * with no transform. Like the particle emitters', they neither own nor null: the system that links a
+ * record holds its row through the scene's rows.
+ *
+ * **The planes are not a schema range.** A hull record names its run where core's shape record keeps
+ * it, as `shape_parameters.x` (the first row) and `.y` (the count), f32, which is the layout
+ * `chunk_shape_record_signed_distance` reads; a range is declared over two u32 words of a record, and
+ * the 80-byte record has none to spare. So the run is the caller's to free with its records
+ * (`GPUFluidForcing#remove_planes`).
+ *
+ * The query tables of the read API (§12, `fluid_query`, `fluid_query_sample`) join this schema at S5;
+ * nothing here depends on the table count or order.
+ *
+ * @type {GPUDatabaseDefinition}
+ */
+export const FLUID_DATABASE_SPEC = GPUDatabaseDefinition.from({
+    [FLUID_EFFECTOR_TABLE]: FLUID_EFFECTOR_RECORD_STRUCT,
+    [FLUID_OBSTACLE_TABLE]: FLUID_OBSTACLE_RECORD_STRUCT,
+    [FLUID_OBSTACLE_PLANE_TABLE]: FLUID_OBSTACLE_PLANE_STRUCT,
+}, FLUID_DATABASE_PAGE_SIZE);
+
+FLUID_DATABASE_SPEC.add_link({
+    table: FLUID_EFFECTOR_TABLE,
+    field: 'node',
+    target_database: SCENE_DATABASE_SPEC,
+    target_table: 'transforms',
+    nullable: false,
+    owning: false,
+});
+
+FLUID_DATABASE_SPEC.add_link({
+    table: FLUID_OBSTACLE_TABLE,
+    field: 'node',
+    target_database: SCENE_DATABASE_SPEC,
+    target_table: 'transforms',
+    nullable: false,
+    owning: false,
+});
+
+/**
+ * The effector table's descriptor: the source of the WGSL reader a forcing pass pulls in.
+ * @type {GPUTypedTableDescriptor}
+ */
+export const FLUID_EFFECTOR_DESCRIPTOR = FLUID_DATABASE_SPEC.get(FLUID_EFFECTOR_TABLE);
+
+/**
+ * The obstacle table's descriptor.
+ * @type {GPUTypedTableDescriptor}
+ */
+export const FLUID_OBSTACLE_DESCRIPTOR = FLUID_DATABASE_SPEC.get(FLUID_OBSTACLE_TABLE);
+
+/**
+ * The hull plane table's descriptor.
+ * @type {GPUTypedTableDescriptor}
+ */
+export const FLUID_OBSTACLE_PLANE_DESCRIPTOR = FLUID_DATABASE_SPEC.get(FLUID_OBSTACLE_PLANE_TABLE);

package/src/shade/renderer/fluid/forcing/FLUID_FORCING.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Cells on each axis of a forcing brick (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10): the unit a
+ * brick query answers for and a forcing workgroup writes, one invocation a cell. Four, the cascade
+ * corners' lattice, so every window is whole bricks.
+ * @type {number}
+ */
+export const FLUID_FORCING_BRICK: number;
+/**
+ * Invocations of a forcing workgroup: one a cell of a brick.
+ * @type {number}
+ */
+export const FLUID_FORCING_BRICK_CELLS: number;
+/**
+ * Most obstacle records a brick keeps, the lowest leaves (rows) of those its query found. The budget
+ * of the solid test: each of a forcing invocation's two cells tests at most this many, each at most
+ * `SHAPE_RECORD_HULL_PLANE_LIMIT` (16) planes, 768 plane tests an invocation at worst.
+ * @type {number}
+ */
+export const FLUID_FORCING_OBSTACLE_LIMIT: number;
+/**
+ * Most effector records a brick keeps, after its obstacles. The budget of the deposits: each of a
+ * forcing invocation's three faces (six on a window's last cell) sums at most this many kernels, 96
+ * kernel evaluations an invocation at worst.
+ * @type {number}
+ */
+export const FLUID_FORCING_EFFECTOR_LIMIT: number;
+/**
+ * Words a brick query writes for its brick: one header (obstacles kept in the low 16 bits, effectors
+ * kept in the high), then {@link FLUID_FORCING_OBSTACLE_LIMIT} obstacle leaves and
+ * {@link FLUID_FORCING_EFFECTOR_LIMIT} effector leaves, each ascending.
+ * @type {number}
+ */
+export const FLUID_FORCING_SURVIVOR_STRIDE: number;
+/**
+ * How far a brick's query box reaches past its cells, in its cascade's cells: the effector kernel
+ * floor (`FLUID_EFFECTOR_KERNEL_FLOOR_CELLS`), so a kernel narrower than that, evaluated at the floor,
+ * still meets every brick it deposits in. Two cells, which also holds the cells one outside the brick
+ * a forcing invocation tests for its faces.
+ * @type {number}
+ */
+export const FLUID_FORCING_QUERY_GROWTH_CELLS: number;
+/**
+ * Above one sort tile of leaves the LBVH is rebuilt every this many frames even when its membership
+ * holds, and refit in between (§17 D11).
+ * @type {number}
+ */
+export const FLUID_FORCING_REBUILD_AGE: number;
+/**
+ * Bit 0 of a cell's solid flags: the cell is solid. What every pass of a cascade step tests.
+ * @type {number}
+ */
+export const FLUID_SOLID_FLAG: number;
+/**
+ * Bit 1 of a cell's solid flags: the forcing wrote the cell's faces' forcing this tick (its −x, −y
+ * and −z faces, and a window's last cell its +boundary faces too). A reader of the forcing reads a
+ * face only under it, so the forcing buffer is never cleared.
+ * @type {number}
+ */
+export const FLUID_FORCED_FLAG: number;
+/**
+ * The flags as WGSL constants.
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_forcing_flags: CodeChunk;
+/**
+ * The brick, survivor and query constants as WGSL.
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_forcing_constants: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=FLUID_FORCING.d.ts.map

package/src/shade/renderer/fluid/forcing/FLUID_FORCING.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_FORCING.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/FLUID_FORCING.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;GAGG;AACH,wCAFU,MAAM,CAEkD;AAElE;;;;;GAKG;AACH,2CAFU,MAAM,CAE+B;AAE/C;;;;;GAKG;AACH,2CAFU,MAAM,CAE+B;AAE/C;;;;;GAKG;AACH,4CAFU,MAAM,CAE6F;AAE7G;;;;;;GAMG;AACH,+CAFU,MAAM,CAEkE;AAElF;;;;GAIG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;;GAKG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;GAGG;AACH,wCAFU,SAAS,CAQjB;AAEF;;;GAGG;AACH,4CAFU,SAAS,CAcjB;0BAlGwB,oCAAoC"}

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

@@ -0,0 +1,100 @@
+import { FLUID_EFFECTOR_KERNEL_FLOOR_CELLS } from "../../../../engine/physics/fluid/effector/record/fluid_effector_record_deposit.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Cells on each axis of a forcing brick (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10): the unit a
+ * brick query answers for and a forcing workgroup writes, one invocation a cell. Four, the cascade
+ * corners' lattice, so every window is whole bricks.
+ * @type {number}
+ */
+export const FLUID_FORCING_BRICK = 4;
+
+/**
+ * Invocations of a forcing workgroup: one a cell of a brick.
+ * @type {number}
+ */
+export const FLUID_FORCING_BRICK_CELLS = FLUID_FORCING_BRICK ** 3;
+
+/**
+ * Most obstacle records a brick keeps, the lowest leaves (rows) of those its query found. The budget
+ * of the solid test: each of a forcing invocation's two cells tests at most this many, each at most
+ * `SHAPE_RECORD_HULL_PLANE_LIMIT` (16) planes, 768 plane tests an invocation at worst.
+ * @type {number}
+ */
+export const FLUID_FORCING_OBSTACLE_LIMIT = 24;
+
+/**
+ * Most effector records a brick keeps, after its obstacles. The budget of the deposits: each of a
+ * forcing invocation's three faces (six on a window's last cell) sums at most this many kernels, 96
+ * kernel evaluations an invocation at worst.
+ * @type {number}
+ */
+export const FLUID_FORCING_EFFECTOR_LIMIT = 16;
+
+/**
+ * Words a brick query writes for its brick: one header (obstacles kept in the low 16 bits, effectors
+ * kept in the high), then {@link FLUID_FORCING_OBSTACLE_LIMIT} obstacle leaves and
+ * {@link FLUID_FORCING_EFFECTOR_LIMIT} effector leaves, each ascending.
+ * @type {number}
+ */
+export const FLUID_FORCING_SURVIVOR_STRIDE = 1 + FLUID_FORCING_OBSTACLE_LIMIT + FLUID_FORCING_EFFECTOR_LIMIT;
+
+/**
+ * How far a brick's query box reaches past its cells, in its cascade's cells: the effector kernel
+ * floor (`FLUID_EFFECTOR_KERNEL_FLOOR_CELLS`), so a kernel narrower than that, evaluated at the floor,
+ * still meets every brick it deposits in. Two cells, which also holds the cells one outside the brick
+ * a forcing invocation tests for its faces.
+ * @type {number}
+ */
+export const FLUID_FORCING_QUERY_GROWTH_CELLS = FLUID_EFFECTOR_KERNEL_FLOOR_CELLS;
+
+/**
+ * Above one sort tile of leaves the LBVH is rebuilt every this many frames even when its membership
+ * holds, and refit in between (§17 D11).
+ * @type {number}
+ */
+export const FLUID_FORCING_REBUILD_AGE = 16;
+
+/**
+ * Bit 0 of a cell's solid flags: the cell is solid. What every pass of a cascade step tests.
+ * @type {number}
+ */
+export const FLUID_SOLID_FLAG = 1;
+
+/**
+ * Bit 1 of a cell's solid flags: the forcing wrote the cell's faces' forcing this tick (its −x, −y
+ * and −z faces, and a window's last cell its +boundary faces too). A reader of the forcing reads a
+ * face only under it, so the forcing buffer is never cleared.
+ * @type {number}
+ */
+export const FLUID_FORCED_FLAG = 2;
+
+/**
+ * The flags as WGSL constants.
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_forcing_flags = CodeChunk.from(
+    //language=WGSL
+    `
+const FLUID_SOLID_FLAG: u32 = ${FLUID_SOLID_FLAG}u;
+const FLUID_FORCED_FLAG: u32 = ${FLUID_FORCED_FLAG}u;
+`
+);
+
+/**
+ * The brick, survivor and query constants as WGSL.
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_forcing_constants = CodeChunk.from(
+    //language=WGSL
+    `
+const FLUID_FORCING_BRICK: u32 = ${FLUID_FORCING_BRICK}u;
+const FLUID_FORCING_BRICK_CELLS: u32 = ${FLUID_FORCING_BRICK_CELLS}u;
+const FLUID_FORCING_OBSTACLE_LIMIT: u32 = ${FLUID_FORCING_OBSTACLE_LIMIT}u;
+const FLUID_FORCING_EFFECTOR_LIMIT: u32 = ${FLUID_FORCING_EFFECTOR_LIMIT}u;
+const FLUID_FORCING_SURVIVOR_STRIDE: u32 = ${FLUID_FORCING_SURVIVOR_STRIDE}u;
+const FLUID_FORCING_QUERY_GROWTH_CELLS: f32 = ${FLUID_FORCING_QUERY_GROWTH_CELLS.toFixed(1)};
+`, [
+        chunk_fluid_forcing_flags,
+    ]
+);

package/src/shade/renderer/fluid/forcing/FLUID_FORCING_APPLY_STRUCT.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What a stepping cascade's forcing (`shader_fluid_forcing_apply`, Q3) reads.
+ *
+ * - `cells`: the window, `corner` its world cell at window-local 0 and `size` its cells;
+ * - `faces_u`, `faces_v`, `faces_w`: where the cascade's persistent faces are stored, toroidally, as
+ *   the step reads them (`GPUFluidCascade#faces_window`), which a pinned face's wall velocity is
+ *   written through;
+ * - `bricks`: bricks on each axis of the window;
+ * - `query_base`: the slot's first query, its brick 0;
+ * - `cell_size`: `h_c`, metres;
+ * - `dt`: `dt_c`, the step's seconds, which the deposits are over;
+ * - `inverse_frame_dt`: `1 / (frame_dt · fixedStepTimeScale)`, 0 when no game time passed, which a
+ *   wake's node velocity is taken with;
+ * - `forcing_v`, `forcing_w`: where the v and w faces start in the forcing buffer, which holds the u
+ *   faces from 0, each component's faces laid out over its own face lattice, x fastest.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_FORCING_APPLY_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=FLUID_FORCING_APPLY_STRUCT.d.ts.map

package/src/shade/renderer/fluid/forcing/FLUID_FORCING_APPLY_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_FORCING_APPLY_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/FLUID_FORCING_APPLY_STRUCT.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,yCAFU,YAAY,CAcE;6BAhCK,mCAAmC"}