@woosh/meep-engine 3.24.0 → 3.26.0

package/src/engine/physics/cloth/ecs/cloth_worker_protocol.js

@@ -0,0 +1,78 @@
+import { CLOTH_STEP_PARAM_STRIDE } from "../solver/cloth_step_instance.js";
+
+/**
+ * # The command region, and what is *not* in it
+ *
+ * Layout of the {@link WorkerSystem} command region used by
+ * {@link WorkerClothSystem}: a count, then one {@link ClothStepParam} block per
+ * cloth to step this tick.
+ *
+ * §12 asks for exactly this shape — "the command region names which instances
+ * are live this step, so sleeping (P5) and culled (§12.1) instances cost nothing
+ * but their absence from a list" — and for `ClothDynamics` to travel with it,
+ * "written every step … cheaper than tracking dirtiness, and it keeps
+ * `cloth.dynamics.slack = 0.2` working live". Both hold. What changed on the way
+ * to being built is that the per-cloth words are not a serialization of
+ * `ClothDynamics` but the **step's own parameter block** — `dt`, local gravity, a
+ * retention, a clamp — because a cloth's dynamics have already been mapped
+ * through `cloth_dynamics_map.js` by the time the step can use them, and mapping
+ * them on the far side would be a second copy of that mapping with no way to
+ * prove it agreed. `MEASUREMENTS.md` §38.
+ *
+ * The consequence is the useful one: the same block the worker reads is the
+ * block {@link ClothSystem} fills in a private scratch array, so the two systems
+ * do not agree on the numbers, they *share* them.
+ *
+ * ## What travels on the cold plane instead
+ *
+ * A cloth's `ClothState` — the particles, the rows, the duals, the collider
+ * table, the pair list. That is a `SharedArrayBuffer` per cloth, registered once
+ * when the cloth seeds and again whenever a re-seed replaces it, and nothing of
+ * it is ever copied: the worker cuts its own views over the same bytes
+ * (`ClothState.fromSharedDescriptor`). §12 asked for one buffer for the whole
+ * cloth world; `MEASUREMENTS.md` §39 is why it is one per cloth.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Header words of the command region.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const ClothCommand = {
+    /**
+     * How many {@link ClothStepParam} blocks follow.
+     */
+    CLOTH_COUNT: 0
+};
+
+/**
+ * Command words consumed before the first cloth's block.
+ * @type {number}
+ */
+export const CLOTH_COMMAND_HEADER_WORDS = 1;
+
+/**
+ * First word of the `index`-th cloth's parameter block.
+ *
+ * @param {number} index
+ * @returns {number}
+ */
+export function cloth_command_offset(index) {
+    return CLOTH_COMMAND_HEADER_WORDS + index * CLOTH_STEP_PARAM_STRIDE;
+}
+
+/**
+ * Size the command region for a ceiling on simultaneously stepped cloths. The
+ * region is allocated once at startup and cannot grow, which is what makes that
+ * ceiling a constructor argument rather than something discovered at runtime.
+ *
+ * @param {number} max_cloth_count
+ * @returns {number} `Float64` words
+ */
+export function cloth_command_word_count(max_cloth_count) {
+    return cloth_command_offset(max_cloth_count);
+}

package/src/engine/physics/cloth/ecs/cloth_write_back.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_write_back.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_write_back.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH;;;;;;GAMG;AACH,wFAFa,IAAI,CAmDhB;AAyBD;;;;;;;;;GASG;AACH,0FAJW,MAAM,UACN,MAAM,GACJ,IAAI,CA4BhB"}
+{"version":3,"file":"cloth_write_back.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_write_back.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH;;;;;;GAMG;AACH,wFAFa,IAAI,CA2DhB;AAyBD;;;;;;;;;GASG;AACH,0FAJW,MAAM,UACN,MAAM,GACJ,IAAI,CA4BhB"}

package/src/engine/physics/cloth/ecs/cloth_write_back.js

