@woosh/meep-engine 3.24.0 → 3.25.0

package/src/engine/physics/cloth/wind/ClothFluidWind.js

@@ -0,0 +1,210 @@
+import { FluidComponent } from "../../fluid/ecs/FluidComponent.js";
+import { AbstractClothWind } from "./AbstractClothWind.js";
+import { ClothAmbientWind } from "./ClothAmbientWind.js";
+
+/**
+ * # The air, read out of the fluid simulation that is already running
+ *
+ * §10's whole argument: this engine has a fluid simulator, `FluidObstacle`
+ * already voxelises physics colliders into it, so a character running past a
+ * cape gets a **wake** without anything cloth-specific being authored. This is
+ * the source that reads it — every enabled {@link FluidComponent} in the scene,
+ * sampled trilinearly where a particle actually is.
+ *
+ * Where no field reaches, {@link ambient} answers instead, so this is the one
+ * source a scene needs rather than a thing to switch between: a banner inside a
+ * wind tunnel volume reads the tunnel, the same banner carried outside reads the
+ * prevailing weather, and the cloth never learns which happened.
+ *
+ * ## Two units problems, and they are the reason this class exists at all
+ *
+ * A caller cannot simply forward `FluidComponent#sampleVelocityAtWorld`:
+ *
+ * - **Cells, not metres.** `FluidField#sampleVelocity` answers in *grid cells*
+ *   per second and says so — it "does NOT rescale them, on the assumption that
+ *   callers (vegetation sway, dust drift) interpret the field as a direction ×
+ *   magnitude wind". Cloth's drag row is a relaxation toward a **velocity**, so
+ *   the same wind voxelised at 0.25 m instead of 1 m would blow a garment four
+ *   times as hard. The multiply by `cell_size` is here. `MEASUREMENTS.md` §45.
+ * - **Unbuilt fields read as null.** A `FluidComponent` exists from the moment
+ *   the entity is spawned and its field's buffers arrive at `build()`. Sampling
+ *   before that is a null dereference rather than a zero, so an unbuilt field is
+ *   skipped exactly like a disabled one.
+ *
+ * ## The field list is rebuilt once a step, not once a cloth
+ *
+ * {@link begin} walks the dataset and caches each live field with its world
+ * box. Every cloth's {@link varies} and every particle's {@link sample} then
+ * read that cache, so a scene with twenty garments and one wind volume walks the
+ * dataset once. `FluidSystem` does the equivalent per field for its effectors
+ * and notes the same trade.
+ *
+ * ## What it does not do
+ *
+ * **It does not blend at a field's edge.** A point inside a field's box reads
+ * the field and a point outside reads the ambient, so a garment straddling the
+ * boundary sees a step in the air rather than a ramp. In a scene where the
+ * ambient is the far field the volume relaxes toward — `GlobalFluidEffector`'s
+ * `wind` — the step is small and mostly the disturbance the volume exists to
+ * carry; where it is not, it is visible, and the answer is a volume large enough
+ * to hold what moves through it. **Overlapping fields are resolved by order**,
+ * first match wins, which is the same arbitrary-but-deterministic rule
+ * `FluidSystem` applies when it steps them independently.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothFluidWind extends AbstractClothWind {
+
+    /**
+     * What the air is where no field reaches. Present rather than optional
+     * because "outside every fluid volume" is most of the world.
+     * @type {ClothAmbientWind}
+     */
+    ambient = new ClothAmbientWind();
+
+    /**
+     * Live fields this step: the component and its world box, six words each.
+     * @type {FluidComponent[]}
+     * @private
+     */
+    __components = [];
+
+    /**
+     * @type {number[]}
+     * @private
+     */
+    __bounds = [];
+
+    /**
+     * @type {number}
+     * @private
+     */
+    __count = 0;
+
+    /**
+     * @param {number} time
+     * @param {EntityComponentDataset} ecd
+     * @returns {void}
+     */
+    begin(time, ecd) {
+        this.ambient.begin(time, ecd);
+
+        const components = this.__components;
+        const bounds = this.__bounds;
+
+        let count = 0;
+
+        if (ecd !== null && ecd !== undefined) {
+            ecd.traverseComponents(FluidComponent, component => {
+                if (!component.enabled) {
+                    return;
+                }
+
+                const field = component.field;
+
+                if (field.velocity_x === null) {
+                    // Not built yet — `setResolution`/`build` has not run, so
+                    // there are no buffers to sample.
+                    return;
+                }
+
+                const resolution = field.getResolution();
+
+                const cell_size = component.cell_size;
+
+                const origin = component.origin;
+
+                const b = count * 6;
+
+                bounds[b] = origin[0];
+                bounds[b + 1] = origin[1];
+                bounds[b + 2] = origin[2];
+                bounds[b + 3] = origin[0] + resolution[0] * cell_size;
+                bounds[b + 4] = origin[1] + resolution[1] * cell_size;
+                bounds[b + 5] = origin[2] + resolution[2] * cell_size;
+
+                components[count] = component;
+
+                count++;
+            });
+        }
+
+        // Drop references to components that are no longer live, so a despawned
+        // fluid volume is not kept alive by this cache.
+        for (let i = count; i < components.length; i++) {
+            components[i] = null;
+        }
+
+        this.__count = count;
+    }
+
+    /**
+     * @param {number} min_x
+     * @param {number} min_y
+     * @param {number} min_z
+     * @param {number} max_x
+     * @param {number} max_y
+     * @param {number} max_z
+     * @returns {boolean} whether a fluid field reaches into this box — and so
+     *   whether the caller has to sample per particle rather than once
+     */
+    varies(min_x, min_y, min_z, max_x, max_y, max_z) {
+        const count = this.__count;
+
+        const bounds = this.__bounds;
+
+        for (let i = 0; i < count; i++) {
+            const b = i * 6;
+
+            if (max_x >= bounds[b]
+                && max_y >= bounds[b + 1]
+                && max_z >= bounds[b + 2]
+                && min_x <= bounds[b + 3]
+                && min_y <= bounds[b + 4]
+                && min_z <= bounds[b + 5]) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * @param {Float64Array|number[]} out
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {Float64Array|number[]}
+     */
+    sample(out, x, y, z) {
+        const count = this.__count;
+
+        const bounds = this.__bounds;
+
+        for (let i = 0; i < count; i++) {
+            const b = i * 6;
+
+            if (x < bounds[b] || x > bounds[b + 3]
+                || y < bounds[b + 1] || y > bounds[b + 4]
+                || z < bounds[b + 2] || z > bounds[b + 5]) {
+                continue;
+            }
+
+            const component = this.__components[i];
+
+            component.sampleVelocityAtWorld(out, x, y, z);
+
+            // Cells per second to metres per second. See the header.
+            const cell_size = component.cell_size;
+
+            out[0] *= cell_size;
+            out[1] *= cell_size;
+            out[2] *= cell_size;
+
+            return out;
+        }
+
+        return this.ambient.sample(out, x, y, z);
+    }
+}

package/src/engine/physics/cloth/wind/cloth_sample_air.d.ts

@@ -0,0 +1,101 @@
+/**
+ * # Reading the air into the cloth's own frame
+ *
+ * The one piece of §10 that has to run on the **main thread**, and the milestone's
+ * design decision. M5 moved every number the solver touches onto a worker; a
+ * fluid field is not one of those numbers. It is an ECS component holding a
+ * hundred thousand floats that the fluid solver rewrites every step, it may
+ * itself already live on a *different* worker (`WorkerFluidSystem`), and nothing
+ * about it is shaped like a cloth. Sending it across per step would cost more
+ * than the whole cloth step it was supposed to feed.
+ *
+ * So the split is the one §12 already draws — "arbitrary user-facing work —
+ * component reads, `Transform64` sync, index queries — stays on the main thread;
+ * the pure numeric step crosses" — applied once more. A field query is an index
+ * query. What crosses is the **answer**: one air velocity per particle, written
+ * into {@link ClothState#air_velocity}, which is a region of the cloth's own
+ * buffer and therefore already shared memory. Nothing is copied and nothing is
+ * marshalled; the main thread writes exactly where the worker reads. §39's "one
+ * buffer per cloth" is what makes that free.
+ *
+ * The **drag arithmetic** is not here, deliberately. It reads positions and
+ * velocities the state already holds, so it belongs with the rest of the
+ * arithmetic in `cloth_step_instance` — which keeps §40's property intact:
+ * neither system computes a step parameter of its own, the drag response crosses
+ * as one more word of the block, and the acceleration is built by the one
+ * function both systems call. `MEASUREMENTS.md` §45.
+ *
+ * ## Two costs, and only one of them scales
+ *
+ * A source that answers `varies() === false` — {@link ClothAmbientWind}, and
+ * {@link ClothFluidWind} anywhere its fields do not reach — is sampled **once**
+ * for the whole cloth. What is left is a bounds scan and a fill, both linear in
+ * particles with a handful of operations each, and both an order below a
+ * trilinear sample. That is the case §10 calls "no fluid field in range", and it
+ * is the common one. `MEASUREMENTS.md` §47 is what each costs.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Fill {@link ClothState#air_velocity} with the air each particle sits in,
+ * rotated into the cloth's local frame.
+ *
+ * @param {ClothState} state
+ * @param {AbstractClothWind} wind
+ * @param {Float64Array} anchor_translation the cloth frame's world origin
+ * @param {Float64Array} anchor_rotation the cloth frame's world rotation, xyzw
+ * @param {Float64Array} [centre] written with the world-space air at the cloth's
+ *   own centre — what the sleep test compares against next step
+ * @returns {boolean} whether the source was sampled per particle
+ */
+export function cloth_sample_air(state: ClothState, wind: AbstractClothWind, anchor_translation: Float64Array, anchor_rotation: Float64Array, centre?: Float64Array): boolean;
+/**
+ * Whether the air at the cloth's centre has moved far enough since the last step
+ * that actually applied it to be worth waking for — §10's "sleep wakes on a wind
+ * change, so a settled banner does not sleep through a gust".
+ *
+ * The comparison is against the last **applied** air rather than the last
+ * sampled one, so a gust that arrives slowly still wakes the cloth: the
+ * difference accumulates instead of being reset by every step that declined to
+ * act on it.
+ *
+ * The threshold is the sleep test's own speed ratio, and that is deliberately
+ * conservative — the velocity a wind change of `Δu` actually produces in one
+ * step is `(1 − e^(−rate·dt))·facing·Δu`, a fraction of it, so this wakes on a
+ * change several times smaller than the one that would keep the cloth awake.
+ * Erring that way is the point: the failure §10 names is a banner sleeping
+ * through a gust, not one waking a few steps early.
+ *
+ * **Its limit, stated.** One point, at the cloth's centre. A wake that reaches
+ * only the hem of a sleeping banner and leaves its middle still will not wake
+ * it. The collider wake test next to it has no such gap because a collider's
+ * pose is seven exact numbers and a field is a continuum — the honest fix is
+ * more sample points, and the measurement is that one is enough for anything
+ * that crosses a garment rather than grazing it.
+ *
+ * @param {ClothState} state
+ * @param {AbstractClothWind} wind
+ * @param {Float64Array} anchor_translation
+ * @param {Float64Array} anchor_rotation
+ * @param {Float64Array} previous the air last applied to this cloth, world-space
+ * @param {number} threshold m/s
+ * @returns {boolean}
+ */
+export function cloth_air_changed(state: ClothState, wind: AbstractClothWind, anchor_translation: Float64Array, anchor_rotation: Float64Array, previous: Float64Array, threshold: number): boolean;
+/**
+ * The cloth's world-space axis-aligned bounds.
+ *
+ * The particles are local, so this is the bounds of the **rotated** local box
+ * rather than the rotation of its bounds — the same eight-corner argument
+ * `cloth_gather_colliders` makes for its own query volume, and the same reason:
+ * a rotated box is not a box.
+ *
+ * @param {ClothState} state
+ * @param {Float64Array} anchor_translation
+ * @param {Float64Array} anchor_rotation
+ * @param {Float64Array} out six words, min then max
+ * @returns {void}
+ */
+export function cloth_air_bounds(state: ClothState, anchor_translation: Float64Array, anchor_rotation: Float64Array, out: Float64Array): void;
+//# sourceMappingURL=cloth_sample_air.d.ts.map

package/src/engine/physics/cloth/wind/cloth_sample_air.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_sample_air.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/wind/cloth_sample_air.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;;;;;GAWG;AACH,iGANW,YAAY,mBACZ,YAAY,WACZ,YAAY,GAEV,OAAO,CA6EnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,kGANW,YAAY,mBACZ,YAAY,YACZ,YAAY,aACZ,MAAM,GACJ,OAAO,CAqBnB;AAED;;;;;;;;;;;;;GAaG;AACH,wEALW,YAAY,mBACZ,YAAY,OACZ,YAAY,GACV,IAAI,CAoEhB"}

package/src/engine/physics/cloth/wind/cloth_sample_air.js

@@ -0,0 +1,290 @@
+import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
+import { v3_quaternion_apply_inverse } from "../../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
+
+/**
+ * # Reading the air into the cloth's own frame
+ *
+ * The one piece of §10 that has to run on the **main thread**, and the milestone's
+ * design decision. M5 moved every number the solver touches onto a worker; a
+ * fluid field is not one of those numbers. It is an ECS component holding a
+ * hundred thousand floats that the fluid solver rewrites every step, it may
+ * itself already live on a *different* worker (`WorkerFluidSystem`), and nothing
+ * about it is shaped like a cloth. Sending it across per step would cost more
+ * than the whole cloth step it was supposed to feed.
+ *
+ * So the split is the one §12 already draws — "arbitrary user-facing work —
+ * component reads, `Transform64` sync, index queries — stays on the main thread;
+ * the pure numeric step crosses" — applied once more. A field query is an index
+ * query. What crosses is the **answer**: one air velocity per particle, written
+ * into {@link ClothState#air_velocity}, which is a region of the cloth's own
+ * buffer and therefore already shared memory. Nothing is copied and nothing is
+ * marshalled; the main thread writes exactly where the worker reads. §39's "one
+ * buffer per cloth" is what makes that free.
+ *
+ * The **drag arithmetic** is not here, deliberately. It reads positions and
+ * velocities the state already holds, so it belongs with the rest of the
+ * arithmetic in `cloth_step_instance` — which keeps §40's property intact:
+ * neither system computes a step parameter of its own, the drag response crosses
+ * as one more word of the block, and the acceleration is built by the one
+ * function both systems call. `MEASUREMENTS.md` §45.
+ *
+ * ## Two costs, and only one of them scales
+ *
+ * A source that answers `varies() === false` — {@link ClothAmbientWind}, and
+ * {@link ClothFluidWind} anywhere its fields do not reach — is sampled **once**
+ * for the whole cloth. What is left is a bounds scan and a fill, both linear in
+ * particles with a handful of operations each, and both an order below a
+ * trilinear sample. That is the case §10 calls "no fluid field in range", and it
+ * is the common one. `MEASUREMENTS.md` §47 is what each costs.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Fill {@link ClothState#air_velocity} with the air each particle sits in,
+ * rotated into the cloth's local frame.
+ *
+ * @param {ClothState} state
+ * @param {AbstractClothWind} wind
+ * @param {Float64Array} anchor_translation the cloth frame's world origin
+ * @param {Float64Array} anchor_rotation the cloth frame's world rotation, xyzw
+ * @param {Float64Array} [centre] written with the world-space air at the cloth's
+ *   own centre — what the sleep test compares against next step
+ * @returns {boolean} whether the source was sampled per particle
+ */
+export function cloth_sample_air(state, wind, anchor_translation, anchor_rotation, centre = undefined) {
+    const particle_count = state.particle_count;
+
+    const air = state.air_velocity;
+
+    if (particle_count === 0) {
+        return false;
+    }
+
+    const position = state.position;
+
+    const anchor_x = anchor_translation[0];
+    const anchor_y = anchor_translation[1];
+    const anchor_z = anchor_translation[2];
+
+    const qx = anchor_rotation[0];
+    const qy = anchor_rotation[1];
+    const qz = anchor_rotation[2];
+    const qw = anchor_rotation[3];
+
+    cloth_air_bounds(state, anchor_translation, anchor_rotation, BOUNDS);
+
+    const varies = wind.varies(BOUNDS[0], BOUNDS[1], BOUNDS[2], BOUNDS[3], BOUNDS[4], BOUNDS[5]);
+
+    // The cloth's own centre: where a uniform source is read, and where the
+    // sleep test asks whether the air has changed.
+    wind.sample(
+        SAMPLE,
+        (BOUNDS[0] + BOUNDS[3]) * 0.5,
+        (BOUNDS[1] + BOUNDS[4]) * 0.5,
+        (BOUNDS[2] + BOUNDS[5]) * 0.5
+    );
+
+    if (centre !== undefined) {
+        centre[0] = SAMPLE[0];
+        centre[1] = SAMPLE[1];
+        centre[2] = SAMPLE[2];
+    }
+
+    if (!varies) {
+        // One vector for the whole cloth. `varies() === false` is a promise
+        // rather than a hint, so this is exact rather than an approximation the
+        // caller opted into.
+        v3_quaternion_apply_inverse(LOCAL, 0, SAMPLE[0], SAMPLE[1], SAMPLE[2], qx, qy, qz, qw);
+
+        const local_x = LOCAL[0];
+        const local_y = LOCAL[1];
+        const local_z = LOCAL[2];
+
+        for (let i = 0; i < particle_count; i++) {
+            const p = i * 3;
+
+            air[p] = local_x;
+            air[p + 1] = local_y;
+            air[p + 2] = local_z;
+        }
+
+        return false;
+    }
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        v3_quaternion_apply(WORLD, 0, position[p], position[p + 1], position[p + 2], qx, qy, qz, qw);
+
+        wind.sample(SAMPLE, WORLD[0] + anchor_x, WORLD[1] + anchor_y, WORLD[2] + anchor_z);
+
+        v3_quaternion_apply_inverse(LOCAL, 0, SAMPLE[0], SAMPLE[1], SAMPLE[2], qx, qy, qz, qw);
+
+        air[p] = LOCAL[0];
+        air[p + 1] = LOCAL[1];
+        air[p + 2] = LOCAL[2];
+    }
+
+    return true;
+}
+
+/**
+ * Whether the air at the cloth's centre has moved far enough since the last step
+ * that actually applied it to be worth waking for — §10's "sleep wakes on a wind
+ * change, so a settled banner does not sleep through a gust".
+ *
+ * The comparison is against the last **applied** air rather than the last
+ * sampled one, so a gust that arrives slowly still wakes the cloth: the
+ * difference accumulates instead of being reset by every step that declined to
+ * act on it.
+ *
+ * The threshold is the sleep test's own speed ratio, and that is deliberately
+ * conservative — the velocity a wind change of `Δu` actually produces in one
+ * step is `(1 − e^(−rate·dt))·facing·Δu`, a fraction of it, so this wakes on a
+ * change several times smaller than the one that would keep the cloth awake.
+ * Erring that way is the point: the failure §10 names is a banner sleeping
+ * through a gust, not one waking a few steps early.
+ *
+ * **Its limit, stated.** One point, at the cloth's centre. A wake that reaches
+ * only the hem of a sleeping banner and leaves its middle still will not wake
+ * it. The collider wake test next to it has no such gap because a collider's
+ * pose is seven exact numbers and a field is a continuum — the honest fix is
+ * more sample points, and the measurement is that one is enough for anything
+ * that crosses a garment rather than grazing it.
+ *
+ * @param {ClothState} state
+ * @param {AbstractClothWind} wind
+ * @param {Float64Array} anchor_translation
+ * @param {Float64Array} anchor_rotation
+ * @param {Float64Array} previous the air last applied to this cloth, world-space
+ * @param {number} threshold m/s
+ * @returns {boolean}
+ */
+export function cloth_air_changed(state, wind, anchor_translation, anchor_rotation, previous, threshold) {
+    if (state.particle_count === 0) {
+        return false;
+    }
+
+    cloth_air_bounds(state, anchor_translation, anchor_rotation, BOUNDS);
+
+    wind.sample(
+        SAMPLE,
+        (BOUNDS[0] + BOUNDS[3]) * 0.5,
+        (BOUNDS[1] + BOUNDS[4]) * 0.5,
+        (BOUNDS[2] + BOUNDS[5]) * 0.5
+    );
+
+    const dx = SAMPLE[0] - previous[0];
+    const dy = SAMPLE[1] - previous[1];
+    const dz = SAMPLE[2] - previous[2];
+
+    return dx * dx + dy * dy + dz * dz > threshold * threshold;
+}
+
+/**
+ * The cloth's world-space axis-aligned bounds.
+ *
+ * The particles are local, so this is the bounds of the **rotated** local box
+ * rather than the rotation of its bounds — the same eight-corner argument
+ * `cloth_gather_colliders` makes for its own query volume, and the same reason:
+ * a rotated box is not a box.
+ *
+ * @param {ClothState} state
+ * @param {Float64Array} anchor_translation
+ * @param {Float64Array} anchor_rotation
+ * @param {Float64Array} out six words, min then max
+ * @returns {void}
+ */
+export function cloth_air_bounds(state, anchor_translation, anchor_rotation, out) {
+    const particle_count = state.particle_count;
+
+    const position = state.position;
+
+    let min_x = Infinity;
+    let min_y = Infinity;
+    let min_z = Infinity;
+    let max_x = -Infinity;
+    let max_y = -Infinity;
+    let max_z = -Infinity;
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        const x = position[p];
+        const y = position[p + 1];
+        const z = position[p + 2];
+
+        if (x < min_x) { min_x = x; }
+        if (y < min_y) { min_y = y; }
+        if (z < min_z) { min_z = z; }
+        if (x > max_x) { max_x = x; }
+        if (y > max_y) { max_y = y; }
+        if (z > max_z) { max_z = z; }
+    }
+
+    const qx = anchor_rotation[0];
+    const qy = anchor_rotation[1];
+    const qz = anchor_rotation[2];
+    const qw = anchor_rotation[3];
+
+    let world_min_x = Infinity;
+    let world_min_y = Infinity;
+    let world_min_z = Infinity;
+    let world_max_x = -Infinity;
+    let world_max_y = -Infinity;
+    let world_max_z = -Infinity;
+
+    for (let corner = 0; corner < 8; corner++) {
+        v3_quaternion_apply(
+            WORLD, 0,
+            (corner & 1) === 0 ? min_x : max_x,
+            (corner & 2) === 0 ? min_y : max_y,
+            (corner & 4) === 0 ? min_z : max_z,
+            qx, qy, qz, qw
+        );
+
+        const x = WORLD[0] + anchor_translation[0];
+        const y = WORLD[1] + anchor_translation[1];
+        const z = WORLD[2] + anchor_translation[2];
+
+        if (x < world_min_x) { world_min_x = x; }
+        if (y < world_min_y) { world_min_y = y; }
+        if (z < world_min_z) { world_min_z = z; }
+        if (x > world_max_x) { world_max_x = x; }
+        if (y > world_max_y) { world_max_y = y; }
+        if (z > world_max_z) { world_max_z = z; }
+    }
+
+    out[0] = world_min_x;
+    out[1] = world_min_y;
+    out[2] = world_min_z;
+    out[3] = world_max_x;
+    out[4] = world_max_y;
+    out[5] = world_max_z;
+}
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const BOUNDS = new Float64Array(6);
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const WORLD = new Float64Array(3);
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const LOCAL = new Float64Array(3);
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const SAMPLE = new Float64Array(3);

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#391@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#396@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#391@#clear_field"(fluid: FluidComponent): void;
+    static "__#396@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#391@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#396@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#391@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#396@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/shade/device/mock/texture_copy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"texture_copy.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/texture_copy.js"],"names":[],"mappings":"AAiLA;;;;;;;;;;;;;GAaG;AACH;IAP0C,cAAc;IACf,aAAa;IACZ,mBAAmB;IACpB,kBAAkB;IAC9B,IAAI;IACpB,MAAM,GAAC,IAAI,CA4DvB;AAiED;;;;;GAKG;AACH,uHAHW,MAAM,GACJ,IAAI,CA8BhB;;;;;;UA5Fa,WAAW;;;;YACX,MAAM;gBACN,MAAM;kBACN,MAAM"}
+{"version":3,"file":"texture_copy.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/texture_copy.js"],"names":[],"mappings":"AA6MA;;;;;;;;;;;;;GAaG;AACH;IAP0C,cAAc;IACf,aAAa;IACZ,mBAAmB;IACpB,kBAAkB;IAC9B,IAAI;IACpB,MAAM,GAAC,IAAI,CA4DvB;AAiED;;;;;GAKG;AACH,uHAHW,MAAM,GACJ,IAAI,CA8BhB;;;;;;UA5Fa,WAAW;;;;YACX,MAAM;gBACN,MAAM;kBACN,MAAM"}

