@woosh/meep-engine 3.49.0 → 3.50.0

package/src/engine/graphics/ecs/water/WaterWaves.js

@@ -4,32 +4,19 @@ import Vector1 from "../../../../core/geom/Vector1.js";
 export const WATER_WAVES_SHORE_REFLECTION_DEFAULT = 0.5;
 
 /**
- * The waves of the {@link Water} on the same entity: the wind that raises them and how the body's outline
- * treats them (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1).
+ * The waves of the {@link Water} on the same entity: the open water beyond its mesh that the wind crosses, and
+ * how the body's outline treats them (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1).
  *
  * Kept apart from `Water`, which describes the body and its optics and says nothing about how the surface
- * moves. A body without this component is calm, and its outline reflects wave particles (from
- * `WaterSystem.splash`) at the default coefficient.
+ * moves. A body without this component has no water upwind of its mesh, and its outline reflects wave particles
+ * (from `WaterSystem.splash`) at the default coefficient.
  *
- * The wind's waves follow from physics: a fetch-limited JONSWAP sea of this wind speed over the water upwind
- * — the body's own extent along the wind plus {@link upwindFetch} — so the same wind raises centimetre ripples
- * on a puddle and swell on an open sea.
+ * The wind is not here: it is the scene's (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6), the published wind field
+ * 10 m above the body's origin, low-passed on the GPU. The waves follow from physics: a fetch-limited JONSWAP sea
+ * of that wind over the water upwind — the body's own extent along the wind plus {@link upwindFetch} — so the same
+ * wind raises centimetre ripples on a puddle and swell on an open sea.
  */
 class WaterWaves {
-    /**
-     * Wind speed at 10 m, m/s.
-     * @type {Vector1}
-     */
-    windSpeed = new Vector1(3);
-
-    /**
-     * Direction the wind blows towards, radians in the body's local xz plane, measured from +x towards +z.
-     * The angle turns with the body's rotation and is not skewed by its scale. A change turns the waves over
-     * a few seconds.
-     * @type {Vector1}
-     */
-    windDirection = new Vector1(0);
-
     /**
      * Open water upwind of the mesh, metres, added to the mesh's own extent along the wind. Zero for a body
      * that is all the water there is (a pool, a lake); an open sea states the distance to its far shore
@@ -46,14 +33,6 @@ class WaterWaves {
     shoreReflection = new Vector1(WATER_WAVES_SHORE_REFLECTION_DEFAULT);
 
     fromJSON(json) {
-        if (typeof json.windSpeed === 'number') {
-            this.windSpeed.fromJSON(json.windSpeed);
-        }
-
-        if (typeof json.windDirection === 'number') {
-            this.windDirection.fromJSON(json.windDirection);
-        }
-
         if (typeof json.upwindFetch === 'number') {
             this.upwindFetch.fromJSON(json.upwindFetch);
         }
@@ -65,8 +44,6 @@ class WaterWaves {
 
     toJSON() {
         return {
-            windSpeed: this.windSpeed.toJSON(),
-            windDirection: this.windDirection.toJSON(),
             upwindFetch: this.upwindFetch.toJSON(),
             shoreReflection: this.shoreReflection.toJSON(),
         };

package/src/engine/graphics/ecs/water/WaterWavesSerializationAdapter.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Version 2: the upwind fetch and the shore reflection. Version 1 also held the wind speed and direction, which
+ * left `WaterWaves` for the scene's wind (`WaterWavesSerializationUpgrader_1_2` drops them).
+ */
 export class WaterWavesSerializationAdapter extends BinaryClassSerializationAdapter<any> {
     constructor();
     klass: typeof WaterWaves;

package/src/engine/graphics/ecs/water/WaterWavesSerializationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WaterWavesSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterWavesSerializationAdapter.js"],"names":[],"mappings":"AAGA;;IAEI,yBAAmB;IAGnB;;;OAGG;IACH,uCAFW,UAAU,QAOpB;IAED;;;OAGG;IACH,yCAFW,UAAU,QAOpB;CACJ;gDA7B+C,gEAAgE;uBACzF,iBAAiB"}
+{"version":3,"file":"WaterWavesSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterWavesSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;;IAEI,yBAAmB;IAGnB;;;OAGG;IACH,uCAFW,UAAU,QAKpB;IAED;;;OAGG;IACH,yCAFW,UAAU,QAKpB;CACJ;gDA7B+C,gEAAgE;uBACzF,iBAAiB"}

package/src/engine/graphics/ecs/water/WaterWavesSerializationAdapter.js

@@ -1,18 +1,20 @@
 import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
 import WaterWaves from "./WaterWaves.js";
 
+/**
+ * Version 2: the upwind fetch and the shore reflection. Version 1 also held the wind speed and direction, which
+ * left `WaterWaves` for the scene's wind (`WaterWavesSerializationUpgrader_1_2` drops them).
+ */
 export class WaterWavesSerializationAdapter extends BinaryClassSerializationAdapter {
 
     klass = WaterWaves;
-    version = 1;
+    version = 2;
 
     /**
      * @param {BinaryBuffer} buffer
      * @param {WaterWaves} value
      */
     serialize(buffer, value) {
-        buffer.writeFloat32(value.windSpeed.getValue());
-        buffer.writeFloat32(value.windDirection.getValue());
         buffer.writeFloat32(value.upwindFetch.getValue());
         buffer.writeFloat32(value.shoreReflection.getValue());
     }
@@ -22,8 +24,6 @@ export class WaterWavesSerializationAdapter extends BinaryClassSerializationAdap
      * @param {WaterWaves} value
      */
     deserialize(buffer, value) {
-        value.windSpeed.set(buffer.readFloat32());
-        value.windDirection.set(buffer.readFloat32());
         value.upwindFetch.set(buffer.readFloat32());
         value.shoreReflection.set(buffer.readFloat32());
     }

package/src/engine/graphics/ecs/water/WaterWavesSerializationUpgrader_1_2.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Drop version 1's wind speed and direction, which left `WaterWaves` for the scene's wind
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6), and keep its upwind fetch and shore reflection.
+ */
+export class WaterWavesSerializationUpgrader_1_2 extends BinaryClassUpgrader {
+    upgrade(source: any, target: any): void;
+}
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+//# sourceMappingURL=WaterWavesSerializationUpgrader_1_2.d.ts.map

package/src/engine/graphics/ecs/water/WaterWavesSerializationUpgrader_1_2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WaterWavesSerializationUpgrader_1_2.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterWavesSerializationUpgrader_1_2.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH;IAII,wCAOC;CACJ;oCAlBmC,oDAAoD"}

package/src/engine/graphics/ecs/water/WaterWavesSerializationUpgrader_1_2.js

@@ -0,0 +1,19 @@
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+
+/**
+ * Drop version 1's wind speed and direction, which left `WaterWaves` for the scene's wind
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6), and keep its upwind fetch and shore reflection.
+ */
+export class WaterWavesSerializationUpgrader_1_2 extends BinaryClassUpgrader {
+    __startVersion = 1;
+    __targetVersion = 2;
+
+    upgrade(source, target) {
+        // wind speed, m/s, and direction, radians
+        source.readFloat32();
+        source.readFloat32();
+        // upwind fetch, metres, and shore reflection
+        target.writeFloat32(source.readFloat32());
+        target.writeFloat32(source.readFloat32());
+    }
+}

package/src/engine/graphics/texture/3d/scs3d_sample_linear3.d.ts

@@ -44,4 +44,25 @@ export function scs3d_sample_linear3(out: Float32Array | number[], data_0: Float
  * @return {Float32Array|Float64Array|number[]} `out`, for chaining.
  */
 export function scs3d_sample_linear3_array(out: Float32Array | Float64Array | number[], data_0: Float32Array, data_1: Float32Array, data_2: Float32Array, res_x: number, res_y: number, res_z: number, position: Float64Array, position_offset: number): Float32Array | Float64Array | number[];
+/**
+ * {@link scs3d_sample_linear3_array} over three channels interleaved in one array: cell `i`'s
+ * channels are `data[i * stride + channel_offset ..+2]`. For lattices that arrive as records — a GPU
+ * readback of `(x, y, z, pad)` rows is `stride` 4, `channel_offset` 0 — so they are sampled where they
+ * landed rather than split into three planes first.
+ *
+ * The same corners, weights, clamping and lerp order as the planar form, so on the same values it
+ * returns the same result, bit for bit.
+ *
+ * @param {Float32Array|Float64Array|number[]} out length >= 3
+ * @param {Float32Array} data
+ * @param {number} stride elements from one cell's channels to the next's, at least 3
+ * @param {number} channel_offset elements from a cell's start to its first channel
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Float64Array} position `[x, y, z]`, in grid index space
+ * @param {number} position_offset
+ * @return {Float32Array|Float64Array|number[]} `out`, for chaining.
+ */
+export function scs3d_sample_linear3_strided(out: Float32Array | Float64Array | number[], data: Float32Array, stride: number, channel_offset: number, res_x: number, res_y: number, res_z: number, position: Float64Array, position_offset: number): Float32Array | Float64Array | number[];
 //# sourceMappingURL=scs3d_sample_linear3.d.ts.map

package/src/engine/graphics/texture/3d/scs3d_sample_linear3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scs3d_sample_linear3.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/3d/scs3d_sample_linear3.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,0CAZW,YAAY,GAAC,MAAM,EAAE,UACrB,YAAY,UACZ,YAAY,UACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAWhC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,gDAXW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,UAClC,YAAY,UACZ,YAAY,UACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,YACN,YAAY,mBACZ,MAAM,GACL,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,CA0D7C"}
+{"version":3,"file":"scs3d_sample_linear3.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/3d/scs3d_sample_linear3.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,0CAZW,YAAY,GAAC,MAAM,EAAE,UACrB,YAAY,UACZ,YAAY,UACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAWhC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,gDAXW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,UAClC,YAAY,UACZ,YAAY,UACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,YACN,YAAY,mBACZ,MAAM,GACL,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,CA0D7C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,kDAXW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,QAClC,YAAY,UACZ,MAAM,kBACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,YACN,YAAY,mBACZ,MAAM,GACL,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,CA0D7C"}

package/src/engine/graphics/texture/3d/scs3d_sample_linear3.js

@@ -115,3 +115,81 @@ export function scs3d_sample_linear3_array(out, data_0, data_1, data_2, res_x, r
     );
     return out;
 }
+
+/**
+ * {@link scs3d_sample_linear3_array} over three channels interleaved in one array: cell `i`'s
+ * channels are `data[i * stride + channel_offset ..+2]`. For lattices that arrive as records — a GPU
+ * readback of `(x, y, z, pad)` rows is `stride` 4, `channel_offset` 0 — so they are sampled where they
+ * landed rather than split into three planes first.
+ *
+ * The same corners, weights, clamping and lerp order as the planar form, so on the same values it
+ * returns the same result, bit for bit.
+ *
+ * @param {Float32Array|Float64Array|number[]} out length >= 3
+ * @param {Float32Array} data
+ * @param {number} stride elements from one cell's channels to the next's, at least 3
+ * @param {number} channel_offset elements from a cell's start to its first channel
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Float64Array} position `[x, y, z]`, in grid index space
+ * @param {number} position_offset
+ * @return {Float32Array|Float64Array|number[]} `out`, for chaining.
+ */
+export function scs3d_sample_linear3_strided(out, data, stride, channel_offset, res_x, res_y, res_z, position, position_offset) {
+    const x = position[position_offset];
+    const y = position[position_offset + 1];
+    const z = position[position_offset + 2];
+
+    const x_max = res_x - 1;
+    const y_max = res_y - 1;
+    const z_max = res_z - 1;
+
+    const x_clamped = clamp(x, 0, x_max);
+    const y_clamped = clamp(y, 0, y_max);
+    const z_clamped = clamp(z, 0, z_max);
+
+    const x0 = x_clamped | 0;
+    const y0 = y_clamped | 0;
+    const z0 = z_clamped | 0;
+
+    const f_x = x_clamped - x0;
+    const f_y = y_clamped - y0;
+    const f_z = z_clamped - z0;
+
+    const x1 = x_clamped === x0 ? x0 : x0 + 1;
+    const y1 = y_clamped === y0 ? y0 : y0 + 1;
+    const z1 = z_clamped === z0 ? z0 : z0 + 1;
+
+    const slice = res_x * res_y;
+    const z0_offset = z0 * slice;
+    const z1_offset = z1 * slice;
+    const y0_offset = y0 * res_x;
+    const y1_offset = y1 * res_x;
+
+    const c000 = (z0_offset + y0_offset + x0) * stride + channel_offset;
+    const c100 = (z0_offset + y0_offset + x1) * stride + channel_offset;
+    const c010 = (z0_offset + y1_offset + x0) * stride + channel_offset;
+    const c110 = (z0_offset + y1_offset + x1) * stride + channel_offset;
+    const c001 = (z1_offset + y0_offset + x0) * stride + channel_offset;
+    const c101 = (z1_offset + y0_offset + x1) * stride + channel_offset;
+    const c011 = (z1_offset + y1_offset + x0) * stride + channel_offset;
+    const c111 = (z1_offset + y1_offset + x1) * stride + channel_offset;
+
+    out[0] = lerp(
+        lerp(lerp(data[c000], data[c100], f_x), lerp(data[c010], data[c110], f_x), f_y),
+        lerp(lerp(data[c001], data[c101], f_x), lerp(data[c011], data[c111], f_x), f_y),
+        f_z
+    );
+    out[1] = lerp(
+        lerp(lerp(data[c000 + 1], data[c100 + 1], f_x), lerp(data[c010 + 1], data[c110 + 1], f_x), f_y),
+        lerp(lerp(data[c001 + 1], data[c101 + 1], f_x), lerp(data[c011 + 1], data[c111 + 1], f_x), f_y),
+        f_z
+    );
+    out[2] = lerp(
+        lerp(lerp(data[c000 + 2], data[c100 + 2], f_x), lerp(data[c010 + 2], data[c110 + 2], f_x), f_y),
+        lerp(lerp(data[c001 + 2], data[c101 + 2], f_x), lerp(data[c011 + 2], data[c111 + 2], f_x), f_y),
+        f_z
+    );
+    return out;
+}

package/src/engine/graphics3/GPUFluidSystem.d.ts

@@ -0,0 +1,266 @@
+/**
+ * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../shade/renderer/extension/FrameContext.js").FrameContext} FrameContext
+ * @typedef {import("../physics/fluid/effector/AbstractFluidEffector.js").AbstractFluidEffector} AbstractFluidEffector
+ * @typedef {import("../physics/fluid/effector/record/fluid_effector_record_create.js").FluidEffectorRecord} FluidEffectorRecord
+ * @typedef {import("../physics/fluid/obstacle/fluid_obstacle_record_create.js").FluidObstacleRecord} FluidObstacleRecord
+ * @typedef {import("../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} AbstractShape3D
+ */
+/**
+ * The most fixed-step ticks one frame records (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §5). Ticks
+ * pending past it are dropped, and counted ({@link GPUFluidSystem#dropped_tick_count}); the atmosphere
+ * identity covers them.
+ *
+ * @type {number}
+ */
+export const GPU_FLUID_SYSTEM_TICK_CAP: number;
+/**
+ * # The GPU wind fluid of a scene
+ *
+ * GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §5: the ECS half of the GPU fluid. An entity with a
+ * {@link GPUFluidComponent} and a `Transform64` is the fluid's domain — nested, scrolling, two-way
+ * coupled cascades (`GPUFluidCascadeStack`) centred on the entity, stepped on the device at the
+ * simulation's fixed step and published as the scene's wind field (`GPUSceneContext#wind`), which
+ * every GPU consumer samples. `GlobalFluidEffector`s are its far field, folded by
+ * {@link FluidEffectorsSystem}; every other fluid effector and every {@link FluidObstacle} in the
+ * scene forces it.
+ *
+ * ```js
+ * await em.addSystem(new FluidEffectorsSystem());
+ * await em.addSystem(new GPUFluidSystem(graphics, scene));
+ *
+ * new Entity().add(new Transform64()).add(new GPUFluidComponent()).build(dataset);
+ * ```
+ *
+ * ## The CPU half: {@link far_field}
+ *
+ * The far field in m/s, synchronously, from {@link FluidEffectorsSystem}'s fold: deterministic, the
+ * same headless as on a device, and still air with no `FluidEffectorsSystem`. Gameplay reads this,
+ * never the fluid (§6).
+ *
+ * ## The CPU half: {@link request}, a lattice of the wind, asynchronously
+ *
+ * ```js
+ * const h = system.request(min_x, min_y, min_z, max_x, max_y, max_z, nx, ny, nz, target, target_offset);
+ * system.status[h]   // a GPUReadbackStatus: Pending, then Delivered or Dropped for one frame, then None
+ * ```
+ *
+ * The wind at `nx × ny × nz` points over the box, as every GPU consumer reads it
+ * (`wind_field_sample`), lands in `target` from `target_offset`: four floats a point, `(x, y, z, 0)`
+ * m/s, x fastest, point `(i, j, k)` at `mix(min, max, (i, j, k) / (n − 1))` per axis (an axis of one
+ * point at `min`). Presentation only, like everything read back (I-4): cloth, audio, volumetrics.
+ *
+ * - **The apply point is {@link update}**, once a frame: a status set there reads that way until the
+ *   next one, where the handle is recycled. A fixed step reads the statuses its frame's update set.
+ * - **With a device**, the frame's requests are recorded at `FrameStart`, after the publish of the
+ *   wind field: rows of the read API's database (`GPUFluidQueries`), a gather of `wind_field_sample`
+ *   into them, and the readback's copy right after it, in the same pass. Delivery is in order, at
+ *   most 4 batches (a frame's requests each) in flight; a frame's requests past that are dropped,
+ *   with the status. Measured latency: see the proposal (§12). Rows are freed after delivery or a
+ *   drop. A device restart drops what was in flight; requests not yet recorded go to the new device.
+ * - **Headless** (no scene context at the update): answered from {@link far_field} at the next
+ *   {@link update}, every point the far field.
+ *
+ * At steady state nothing is allocated per request.
+ *
+ * ## The GPU half, at `FramePhase.FrameStart`
+ *
+ * - **Ticks.** The ticks `EntityManager.fixedStepTick` has advanced since the frame that last
+ *   recorded, at most {@link GPU_FLUID_SYSTEM_TICK_CAP} of them, the latest; the rest are dropped and
+ *   counted ({@link dropped_tick_count}). Each steps the stack at `fixedUpdateStepSize` against the
+ *   far field at the end of the frame's last tick. `fixedStepTick` is a local counter, which is all a
+ *   presentation fluid needs; nothing simulated reads the fluid.
+ * - **The frame**, on a frame that records ticks: `GPUFluidForcing#record_frame` (the rows' upload,
+ *   the leaves, the LBVH), clipped to the coarsest window, wakes swept over the frame's longest
+ *   step, node motion taken over `1 / (frame_dt · fixedStepTimeScale)`; then each tick's
+ *   `record_tick`; then `record_publish` into the scene's wind field, whose table is uploaded at
+ *   once so the frame's readers see it.
+ * - **No domain:** nothing is recorded and nothing is held on the device; the wind field carries the
+ *   far field alone.
+ *
+ * ## Rows
+ *
+ * Kept from the entities on the CPU (in {@link update}, so a row acquired this frame is written
+ * before the frame reads it, and again at `FrameStart` if no update ran), written only where a field
+ * changed (`write_gpu_record`, `fluid_obstacle_write_gpu_motion` compare while they assign):
+ *
+ * - **Effectors.** Each effector of a {@link FluidEffectorsComponent} with a GPU record (impulse,
+ *   wake, vortex) is a row. Its `node` is its entity's row when the entity has a `Transform64`, held
+ *   with its chain through {@link RowChains}, so the effector follows its entity on the GPU and a
+ *   wake takes its node's motion (`fluid_effector_record_resolve` from the node's `global` and
+ *   `prev_global`; a `TRANSFORM64_EVENT_PLACED` seeds them equal, so a teleport gives no motion).
+ *   Without a `Transform64` it is 0, the world, and the effector writes itself there. Adding or
+ *   removing an effector of the component rewrites the entity's rows.
+ * - **Obstacles.** An entity with {@link FluidObstacle}, `Collider`, `RigidBody` and `Transform64` —
+ *   `FluidObstacleSystem`'s tuple — is a run of rows, one per record its collider's shape packs into
+ *   (`fluid_obstacle_write_gpu_shape`), with its hulls' planes, posed by its row. The shape is packed
+ *   again when the collider is handed another shape object, the run made anew when the count of
+ *   records or planes moves; the inflation and the body's velocities are compared every frame.
+ *
+ * ## Several domains
+ *
+ * The scene has one wind (F2, R1): the domain is the enabled `GPUFluidComponent` on the lowest entity
+ * id. Any other enabled component is dormant — it holds nothing on the device — and takes over when
+ * that one is removed or disabled. Overlapping domains coupled to each other are not in the proposal
+ * (§20).
+ *
+ * ## Lifetime
+ *
+ * The stack is made when a domain first meets a device, from its component, seeded at the far field
+ * (nothing of the fluid is saved, §6), and made again when the component's resolution, cell size or
+ * cascade count changes or another entity becomes the domain. A device restart (a new scene context)
+ * drops the stack, the forcing and their rows with the old device and builds them again on the new
+ * one; the chains held in the scene's rows move to the new rows by themselves. Losing the domain
+ * releases everything, rows included. At a fixed scene, nothing is created after the first frame.
+ */
+export class GPUFluidSystem extends System<any> {
+    /**
+     * @param {import("./GraphicsEngine.js").GraphicsEngine} graphics
+     * @param {import("../../shade/renderer/scene/Scene.js").Scene} scene the scene whose wind this is
+     */
+    constructor(graphics: import("./GraphicsEngine.js").GraphicsEngine, scene: import("../../shade/renderer/scene/Scene.js").Scene);
+    dependencies: (typeof Transform64 | typeof GPUFluidComponent)[];
+    components_used: (ResourceAccessSpecification<typeof FluidEffectorsComponent> | ResourceAccessSpecification<typeof FluidObstacle> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof RigidBody>)[];
+    /**
+     * @returns {import("../../shade/renderer/scene/Scene.js").Scene}
+     */
+    get scene(): import("../../shade/renderer/scene/Scene.js").Scene;
+    /**
+     * The entity whose {@link GPUFluidComponent} is the scene's domain: the lowest one with an enabled
+     * component, or -1 for none. Read once a tick by cloth's default wind; allocates nothing.
+     *
+     * @returns {number}
+     */
+    get domain(): number;
+    /**
+     * The domain's cascades on the device, or null while there is no domain or no device. For
+     * inspection: the system owns it, and makes it anew when the domain changes.
+     *
+     * @returns {GPUFluidCascadeStack|null}
+     */
+    get stack(): GPUFluidCascadeStack;
+    /**
+     * The fluid database of the scene's effectors and obstacles, with its LBVH and forcing, or null
+     * while there is no domain or no device. For inspection: the system keeps its rows.
+     *
+     * @returns {GPUFluidForcing|null}
+     */
+    get forcing(): GPUFluidForcing;
+    /**
+     * Fixed-step ticks no frame recorded since the system started: those pending past
+     * {@link GPU_FLUID_SYSTEM_TICK_CAP} at a frame.
+     *
+     * @returns {number}
+     */
+    get dropped_tick_count(): number;
+    /**
+     * The far field now, m/s: `v_far` at the end of the last fixed step, as {@link FluidEffectorsSystem}
+     * folds the `GlobalFluidEffector`s (§6). Synchronous and deterministic, with or without a device;
+     * still air when there is no `FluidEffectorsSystem`. Allocates nothing.
+     *
+     * @param {Float64Array|Float32Array|number[]} out receives `[x, y, z]`
+     */
+    far_field(out: Float64Array | Float32Array | number[]): void;
+    /**
+     * What became of each request, by handle: a `GPUReadbackStatus`. `Pending` from {@link request}
+     * until the apply point ({@link update}) that answers it, `Delivered` (the lattice is in its
+     * target) or `Dropped` (the target is as it was) from there until the next apply point, then
+     * `None`, the handle recycled.
+     *
+     * Read it fresh each time rather than keeping a reference: the array is replaced when the handle
+     * space grows.
+     *
+     * @returns {Uint8Array}
+     */
+    get status(): Uint8Array;
+    /**
+     * The read API's device half, or null before the first frame with a request on a device. For
+     * inspection: its rows and its readback's counters.
+     *
+     * @returns {GPUFluidQueries|null}
+     */
+    get queries(): GPUFluidQueries;
+    /**
+     * Ask for the wind on a lattice over a box: `count_x × count_y × count_z` points, landing in
+     * `target` from `target_offset` as four floats a point, `(x, y, z, 0)` m/s, x fastest; point
+     * `(i, j, k)` at `mix(min, max, (i, j, k) / (count − 1))` per axis, an axis of one point at its
+     * `min`. Answered at a later apply point ({@link update}); see {@link status}.
+     *
+     * Positional, and a few stores into retained arrays: nothing is allocated per request.
+     *
+     * @param {number} min_x world metres
+     * @param {number} min_y
+     * @param {number} min_z
+     * @param {number} max_x at least `min_x`
+     * @param {number} max_y
+     * @param {number} max_z
+     * @param {number} count_x points along x, at least 1
+     * @param {number} count_y
+     * @param {number} count_z
+     * @param {Float32Array} target memory the caller owns and keeps until the request settles
+     * @param {number} target_offset in floats
+     * @returns {number} a handle into {@link status}
+     */
+    request(min_x: number, min_y: number, min_z: number, max_x: number, max_y: number, max_z: number, count_x: number, count_y: number, count_z: number, target: Float32Array, target_offset: number): number;
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {GPUFluidComponent} component
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(component: GPUFluidComponent, transform: Transform64, entity: number): void;
+    /**
+     * @param {GPUFluidComponent} component
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(component: GPUFluidComponent, transform: Transform64, entity: number): void;
+    /**
+     * The frame's GPU work, at `FramePhase.FrameStart`: the pending ticks and the publish, then the
+     * read API's requests.
+     *
+     * @param {FrameContext} frame
+     */
+    prepare(frame: FrameContext): void;
+    /**
+     * Says what this system is to code that cannot import it: cloth's world finds the scene's GPU fluid
+     * among the entity manager's systems by it, because importing this module needs WebGPU's globals and
+     * a cloth scene on a server has none. The `Scene#isScene` pattern.
+     *
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isGPUFluidSystem: boolean;
+    #private;
+}
+/**
+ * Records {@link GPUFluidSystem}'s ticks and publish at the start of a frame, before anything reads
+ * the scene's wind.
+ */
+export class GPUFluidExtension extends RenderExtension {
+    /**
+     * @param {GPUFluidSystem} system
+     */
+    constructor(system: GPUFluidSystem);
+    system: GPUFluidSystem;
+}
+export type GPUSceneContext = import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext;
+export type FrameContext = import("../../shade/renderer/extension/FrameContext.js").FrameContext;
+export type AbstractFluidEffector = import("../physics/fluid/effector/AbstractFluidEffector.js").AbstractFluidEffector;
+export type FluidEffectorRecord = import("../physics/fluid/effector/record/fluid_effector_record_create.js").FluidEffectorRecord;
+export type FluidObstacleRecord = import("../physics/fluid/obstacle/fluid_obstacle_record_create.js").FluidObstacleRecord;
+export type AbstractShape3D = import("../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D;
+import { System } from "../ecs/System.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
+import { GPUFluidComponent } from "../physics/fluid/ecs/GPUFluidComponent.js";
+import { FluidEffectorsComponent } from "../physics/fluid/ecs/FluidEffectorsComponent.js";
+import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
+import { FluidObstacle } from "../physics/fluid/ecs/FluidObstacle.js";
+import { Collider } from "../physics/ecs/Collider.js";
+import { RigidBody } from "../physics/ecs/RigidBody.js";
+import { GPUFluidCascadeStack } from "../../shade/renderer/fluid/GPUFluidCascadeStack.js";
+import { GPUFluidForcing } from "../../shade/renderer/fluid/forcing/GPUFluidForcing.js";
+import { GPUFluidQueries } from "../../shade/renderer/fluid/query/GPUFluidQueries.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+//# sourceMappingURL=GPUFluidSystem.d.ts.map

package/src/engine/graphics3/GPUFluidSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUFluidSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GPUFluidSystem.js"],"names":[],"mappings":"AAyCA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,wCAFU,MAAM,CAE2B;AAmG3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkGG;AACH;IAyII;;;OAGG;IACH,sBAHW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,EAU7D;IAnJD,gEAAgD;IAEhD,oOAME;IA6IF;;OAEG;IACH,iEAEC;IAED;;;;;OAKG;IACH,qBAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;OAKG;IACH,+BAEC;IAED;;;;;OAKG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,eAFW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,QAQ5C;IAED;;;;;;;;;;OAUG;IACH,yBAEC;IAED;;;;;OAKG;IACH,+BAEC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAbW,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,UACN,YAAY,iBACZ,MAAM,GACJ,MAAM,CA+ClB;IAmMD,2CAoBC;IAED,4CAaC;IA6CD;;;;OAIG;IACH,gBAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAOhB;IAED;;;;OAIG;IACH,kBAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAiBhB;IAohBD;;;;;OAKG;IACH,eAFW,YAAY,QAetB;IAkKL;;;;;;;OAOG;IACH,2BAFU,OAAO,CAEwB;;CAVxC;AAYD;;;GAGG;AACH;IAII;;OAEG;IACH,oBAFW,cAAc,EAMxB;IADG,uBAAoB;CAS3B;8BAliDY,OAAO,+CAA+C,EAAE,eAAe;2BACvE,OAAO,gDAAgD,EAAE,YAAY;oCACrE,OAAO,oDAAoD,EAAE,qBAAqB;kCAClF,OAAO,kEAAkE,EAAE,mBAAmB;kCAC9F,OAAO,2DAA2D,EAAE,mBAAmB;8BACvF,OAAO,6CAA6C,EAAE,eAAe;uBAjC3D,kBAAkB;4BACb,iCAAiC;kCAWtD,2CAA2C;wCARV,iDAAiD;4CAf7C,iDAAiD;8BAiB/D,uCAAuC;yBAJ5C,4BAA4B;0BAC3B,6BAA6B;qCARlB,oDAAoD;gCADzD,uDAAuD;gCAE5B,qDAAqD;gCAJhF,mDAAmD"}