@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -1,7 +1,10 @@
 import { CapsuleShape3D } from "../../../../core/geom/3d/shape/CapsuleShape3D.js";
 import { SphereShape3D } from "../../../../core/geom/3d/shape/SphereShape3D.js";
 import { Skin } from "../../../../shade/renderer/animation/Skin.js";
-import { Node3D } from "../../../../shade/renderer/scene/Node3D.js";
+import { SceneBundle } from "../../../../shade/renderer/loader/SceneBundle.js";
+import { SceneNode } from "../../../../shade/renderer/loader/SceneNode.js";
+import { prefab_compile } from "../../../graphics3/prefab/prefab_compile.js";
+import { prefab_instantiate } from "../../../graphics3/prefab/prefab_instantiate.js";
 import { EntityComponentDataset } from "../../../ecs/EntityComponentDataset.js";
 import { EntityManager } from "../../../ecs/EntityManager.js";
 import { TransformAttachment } from "../../../ecs/transform-attachment/TransformAttachment.js";
@@ -72,8 +75,8 @@ export const GARMENT_PRESETS = [
     {
         id: 'ponytail',
         label: 'ponytail — 1 × 12',
-        blurb: 'One chain, deep. The rig path is the entity path with Node3Ds in it, and a single '
-            + 'chain is where that is most obviously true.',
+        blurb: 'One chain, deep. The rig path is the entity path, and a single chain is where that '
+            + 'is most obviously true.',
         strips: 1,
         links: 12,
         dynamics: 'HAIR'
@@ -114,9 +117,8 @@ export async function build_garment({ preset, dynamics, links, spacing, collide,
 
     const entry = GARMENT_PRESETS.find(p => p.id === preset) ?? GARMENT_PRESETS[0];
 
-    const skeleton = build_skeleton(entry, links, spacing);
-
-    const { proxy, error } = cloth_proxy_from_joints(skeleton.skin, skeleton.garment_names, {
+        const skeleton = build_skeleton(ecd, entry, links, spacing);
+    const { proxy, error } = cloth_proxy_from_joints(skeleton.prefab, skeleton.skin, skeleton.garment_names, {
         name: entry.label
     });
 
@@ -143,7 +145,9 @@ export async function build_garment({ preset, dynamics, links, spacing, collide,
 
     ecd.addComponentToEntity(entity, Cloth.from(fabric, { flags: ClothFlags.NeverSleep }));
 
-    cloth.models = { instance_of: () => ({ skins: [skeleton.skin] }) };
+    // the one method `ClothSystem` calls on a model provider: the instance whose skins address the
+    // joints as entities
+    cloth.models = { instance_of: () => skeleton.instance };
 
     if (collide) {
         add_body_colliders(ecd, skeleton);
@@ -152,11 +156,11 @@ export async function build_garment({ preset, dynamics, links, spacing, collide,
     // One step so the seed runs and the bind pose is on the joints.
     cloth.fixedUpdate(1 / 60);
 
-    const bind = skeleton.joint.map(node => [
-        node.transform_global.translation[0],
-        node.transform_global.translation[1],
-        node.transform_global.translation[2]
-    ]);
+    const bind = skeleton.joint.map(entity => {
+        const t = ecd.getComponent(entity, Transform64).translation;
+
+        return [t[0], t[1], t[2]];
+    });
 
     return {
         ecd,
@@ -173,38 +177,26 @@ export async function build_garment({ preset, dynamics, links, spacing, collide,
  * A character: pelvis, spine, shoulders, two legs, and the garment's own strips
  * hanging from whichever bone the preset says.
  *
+ * @param {EntityComponentDataset} ecd the page's dataset, which the character becomes entities of
  * @param {object} entry
  * @param {number} links
  * @param {number} spacing
- * @returns {object}
+ * @returns {object} the bones and the garment's joints as entities, the prefab and its instance
  * @private
  */
-function build_skeleton(entry, links, spacing) {
-    /** @type {Node3D[]} */
-    const joints = [];
+function build_skeleton(ecd, entry, links, spacing) {
+    // the character as a loader would describe it: nodes in pre-order, every one a joint of the skin
+    const bundle = new SceneBundle();
 
     /**
      * @param {string} name
-     * @param {Node3D|null} parent
+     * @param {number} parent
      * @param {number[]} offset
-     * @returns {Node3D}
+     * @returns {number} the node's index
      */
-    const bone = (name, parent, offset) => {
-        const node = new Node3D();
-
-        node.name = name;
-        node.transform_local.setTranslation(offset[0], offset[1], offset[2]);
-
-        if (parent !== null) {
-            parent.addChild(node);
-        }
-
-        joints.push(node);
+    const bone = (name, parent, offset) => bundle.add_node(SceneNode.from({ name, parent, translation: offset }));
 
-        return node;
-    };
-
-    const root = bone('root', null, [0, 0, 0]);
+    const root = bone('root', -1, [0, 0, 0]);
     const pelvis = bone('pelvis', root, [0, 0.95, 0]);
     const spine = bone('spine', pelvis, [0, 0.22, 0]);
     const chest = bone('chest', spine, [0, 0.2, 0]);
@@ -218,15 +210,13 @@ function build_skeleton(entry, links, spacing) {
     bone('knee_l', left_leg, [0, -0.42, 0]);
     bone('knee_r', right_leg, [0, -0.42, 0]);
 
-    const character = joints.slice();
+    const character_count = bundle.nodes.length;
 
     // The garment hangs from the chest for a cape and from the pelvis for a
     // loincloth, which is the difference between the two presets.
     const from = entry.id === 'loincloth' ? pelvis : (entry.id === 'ponytail' ? neck : chest);
 
     const garment_names = [];
-    const garment = [];
-
     const strips = entry.strips;
 
     for (let s = 0; s < strips; s++) {
@@ -235,8 +225,10 @@ function build_skeleton(entry, links, spacing) {
         let parent = from;
 
         for (let i = 0; i < links; i++) {
-            const node = bone(
-                `garment_${s}_${i}`,
+            const name = `garment_${s}_${i}`;
+
+            parent = bone(
+                name,
                 parent,
                 i === 0
                     // The first link carries the strip sideways and behind, so
@@ -252,25 +244,40 @@ function build_skeleton(entry, links, spacing) {
                     : [0, -spacing, -spacing * 0.05]
             );
 
-            garment_names.push(node.name);
-            garment.push(node);
-
-            parent = node;
+            garment_names.push(name);
         }
     }
 
-    root.updateMatrices();
+    const joints = bundle.nodes.map((_node, index) => index);
+
+    bundle.skins = [Skin.from({
+        joints,
+        inverse_bind_matrices: new Float32Array(joints.length * 16)
+    })];
+
+    const prefab = prefab_compile(bundle);
+
+    // the character is entities of the page's dataset, under a placement standing at the origin;
+    // the attachment system composes every joint's world from there, the way a rig's would
+    const placement = ecd.createEntity();
+    const placement_transform = new Transform64();
+
+    placement_transform.updateMatrix();
+
+    ecd.addComponentToEntity(placement, placement_transform);
+
+    const instance = prefab_instantiate(prefab, ecd, placement);
 
     return {
-        root,
-        pelvis,
-        bone: character,
-        joint: garment,
+        prefab,
+        instance,
+        placement,
+        root: instance.entity_of('root'),
+        pelvis: instance.entity_of('pelvis'),
+        bone: bundle.nodes.slice(0, character_count).map(node => instance.entity_of(node.name)),
+        joint: garment_names.map(name => instance.entity_of(name)),
         garment_names,
-        skin: Skin.from({
-            joints,
-            inverse_bind_matrices: new Float32Array(joints.length * 16)
-        })
+        skin: prefab.skins[0]
     };
 }
 
@@ -278,7 +285,7 @@ function build_skeleton(entry, links, spacing) {
  * Capsules on the character's own bones, opted into cloth the way any collider
  * is: a `ClothCollider` beside an existing `(Collider, Transform64)`.
  *
- * They are entities rather than nodes because that is what a `ClothCollider`
+ * They are entities of their own because that is what a `ClothCollider`
  * is — §3.5's "the `RigidBody`-analogue" — and because a character's collision
  * capsules are authored as entities in a real scene too. The page keeps their
  * transforms in step with the bones by hand, which is what a rig would do.
@@ -288,7 +295,7 @@ function build_skeleton(entry, links, spacing) {
  * @private
  */
 function add_body_colliders(ecd, skeleton) {
-    const by_name = new Map(skeleton.bone.map(node => [node.name, node]));
+    const instance = skeleton.instance;
 
     const parts = [
         { bone: 'spine', shape: CapsuleShape3D.from(0.13, 0.3), offset: [0, 0.1, 0] },
@@ -300,9 +307,9 @@ function add_body_colliders(ecd, skeleton) {
     skeleton.body = [];
 
     for (const part of parts) {
-        const node = by_name.get(part.bone);
+        const node = instance.entity_of(part.bone);
 
-        if (node === undefined) {
+        if (node === -1) {
             continue;
         }
 
@@ -340,9 +347,8 @@ export function garment_sync_colliders(scene) {
     }
 
     for (const part of body) {
-        const node = part.node;
-
-        const t = node.transform_global;
+        // the bone's world, as the attachment system composed it
+        const t = scene.ecd.getComponent(part.node, Transform64);
 
         part.transform.setTranslation(
             t.translation[0] + part.offset[0],

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

@@ -2,6 +2,9 @@ import { Cloth } from "../ecs/Cloth.js";
 import { CLOTH_DYNAMICS_BY_NAME } from "../ecs/cloth_dynamics_library.js";
 import { PlaygroundCamera, project } from "./cloth_playground_draw.js";
 import { GARMENT_PRESETS, build_garment, garment_sync_colliders } from "./garment_build.js";
+import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../../../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
+import { TransformAttachment } from "../../../ecs/transform-attachment/TransformAttachment.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
 
 /**
  * # Skinned garments playground — M3
@@ -11,9 +14,9 @@ import { GARMENT_PRESETS, build_garment, garment_sync_colliders } from "./garmen
  *
  * The rig page (`rig.html`) is a `Cloth` over an entity subtree; this is a
  * `Cloth` + a `ClothRig` over a skinned model's **joints**. Every point on
- * screen is a `Node3D.transform_global` — a joint of a `Skin`, not an entity —
- * and it is where it is because the solver wrote its `transform_local` and this
- * page composed the chain.
+ * screen is a joint's world `Transform64` — an entity of the character's prefab
+ * instance — and it is where it is because the solver wrote the joint's own
+ * offset and the attachment system composed the chain.
  *
  * What it exists to show, because these are claims about a hierarchy rather
  * than about an array:
@@ -122,35 +125,43 @@ function step_once() {
  * the race it exists to prevent.
  */
 function drive_character() {
-    const root = scene.root;
-    const pelvis = scene.pelvis;
+    const ecd = scene.ecd;
+
+    // the bones' own offsets, under their parents: what a rig's animation would write
+    const root = ecd.getComponent(scene.root, TransformAttachment).transform;
+    const pelvis = ecd.getComponent(scene.pelvis, TransformAttachment).transform;
 
     if (control.motion === 'still') {
-        root.transform_local.setTranslation(0, 0, 0);
-        root.transform_local.setRotation(0, 0, 0, 1);
-        pelvis.transform_local.setTranslation(0, 0.95, 0);
+        root.setTranslation(0, 0, 0);
+        root.setRotation(0, 0, 0, 1);
+        pelvis.setTranslation(0, 0.95, 0);
     } else if (control.motion === 'walk') {
-        root.transform_local.setTranslation(0, 0, Math.sin(time * 1.6) * 0.9);
-        root.transform_local.setRotation(0, 0, 0, 1);
-        pelvis.transform_local.setTranslation(0, 0.95 + Math.sin(time * 6.4) * 0.02, 0);
+        root.setTranslation(0, 0, Math.sin(time * 1.6) * 0.9);
+        root.setRotation(0, 0, 0, 1);
+        pelvis.setTranslation(0, 0.95 + Math.sin(time * 6.4) * 0.02, 0);
     } else if (control.motion === 'turn') {
         const angle = time * 1.9;
 
-        root.transform_local.setTranslation(0, 0, 0);
-        root.transform_local.setRotation(0, Math.sin(angle * 0.5), 0, Math.cos(angle * 0.5));
-        pelvis.transform_local.setTranslation(0, 0.95, 0);
+        root.setTranslation(0, 0, 0);
+        root.setRotation(0, Math.sin(angle * 0.5), 0, Math.cos(angle * 0.5));
+        pelvis.setTranslation(0, 0.95, 0);
     } else {
         // §7 P7's own profile: a **square wave in velocity**, integrated rather
         // than written as a position — a position that resets is a nine-metre
         // discontinuity, which is a teleport (§7 P6) wearing a sprint's clothes.
         sprint_z += (Math.floor(time) % 2 === 0 ? 9 : -9) * FIXED_STEP;
 
-        root.transform_local.setTranslation(0, 0, sprint_z);
-        root.transform_local.setRotation(0, 0, 0, 1);
-        pelvis.transform_local.setTranslation(0, 0.95, 0);
+        root.setTranslation(0, 0, sprint_z);
+        root.setRotation(0, 0, 0, 1);
+        pelvis.setTranslation(0, 0.95, 0);
     }
 
-    root.updateMatrices();
+    root.updateMatrix();
+    pelvis.updateMatrix();
+
+    // announced, so the attachment system composes the chain below each
+    ecd.sendEvent(scene.root, TRANSFORM_ATTACHMENT_EVENT_CHANGE);
+    ecd.sendEvent(scene.pelvis, TRANSFORM_ATTACHMENT_EVENT_CHANGE);
 }
 
 // ------------------------------------------------------------------- draw
@@ -183,18 +194,35 @@ function draw() {
 }
 
 /**
- * @param {Node3D} node
+ * @param {number} node an entity of the character
  * @param {Float64Array} out
  * @param {number} width
  * @param {number} height
  * @returns {number} depth
  */
 function project_node(node, out, width, height) {
-    const t = node.transform_global.translation;
+    const t = scene.ecd.getComponent(node, Transform64).translation;
 
     return project(out, camera, t[0], t[1], t[2], width, height);
 }
 
+/**
+ * The bone an entity hangs from, or -1 at the top of the character — the placement above the
+ * root is not a bone.
+ *
+ * @param {number} node
+ * @returns {number}
+ */
+function parent_of(node) {
+    const attachment = scene.ecd.getComponent(node, TransformAttachment);
+
+    if (attachment === undefined || attachment.parent === scene.placement) {
+        return -1;
+    }
+
+    return attachment.parent;
+}
+
 function draw_ground(width, height) {
     context.save();
     context.strokeStyle = '#1d222a';
@@ -227,11 +255,13 @@ function draw_body(width, height) {
     context.lineWidth = Math.max(2, width / 500);
 
     for (const node of scene.bone) {
-        if (node.parent === null) {
+        const parent = parent_of(node);
+
+        if (parent === -1) {
             continue;
         }
 
-        project_node(node.parent, SCREEN, width, height);
+        project_node(parent, SCREEN, width, height);
         project_node(node, OTHER, width, height);
 
         context.beginPath();
@@ -257,17 +287,13 @@ function draw_bind(width, height) {
     const joint = scene.joint;
 
     for (let i = 0; i < joint.length; i++) {
-        const node = joint[i];
-
-        const parent_index = joint.indexOf(node.parent);
+                const node = joint[i];
+        const parent = parent_of(node);
+        const parent_index = joint.indexOf(parent);
 
         const from = parent_index >= 0
             ? bind[parent_index]
-            : [
-                node.parent.transform_global.translation[0],
-                node.parent.transform_global.translation[1],
-                node.parent.transform_global.translation[2]
-            ];
+            : Array.from(scene.ecd.getComponent(parent, Transform64).translation);
 
         project(SCREEN, camera, from[0], from[1], from[2], width, height);
         project(OTHER, camera, bind[i][0], bind[i][1], bind[i][2], width, height);
@@ -287,7 +313,7 @@ function draw_garment(width, height) {
     context.lineWidth = Math.max(1.5, width / 700);
 
     for (const node of scene.joint) {
-        project_node(node.parent, SCREEN, width, height);
+        project_node(parent_of(node), SCREEN, width, height);
         project_node(node, OTHER, width, height);
 
         context.beginPath();
@@ -313,7 +339,7 @@ function draw_garment(width, height) {
  * Each joint's reconstructed orientation, as an axis triple. A particle has no
  * orientation, so this is §11.1's swing — the minimal rotation from the link's
  * bind direction to its simulated one, and the reason the rig path can write a
- * `transform_local` at all.
+ * offset of its own at all.
  */
 function draw_frames(width, height) {
     const axes = [
@@ -328,7 +354,7 @@ function draw_frames(width, height) {
     context.lineWidth = 1;
 
     for (const node of scene.joint) {
-        const t = node.transform_global;
+        const t = scene.ecd.getComponent(node, Transform64);
 
         project(SCREEN, camera, t.translation[0], t.translation[1], t.translation[2], width, height);
 

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"}