package/src/shade/device/mock/texture_copy.js

@@ -104,6 +104,34 @@ function texture_endpoint_refusal(info, role, required_usage, required_usage_nam
         return `${role} copySize.height (${extent.height}) is not a multiple of the ${format.block_height}-texel block height of ${texture.format}`;
     }
 
+    /*
+     WebGPU's rule for `copyTextureToBuffer`/`copyBufferToTexture`/`writeTexture`: "if the
+     GPUTexture.format is a depth-or-stencil format or GPUTexture.sampleCount is more than 1, the
+     subresource size is equal to size". A depth buffer is copied whole or not at all — there is no
+     reading one texel of one, and the one-pixel read that looks like the obvious way to pick an
+     entity off the frame's depth is the thing this forbids. The restriction comes from D3D12, so
+     it is enforced everywhere rather than being a Windows-only surprise.
+
+     Only the two axes a region is named in: this does not also require a layered copy to take every
+     layer, which WebGPU's definition of a subresource's size does.
+    */
+    const depth_or_stencil = !format.aspects.includes("all");
+
+    if (depth_or_stencil || texture.sampleCount > 1) {
+        const full_width = texture.mip_width(mip);
+        const full_height = texture.mip_height(mip);
+
+        if (origin.x !== 0 || origin.y !== 0 || extent.width !== full_width || extent.height !== full_height) {
+            const why = depth_or_stencil
+                ? `is ${texture.format}, a depth-or-stencil format`
+                : `has sampleCount ${texture.sampleCount}`;
+
+            return `${role} texture '${texture.label}' ${why}, so a copy must cover the whole`
+                + ` subresource; mip ${mip} is ${full_width}x${full_height} and the region asked for`
+                + ` is ${extent.width}x${extent.height} at (${origin.x}, ${origin.y})`;
+        }
+    }
+
     return null;
 }