@@ -76,16 +76,24 @@ export function cloth_write_back(instance, ecd) {
     const blended = instance.blended_position;
     const reconstructed = instance.blended_rotation;
 
-    const anchor = instance.node_transform[0];
-
-    const ax = anchor[TRANSFORM64_TRANSLATION_OFFSET];
-    const ay = anchor[TRANSFORM64_TRANSLATION_OFFSET + 1];
-    const az = anchor[TRANSFORM64_TRANSLATION_OFFSET + 2];
-
-    const aqx = anchor[TRANSFORM64_ROTATION_OFFSET];
-    const aqy = anchor[TRANSFORM64_ROTATION_OFFSET + 1];
-    const aqz = anchor[TRANSFORM64_ROTATION_OFFSET + 2];
-    const aqw = anchor[TRANSFORM64_ROTATION_OFFSET + 3];
+    // The anchor pose the particles were carried into **this step**, not the
+    // live component. For `ClothSystem` those are the same value, because the
+    // step happened between them. For `WorkerClothSystem` they are not: it
+    // writes step T−1 back at the top of tick T, by which time the anchor has
+    // moved on, and composing last step's shape against this tick's anchor
+    // produces a world pose that describes neither. Nothing rendered can tell —
+    // the attachment cascade re-derives position from the anchor and the local
+    // transforms either way (§4.1) — but a **nested** cloth reads this pose as
+    // its own anchor, and then the two systems hand it different numbers.
+    // `MEASUREMENTS.md` §56.
+    const ax = instance.anchor_translation[0];
+    const ay = instance.anchor_translation[1];
+    const az = instance.anchor_translation[2];
+
+    const aqx = instance.anchor_rotation[0];
+    const aqy = instance.anchor_rotation[1];
+    const aqz = instance.anchor_rotation[2];
+    const aqw = instance.anchor_rotation[3];
 
     const parent = instance.node_parent;
 

package/src/engine/physics/cloth/ecs/makeClothWorker.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Spawn the cloth solver worker.
+ *
+ * Isolated in its own module on purpose: `import.meta` is a syntax error under
+ * the CommonJS transform the test runner uses, so any module containing it
+ * cannot be imported by a spec — even transitively. Keeping the expression here
+ * lets {@link WorkerClothSystem} stay testable while application code gets a
+ * one-import default.
+ *
+ * The `new Worker(new URL(...), { type: "module" })` form is what webpack 5
+ * detects statically, so the worker is emitted as a real chunk with its full
+ * dependency graph rather than being assembled at runtime.
+ *
+ * @returns {Worker}
+ */
+export function makeClothWorker(): Worker;
+//# sourceMappingURL=makeClothWorker.d.ts.map

package/src/engine/physics/cloth/ecs/makeClothWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"makeClothWorker.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/makeClothWorker.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,mCAFa,MAAM,CAIlB"}

package/src/engine/physics/cloth/ecs/makeClothWorker.js

@@ -0,0 +1,18 @@
+/**
+ * Spawn the cloth solver worker.
+ *
+ * Isolated in its own module on purpose: `import.meta` is a syntax error under
+ * the CommonJS transform the test runner uses, so any module containing it
+ * cannot be imported by a spec — even transitively. Keeping the expression here
+ * lets {@link WorkerClothSystem} stay testable while application code gets a
+ * one-import default.
+ *
+ * The `new Worker(new URL(...), { type: "module" })` form is what webpack 5
+ * detects statically, so the worker is emitted as a real chunk with its full
+ * dependency graph rather than being assembled at runtime.
+ *
+ * @returns {Worker}
+ */
+export function makeClothWorker() {
+    return new Worker(new URL("./cloth.worker.js", import.meta.url), { type: "module" });
+}

package/src/engine/physics/cloth/playground/README.md

@@ -4,7 +4,7 @@
 npm run dev --workspace @woosh/meep-engine
 ```
 
-Four pages, one directory, one layer of the system each. (Vite takes the next
+Five pages, one directory, one layer of the system each. (Vite takes the next
 free port if 5173 is busy — the terminal says which.)
 
 | | |
@@ -13,10 +13,16 @@ free port if 5173 is busy — the terminal says which.)
 | [`rig.html`](./rig.html) | **the entity subtree, M1.** A real `EntityManager`, real entities, `ClothSystem` walking and writing back. |
 | [`collide.html`](./collide.html) | **collision, M2.** The solver again, with a packed collider table in the argument list. |
 | [`garment.html`](./garment.html) | **skinned garments, M3, and self-collision, M4.** A skeleton of entities, a `Skin`, and a `Cloth` + `ClothRig` driving some of its joints. |
+| [`wind.html`](./wind.html) | **wind, M6.** A banner hanging in a real `FluidSimulator`'s wake, reading it through `ClothFluidWind`. |
 
-Both are at
+All are at
 `http://localhost:5173/src/engine/physics/cloth/playground/<page>`.
 
