npm - @woosh/meep-engine - Versions diffs - 3.21.0 → 3.22.0 - Mend

@woosh/meep-engine 3.21.0 → 3.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1596) hide show

package/src/engine/physics/cloth/playground/rig.html ADDED Viewed

@@ -0,0 +1,187 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — cloth rigs (M1)</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: 268px;
+        }
+        #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;
+        }
+        label.check { gap: 6px; }
+        label.check > span:first-child { width: auto; }
+        .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); }
+        #rigs { display: flex; flex-direction: column; gap: 4px; }
+        #rigs button { text-align: left; }
+        #rigs small { color: var(--dim); display: block; }
+        #asleep.yes { 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>fixed step</td><td><b id="ms">—</b> ms <span id="ms_min" style="color:var(--dim)"></span></td></tr>
+            <tr><td>cloths / particles</td><td id="counts">—</td></tr>
+            <tr><td>rows  s / b / leash</td><td id="rows">—</td></tr>
+            <tr><td>colours</td><td id="colours">—</td></tr>
+            <tr><td>worst  |x−anchor| / d_geo</td><td id="tether">—</td></tr>
+            <tr><td>fastest particle</td><td id="speed">—</td></tr>
+            <tr><td>teleports</td><td id="teleports">—</td></tr>
+            <tr><td>asleep</td><td id="asleep">no</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 the background to orbit · wheel to zoom · shift-drag to pan · the anchor is the red dot</div>
+</div>
+<aside>
+    <h1>Cloth rigs — M1</h1>
+    <p class="blurb">
+        The entity-subtree path, through a real <code>EntityManager</code>: entities with
+        <code>TransformAttachment</code>, a <code>Cloth</code> on top, and <code>ClothSystem</code>
+        walking the subtree and writing <code>Transform64</code> back. Every point on screen is an
+        entity's world transform. The solver-only page is
+        <a href="./index.html">index.html</a>.
+    </p>
+    <h2>Rig</h2>
+    <div id="rigs"></div>
+    <h2>Shape</h2>
+    <label><span>links</span><input id="links" type="range" min="3" max="40" step="1"><output id="links_out"></output></label>
+    <label><span>spacing</span><input id="spacing" type="range" min="0.01" max="0.12" step="0.005"><output id="spacing_out"></output></label>
+    <h2>Fabric</h2>
+    <label><span>library</span><select id="dynamics"></select></label>
+    <label><span>stretch</span><input id="stretch" type="range" min="0" max="1" step="0.01"><output id="stretch_out"></output></label>
+    <label><span>bend</span><input id="bend" type="range" min="0" max="1" step="0.01"><output id="bend_out"></output></label>
+    <label><span>damping</span><input id="damping" type="range" min="0" max="1" step="0.01"><output id="damping_out"></output></label>
+    <label><span>slack</span><input id="slack" type="range" min="0" max="1" step="0.01"><output id="slack_out"></output></label>
+    <label><span>inertia</span><input id="inertia" type="range" min="0" max="1" step="0.01"><output id="inertia_out"></output></label>
+    <label><span>blend</span><input id="blend" type="range" min="0" max="1" step="0.01"><output id="blend_out"></output></label>
+    <label><span>substeps</span><input id="substeps" type="range" min="1" max="8" step="1"><output id="substeps_out"></output></label>
+    <label><span>iterations</span><input id="iterations" type="range" min="1" max="16" step="1"><output id="iterations_out"></output></label>
+    <h2>Drive the anchor</h2>
+    <p class="blurb">
+        §7 P7 is the inertia model and §7 P6 is the teleport. Both are about what the anchor does,
+        so this is where they are visible.
+    </p>
+    <label><span>motion</span><select id="motion">
+        <option value="still">still</option>
+        <option value="sway">sway</option>
+        <option value="sprint">sprint / stop / sprint back</option>
+        <option value="spin">spin</option>
+        <option value="orbit">orbit</option>
+    </select></label>
+    <div class="buttons">
+        <button id="teleport">teleport 1 km</button>
+        <button id="keep">TeleportKeep</button>
+        <button id="never_sleep">never sleep</button>
+    </div>
+    <h2>View</h2>
+    <div class="buttons">
+        <button id="view_links" class="on">links</button>
+        <button id="view_animated">animated pose</button>
+        <button id="view_frames">frames</button>
+    </div>
+    <h2>Run</h2>
+    <div class="buttons">
+        <button id="pause">pause</button>
+        <button id="single">step once</button>
+        <button id="reset">rebuild</button>
+        <button id="poke">poke</button>
+    </div>
+</aside>
+<script type="module" src="./rig_main.js"></script>
+</body>
+</html>

package/src/engine/physics/cloth/playground/rig_build.d.ts ADDED Viewed

@@ -0,0 +1,81 @@
+/**
+ * **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 function build_cloth_rig({ rig, dynamics, links, spacing }: {
+    rig: string;
+    dynamics: string;
+    links: number;
+    spacing: number;
+}): Promise<ClothRigScene>;
+/**
+ * # 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: Array<{
+    id: string;
+    label: string;
+    blurb: string;
+    dynamics: string;
+}>;
+export type ClothRigScene = {
+    em: EntityManager;
+    ecd: EntityComponentDataset;
+    cloth: ClothSystem;
+    /**
+     * the entity each `Cloth` sits on
+     */
+    anchor: number[];
+    /**
+     * entity ids per strand, for drawing
+     */
+    strand: number[][];
+    /**
+     * entities pruned out of the walk, drawn differently
+     */
+    excluded: number[];
+};
+import { EntityManager } from "../../../ecs/EntityManager.js";
+import { EntityComponentDataset } from "../../../ecs/EntityComponentDataset.js";
+import { ClothSystem } from "../ecs/ClothSystem.js";
+//# sourceMappingURL=rig_build.d.ts.map

package/src/engine/physics/cloth/playground/rig_build.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"rig_build.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/playground/rig_build.js"],"names":[],"mappings":"AAmFA;;;;;;;;;;;;;GAaG;AACH;IAN2B,GAAG,EAAnB,MAAM;IACU,QAAQ,EAAxB,MAAM;IACU,KAAK,EAArB,MAAM;IACU,OAAO,EAAvB,MAAM;IACJ,QAAQ,aAAa,CAAC,CAyClC;AA1HD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;GAQG;AAEH;;;GAGG;AACH,yBAFU,MAAM;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAAC,CAiC3E;;QA3CY,aAAa;SACb,sBAAsB;WACtB,WAAW;;;;YACX,MAAM,EAAE;;;;YACR,MAAM,EAAE,EAAE;;;;cACV,MAAM,EAAE;;8BA1CQ,+BAA+B;uCADtB,wCAAwC;4BAWnD,uBAAuB"}

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

@@ -0,0 +1,296 @@
+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);
+}

package/src/engine/physics/cloth/playground/rig_main.d.ts ADDED Viewed

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

package/src/engine/physics/cloth/playground/rig_main.d.ts.map ADDED Viewed

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