@woosh/meep-engine 3.47.0 → 3.50.0

package/src/engine/graphics3/GPUFluidSystem.js

@@ -0,0 +1,1613 @@
+import { assert } from "../../core/assert.js";
+import { isPowerOfTwo } from "../../core/math/isPowerOfTwo.js";
+import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
+import { GPUReadbackStatus } from "../../shade/renderer/buffer/table/GPUReadbackStatus.js";
+import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { fluid_cascade_ruler } from "../../shade/renderer/fluid/fluid_cascade_ruler.js";
+import { GPUFluidForcing } from "../../shade/renderer/fluid/forcing/GPUFluidForcing.js";
+import { GPUFluidCascadeStack } from "../../shade/renderer/fluid/GPUFluidCascadeStack.js";
+import { FLUID_QUERY_SAMPLE_FLOATS, GPUFluidQueries } from "../../shade/renderer/fluid/query/GPUFluidQueries.js";
+import { NODE3D_SCENE_ID } from "../../shade/renderer/scene/NODE3D_STRUCT.js";
+import { row_of_entity } from "../../shade/renderer/scene/rows/GPUSceneRows.js";
+import { EntityObserver } from "../ecs/EntityObserver.js";
+import { System } from "../ecs/System.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
+import { Collider } from "../physics/ecs/Collider.js";
+import { RigidBody } from "../physics/ecs/RigidBody.js";
+import { FluidEffectorsComponent } from "../physics/fluid/ecs/FluidEffectorsComponent.js";
+import { FluidEffectorsSystem } from "../physics/fluid/ecs/FluidEffectorsSystem.js";
+import { FluidObstacle } from "../physics/fluid/ecs/FluidObstacle.js";
+import {
+    GPU_FLUID_COMPONENT_CASCADE_LIMIT,
+    GPU_FLUID_COMPONENT_RESOLUTION_MAX,
+    GPU_FLUID_COMPONENT_RESOLUTION_MIN,
+    GPUFluidComponent
+} from "../physics/fluid/ecs/GPUFluidComponent.js";
+import { fluid_effector_record_create } from "../physics/fluid/effector/record/fluid_effector_record_create.js";
+import { FLUID_ATMOSPHERE_WORDS, FluidAtmosphere } from "../physics/fluid/FluidAtmosphere.js";
+import { fluid_obstacle_record_create } from "../physics/fluid/obstacle/fluid_obstacle_record_create.js";
+import {
+    FLUID_OBSTACLE_PLANES_CHANGED,
+    FLUID_OBSTACLE_RECORD_CHANGED,
+    fluid_obstacle_plane_count,
+    fluid_obstacle_record_count,
+    fluid_obstacle_record_plane_count,
+    fluid_obstacle_write_gpu_motion,
+    fluid_obstacle_write_gpu_shape
+} from "../physics/fluid/obstacle/fluid_obstacle_write_gpu_record.js";
+import { RowChains } from "./RowChains.js";
+
+/**
+ * @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 = 2;
+
+/** Handles the read API starts with, doubling. */
+const REQUEST_INITIAL_CAPACITY = 16;
+
+/**
+ * @param {Uint32Array|Float64Array|Uint8Array} array
+ * @param {number} length
+ * @returns {Uint32Array|Float64Array|Uint8Array} `array`, or a copy of it at least `length` long
+ */
+function fit(array, length) {
+    if (array.length >= length) {
+        return array;
+    }
+
+    const grown = new array.constructor(Math.max(length, 2 * array.length));
+
+    grown.set(array);
+
+    return grown;
+}
+
+/**
+ * One entity's {@link FluidEffectorsComponent}, as the fluid database holds it: a row for each
+ * effector with a GPU record, in the component's order.
+ */
+class EffectorEntry {
+    /** @type {number} */
+    entity = -1;
+
+    /** @type {FluidEffectorsComponent|null} */
+    component = null;
+
+    /**
+     * The component's effectors as the rows were made for them, by identity.
+     * @type {AbstractFluidEffector[]}
+     */
+    effectors = [];
+
+    /**
+     * The row of each of {@link effectors}, -1 for one with no GPU record or no row yet.
+     * @type {number[]}
+     */
+    rows = [];
+
+    /**
+     * The staging record of each of {@link effectors}, what its row was last written from.
+     * @type {(FluidEffectorRecord|null)[]}
+     */
+    records = [];
+
+    /**
+     * The transforms row the records are posed by: the entity's, or 0 for an entity without a
+     * `Transform64`. -1 before the first sync.
+     * @type {number}
+     */
+    node = -1;
+
+    /** Whether the entity's chain is held in the scene's rows. */
+    held = false;
+}
+
+/**
+ * One obstacle tuple's collider, as the fluid database holds it: a run of obstacle rows, one for each
+ * record its shape packs into, and a run of plane rows for its hulls.
+ */
+class ObstacleEntry {
+    /** @type {number} */
+    entity = -1;
+
+    /** @type {FluidObstacle|null} */
+    obstacle = null;
+
+    /** @type {Collider|null} */
+    collider = null;
+
+    /** @type {RigidBody|null} */
+    body = null;
+
+    /**
+     * The shape the records were packed from, null before the first pack.
+     * @type {AbstractShape3D|null}
+     */
+    shape = null;
+
+    /** The run's first obstacle row, -1 for none. */
+    first = -1;
+
+    /** @type {FluidObstacleRecord[]} one per record of the shape, the run's length */
+    records = [];
+
+    /** The plane run's first row, -1 for none. */
+    plane_first = -1;
+    plane_count = 0;
+
+    /** Whether the entity's chain is held in the scene's rows. */
+    held = false;
+}
+
+/**
+ * # 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 {
+
+    dependencies = [GPUFluidComponent, Transform64];
+
+    components_used = [
+        // the effectors and obstacles are read into rows; FluidEffectorsSystem advances the effectors
+        ResourceAccessSpecification.from(FluidEffectorsComponent, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(FluidObstacle, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(RigidBody, ResourceAccessKind.Read),
+    ];
+
+    /** @type {import("./GraphicsEngine.js").GraphicsEngine} */
+    #graphics;
+
+    /** @type {import("../../shade/renderer/scene/Scene.js").Scene} */
+    #scene;
+
+    /** @type {GPUFluidExtension|null} */
+    #extension = null;
+
+    /**
+     * Every entity with the system's tuple, by entity: candidates for the domain.
+     * @type {Map<number, {component: GPUFluidComponent, transform: Transform64}>}
+     */
+    #domains = new Map();
+
+    /** The same candidates as two arrays, for {@link #pick_domain}'s walk. @type {number[]} */
+    #domain_entities = [];
+
+    /** @type {GPUFluidComponent[]} */
+    #domain_components = [];
+
+    /** @type {Map<number, EffectorEntry>} */
+    #effectors = new Map();
+
+    /** @type {Map<number, ObstacleEntry>} */
+    #obstacles = new Map();
+
+    /** @type {EntityObserver} */
+    #effector_observer = new EntityObserver([FluidEffectorsComponent], this.#effectors_linked, this.#effectors_unlinked, this);
+
+    /** @type {EntityObserver} */
+    #obstacle_observer = new EntityObserver([FluidObstacle, Collider, RigidBody, Transform64], this.#obstacle_linked, this.#obstacle_unlinked, this);
+
+    /** @type {import("../ecs/EntityComponentDataset.js").EntityComponentDataset|null} */
+    #dataset = null;
+
+    /** `Transform64`'s index in {@link #dataset}. */
+    #transform_index = -1;
+
+    /** @type {RowChains|null} */
+    #chains = null;
+
+    /** @type {FluidEffectorsSystem|null} */
+    #effectors_system = null;
+
+    /** The far field, as {@link FluidEffectorsSystem#read_atmosphere} hands it out. */
+    #atmosphere = new Float64Array(FLUID_ATMOSPHERE_WORDS);
+
+    /**
+     * The scene context the device state below belongs to.
+     * @type {GPUSceneContext|null}
+     */
+    #context = null;
+
+    /** @type {GPUFluidForcing|null} */
+    #forcing = null;
+
+    /** @type {GPUFluidCascadeStack|null} */
+    #stack = null;
+
+    /** The entity whose component {@link #stack} was made from, -1 for none. */
+    #stack_entity = -1;
+
+    /** What {@link #stack} was made with. */
+    #stack_resolution = new Int32Array(3);
+    #stack_cell_size = 0;
+    #stack_cascade_count = 0;
+
+    /** Whether {@link #stack} has not been published yet. */
+    #stack_fresh = false;
+
+    /** The last tick a frame recorded, or the tick the stack was made at. */
+    #last_tick = 0;
+
+    #dropped_ticks = 0;
+
+    /** Game-clock seconds {@link update} has seen since the last frame's `FrameStart`, wall time. */
+    #frame_seconds = 0;
+
+    /** Whether {@link update} has kept the rows since the last `FrameStart`. */
+    #refreshed = false;
+
+    /** Whether an entry may hold a chain in the scene's rows. */
+    #holding = false;
+
+    /** How many cascades the wind field was last given, and the far field it was last given. */
+    #wind_cascades = 0;
+    #wind_far = Float64Array.of(NaN, NaN, NaN);
+
+    #anchor = new Float64Array(3);
+    #bounds = new Float64Array(6);
+    #far = new Float64Array(3);
+
+    /*
+     The read API: per handle, the request's box and counts, its target, and its status.
+    */
+    #request_box = new Float64Array(6 * REQUEST_INITIAL_CAPACITY);
+    #request_counts = new Uint32Array(3 * REQUEST_INITIAL_CAPACITY);
+    #request_offsets = new Uint32Array(REQUEST_INITIAL_CAPACITY);
+    /** @type {(Float32Array|null)[]} */
+    #request_targets = new Array(REQUEST_INITIAL_CAPACITY).fill(null);
+    #status = new Uint8Array(REQUEST_INITIAL_CAPACITY);
+
+    /** Recycled handles. */
+    #free_handles = new Uint32Array(REQUEST_INITIAL_CAPACITY);
+    #free_count = 0;
+
+    /** Handles below this have been handed out at least once. */
+    #fresh = 0;
+
+    /** Handles asked for and not yet answered headless or handed to the device. */
+    #asked = new Uint32Array(REQUEST_INITIAL_CAPACITY);
+    #asked_count = 0;
+
+    /** Handles that settled at the last apply point, recycled at the next. */
+    #settled = new Uint32Array(REQUEST_INITIAL_CAPACITY);
+    #settled_count = 0;
+
+    /**
+     * The read API on the device: its database, gather and readback. Made by the first frame with a
+     * request, dropped with the device.
+     * @type {GPUFluidQueries|null}
+     */
+    #queries = null;
+
+    /**
+     * @param {import("./GraphicsEngine.js").GraphicsEngine} graphics
+     * @param {import("../../shade/renderer/scene/Scene.js").Scene} scene the scene whose wind this is
+     */
+    constructor(graphics, scene) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.equal(scene.isScene, true, 'scene.isScene !== true');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+    }
+
+    /**
+     * @returns {import("../../shade/renderer/scene/Scene.js").Scene}
+     */
+    get scene() {
+        return this.#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() {
+        return this.#pick_domain();
+    }
+
+    /**
+     * 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() {
+        return this.#stack;
+    }
+
+    /**
+     * 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() {
+        return this.#forcing;
+    }
+
+    /**
+     * 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() {
+        return this.#dropped_ticks;
+    }
+
+    /**
+     * 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) {
+        const atmosphere = this.#read_atmosphere();
+
+        out[0] = atmosphere[FluidAtmosphere.VELOCITY_X];
+        out[1] = atmosphere[FluidAtmosphere.VELOCITY_Y];
+        out[2] = atmosphere[FluidAtmosphere.VELOCITY_Z];
+    }
+
+    /**
+     * 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() {
+        return this.#status;
+    }
+
+    /**
+     * 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() {
+        return this.#queries;
+    }
+
+    /**
+     * 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, min_y, min_z, max_x, max_y, max_z, count_x, count_y, count_z, target, target_offset) {
+        assert.isFinite(min_x, 'min_x');
+        assert.isFinite(min_y, 'min_y');
+        assert.isFinite(min_z, 'min_z');
+        assert.isFinite(max_x, 'max_x');
+        assert.isFinite(max_y, 'max_y');
+        assert.isFinite(max_z, 'max_z');
+        assert.lessThanOrEqual(min_x, max_x, 'min_x');
+        assert.lessThanOrEqual(min_y, max_y, 'min_y');
+        assert.lessThanOrEqual(min_z, max_z, 'min_z');
+        assert.isPositiveInteger(count_x, 'count_x');
+        assert.isPositiveInteger(count_y, 'count_y');
+        assert.isPositiveInteger(count_z, 'count_z');
+        assert.ok(target instanceof Float32Array, 'target must be a Float32Array');
+        assert.isNonNegativeInteger(target_offset, 'target_offset');
+        assert.lessThanOrEqual(target_offset + FLUID_QUERY_SAMPLE_FLOATS * count_x * count_y * count_z, target.length, 'the lattice reaches past the target');
+
+        const h = this.#allocate_handle();
+
+        const box = this.#request_box;
+
+        box[6 * h] = min_x;
+        box[6 * h + 1] = min_y;
+        box[6 * h + 2] = min_z;
+        box[6 * h + 3] = max_x;
+        box[6 * h + 4] = max_y;
+        box[6 * h + 5] = max_z;
+
+        const counts = this.#request_counts;
+
+        counts[3 * h] = count_x;
+        counts[3 * h + 1] = count_y;
+        counts[3 * h + 2] = count_z;
+
+        this.#request_offsets[h] = target_offset;
+        this.#request_targets[h] = target;
+        this.#status[h] = GPUReadbackStatus.Pending;
+
+        if (this.#asked_count === this.#asked.length) {
+            this.#asked = fit(this.#asked, this.#asked_count + 1);
+        }
+
+        this.#asked[this.#asked_count++] = h;
+
+        return h;
+    }
+
+    /**
+     * @returns {number}
+     */
+    #allocate_handle() {
+        if (this.#free_count > 0) {
+            return this.#free_handles[--this.#free_count];
+        }
+
+        const h = this.#fresh++;
+
+        if (h === this.#status.length) {
+            const capacity = 2 * h;
+
+            this.#request_box = fit(this.#request_box, 6 * capacity);
+            this.#request_counts = fit(this.#request_counts, 3 * capacity);
+            this.#request_offsets = fit(this.#request_offsets, capacity);
+            this.#status = fit(this.#status, capacity);
+            this.#free_handles = fit(this.#free_handles, capacity);
+            this.#settled = fit(this.#settled, capacity);
+
+            for (let i = this.#request_targets.length; i < capacity; i++) {
+                this.#request_targets.push(null);
+            }
+        }
+
+        return h;
+    }
+
+    /**
+     * A request answered: its status set, readable until the next apply point.
+     *
+     * @param {number} h
+     * @param {number} status
+     */
+    #settle(h, status) {
+        this.#status[h] = status;
+        this.#request_targets[h] = null;
+        this.#settled[this.#settled_count++] = h;
+    }
+
+    /**
+     * The apply point's first half: the handles answered at the last one go back to the free list.
+     */
+    #recycle_requests() {
+        const settled = this.#settled;
+        const status = this.#status;
+        const free = this.#free_handles;
+
+        for (let i = 0; i < this.#settled_count; i++) {
+            const h = settled[i];
+
+            status[h] = GPUReadbackStatus.None;
+            free[this.#free_count++] = h;
+        }
+
+        this.#settled_count = 0;
+    }
+
+    /**
+     * The apply point's second half: what the device delivered or dropped, and, headless, every
+     * request asked since from the far field.
+     */
+    #answer_requests() {
+        const queries = this.#queries;
+
+        if (queries !== null) {
+            queries.apply();
+
+            this.#take_settled(queries);
+        }
+
+        if (this.#context !== null || this.#asked_count === 0) {
+            return;
+        }
+
+        // headless: every point the far field
+        const far = this.#far;
+
+        this.far_field(far);
+
+        const asked = this.#asked;
+        const counts = this.#request_counts;
+
+        for (let i = 0; i < this.#asked_count; i++) {
+            const h = asked[i];
+            const target = this.#request_targets[h];
+            const points = counts[3 * h] * counts[3 * h + 1] * counts[3 * h + 2];
+
+            let at = this.#request_offsets[h];
+
+            for (let p = 0; p < points; p++, at += FLUID_QUERY_SAMPLE_FLOATS) {
+                target[at] = far[0];
+                target[at + 1] = far[1];
+                target[at + 2] = far[2];
+                target[at + 3] = 0;
+            }
+
+            this.#settle(h, GPUReadbackStatus.Delivered);
+        }
+
+        this.#asked_count = 0;
+    }
+
+    /**
+     * @param {GPUFluidQueries} queries after an apply or a destroy
+     */
+    #take_settled(queries) {
+        for (let i = 0; i < queries.settled_count; i++) {
+            this.#settle(queries.settled_tag(i), queries.settled_status(i));
+        }
+    }
+
+    /**
+     * Hand the frame's requests to the device, after the frame's publish of the wind field.
+     *
+     * @param {import("../graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
+     * @param {GPUSceneContext} context
+     */
+    #record_requests(graph, context) {
+        const count = this.#asked_count;
+
+        if (count === 0) {
+            return;
+        }
+
+        let queries = this.#queries;
+
+        if (queries === null) {
+            queries = this.#queries = new GPUFluidQueries({ device: this.#graphics.renderer.graphics.device });
+        }
+
+        const asked = this.#asked;
+        const box = this.#request_box;
+        const counts = this.#request_counts;
+
+        for (let i = 0; i < count; i++) {
+            const h = asked[i];
+
+            queries.request(
+                box[6 * h], box[6 * h + 1], box[6 * h + 2],
+                box[6 * h + 3], box[6 * h + 4], box[6 * h + 5],
+                counts[3 * h], counts[3 * h + 1], counts[3 * h + 2],
+                this.#request_targets[h], this.#request_offsets[h],
+                h
+            );
+        }
+
+        this.#asked_count = 0;
+
+        queries.record({ graph, wind: context.wind });
+    }
+
+    /**
+     * Let go of the read API's device half: whatever it had in flight is dropped, its status set now.
+     */
+    #drop_queries() {
+        const queries = this.#queries;
+
+        if (queries === null) {
+            return;
+        }
+
+        queries.destroy();
+
+        this.#take_settled(queries);
+
+        this.#queries = null;
+    }
+
+    /**
+     * The far field and its terms, into {@link #atmosphere}; still air at time 0 with no effectors
+     * system.
+     *
+     * @returns {Float64Array}
+     */
+    #read_atmosphere() {
+        const atmosphere = this.#atmosphere;
+        let effectors = this.#effectors_system;
+
+        if (effectors === null && this.entityManager !== null) {
+            // registered later than this system, or never
+            effectors = this.#effectors_system = this.entityManager.getSystem(FluidEffectorsSystem);
+        }
+
+        if (effectors === null) {
+            atmosphere.fill(0);
+        } else {
+            effectors.read_atmosphere(atmosphere, 0);
+        }
+
+        return atmosphere;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        const dataset = entityManager.dataset;
+        const scene = this.#scene;
+
+        assert.ok(
+            scene.dataset === null || scene.dataset === undefined || dataset === null || scene.dataset === dataset,
+            'the scene is bound to another dataset'
+        );
+
+        if (dataset !== null) {
+            // the scene's rows are this dataset's entities; the first system to place one says so
+            scene.dataset = dataset;
+        }
+
+        this.#effectors_system = entityManager.getSystem(FluidEffectorsSystem);
+
+        this.#extension = new GPUFluidExtension(this);
+        this.#graphics.add_extension(this.#extension);
+    }
+
+    async shutdown(entityManager) {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+            this.#extension = null;
+        }
+
+        this.#detach();
+
+        this.#drop_device(true);
+        this.#drop_queries();
+
+        this.#context = null;
+        this.#effectors_system = null;
+    }
+
+    /**
+     * @param {import("../ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
+     */
+    handleDatasetAttached(dataset) {
+        this.#detach();
+
+        this.#dataset = dataset;
+        this.#transform_index = dataset.computeComponentTypeIndex(Transform64);
+        this.#chains = new RowChains(dataset);
+
+        dataset.addObserver(this.#effector_observer, true);
+        dataset.addObserver(this.#obstacle_observer, true);
+    }
+
+    /**
+     * @param {import("../ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
+     */
+    handleDatasetDetached(dataset) {
+        this.#detach();
+    }
+
+    /**
+     * Stop watching the dataset: every entry let go, the device state and the chains with them.
+     */
+    #detach() {
+        const dataset = this.#dataset;
+
+        if (dataset === null) {
+            return;
+        }
+
+        dataset.removeObserver(this.#effector_observer, true);
+        dataset.removeObserver(this.#obstacle_observer, true);
+
+        this.#drop_device(true);
+
+        this.#chains.destroy();
+        this.#chains = null;
+
+        this.#dataset = null;
+        this.#transform_index = -1;
+    }
+
+    /**
+     * @param {GPUFluidComponent} component
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(component, transform, entity) {
+        this.#domains.set(entity, { component, transform });
+
+        this.#domain_entities.push(entity);
+        this.#domain_components.push(component);
+    }
+
+    /**
+     * @param {GPUFluidComponent} component
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(component, transform, entity) {
+        this.#domains.delete(entity);
+
+        const entities = this.#domain_entities;
+        const index = entities.indexOf(entity);
+
+        if (index !== -1) {
+            const last = entities.length - 1;
+
+            entities[index] = entities[last];
+            this.#domain_components[index] = this.#domain_components[last];
+
+            entities.length = last;
+            this.#domain_components.length = last;
+        }
+    }
+
+    /**
+     * @param {FluidEffectorsComponent} component
+     * @param {number} entity
+     */
+    #effectors_linked(component, entity) {
+        const entry = new EffectorEntry();
+
+        entry.entity = entity;
+        entry.component = component;
+
+        this.#effectors.set(entity, entry);
+    }
+
+    /**
+     * @param {FluidEffectorsComponent} component
+     * @param {number} entity
+     */
+    #effectors_unlinked(component, entity) {
+        const entry = this.#effectors.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#remove_effector_rows(entry);
+        this.#let_go(entry);
+
+        this.#effectors.delete(entity);
+    }
+
+    /**
+     * @param {FluidObstacle} obstacle
+     * @param {Collider} collider
+     * @param {RigidBody} body
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    #obstacle_linked(obstacle, collider, body, transform, entity) {
+        const entry = new ObstacleEntry();
+
+        entry.entity = entity;
+        entry.obstacle = obstacle;
+        entry.collider = collider;
+        entry.body = body;
+
+        this.#obstacles.set(entity, entry);
+    }
+
+    /**
+     * @param {FluidObstacle} obstacle
+     * @param {Collider} collider
+     * @param {RigidBody} body
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    #obstacle_unlinked(obstacle, collider, body, transform, entity) {
+        const entry = this.#obstacles.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#remove_obstacle_rows(entry);
+        this.#let_go(entry);
+
+        this.#obstacles.delete(entity);
+    }
+
+    /**
+     * Release an entry's hold on its chain.
+     *
+     * @param {EffectorEntry|ObstacleEntry} entry
+     */
+    #let_go(entry) {
+        if (entry.held) {
+            this.#chains.release(entry.entity);
+            entry.held = false;
+        }
+    }
+
+    /**
+     * @returns {number} the domain's entity, or -1
+     */
+    #pick_domain() {
+        // by index over the candidates, not over the map: `domain` is read once a tick by cloth's
+        // default wind, and a map walk makes an entry a candidate
+        const entities = this.#domain_entities;
+        const components = this.#domain_components;
+
+        let best = -1;
+
+        for (let i = 0; i < entities.length; i++) {
+            const entity = entities[i];
+
+            if (components[i].enabled && (best === -1 || entity < best)) {
+                best = entity;
+            }
+        }
+
+        return best;
+    }
+
+    /**
+     * Keep the rows on the CPU, before the frame's scene context is built: a chain held here is
+     * written into the scene's rows this frame.
+     *
+     * @param {number} time_delta_seconds
+     */
+    update(time_delta_seconds) {
+        this.#frame_seconds += time_delta_seconds;
+
+        // the read API's apply point: last frame's answers recycled, then this frame's taken
+        this.#recycle_requests();
+
+        this.#refresh();
+
+        this.#answer_requests();
+
+        this.#refreshed = true;
+    }
+
+    /**
+     * Follow the device and the domain, and keep the rows.
+     */
+    #refresh() {
+        if (this.#dataset === null) {
+            return;
+        }
+
+        const context = this.#graphics.scene_context(this.#scene);
+
+        if (context === null) {
+            // No device: the old one took its buffers with it. The chains hold nothing meanwhile.
+            this.#drop_device(false);
+            this.#drop_queries();
+            this.#chains.bind(null);
+            this.#context = null;
+
+            return;
+        }
+
+        if (context !== this.#context) {
+            this.#drop_device(false);
+            this.#drop_queries();
+
+            this.#context = context;
+
+            // every held chain is acquired in the new rows
+            this.#chains.bind(context.rows);
+
+            this.#wind_cascades = 0;
+            this.#wind_far.fill(NaN);
+        }
+
+        const entity = this.#pick_domain();
+
+        if (entity === -1) {
+            if (this.#stack !== null || this.#forcing !== null || this.#holding) {
+                this.#drop_device(true);
+            }
+
+            return;
+        }
+
+        const domain = this.#domains.get(entity);
+
+        this.#ensure_device(entity, domain.component, domain.transform);
+
+        this.#sync_effectors();
+        this.#sync_obstacles();
+    }
+
+    /**
+     * Make the forcing and the stack for the domain, or the stack again when the domain or its shape
+     * changed.
+     *
+     * @param {number} entity
+     * @param {GPUFluidComponent} component
+     * @param {Transform64} transform
+     */
+    #ensure_device(entity, component, transform) {
+        const resolution = component.resolution;
+        const cell_size = component.cell_size;
+        const cascade_count = component.cascade_count;
+
+        const stack = this.#stack;
+
+        if (stack !== null
+            && this.#stack_entity === entity
+            && this.#stack_resolution[0] === resolution[0]
+            && this.#stack_resolution[1] === resolution[1]
+            && this.#stack_resolution[2] === resolution[2]
+            && this.#stack_cell_size === cell_size
+            && this.#stack_cascade_count === cascade_count) {
+            return;
+        }
+
+        for (let axis = 0; axis < 3; axis++) {
+            const n = resolution[axis];
+
+            assert.isPositiveInteger(n, 'GPUFluidComponent.resolution');
+            assert.ok(isPowerOfTwo(n), 'GPUFluidComponent.resolution is a power of two on each axis');
+            assert.greaterThanOrEqual(n, GPU_FLUID_COMPONENT_RESOLUTION_MIN, 'GPUFluidComponent.resolution');
+            assert.lessThanOrEqual(n, GPU_FLUID_COMPONENT_RESOLUTION_MAX, 'GPUFluidComponent.resolution');
+        }
+
+        assert.isFinite(cell_size, 'GPUFluidComponent.cell_size');
+        assert.greaterThan(cell_size, 0, 'GPUFluidComponent.cell_size');
+        assert.isPositiveInteger(cascade_count, 'GPUFluidComponent.cascade_count');
+        assert.lessThanOrEqual(cascade_count, GPU_FLUID_COMPONENT_CASCADE_LIMIT, 'GPUFluidComponent.cascade_count');
+
+        const device = this.#graphics.renderer.graphics.device;
+
+        if (this.#forcing === null) {
+            this.#forcing = new GPUFluidForcing({ device });
+        }
+
+        if (stack !== null) {
+            stack.destroy();
+        }
+
+        const anchor = this.#anchor;
+
+        anchor[0] = transform.translation_x;
+        anchor[1] = transform.translation_y;
+        anchor[2] = transform.translation_z;
+
+        // seeded at the far field: nothing of the fluid is saved, it warms up (§6)
+        this.#stack = new GPUFluidCascadeStack({
+            device,
+            resolution,
+            cell_size,
+            cascade_count,
+            anchor,
+            atmosphere: this.#atmosphere_without_force(),
+            atmosphere_offset: 0,
+        });
+
+        this.#stack_entity = entity;
+        this.#stack_resolution[0] = resolution[0];
+        this.#stack_resolution[1] = resolution[1];
+        this.#stack_resolution[2] = resolution[2];
+        this.#stack_cell_size = cell_size;
+        this.#stack_cascade_count = cascade_count;
+        this.#stack_fresh = true;
+
+        // nothing is pending for a stack made now
+        this.#last_tick = this.entityManager.fixedStepTick;
+    }
+
+    /**
+     * The far field for the GPU fluid, which has no body force (§6): a `GlobalFluidEffector#force` is a
+     * CPU-field term, and the GPU path drops it.
+     *
+     * @returns {Float64Array}
+     */
+    #atmosphere_without_force() {
+        const atmosphere = this.#read_atmosphere();
+
+        assert.equal(atmosphere[FluidAtmosphere.FORCE_X], 0, 'a GlobalFluidEffector has a force, which the GPU fluid drops: force is a CPU-field term, not part of the far field');
+        assert.equal(atmosphere[FluidAtmosphere.FORCE_Y], 0, 'a GlobalFluidEffector has a force, which the GPU fluid drops: force is a CPU-field term, not part of the far field');
+        assert.equal(atmosphere[FluidAtmosphere.FORCE_Z], 0, 'a GlobalFluidEffector has a force, which the GPU fluid drops: force is a CPU-field term, not part of the far field');
+
+        return atmosphere;
+    }
+
+    /**
+     * Let go of the device state: the stack, the forcing and every row in it. `release_chains` lets go
+     * of the scene rows the entries hold too, which a restart keeps (the chains move to the new rows).
+     *
+     * @param {boolean} release_chains
+     */
+    #drop_device(release_chains) {
+        if (this.#stack !== null) {
+            this.#stack.destroy();
+            this.#stack = null;
+            this.#stack_entity = -1;
+        }
+
+        if (this.#forcing !== null) {
+            this.#forcing.destroy();
+            this.#forcing = null;
+        }
+
+        if (release_chains) {
+            this.#holding = false;
+        }
+
+        // the rows went with the forcing
+        for (const entry of this.#effectors.values()) {
+            entry.rows.fill(-1);
+
+            if (release_chains) {
+                this.#let_go(entry);
+                entry.node = -1;
+            }
+        }
+
+        for (const entry of this.#obstacles.values()) {
+            entry.first = -1;
+            entry.plane_first = -1;
+            entry.shape = null;
+
+            if (release_chains) {
+                this.#let_go(entry);
+            }
+        }
+
+        if (release_chains && this.#wind_cascades !== 0 && this.#context !== null) {
+            // the field goes back to the far field alone
+            this.#context.wind.set_cascades(0, this.#stack_resolution);
+            this.#wind_cascades = 0;
+            this.#wind_far.fill(NaN);
+        }
+    }
+
+    /**
+     * The effectors' rows: membership by identity, each row written when its record changed.
+     */
+    #sync_effectors() {
+        const forcing = this.#forcing;
+        const dataset = this.#dataset;
+        const transform_index = this.#transform_index;
+
+        for (const entry of this.#effectors.values()) {
+            const entity = entry.entity;
+
+            const node = transform_index !== -1 && dataset.getComponentByIndex(entity, transform_index) !== undefined
+                ? row_of_entity(entity)
+                : NODE3D_SCENE_ID;
+
+            const moved = node !== entry.node;
+
+            if (moved) {
+                if (node !== NODE3D_SCENE_ID && !entry.held) {
+                    this.#chains.hold(entity);
+                    entry.held = true;
+                    this.#holding = true;
+                } else if (node === NODE3D_SCENE_ID) {
+                    this.#let_go(entry);
+                }
+
+                entry.node = node;
+            }
+
+            const effectors = entry.component.effectors;
+            const count = effectors.length;
+
+            let same = entry.effectors.length === count;
+
+            for (let i = 0; same && i < count; i++) {
+                same = entry.effectors[i] === effectors[i];
+            }
+
+            if (!same) {
+                this.#remove_effector_rows(entry);
+
+                entry.effectors.length = count;
+                entry.rows.length = count;
+
+                for (let i = 0; i < count; i++) {
+                    entry.effectors[i] = effectors[i];
+                    entry.rows[i] = -1;
+
+                    if (effectors[i].has_gpu_record && (entry.records[i] === undefined || entry.records[i] === null)) {
+                        entry.records[i] = fluid_effector_record_create();
+                    }
+                }
+            }
+
+            for (let i = 0; i < count; i++) {
+                const effector = effectors[i];
+
+                if (!effector.has_gpu_record) {
+                    continue;
+                }
+
+                const record = entry.records[i];
+
+                record.node = node;
+
+                const changed = effector.write_gpu_record(record);
+
+                if (entry.rows[i] === -1) {
+                    entry.rows[i] = forcing.add_effector(record);
+                } else if (changed || moved) {
+                    forcing.set_effector(entry.rows[i], record);
+                }
+            }
+        }
+    }
+
+    /**
+     * @param {EffectorEntry} entry
+     */
+    #remove_effector_rows(entry) {
+        const forcing = this.#forcing;
+        const rows = entry.rows;
+
+        for (let i = 0; i < rows.length; i++) {
+            if (rows[i] !== -1) {
+                if (forcing !== null) {
+                    forcing.remove_effector(rows[i]);
+                }
+
+                rows[i] = -1;
+            }
+        }
+    }
+
+    /**
+     * The obstacles' rows: a collider packed when its shape object changes, its motion compared every
+     * frame.
+     */
+    #sync_obstacles() {
+        const forcing = this.#forcing;
+
+        for (const entry of this.#obstacles.values()) {
+            if (!entry.held) {
+                this.#chains.hold(entry.entity);
+                entry.held = true;
+                this.#holding = true;
+            }
+
+            const shape = entry.collider.shape;
+
+            if (shape !== entry.shape) {
+                this.#pack(entry, shape);
+            }
+
+            const records = entry.records;
+            const first = entry.first;
+
+            if (first === -1) {
+                continue;
+            }
+
+            for (let i = 0; i < records.length; i++) {
+                if (fluid_obstacle_write_gpu_motion(records[i], entry.obstacle, entry.body)) {
+                    forcing.set_obstacle(first + i, records[i]);
+                }
+            }
+        }
+    }
+
+    /**
+     * Pack a collider's shape into its records, its run made anew when its record or plane count moved.
+     *
+     * @param {ObstacleEntry} entry
+     * @param {AbstractShape3D} shape
+     */
+    #pack(entry, shape) {
+        const forcing = this.#forcing;
+
+        const count = fluid_obstacle_record_count(shape);
+        const plane_count = count === 0 ? 0 : fluid_obstacle_plane_count(shape);
+
+        const records = entry.records;
+        const node = row_of_entity(entry.entity);
+
+        const remake = entry.first === -1 || records.length !== count || entry.plane_count !== plane_count;
+
+        if (remake) {
+            this.#remove_obstacle_rows(entry);
+
+            while (records.length < count) {
+                records.push(fluid_obstacle_record_create());
+            }
+
+            records.length = count;
+
+            entry.plane_count = plane_count;
+            entry.plane_first = plane_count > 0 ? forcing.add_planes(plane_count) : -1;
+        }
+
+        // the mirror is replaced, not grown, by add_planes: read it after
+        const planes = forcing.planes;
+
+        let cursor = entry.plane_first;
+        let planes_changed = false;
+
+        for (let i = 0; i < count; i++) {
+            const record = records[i];
+
+            record.node = node;
+
+            const changed = fluid_obstacle_write_gpu_shape(record, planes, cursor, shape, i);
+            const moved = fluid_obstacle_write_gpu_motion(record, entry.obstacle, entry.body);
+
+            cursor += fluid_obstacle_record_plane_count(record);
+
+            planes_changed = planes_changed || (changed & FLUID_OBSTACLE_PLANES_CHANGED) !== 0;
+
+            if (!remake && ((changed & FLUID_OBSTACLE_RECORD_CHANGED) !== 0 || moved)) {
+                forcing.set_obstacle(entry.first + i, record);
+            }
+        }
+
+        if (plane_count > 0 && (remake || planes_changed)) {
+            forcing.set_planes(entry.plane_first, plane_count);
+        }
+
+        if (remake && count > 0) {
+            entry.first = forcing.add_obstacles(records);
+        }
+
+        entry.shape = shape;
+    }
+
+    /**
+     * @param {ObstacleEntry} entry
+     */
+    #remove_obstacle_rows(entry) {
+        const forcing = this.#forcing;
+
+        if (forcing !== null) {
+            if (entry.first !== -1) {
+                forcing.remove_obstacles(entry.first, entry.records.length);
+            }
+
+            if (entry.plane_first !== -1) {
+                forcing.remove_planes(entry.plane_first, entry.plane_count);
+            }
+        }
+
+        entry.first = -1;
+        entry.plane_first = -1;
+        entry.shape = null;
+    }
+
+    /**
+     * 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) {
+        const scene_context = frame.view.scene;
+
+        if (scene_context.scene !== this.#scene || this.entityManager === null) {
+            return;
+        }
+
+        this.#prepare_fluid(frame, scene_context);
+
+        // after the publish: the gather reads the field the frame publishes
+        if (this.#context === scene_context) {
+            this.#record_requests(frame.graph, scene_context);
+        }
+    }
+
+    /**
+     * The fluid's part of {@link prepare}: the pending ticks and the publish.
+     *
+     * @param {FrameContext} frame
+     * @param {GPUSceneContext} scene_context
+     */
+    #prepare_fluid(frame, scene_context) {
+        if (!this.#refreshed) {
+            // a frame no update preceded
+            this.#refresh();
+        }
+
+        this.#refreshed = false;
+
+        const frame_seconds = this.#frame_seconds;
+        this.#frame_seconds = 0;
+
+        if (this.#context !== scene_context) {
+            return;
+        }
+
+        const stack = this.#stack;
+
+        if (stack === null) {
+            this.#publish_far_field(scene_context);
+
+            return;
+        }
+
+        const em = this.entityManager;
+        const tick_now = em.fixedStepTick;
+
+        if (tick_now < this.#last_tick) {
+            // the counter went back (a new EntityManager clock): the fluid starts over from it
+            const domain = this.#domains.get(this.#stack_entity);
+
+            this.#stack.destroy();
+            this.#stack = null;
+
+            this.#ensure_device(this.#stack_entity, domain.component, domain.transform);
+        }
+
+        const pending = tick_now - this.#last_tick;
+        const count = pending < GPU_FLUID_SYSTEM_TICK_CAP ? pending : GPU_FLUID_SYSTEM_TICK_CAP;
+
+        this.#dropped_ticks += pending - count;
+
+        if (count === 0 && !this.#stack_fresh) {
+            return;
+        }
+
+        this.#record(frame.graph, tick_now, count, frame_seconds);
+    }
+
+    /**
+     * Record `count` ticks, the latest up to `tick_now`, and the publish.
+     *
+     * @param {import("../graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
+     * @param {number} tick_now
+     * @param {number} count
+     * @param {number} frame_seconds wall seconds since the last frame
+     */
+    #record(graph, tick_now, count, frame_seconds) {
+        const stack = this.#stack;
+        const context = this.#context;
+        const em = this.entityManager;
+        const atmosphere = this.#atmosphere_without_force();
+
+        if (count > 0) {
+            const dt = em.fixedUpdateStepSize;
+            const cascade_count = stack.cascade_count;
+            const first_tick = tick_now - count + 1;
+
+            // the longest step of the frame's stepping cascades, which a wake's box is swept over
+            let sweep_time = dt;
+
+            for (let tick = first_tick; tick <= tick_now; tick++) {
+                const coarse = fluid_cascade_ruler(tick, cascade_count);
+
+                if (coarse > 0) {
+                    sweep_time = Math.max(sweep_time, dt * 2 ** coarse);
+                }
+            }
+
+            // the game seconds between a node's prev_global and global, one render frame apart
+            const time_scale = em.fixedStepTimeScale;
+            const inverse_frame_dt = frame_seconds > 0 && time_scale > 0 ? 1 / (frame_seconds * time_scale) : 0;
+
+            const bounds = this.#bounds;
+            stack.coarsest_bounds(bounds);
+
+            this.#forcing.record_frame({
+                graph,
+                scene_database: context.scene_database,
+                bounds,
+                sweep_time,
+                inverse_frame_dt,
+                cell_size: this.#stack_cell_size,
+            });
+
+            const domain = this.#domains.get(this.#stack_entity);
+            const transform = domain.transform;
+            const anchor = this.#anchor;
+
+            anchor[0] = transform.translation_x;
+            anchor[1] = transform.translation_y;
+            anchor[2] = transform.translation_z;
+
+            for (let tick = first_tick; tick <= tick_now; tick++) {
+                stack.record_tick({
+                    graph,
+                    tick,
+                    dt,
+                    anchor,
+                    atmosphere,
+                    atmosphere_offset: 0,
+                    forcing: this.#forcing,
+                    vorticity_confinement: domain.component.vorticity_confinement,
+                });
+            }
+        }
+
+        const wind = context.wind;
+
+        stack.record_publish({ graph, wind, atmosphere, atmosphere_offset: 0 });
+
+        // the scene context uploaded the field's table before this phase: the frame's readers need it now
+        wind.update();
+
+        this.#wind_cascades = stack.cascade_count;
+        this.#last_tick = tick_now;
+        this.#stack_fresh = false;
+    }
+
+    /**
+     * With no domain, the wind field is the far field alone: written when it changes.
+     *
+     * @param {GPUSceneContext} context
+     */
+    #publish_far_field(context) {
+        const far = this.#far;
+        const written = this.#wind_far;
+
+        this.far_field(far);
+
+        if (far[0] === written[0] && far[1] === written[1] && far[2] === written[2]) {
+            return;
+        }
+
+        const wind = context.wind;
+
+        wind.set_far_velocity(far);
+        wind.update();
+
+        written[0] = far[0];
+        written[1] = far[1];
+        written[2] = far[2];
+    }
+}
+
+/**
+ * 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}
+ */
+GPUFluidSystem.prototype.isGPUFluidSystem = true;
+
+/**
+ * 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 {
+    name = 'gpu fluid';
+    phase = FramePhase.FrameStart;
+
+    /**
+     * @param {GPUFluidSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.system = system;
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        this.system.prepare(frame);
+    }
+}