+There is no M5 page, and that is deliberate: a `SharedArrayBuffer` needs a
+cross-origin isolated page and `vite.config.mjs` sends no `COOP`/`COEP`
+(`MEASUREMENTS.md` §44). The worker bridge is tested by
+`SystemWorkerLoopback` instead, more precisely than a page could.
+
 ---
 
 # The solver page — `index.html`
@@ -337,3 +343,68 @@ has the numbers, because it cost an hour to diagnose the first time.
 step_once, draw, scene }`. `rebuild` returns a promise, because
 `EntityManager#startup` does and an entity created before it resolves is never
 linked.
+
+---
+
+# The wind page — `wind.html`
+
+## What it is
+
+§10's argument made watchable, and the word that matters is **simulated**. There
+is no wind model on this page. There is a `FluidField`, a `FluidSimulator`, a
+`GlobalFluidEffector` in its prevailing-wind regime, and a solid post standing in
+the flow; the banner reads the result through exactly the `ClothFluidWind` and
+`cloth_sample_air` a scene uses. The blue threads are the air on a horizontal
+slice through the banner's waist, the red squares are the post.
+
+The cloth is driven like the solver and collision pages — `cloth_step` in
+process, no `EntityManager` — because what is being shown is the air rather than
+the ECS wiring, and `ecs/cloth_wind.spec.js` covers that more precisely.
+
+## Three things to watch rather than read
+
+- **Turn the flow to 90° on `ambient only`.** The banner goes limp at the same
+  wind speed: the *drag accel* readout falls from 43 m/s² to 0.08, and the mean
+  facing factor from 0.221 to 0.000. That is §10's normal-facing factor, and it
+  is the sharpest single result in M6.
+- **Do the same on `fluid field + ambient`, and it does not go limp.** 0.216 at
+  0°, 0.280 at 90°. A wake has velocity in every direction, so no orientation of
+  a banner is edge-on to one — which is something the simulation knows and a wind
+  zone could not have told it.
+- **Take the post away.** The air at the banner goes from 6.0 m/s to 8.7. That
+  31% deficit is the incompressible projection's answer to a solid standing in a
+  flow, and there is no authored falloff anywhere in it.
+
+## The readout
+
+- **cloth step** — `cloth_wind_accelerate` plus `cloth_step`, against §17's 2 ms
+  bar. The wind's own share of it is about one per cent (`MEASUREMENTS.md` §49);
+  everything else on that bar is the solver.
+- **fluid step** — the `FluidSimulator`, which at the default grid is several
+  times the cloth. It is on the page to be honest about where the frame goes: the
+  simulation is the expensive half and cloth is renting it.
+- **air sample** and **sampled** — `cloth_sample_air`. Switch the source to
+  `ambient only` and watch it drop by a factor of twenty-five as "per particle"
+  becomes "once for the cloth". That is §10's "a cloth outside every fluid field's
+  bounds skips it entirely", and it is the reason the fallback is affordable.
+- **drag accel, mean** — the external acceleration with gravity taken back out:
+  the facing factor as a number.
+
+## What it does not show
+
+**A shedding street.** At the grids this page can afford the wake is a *steady*
+velocity deficit — measured at 18, 26 and 34 cells across, with damping and
+vorticity confinement at both ends of their range, the air behind the post varies
+by under 0.03 m/s. The banner's free corner moves twelve times as far per step
+with the post as without, and both of those are settled rather than fluttering.
+That is the fluid solver's answer at this scale rather than the cloth's, and
+`MEASUREMENTS.md` §51 records it so the page is not read as promising something
+it does not do.
+
+## Notes
+
+`globalThis.cloth_wind_playground` exposes `{ control, camera, rebuild,
+step_once, refresh_post, cloth, tunnel, wind, air_centre, sampled_per_particle,
+mean_drag, tripwire, timings }`. Changing `control.yaw` needs a `refresh_post()`
+after it, because the post stands upstream along the flow and only moves when it
+is asked to.

package/src/engine/physics/cloth/playground/collide_main.js

