@woosh/meep-engine 3.43.0 → 3.44.0

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

@@ -1,296 +1,302 @@
-import { EntityComponentDataset } from "../../../ecs/EntityComponentDataset.js";
-import { EntityManager } from "../../../ecs/EntityManager.js";
-import {
-    TransformAttachment
-} from "../../../ecs/transform-attachment/TransformAttachment.js";
-import {
-    TransformAttachmentSystem
-} from "../../../ecs/transform-attachment/TransformAttachmentSystem.js";
-import { Transform64 } from "../../../ecs/transform/Transform64.js";
-import { Cloth } from "../ecs/Cloth.js";
-import { ClothExclude } from "../ecs/ClothExclude.js";
-import { ClothSystem } from "../ecs/ClothSystem.js";
-import { CLOTH_DYNAMICS_BY_NAME } from "../ecs/cloth_dynamics_library.js";
-
-/**
- * # Rigs for the M1 playground
- *
- * Entities, transforms, attachments and one {@link Cloth} — the real thing, not
- * a stand-in. Every rig here is built the way a scene would build it: a chain of
- * entities each carrying a `TransformAttachment` naming its parent, and the
- * component on top of the pile.
- *
- * The rigs exist to make §3.1's claim visible: **several hanging parts under one
- * `Cloth` are one coupled solve**, in one `ClothState`, with one colouring. The
- * readout on the page says how many particles and how many colours, and the
- * multi-strand rig is the one where that stops being an implementation detail.
- *
- * This is playground code rather than an `__fixtures__` module, for the same
- * reason `cloth_playground_build.js` is: `__fixtures__` is excluded from the
- * published package and this page is not, so importing across that line would
- * ship a broken module.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/**
- * @typedef {object} ClothRigScene
- * @property {EntityManager} em
- * @property {EntityComponentDataset} ecd
- * @property {ClothSystem} cloth
- * @property {number[]} anchor the entity each `Cloth` sits on
- * @property {number[][]} strand entity ids per strand, for drawing
- * @property {number[]} excluded entities pruned out of the walk, drawn differently
- */
-
-/**
- * Every rig the page can build, in the order the buttons appear.
- * @type {Array<{id: string, label: string, blurb: string, dynamics: string}>}
- */
-export const CLOTH_RIGS = [
-    {
-        id: 'rope',
-        label: 'rope',
-        blurb: '24 links, one strand. The simplest thing the subtree path does.',
-        dynamics: 'ROPE'
-    },
-    {
-        id: 'chain',
-        label: 'chain',
-        blurb: 'Shorter, stiffer links at 2×6 — the deepest budget in the library.',
-        dynamics: 'CHAIN'
-    },
-    {
-        id: 'strands',
-        label: 'multi-strand rig',
-        blurb: 'Five strands under ONE Cloth: one solve, one state, one colouring.',
-        dynamics: 'HAIR'
-    },
-    {
-        id: 'sign',
-        label: 'hanging sign',
-        blurb: 'Two ropes to a crossbar, with the sign itself excluded from the walk.',
-        dynamics: 'ROPE'
-    },
-    {
-        id: 'nested',
-        label: 'nested cloths',
-        blurb: 'A rope with a second Cloth partway down: two solves, ordered by depth.',
-        dynamics: 'ROPE'
-    }
-];
-
-/**
- * **Asynchronous, and it has to be.** `EntityManager#startup` resolves through
- * a callback, and an entity created before it resolves is never linked — the
- * observers that watch for a complete component tuple are wired during startup.
- * A page that built its rig synchronously would get a `Cloth` the system never
- * saw, which looks exactly like a solver that produced nothing.
- *
- * @param {object} options
- * @param {string} options.rig one of {@link CLOTH_RIGS}
- * @param {string} options.dynamics library entry name
- * @param {number} options.links
- * @param {number} options.spacing
- * @returns {Promise<ClothRigScene>}
- */
-export async function build_cloth_rig({ rig, dynamics, links, spacing }) {
-    const em = new EntityManager();
-    const ecd = new EntityComponentDataset();
-
-    ecd.setComponentTypeMap([Transform64, TransformAttachment, Cloth, ClothExclude]);
-
-    em.addSystem(new TransformAttachmentSystem());
-
-    const cloth = new ClothSystem();
-
-    em.addSystem(cloth);
-
-    em.attachDataset(ecd);
-
-    await new Promise((resolve, reject) => em.startup(resolve, reject));
-
-    const scene = { em, ecd, cloth, anchor: [], strand: [], excluded: [] };
-
-    const entry = CLOTH_DYNAMICS_BY_NAME[dynamics] ?? CLOTH_DYNAMICS_BY_NAME.ROPE;
-
-    switch (rig) {
-        case 'strands':
-            build_strands(scene, entry, links, spacing);
-            break;
-
-        case 'sign':
-            build_sign(scene, entry, links, spacing);
-            break;
-
-        case 'nested':
-            build_nested(scene, entry, links, spacing);
-            break;
-
-        default:
-            build_rope(scene, entry, links, spacing);
-            break;
-    }
-
-    return scene;
-}
-
-/**
- * @param {ClothRigScene} scene
- * @param {number[]} position
- * @returns {number}
- * @private
- */
-function root_at(scene, position) {
-    const entity = scene.ecd.createEntity();
-
-    const transform = new Transform64();
-
-    transform.setTranslation(position[0], position[1], position[2]);
-    transform.updateMatrix();
-
-    scene.ecd.addComponentToEntity(entity, transform);
-
-    return entity;
-}
-
-/**
- * @param {ClothRigScene} scene
- * @param {number} parent
- * @param {number[]} local
- * @param {boolean} [exclude]
- * @returns {number}
- * @private
- */
-function child_of(scene, parent, local, exclude = false) {
-    const entity = scene.ecd.createEntity();
-
-    const attachment = new TransformAttachment();
-
-    attachment.parent = parent;
-    attachment.transform.setTranslation(local[0], local[1], local[2]);
-    attachment.transform.updateMatrix();
-
-    scene.ecd.addComponentToEntity(entity, attachment);
-    scene.ecd.addComponentToEntity(entity, new Transform64());
-
-    if (exclude) {
-        scene.ecd.addComponentToEntity(entity, new ClothExclude());
-
-        scene.excluded.push(entity);
-    }
-
-    return entity;
-}
-
-/**
- * @param {ClothRigScene} scene
- * @param {number} parent
- * @param {number} count
- * @param {number[]} step
- * @returns {number[]}
- * @private
- */
-function chain_from(scene, parent, count, step) {
-    const chain = [parent];
-
-    let previous = parent;
-
-    for (let i = 0; i < count; i++) {
-        previous = child_of(scene, previous, step);
-
-        chain.push(previous);
-    }
-
-    scene.strand.push(chain);
-
-    return chain;
-}
-
-/**
- * @private
- */
-function build_rope(scene, dynamics, links, spacing) {
-    const anchor = root_at(scene, [0, 0, 0]);
-
-    chain_from(scene, anchor, links, [0, -spacing, 0]);
-
-    scene.ecd.addComponentToEntity(anchor, Cloth.from(dynamics));
-    scene.anchor.push(anchor);
-}
-
-/**
- * Five strands from one anchor, splayed around it. This is the rig §3.1 is
- * about: the `Cloth` sits on the node above all of them, so the walk finds
- * every strand and they are solved together.
- * @private
- */
-function build_strands(scene, dynamics, links, spacing) {
-    const anchor = root_at(scene, [0, 0, 0]);
-
-    const count = 5;
-
-    for (let strand = 0; strand < count; strand++) {
-        const angle = strand / count * Math.PI * 2;
-
-        const head = child_of(scene, anchor, [
-            Math.cos(angle) * spacing * 1.6,
-            -spacing,
-            Math.sin(angle) * spacing * 1.6
-        ]);
-
-        const chain = chain_from(scene, head, links - 1, [0, -spacing, 0]);
-
-        chain.unshift(anchor);
-    }
-
-    scene.ecd.addComponentToEntity(anchor, Cloth.from(dynamics));
-    scene.anchor.push(anchor);
-}
-
-/**
- * A crossbar with two ropes to a sign. The sign is a {@link ClothExclude}, so
- * it is not a particle — it hangs off the last link of the left rope and is
- * posed by the write-back rather than solved.
- * @private
- */
-function build_sign(scene, dynamics, links, spacing) {
-    const anchor = root_at(scene, [0, 0, 0]);
-
-    const left = child_of(scene, anchor, [-spacing * 3, 0, 0]);
-    const right = child_of(scene, anchor, [spacing * 3, 0, 0]);
-
-    scene.strand.push([anchor, left]);
-    scene.strand.push([anchor, right]);
-
-    const left_chain = chain_from(scene, left, links, [0, -spacing, 0]);
-
-    chain_from(scene, right, links, [0, -spacing, 0]);
-
-    child_of(scene, left_chain[left_chain.length - 1], [spacing * 3, -spacing, 0], true);
-
-    scene.ecd.addComponentToEntity(anchor, Cloth.from(dynamics));
-    scene.anchor.push(anchor);
-}
-
-/**
- * A rope with a second `Cloth` partway down. The outer walk stops there, the
- * inner one starts, and the two solve in hierarchy order so the inner anchor is
- * already where the outer solve put it.
- * @private
- */
-function build_nested(scene, dynamics, links, spacing) {
-    const anchor = root_at(scene, [0, 0, 0]);
-
-    const upper = chain_from(scene, anchor, Math.max(2, Math.floor(links / 2)), [0, -spacing, 0]);
-
-    const joint = child_of(scene, upper[upper.length - 1], [0, -spacing, 0]);
-
-    chain_from(scene, joint, Math.max(2, Math.floor(links / 2)), [0, -spacing, 0]);
-
-    scene.ecd.addComponentToEntity(anchor, Cloth.from(dynamics));
-    scene.ecd.addComponentToEntity(joint, Cloth.from(dynamics));
-
-    scene.anchor.push(anchor, joint);
-}
+import { EntityComponentDataset } from "../../../ecs/EntityComponentDataset.js";
+import { EntityManager } from "../../../ecs/EntityManager.js";
+import {
+    TransformAttachment
+} from "../../../ecs/transform-attachment/TransformAttachment.js";
+import {
+    TransformAttachmentSystem
+} from "../../../ecs/transform-attachment/TransformAttachmentSystem.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
+import { Cloth } from "../ecs/Cloth.js";
+import { ClothPin } from "../ecs/ClothPin.js";
+import { ClothExclude } from "../ecs/ClothExclude.js";
+import { ClothSystem } from "../ecs/ClothSystem.js";
+import { CLOTH_DYNAMICS_BY_NAME } from "../ecs/cloth_dynamics_library.js";
+
+/**
+ * # Rigs for the M1 playground
+ *
+ * Entities, transforms, attachments and one {@link Cloth} — the real thing, not
+ * a stand-in. Every rig here is built the way a scene would build it: a chain of
+ * entities each carrying a `TransformAttachment` naming its parent, and the
+ * component on top of the pile.
+ *
+ * The rigs exist to make §3.1's claim visible: **several hanging parts under one
+ * `Cloth` are one coupled solve**, in one `ClothState`, with one colouring. The
+ * readout on the page says how many particles and how many colours, and the
+ * multi-strand rig is the one where that stops being an implementation detail.
+ *
+ * This is playground code rather than an `__fixtures__` module, for the same
+ * reason `cloth_playground_build.js` is: `__fixtures__` is excluded from the
+ * published package and this page is not, so importing across that line would
+ * ship a broken module.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @typedef {object} ClothRigScene
+ * @property {EntityManager} em
+ * @property {EntityComponentDataset} ecd
+ * @property {ClothSystem} cloth
+ * @property {number[]} anchor the entity each `Cloth` sits on
+ * @property {number[][]} strand entity ids per strand, for drawing
+ * @property {number[]} excluded entities pruned out of the walk, drawn differently
+ */
+
+/**
+ * Every rig the page can build, in the order the buttons appear.
+ * @type {Array<{id: string, label: string, blurb: string, dynamics: string}>}
+ */
+export const CLOTH_RIGS = [
+    {
+        id: 'rope',
+        label: 'rope',
+        blurb: '24 links, one strand. The simplest thing the subtree path does.',
+        dynamics: 'ROPE'
+    },
+    {
+        id: 'chain',
+        label: 'chain',
+        blurb: 'Shorter, stiffer links at 2×6 — the deepest budget in the library.',
+        dynamics: 'CHAIN'
+    },
+    {
+        id: 'strands',
+        label: 'multi-strand rig',
+        blurb: 'Five strands under ONE Cloth: one solve, one state, one colouring.',
+        dynamics: 'HAIR'
+    },
+    {
+        id: 'sign',
+        label: 'hanging sign',
+        blurb: 'Two ropes to a crossbar, with the sign itself excluded from the walk.',
+        dynamics: 'ROPE'
+    },
+    {
+        id: 'nested',
+        label: 'nested cloths',
+        blurb: 'A rope with a second Cloth partway down: two solves, ordered by depth.',
+        dynamics: 'ROPE'
+    }
+];
+
+/**
+ * **Asynchronous, and it has to be.** `EntityManager#startup` resolves through
+ * a callback, and an entity created before it resolves is never linked — the
+ * observers that watch for a complete component tuple are wired during startup.
+ * A page that built its rig synchronously would get a `Cloth` the system never
+ * saw, which looks exactly like a solver that produced nothing.
+ *
+ * @param {object} options
+ * @param {string} options.rig one of {@link CLOTH_RIGS}
+ * @param {string} options.dynamics library entry name
+ * @param {number} options.links
+ * @param {number} options.spacing
+ * @returns {Promise<ClothRigScene>}
+ */
+export async function build_cloth_rig({ rig, dynamics, links, spacing }) {
+    const em = new EntityManager();
+    const ecd = new EntityComponentDataset();
+
+    ecd.setComponentTypeMap([Transform64, TransformAttachment, Cloth, ClothExclude]);
+
+    em.addSystem(new TransformAttachmentSystem());
+
+    const cloth = new ClothSystem();
+
+    em.addSystem(cloth);
+
+    em.attachDataset(ecd);
+
+    await new Promise((resolve, reject) => em.startup(resolve, reject));
+
+    const scene = { em, ecd, cloth, anchor: [], strand: [], excluded: [] };
+
+    const entry = CLOTH_DYNAMICS_BY_NAME[dynamics] ?? CLOTH_DYNAMICS_BY_NAME.ROPE;
+
+    switch (rig) {
+        case 'strands':
+            build_strands(scene, entry, links, spacing);
+            break;
+
+        case 'sign':
+            build_sign(scene, entry, links, spacing);
+            break;
+
+        case 'nested':
+            build_nested(scene, entry, links, spacing);
+            break;
+
+        default:
+            build_rope(scene, entry, links, spacing);
+            break;
+    }
+
+    return scene;
+}
+
+/**
+ * @param {ClothRigScene} scene
+ * @param {number[]} position
+ * @returns {number}
+ * @private
+ */
+function root_at(scene, position) {
+    const entity = scene.ecd.createEntity();
+
+    const transform = new Transform64();
+
+    transform.setTranslation(position[0], position[1], position[2]);
+    transform.updateMatrix();
+
+    scene.ecd.addComponentToEntity(entity, transform);
+
+    return entity;
+}
+
+/**
+ * @param {ClothRigScene} scene
+ * @param {number} parent
+ * @param {number[]} local
+ * @param {boolean} [exclude]
+ * @returns {number}
+ * @private
+ */
+function child_of(scene, parent, local, exclude = false) {
+    const entity = scene.ecd.createEntity();
+
+    const attachment = new TransformAttachment();
+
+    attachment.parent = parent;
+    attachment.transform.setTranslation(local[0], local[1], local[2]);
+    attachment.transform.updateMatrix();
+
+    scene.ecd.addComponentToEntity(entity, attachment);
+    scene.ecd.addComponentToEntity(entity, new Transform64());
+
+    if (exclude) {
+        scene.ecd.addComponentToEntity(entity, new ClothExclude());
+
+        scene.excluded.push(entity);
+    }
+
+    return entity;
+}
+
+/**
+ * @param {ClothRigScene} scene
+ * @param {number} parent
+ * @param {number} count
+ * @param {number[]} step
+ * @returns {number[]}
+ * @private
+ */
+function chain_from(scene, parent, count, step) {
+    const chain = [parent];
+
+    let previous = parent;
+
+    for (let i = 0; i < count; i++) {
+        previous = child_of(scene, previous, step);
+
+        chain.push(previous);
+    }
+
+    scene.strand.push(chain);
+
+    return chain;
+}
+
+/**
+ * @private
+ */
+function build_rope(scene, dynamics, links, spacing) {
+    const anchor = root_at(scene, [0, 0, 0]);
+
+    chain_from(scene, anchor, links, [0, -spacing, 0]);
+
+    scene.ecd.addComponentToEntity(anchor, ClothPin.from({ cloth: anchor, particles: [0] }));
+    scene.ecd.addComponentToEntity(anchor, Cloth.from(dynamics));
+    scene.anchor.push(anchor);
+}
+
+/**
+ * Five strands from one anchor, splayed around it. This is the rig §3.1 is
+ * about: the `Cloth` sits on the node above all of them, so the walk finds
+ * every strand and they are solved together.
+ * @private
+ */
+function build_strands(scene, dynamics, links, spacing) {
+    const anchor = root_at(scene, [0, 0, 0]);
+
+    const count = 5;
+
+    for (let strand = 0; strand < count; strand++) {
+        const angle = strand / count * Math.PI * 2;
+
+        const head = child_of(scene, anchor, [
+            Math.cos(angle) * spacing * 1.6,
+            -spacing,
+            Math.sin(angle) * spacing * 1.6
+        ]);
+
+        const chain = chain_from(scene, head, links - 1, [0, -spacing, 0]);
+
+        chain.unshift(anchor);
+    }
+
+    scene.ecd.addComponentToEntity(anchor, ClothPin.from({ cloth: anchor, particles: [0] }));
+    scene.ecd.addComponentToEntity(anchor, Cloth.from(dynamics));
+    scene.anchor.push(anchor);
+}
+
+/**
+ * A crossbar with two ropes to a sign. The sign is a {@link ClothExclude}, so
+ * it is not a particle — it hangs off the last link of the left rope and is
+ * posed by the write-back rather than solved.
+ * @private
+ */
+function build_sign(scene, dynamics, links, spacing) {
+    const anchor = root_at(scene, [0, 0, 0]);
+
+    const left = child_of(scene, anchor, [-spacing * 3, 0, 0]);
+    const right = child_of(scene, anchor, [spacing * 3, 0, 0]);
+
+    scene.strand.push([anchor, left]);
+    scene.strand.push([anchor, right]);
+
+    const left_chain = chain_from(scene, left, links, [0, -spacing, 0]);
+
+    chain_from(scene, right, links, [0, -spacing, 0]);
+
+    child_of(scene, left_chain[left_chain.length - 1], [spacing * 3, -spacing, 0], true);
+
+    scene.ecd.addComponentToEntity(anchor, ClothPin.from({ cloth: anchor, particles: [0] }));
+    scene.ecd.addComponentToEntity(anchor, Cloth.from(dynamics));
+    scene.anchor.push(anchor);
+}
+
+/**
+ * A rope with a second `Cloth` partway down. The outer walk stops there, the
+ * inner one starts, and the two solve in hierarchy order so the inner anchor is
+ * already where the outer solve put it.
+ * @private
+ */
+function build_nested(scene, dynamics, links, spacing) {
+    const anchor = root_at(scene, [0, 0, 0]);
+
+    const upper = chain_from(scene, anchor, Math.max(2, Math.floor(links / 2)), [0, -spacing, 0]);
+
+    const joint = child_of(scene, upper[upper.length - 1], [0, -spacing, 0]);
+
+    chain_from(scene, joint, Math.max(2, Math.floor(links / 2)), [0, -spacing, 0]);
+
+    scene.ecd.addComponentToEntity(anchor, ClothPin.from({ cloth: anchor, particles: [0] }));
+    scene.ecd.addComponentToEntity(anchor, Cloth.from(dynamics));
+    scene.ecd.addComponentToEntity(joint, ClothPin.from({ cloth: joint, particles: [0] }));
+    scene.ecd.addComponentToEntity(joint, Cloth.from(dynamics));
+
+    scene.anchor.push(anchor, joint);
+}