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

@woosh/meep-engine 3.21.0 → 3.23.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 (1803) hide show

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

@@ -0,0 +1,182 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — skinned garments (M3)</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: 250px;
+        }
+        #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); }
+        aside {
+            width: 310px; flex: none; overflow-y: auto;
+            background: var(--panel); border-left: 1px solid var(--line);
+            padding: 12px 14px 40px;
+        }
+        aside h2 {
+            font-size: 11px; text-transform: uppercase; letter-spacing: 0.08em;
+            color: var(--dim); margin: 18px 0 6px; font-weight: 600;
+        }
+        aside h2:first-child { margin-top: 0; }
+        .blurb { color: var(--dim); margin: 0 0 8px; font-size: 11px; }
+        .blurb b { color: var(--ink); font-weight: 600; }
+        label { display: flex; align-items: center; gap: 8px; margin: 3px 0; }
+        label > span { flex: none; width: 92px; color: var(--dim); }
+        label > input[type=range] { flex: 1; min-width: 0; accent-color: #6b8afd; }
+        label > output { flex: none; width: 54px; text-align: right; }
+        select {
+            width: 100%; background: #1b1f26; color: var(--ink);
+            border: 1px solid var(--line); padding: 4px 6px; font: inherit;
+        }
+        .buttons { display: flex; flex-wrap: wrap; gap: 6px; margin: 6px 0; }
+        button {
+            background: #1b1f26; color: var(--ink); border: 1px solid var(--line);
+            padding: 4px 9px; font: inherit; cursor: pointer;
+        }
+        button:hover { border-color: #47506045; background: #232833; }
+        button.on { background: #2b3546; border-color: #4a5b7d; color: #cfe0ff; }
+        .bad { color: var(--bad); }
+        .good { color: var(--good); }
+    </style>
+</head>
+<body>
+<div id="stage">
+    <canvas id="view"></canvas>
+    <div id="readout">
+        <table>
+            <tr><td>joints simulated</td><td id="r_joints">—</td></tr>
+            <tr><td>particles</td><td id="r_particles">—</td></tr>
+            <tr><td>rows s / leash</td><td id="r_rows">—</td></tr>
+            <tr><td>contacts</td><td id="r_contacts">—</td></tr>
+            <tr><td>self pairs</td><td id="r_self">—</td></tr>
+            <tr><td>worst |x−anchor| / d_geo</td><td id="r_reach">—</td></tr>
+            <tr><td>fixed step</td><td id="r_step">—</td></tr>
+        </table>
+    </div>
+    <div id="hint">drag to orbit · shift-drag to pan · wheel to zoom</div>
+</div>
+<aside>
+    <h2>Garment</h2>
+    <select id="preset"></select>
+    <p class="blurb" id="preset_blurb"></p>
+    <label><span>links</span><input id="links" type="range" min="3" max="16" step="1"><output id="links_out"></output></label>
+    <label><span>spacing</span><input id="spacing" type="range" min="0.03" max="0.14" step="0.005"><output id="spacing_out"></output></label>
+    <h2>Fabric</h2>
+    <select id="dynamics"></select>
+    <p class="blurb">
+        The same library the entity path uses. <b>The solver is identical either way</b> — §11's claim,
+        and what makes it true is that seeding and write-back are the only two files that differ.
+    </p>
+    <h2>Motion</h2>
+    <div class="buttons">
+        <button id="motion_still" class="on">still</button>
+        <button id="motion_walk">walk</button>
+        <button id="motion_turn">turn</button>
+        <button id="motion_sprint">sprint</button>
+    </div>
+    <p class="blurb">
+        The motion drives the <b>character's own bones</b> and nothing else. The garment's joints are
+        cloth's, and the seed says so: it claims <b>TransformAuthority.CPU</b> on every one of them,
+        because a joint a clip drives is under GPU authority and its <code>transform_local</code> is
+        not read by anything. Two writers of one row is the race the authority enum exists to prevent.
+    </p>
+    <h2>Body</h2>
+    <div class="buttons">
+        <button id="collide" class="on">collide with the body</button>
+    </div>
+    <h2>Self-collision</h2>
+    <div class="buttons">
+        <button id="self_collision" class="on">collide with itself</button>
+    </div>
+    <p class="blurb">
+        §9's first tier: a hash grid over the particles, and a one-sided penalty on every pair
+        no row already governs. Watch <b>self pairs</b> on a cape in a sprint — it is zero while
+        the garment hangs and climbs the moment a fold closes. <b>The radius is the proxy's
+        resolution, not the fabric's thickness</b>: at 6 mm of silk on 8 cm particles the two
+        layers of a fold are never in contact at all, which is what MEASUREMENTS §31 measured
+        before the field existed.
+    </p>
+    <h2>Blend</h2>
+    <label><span>blend</span><input id="blend" type="range" min="0" max="1" step="0.01"><output id="blend_out"></output></label>
+    <p class="blurb">
+        At <b>0</b> the garment is exactly its baked bind pose, carried by the animated bone it hangs
+        from — which is what a proxy's rest data is for, and why a re-seed of a live garment does not
+        mistake the shape the solver left behind for the shape the artist authored.
+    </p>
+    <h2>View</h2>
+    <div class="buttons">
+        <button id="view_bind" class="on">bind pose</button>
+        <button id="view_frames">frames</button>
+        <button id="view_body" class="on">body</button>
+    </div>
+    <h2>Run</h2>
+    <div class="buttons">
+        <button id="pause">pause</button>
+        <button id="single">step once</button>
+        <button id="reset">reset</button>
+    </div>
+</aside>
+<script type="module" src="./garment_main.js"></script>
+</body>
+</html>

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

@@ -0,0 +1,78 @@
+/**
+ * @param {object} options
+ * @returns {Promise<GarmentScene>}
+ */
+export function build_garment({ preset, dynamics, links, spacing, collide, self_collision }: object): Promise<GarmentScene>;
+/**
+ * Put every body collider where its bone is. Called once a step, before the
+ * cloth, which is what a rig binding collision capsules to bones would do.
+ *
+ * @param {object} scene
+ * @returns {void}
+ */
+export function garment_sync_colliders(scene: object): void;
+/**
+ * # A rigged character for the M3 page
+ *
+ * A `Node3D` skeleton with a `Skin` over it, a garment built out of some of its
+ * joints, and a real `ClothSystem` driving them — the §11.2 path with nothing
+ * standing in for it except the renderer, which a 2D canvas does not need.
+ *
+ * `ClothSystem#models` takes the stub below rather than a `MeshSystem` for the
+ * reason the field exists: a `MeshSystem` needs a graphics engine, a scene and a
+ * loader, and a garment's joints are a `Node3D` tree that needs none of the
+ * three. The stub answers exactly the one method the system calls.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @typedef {object} GarmentScene
+ * @property {EntityComponentDataset} ecd
+ * @property {ClothSystem} cloth
+ * @property {ClothColliderSystem} colliders
+ * @property {number} entity
+ * @property {Node3D} root the character's own node — what the motion drives
+ * @property {Node3D} pelvis
+ * @property {Node3D[]} bone the character's bones, for drawing
+ * @property {Node3D[]} joint the garment's joints, for drawing
+ * @property {ClothProxy} proxy
+ * @property {number[][]} bind the garment's bind-pose world positions, for drawing
+ */
+export const GARMENT_PRESETS: {
+    id: string;
+    label: string;
+    blurb: string;
+    strips: number;
+    links: number;
+    dynamics: string;
+}[];
+export type GarmentScene = {
+    ecd: EntityComponentDataset;
+    cloth: ClothSystem;
+    colliders: ClothColliderSystem;
+    entity: number;
+    /**
+     * the character's own node — what the motion drives
+     */
+    root: Node3D;
+    pelvis: Node3D;
+    /**
+     * the character's bones, for drawing
+     */
+    bone: Node3D[];
+    /**
+     * the garment's joints, for drawing
+     */
+    joint: Node3D[];
+    proxy: ClothProxy;
+    /**
+     * the garment's bind-pose world positions, for drawing
+     */
+    bind: number[][];
+};
+import { EntityComponentDataset } from "../../../ecs/EntityComponentDataset.js";
+import { ClothSystem } from "../ecs/ClothSystem.js";
+import { ClothColliderSystem } from "../ecs/ClothColliderSystem.js";
+import { Node3D } from "../../../../shade/renderer/scene/Node3D.js";
+//# sourceMappingURL=garment_build.d.ts.map

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

@@ -0,0 +1 @@

+ {"version":3,"file":"garment_build.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/playground/garment_build.js"],"names":[],"mappings":"AA2FA;;;GAGG;AACH,6FAHW,MAAM,GACJ,QAAQ,YAAY,CAAC,CA4EjC;AA8JD;;;;;;GAMG;AACH,8CAHW,MAAM,GACJ,IAAI,CA0BhB;AAhVD;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;;;;;IAqCE;;SAjDY,sBAAsB;WACtB,WAAW;eACX,mBAAmB;YACnB,MAAM;;;;UACN,MAAM;YACN,MAAM;;;;UACN,MAAM,EAAE;;;;WACR,MAAM,EAAE;;;;;UAER,MAAM,EAAE,EAAE;;uCA7Ce,wCAAwC;4BAcnD,uBAAuB;oCAHf,+BAA+B;uBAZ5C,4CAA4C"}

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

@@ -0,0 +1,359 @@
+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 { 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 { Collider } from "../../ecs/Collider.js";
+import { cloth_proxy_from_joints } from "../build/cloth_proxy_from_joints.js";
+import { Cloth } from "../ecs/Cloth.js";
+import { ClothCollider } from "../ecs/ClothCollider.js";
+import { ClothColliderSystem } from "../ecs/ClothColliderSystem.js";
+import { ClothFlags } from "../ecs/ClothFlags.js";
+import { ClothRig } from "../ecs/ClothRig.js";
+import { ClothSystem } from "../ecs/ClothSystem.js";
+import { ClothDynamicsFlags } from "../ecs/ClothDynamicsFlags.js";
+import { CLOTH_DYNAMICS_BY_NAME } from "../ecs/cloth_dynamics_library.js";
+/**
+ * # A rigged character for the M3 page
+ *
+ * A `Node3D` skeleton with a `Skin` over it, a garment built out of some of its
+ * joints, and a real `ClothSystem` driving them — the §11.2 path with nothing
+ * standing in for it except the renderer, which a 2D canvas does not need.
+ *
+ * `ClothSystem#models` takes the stub below rather than a `MeshSystem` for the
+ * reason the field exists: a `MeshSystem` needs a graphics engine, a scene and a
+ * loader, and a garment's joints are a `Node3D` tree that needs none of the
+ * three. The stub answers exactly the one method the system calls.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @typedef {object} GarmentScene
+ * @property {EntityComponentDataset} ecd
+ * @property {ClothSystem} cloth
+ * @property {ClothColliderSystem} colliders
+ * @property {number} entity
+ * @property {Node3D} root the character's own node — what the motion drives
+ * @property {Node3D} pelvis
+ * @property {Node3D[]} bone the character's bones, for drawing
+ * @property {Node3D[]} joint the garment's joints, for drawing
+ * @property {ClothProxy} proxy
+ * @property {number[][]} bind the garment's bind-pose world positions, for drawing
+ */
+export const GARMENT_PRESETS = [
+    {
+        id: 'cape',
+        label: 'cape — 5 strips × 7',
+        blurb: 'The common case, and the cheap one: an artist made the joints and skinned the cape '
+            + 'to them, so the proxy is joint indices, the topology, and the bind pose. No binding '
+            + 'step and no generated geometry.',
+        strips: 5,
+        links: 7,
+        dynamics: 'SILK'
+    },
+    {
+        id: 'coat',
+        label: 'coat tails — 3 strips × 9',
+        blurb: 'Longer and heavier. Denim at 2×2, which is what the library spends its two levers on.',
+        strips: 3,
+        links: 9,
+        dynamics: 'DENIM'
+    },
+    {
+        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.',
+        strips: 1,
+        links: 12,
+        dynamics: 'HAIR'
+    },
+    {
+        id: 'loincloth',
+        label: 'loincloth — 7 strips × 5',
+        blurb: 'Wide and short, hanging from the hips rather than the shoulders — and the one preset '
+            + 'that spends most of its time against the leg colliders.',
+        strips: 7,
+        links: 5,
+        dynamics: 'COTTON'
+    }
+];
+/**
+ * @param {object} options
+ * @returns {Promise<GarmentScene>}
+ */
+export async function build_garment({ preset, dynamics, links, spacing, collide, self_collision }) {
+    const em = new EntityManager();
+    const ecd = new EntityComponentDataset();
+    ecd.setComponentTypeMap([Transform64, TransformAttachment, Cloth, ClothRig, Collider, ClothCollider]);
+    em.addSystem(new TransformAttachmentSystem());
+    const colliders = new ClothColliderSystem();
+    em.addSystem(colliders);
+    const cloth = new ClothSystem();
+    em.addSystem(cloth);
+    em.attachDataset(ecd);
+    await new Promise((resolve, reject) => em.startup(resolve, reject));
+    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, {
+        name: entry.label
+    });
+    if (proxy === null) {
+        throw new Error(error);
+    }
+    const entity = ecd.createEntity();
+    const transform = new Transform64();
+    transform.updateMatrix();
+    ecd.addComponentToEntity(entity, transform);
+    ecd.addComponentToEntity(entity, ClothRig.from(proxy));
+    // The library entry is frozen and shared, so a page that wants to switch
+    // one flag owns a copy — which is the whole of what `.clone()` is for.
+    const fabric = (CLOTH_DYNAMICS_BY_NAME[dynamics] ?? CLOTH_DYNAMICS_BY_NAME[entry.dynamics]).clone();
+    fabric.flags = self_collision
+        ? fabric.flags | ClothDynamicsFlags.SelfCollision
+        : fabric.flags & ~ClothDynamicsFlags.SelfCollision;
+    ecd.addComponentToEntity(entity, Cloth.from(fabric, { flags: ClothFlags.NeverSleep }));
+    cloth.models = { instance_of: () => ({ skins: [skeleton.skin] }) };
+    if (collide) {
+        add_body_colliders(ecd, skeleton);
+    }
+    // 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]
+    ]);
+    return {
+        ecd,
+        cloth,
+        colliders,
+        entity,
+        proxy,
+        bind,
+        ...skeleton
+    };
+}
+/**
+ * A character: pelvis, spine, shoulders, two legs, and the garment's own strips
+ * hanging from whichever bone the preset says.
+ *
+ * @param {object} entry
+ * @param {number} links
+ * @param {number} spacing
+ * @returns {object}
+ * @private
+ */
+function build_skeleton(entry, links, spacing) {
+    /** @type {Node3D[]} */
+    const joints = [];
+    /**
+     * @param {string} name
+     * @param {Node3D|null} parent
+     * @param {number[]} offset
+     * @returns {Node3D}
+     */
+    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);
+        return node;
+    };
+    const root = bone('root', null, [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]);
+    const neck = bone('neck', chest, [0, 0.16, 0]);
+    bone('head', neck, [0, 0.12, 0]);
+    const left_leg = bone('leg_l', pelvis, [-0.1, -0.06, 0]);
+    const right_leg = bone('leg_r', pelvis, [0.1, -0.06, 0]);
+    bone('knee_l', left_leg, [0, -0.42, 0]);
+    bone('knee_r', right_leg, [0, -0.42, 0]);
+    const character = joints.slice();
+    // 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++) {
+        const across = strips === 1 ? 0 : (s / (strips - 1) - 0.5) * 0.34;
+        let parent = from;
+        for (let i = 0; i < links; i++) {
+            const node = bone(
+                `garment_${s}_${i}`,
+                parent,
+                i === 0
+                    // The first link carries the strip sideways and behind, so
+                    // the garment starts as a fan rather than as a bundle.
+                    // Clear of the body colliders, deliberately: §11.3 step 10
+                    // validates that a garment's bind pose is collision-free
+                    // against the character's collider set, and a garment that
+                    // is not reads as a *tether* failure — the contact row
+                    // pushes it out past its own reach and the readout says so.
+                    // M3 does not build that validation, so the scene has to be
+                    // right by hand.
+                    ? [across, -spacing * 0.4, entry.id === 'ponytail' ? -0.09 : -0.21]
+                    : [0, -spacing, -spacing * 0.05]
+            );
+            garment_names.push(node.name);
+            garment.push(node);
+            parent = node;
+        }
+    }
+    root.updateMatrices();
+    return {
+        root,
+        pelvis,
+        bone: character,
+        joint: garment,
+        garment_names,
+        skin: Skin.from({
+            joints,
+            inverse_bind_matrices: new Float32Array(joints.length * 16)
+        })
+    };
+}
+/**
+ * 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`
+ * 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.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {object} skeleton
+ * @private
+ */
+function add_body_colliders(ecd, skeleton) {
+    const by_name = new Map(skeleton.bone.map(node => [node.name, node]));
+    const parts = [
+        { bone: 'spine', shape: CapsuleShape3D.from(0.13, 0.3), offset: [0, 0.1, 0] },
+        { bone: 'pelvis', shape: SphereShape3D.from(0.13), offset: [0, 0, 0] },
+        { bone: 'leg_l', shape: CapsuleShape3D.from(0.08, 0.34), offset: [0, -0.21, 0] },
+        { bone: 'leg_r', shape: CapsuleShape3D.from(0.08, 0.34), offset: [0, -0.21, 0] }
+    ];
+    skeleton.body = [];
+    for (const part of parts) {
+        const node = by_name.get(part.bone);
+        if (node === undefined) {
+            continue;
+        }
+        const entity = ecd.createEntity();
+        const transform = new Transform64();
+        transform.updateMatrix();
+        const collider = new Collider();
+        collider.shape = part.shape;
+        collider.friction = 0.35;
+        ecd.addComponentToEntity(entity, transform);
+        ecd.addComponentToEntity(entity, collider);
+        ecd.addComponentToEntity(entity, ClothCollider.from({ inflation: 0.01 }));
+        skeleton.body.push({ entity, node, transform, offset: part.offset, shape: part.shape });
+    }
+}
+/**
+ * Put every body collider where its bone is. Called once a step, before the
+ * cloth, which is what a rig binding collision capsules to bones would do.
+ *
+ * @param {object} scene
+ * @returns {void}
+ */
+export function garment_sync_colliders(scene) {
+    const body = scene.body;
+    if (body === undefined) {
+        return;
+    }
+    for (const part of body) {
+        const node = part.node;
+        const t = node.transform_global;
+        part.transform.setTranslation(
+            t.translation[0] + part.offset[0],
+            t.translation[1] + part.offset[1],
+            t.translation[2] + part.offset[2]
+        );
+        part.transform.setRotation(
+            t.rotation[0], t.rotation[1], t.rotation[2], t.rotation[3]
+        );
+        part.transform.updateMatrix();
+    }
+}

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

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

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

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