@@ -173,7 +173,7 @@ function step_once() {
 
     const started = performance.now();
 
-    contact_rows = cloth_contact_find(state, colliders.table, colliders.keys, colliders.count);
+    contact_rows = cloth_contact_find(state, colliders.table, colliders.keys, colliders.count, FIXED_STEP);
 
     cloth_step(
         state, FIXED_STEP, 0, -9.81, 0,

package/src/engine/physics/cloth/playground/wind.html

@@ -0,0 +1,166 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — cloth wind (M6)</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --ink: #d6dae0;
+            --dim: #8b939f;
+            --line: #2b3038;
+            --panel: #14171c;
+            --warn: #e5b54a;
+            --bad: #e5533d;
+            --good: #5ad19a;
+        }
+
+        html, body {
+            margin: 0;
+            height: 100%;
+            background: #0d0f12;
+            color: var(--ink);
+            font: 12px/1.5 ui-monospace, Consolas, monospace;
+            overflow: hidden;
+        }
+
+        body { display: flex; }
+
+        #stage { position: relative; flex: 1; min-width: 0; }
+        #view { display: block; width: 100%; height: 100%; cursor: grab; }
+        #view.grabbing { cursor: grabbing; }
+
+        #hint {
+            position: absolute; left: 14px; bottom: 12px;
+            color: var(--dim); pointer-events: none;
+        }
+
+        #readout {
+            position: absolute; left: 14px; top: 12px;
+            background: rgba(13, 15, 18, 0.82);
+            border: 1px solid var(--line);
+            padding: 8px 12px;
+            min-width: 288px;
+        }
+
+        #readout table { border-collapse: collapse; width: 100%; }
+        #readout td { padding: 1px 0; white-space: nowrap; }
+        #readout td:last-child { text-align: right; padding-left: 18px; }
+        #readout td:first-child { color: var(--dim); }
+
+        #budget { height: 4px; margin-top: 7px; background: #22262d; position: relative; overflow: hidden; }
+        #budget > i { display: block; height: 100%; background: var(--good); width: 0; }
+        #budget.over > i { background: var(--bad); }
+
+        aside {
+            width: 300px; flex: none;
+            border-left: 1px solid var(--line);
+            background: var(--panel);
+            overflow-y: auto;
+            padding: 12px 14px 40px;
+        }
+
+        h1 { font-size: 13px; margin: 0 0 2px; }
+        h2 {
+            font-size: 11px; margin: 18px 0 6px; color: var(--dim);
+            text-transform: uppercase; letter-spacing: 0.08em; font-weight: normal;
+            border-bottom: 1px solid var(--line); padding-bottom: 4px;
+        }
+        p.blurb { color: var(--dim); margin: 0 0 6px; }
+        a { color: #6fa8dc; }
+
+        label { display: flex; align-items: center; gap: 8px; margin: 5px 0; }
+        label > span:first-child { flex: none; width: 96px; color: var(--dim); }
+        label > input[type=range] { flex: 1; min-width: 0; height: 16px; }
+        label > output { flex: none; width: 62px; text-align: right; }
+        label > select {
+            flex: 1; min-width: 0; background: #0d0f12; color: var(--ink);
+            border: 1px solid var(--line); font: inherit; padding: 2px 4px;
+        }
+
+        .buttons { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }
+        button {
+            background: #1b1f26; color: var(--ink); border: 1px solid var(--line);
+            font: inherit; padding: 4px 10px; cursor: pointer;
+        }
+        button:hover { background: #232832; }
+        button.on { border-color: var(--warn); color: var(--warn); }
+
+        #tripwire.bad { color: var(--bad); }
+        #tripwire.good { color: var(--good); }
+    </style>
+</head>
+<body>
+
+<div id="stage">
+    <canvas id="view"></canvas>
+
+    <div id="readout">
+        <table>
+            <tr><td>cloth step</td><td><b id="ms">—</b> ms</td></tr>
+            <tr><td>fluid step</td><td><span id="fluid_ms">—</span> ms</td></tr>
+            <tr><td>air sample</td><td><span id="sample_us">—</span> µs</td></tr>
+            <tr><td>sampled</td><td id="sample_mode">—</td></tr>
+            <tr><td>particles / rows</td><td id="counts">—</td></tr>
+            <tr><td>air at the banner</td><td id="air">—</td></tr>
+            <tr><td>drag accel, mean</td><td id="drag_accel">—</td></tr>
+            <tr><td>state</td><td id="tripwire" class="good">ok</td></tr>
+        </table>
+        <div id="budget"><i></i></div>
+    </div>
+
+    <div id="hint">drag to orbit · wheel to zoom · shift-drag to pan · the blue threads are the air, the red squares the post</div>
+</div>
+
+<aside>
+    <h1>Cloth wind — M6</h1>
+    <p class="blurb">
+        §10's argument, made watchable: there is no wind model here. A real
+        <code>FluidField</code>, a real <code>FluidSimulator</code>, a solid post standing in the
+        flow, and a banner reading the result through <code>ClothFluidWind</code> — the same path a
+        scene uses. The other pages are
+        <a href="./index.html">index</a>, <a href="./rig.html">rig</a>,
+        <a href="./collide.html">collide</a> and <a href="./garment.html">garment</a>.
+    </p>
+
+    <h2>Banner</h2>
+    <label><span>fabric</span><select id="fabric"></select></label>
+    <label><span>size</span><input id="size" type="range" min="6" max="28" step="1"><output id="size_out"></output></label>
+    <label><span>spacing</span><input id="spacing" type="range" min="0.02" max="0.09" step="0.005"><output id="spacing_out"></output></label>
+    <label><span>drag</span><input id="drag" type="range" min="0" max="1" step="0.01"><output id="drag_out"></output></label>
+    <label><span>substeps</span><input id="substeps" type="range" min="1" max="6" step="1"><output id="substeps_out"></output></label>
+    <label><span>iterations</span><input id="iterations" type="range" min="1" max="12" step="1"><output id="iterations_out"></output></label>
+
+    <h2>Air</h2>
+    <p class="blurb">
+        On <em>ambient only</em>, turn the flow to 90° and the banner goes limp at the same wind
+        speed — <em>drag accel</em> falls from 43 to 0.08. That is §10's normal-facing factor.
+        On the <em>fluid field</em> it does not go limp: a wake has velocity in every direction,
+        so nothing is edge-on to one. Take the post away and the air at the banner goes from
+        6.0 to 8.7 m/s — that deficit is the projection's answer, not an authored falloff.
+    </p>
+    <label><span>source</span><select id="source">
+        <option value="field">fluid field + ambient</option>
+        <option value="ambient">ambient only</option>
+    </select></label>
+    <label><span>wind</span><input id="speed" type="range" min="0" max="20" step="0.5"><output id="speed_out"></output></label>
+    <label><span>flow angle</span><input id="yaw" type="range" min="0" max="90" step="5"><output id="yaw_out"></output></label>
+    <label><span>ambient gust</span><input id="gust" type="range" min="0" max="6" step="0.1"><output id="gust_out"></output></label>
+    <label><span>grid</span><input id="resolution" type="range" min="8" max="28" step="2"><output id="resolution_out"></output></label>
+
+    <div class="buttons">
+        <button id="post">post</button>
+        <button id="show_field">show the air</button>
+    </div>
+
+    <h2>Run</h2>
+    <div class="buttons">
+        <button id="pause">pause</button>
+        <button id="single">step once</button>
+        <button id="reset">rebuild</button>
+    </div>
+</aside>
+
+<script type="module" src="./wind_main.js"></script>
+</body>
+</html>

package/src/engine/physics/cloth/playground/wind_build.d.ts

@@ -0,0 +1,81 @@
+/**
+ * # The wind tunnel the banner hangs in
+ *
+ * A real {@link FluidField} stepped by a real {@link FluidSimulator}, with a
+ * real {@link GlobalFluidEffector} driving the flow and a solid post standing in
+ * it — which is the whole of §10's argument made visible. Nothing here is a
+ * wind model: the wake behind the post is the incompressible projection's
+ * answer, and the cloth reads it through the same {@link FluidComponent} an
+ * ordinary scene would.
+ *
+ * At the grid a sixty-hertz page can afford the wake is a **steady** velocity
+ * deficit rather than a shedding street — measured at 18, 26 and 34 cells
+ * across, with and without damping and confinement, the air a banner's width
+ * downstream varies by under 0.03 m/s. That is the fluid solver's answer at
+ * this scale rather than the cloth's, and `MEASUREMENTS.md` §49 records it so
+ * the page is not read as promising something it does not do.
+ *
+ * The post is written straight into `FluidField#solid` rather than voxelised by
+ * `FluidObstacle`, because the page has no ECS to hang a `Collider` on and the
+ * obstacle is not what is being demonstrated. `FluidSimulator#step` refreshes
+ * the derived masks itself, so writing the cells is the whole of it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @typedef {object} WindTunnel
+ * @property {FluidComponent} component the volume, placed in world space
+ * @property {FluidSimulator} simulator
+ * @property {GlobalFluidEffector} effector the prevailing flow
+ * @property {Float32Array} world_to_grid
+ * @property {number} cell_size
+ * @property {number[]} resolution
+ */
+/**
+ * @param {object} options
+ * @param {number} options.cell_size metres
+ * @param {number[]} options.resolution cells along x, y, z
+ * @param {number[]} options.origin world position of cell (0,0,0)'s centre
+ * @returns {WindTunnel}
+ */
+export function build_wind_tunnel({ cell_size, resolution, origin }: {
+    cell_size: number;
+    resolution: number[];
+    origin: number[];
+}): WindTunnel;
+/**
+ * Stand a solid post across the flow, upstream of the banner.
+ *
+ * @param {WindTunnel} tunnel
+ * @param {object} options
+ * @param {boolean} options.present
+ * @param {number} options.x world x of the post's centre
+ * @param {number} options.z world z of the post's centre
+ * @param {number} options.radius metres
+ * @returns {void}
+ */
+export function place_wind_post(tunnel: WindTunnel, { present, x, z, radius }: {
+    present: boolean;
+    x: number;
+    z: number;
+    radius: number;
+}): void;
+export type WindTunnel = {
+    /**
+     * the volume, placed in world space
+     */
+    component: FluidComponent;
+    simulator: FluidSimulator;
+    /**
+     * the prevailing flow
+     */
+    effector: GlobalFluidEffector;
+    world_to_grid: Float32Array;
+    cell_size: number;
+    resolution: number[];
+};
+import { FluidComponent } from "../../fluid/ecs/FluidComponent.js";
+import { FluidSimulator } from "../../fluid/FluidSimulator.js";
+import { GlobalFluidEffector } from "../../fluid/effector/GlobalFluidEffector.js";
+//# sourceMappingURL=wind_build.d.ts.map

package/src/engine/physics/cloth/playground/wind_build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wind_build.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/playground/wind_build.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH;IAL2B,SAAS,EAAzB,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACU,MAAM,EAAxB,MAAM,EAAE;IACN,UAAU,CA2CtB;AAED;;;;;;;;;;GAUG;AACH,wCARW,UAAU;IAEO,OAAO,EAAxB,OAAO;IACS,CAAC,EAAjB,MAAM;IACU,CAAC,EAAjB,MAAM;IACU,MAAM,EAAtB,MAAM;IACJ,IAAI,CAwChB;;;;;eA3Ga,cAAc;eACd,cAAc;;;;cACd,mBAAmB;mBACnB,YAAY;eACZ,MAAM;gBACN,MAAM,EAAE;;+BAnCS,mCAAmC;+BAFnC,+BAA+B;oCAC1B,6CAA6C"}

package/src/engine/physics/cloth/playground/wind_build.js

@@ -0,0 +1,141 @@
+import { FluidField } from "../../fluid/FluidField.js";
+import { FluidSimulator } from "../../fluid/FluidSimulator.js";
+import { GlobalFluidEffector } from "../../fluid/effector/GlobalFluidEffector.js";
+import { FluidComponent } from "../../fluid/ecs/FluidComponent.js";
+
+/**
+ * # The wind tunnel the banner hangs in
+ *
+ * A real {@link FluidField} stepped by a real {@link FluidSimulator}, with a
+ * real {@link GlobalFluidEffector} driving the flow and a solid post standing in
+ * it — which is the whole of §10's argument made visible. Nothing here is a
+ * wind model: the wake behind the post is the incompressible projection's
+ * answer, and the cloth reads it through the same {@link FluidComponent} an
+ * ordinary scene would.
+ *
+ * At the grid a sixty-hertz page can afford the wake is a **steady** velocity
+ * deficit rather than a shedding street — measured at 18, 26 and 34 cells
+ * across, with and without damping and confinement, the air a banner's width
+ * downstream varies by under 0.03 m/s. That is the fluid solver's answer at
+ * this scale rather than the cloth's, and `MEASUREMENTS.md` §49 records it so
+ * the page is not read as promising something it does not do.
+ *
+ * The post is written straight into `FluidField#solid` rather than voxelised by
+ * `FluidObstacle`, because the page has no ECS to hang a `Collider` on and the
+ * obstacle is not what is being demonstrated. `FluidSimulator#step` refreshes
+ * the derived masks itself, so writing the cells is the whole of it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @typedef {object} WindTunnel
+ * @property {FluidComponent} component the volume, placed in world space
+ * @property {FluidSimulator} simulator
+ * @property {GlobalFluidEffector} effector the prevailing flow
+ * @property {Float32Array} world_to_grid
+ * @property {number} cell_size
+ * @property {number[]} resolution
+ */
+
+/**
+ * @param {object} options
+ * @param {number} options.cell_size metres
+ * @param {number[]} options.resolution cells along x, y, z
+ * @param {number[]} options.origin world position of cell (0,0,0)'s centre
+ * @returns {WindTunnel}
+ */
+export function build_wind_tunnel({ cell_size, resolution, origin }) {
+    const component = new FluidComponent();
+
+    component.cell_size = cell_size;
+    component.origin = origin.slice();
+
+    const field = new FluidField();
+
+    field.setResolution(resolution[0], resolution[1], resolution[2]);
+    field.build();
+
+    component.field = field;
+
+    const simulator = new FluidSimulator();
+
+    // A little damping so a gust decays rather than accumulating forever, and a
+    // little confinement so the wake keeps its eddies at this cell count. Both
+    // are the simulator's own documented knobs.
+    simulator.velocity_damping = 0.2;
+    simulator.vorticity_confinement = 0.35;
+
+    const effector = new GlobalFluidEffector();
+
+    // Wind plus drag is `GlobalFluidEffector`'s "prevailing wind" regime: the
+    // air relaxes toward `wind`, so the volume's far field *is* the ambient the
+    // cloth reads outside it, and a garment carried out of the volume does not
+    // walk into still air.
+    // Six per second, so the volume reaches nine tenths of the driving wind
+    // within a second and the slider means roughly what it says. Measured on
+    // this grid: 8.7 m/s of a 9 m/s wind in the free stream, and 3.1 m/s
+    // directly behind the post, which is the wake the banner hangs in.
+    effector.drag = 6;
+
+    return {
+        component,
+        simulator,
+        effector,
+        world_to_grid: new Float32Array(16),
+        cell_size,
+        resolution: resolution.slice()
+    };
+}
+
+/**
+ * Stand a solid post across the flow, upstream of the banner.
+ *
+ * @param {WindTunnel} tunnel
+ * @param {object} options
+ * @param {boolean} options.present
+ * @param {number} options.x world x of the post's centre
+ * @param {number} options.z world z of the post's centre
+ * @param {number} options.radius metres
+ * @returns {void}
+ */
+export function place_wind_post(tunnel, { present, x, z, radius }) {
+    const field = tunnel.component.field;
+
+    const solid = field.solid;
+
+    solid.fill(0);
+
+    if (!present) {
+        return;
+    }
+
+    const [res_x, res_y, res_z] = tunnel.resolution;
+
+    const cell_size = tunnel.cell_size;
+
+    const origin = tunnel.component.origin;
+
+    const radius_squared = radius * radius;
+
+    for (let k = 0; k < res_z; k++) {
+        const world_z = origin[2] + k * cell_size;
+
+        const dz = world_z - z;
+
+        for (let i = 0; i < res_x; i++) {
+            const dx = origin[0] + i * cell_size - x;
+
+            // A round post: solid where the cell centre is inside the circle in
+            // the flow's own plane, spanning the whole height.
+            if (dx * dx + dz * dz > radius_squared) {
+                continue;
+            }
+
+            for (let j = 0; j < res_y; j++) {
+                solid[k * res_x * res_y + j * res_x + i] = 1;
+            }
+        }
+    }
+}

package/src/engine/physics/cloth/playground/wind_main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=wind_main.d.ts.map

package/src/engine/physics/cloth/playground/wind_main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wind_main.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/playground/wind_main.js"],"names":[],"mappings":""}