@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -1,57 +1,66 @@
-/**
- * Boolean switches on {@link ClothDynamics} — the things that are on or off
- * rather than more or less.
- *
- * A flag lives here rather than as a field because it has no middle: a garment
- * either collides with itself or it does not, and "0.5 of self-collision" is
- * not a state the solver can be in. Everything with a middle is a normalised
- * field in `[0, 1]` instead.
- *
- * @readonly
- * @enum {number}
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export const ClothDynamicsFlags = {
-    None: 0,
-
-    /**
-     * Particles of this cloth collide with each other (§9). Off by default and
-     * set only on the library entries that need it — skirts, long coats, hair —
-     * because it is the most expensive part of every cloth system that has one
-     * and none of §7's guarantees depend on it.
-     *
-     * **M4 implements it.** Set on a library entry before then and it is simply
-     * not read, which is deliberate: the entry says what the fabric *is*, and
-     * the milestone that can honour it does.
-     */
-    SelfCollision: 1,
-
-    /**
-     * Build the strain-limit row of §6 alongside each stretch row: a second
-     * hard, one-sided row on the same edge at `L₀·(1 + ε)`, where `ε` is what
-     * {@link ClothDynamics#stretch} maps to.
-     *
-     * It exists because a hard stretch row is only hard *at convergence*, and
-     * M1's library ships low iteration counts to stay inside the performance
-     * budget — where a hard row still carries several per cent of residual
-     * strain (`MEASUREMENTS.md` §6). The strain-limit row is the bound on that
-     * residual, and it is what makes `stretch` an observable property of a
-     * fabric at a low budget rather than a property of the budget.
-     *
-     * Off where measurement says the tether already carries it — see
-     * `cloth_dynamics_library.js` for which entries set it and why.
-     */
-    StrainLimit: 2,
-
-    /**
-     * A teleport re-seeds the cloth at its animated pose with zero velocity
-     * (§7 P6). This flag is *not* here — it is on {@link ClothFlags}, because
-     * teleport behaviour is a property of the thing being simulated rather
-     * than of the fabric it is made of. Named in this comment only so that a
-     * reader looking for it here finds where it went.
-     */
-};
-
-Object.freeze(ClothDynamicsFlags);
+/**
+ * Boolean switches on {@link ClothDynamics} — the things that are on or off
+ * rather than more or less.
+ *
+ * A flag lives here rather than as a field because it has no middle: a garment
+ * either collides with itself or it does not, and "0.5 of self-collision" is
+ * not a state the solver can be in. Everything with a middle is a normalised
+ * field in `[0, 1]` instead.
+ *
+ * @readonly
+ * @enum {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const ClothDynamicsFlags = {
+    None: 0,
+
+    /**
+     * Particles of this cloth collide with each other (§9). Off by default,
+     * because it is the most expensive part of every cloth system that has one
+     * and none of §7's guarantees depend on it.
+     *
+     * **M4 implements it, and measured which entries want it.** This comment
+     * used to say "skirts, long coats, hair" — a list of what the garment *is*.
+     * What decides is how far the fabric bends. A floppy fabric passes through
+     * itself 8 to 11 times a sample on a folding sheet and the row removes 71%
+     * to 81% of that; leather, at the top of the bend scale, does not tangle at
+     * all and the row makes it marginally *worse*. `CLOTH_SILK`, `CLOTH_COTTON`
+     * and `CLOTH_HAIR` set it; nothing else does. `MEASUREMENTS.md` §33.
+     *
+     * What it buys is **fewer crossings while the cloth moves**, not a cleaner
+     * cloth at rest: a sheet that settles takes its tangles out with it either
+     * way. And it is one tier of two — `MEASUREMENTS.md` §32 measures the limit
+     * §9 states, that a particle-particle row cannot see cloth passing *between*
+     * particles.
+     */
+    SelfCollision: 1,
+
+    /**
+     * Build the strain-limit row of §6 alongside each stretch row: a second
+     * hard, one-sided row on the same edge at `L₀·(1 + ε)`, where `ε` is what
+     * {@link ClothDynamics#stretch} maps to.
+     *
+     * It exists because a hard stretch row is only hard *at convergence*, and
+     * M1's library ships low iteration counts to stay inside the performance
+     * budget — where a hard row still carries several per cent of residual
+     * strain (`MEASUREMENTS.md` §6). The strain-limit row is the bound on that
+     * residual, and it is what makes `stretch` an observable property of a
+     * fabric at a low budget rather than a property of the budget.
+     *
+     * Off where measurement says the tether already carries it — see
+     * `cloth_dynamics_library.js` for which entries set it and why.
+     */
+    StrainLimit: 2,
+
+    /**
+     * A teleport re-seeds the cloth at its animated pose with zero velocity
+     * (§7 P6). This flag is *not* here — it is on {@link ClothFlags}, because
+     * teleport behaviour is a property of the thing being simulated rather
+     * than of the fabric it is made of. Named in this comment only so that a
+     * reader looking for it here finds where it went.
+     */
+};
+
+Object.freeze(ClothDynamicsFlags);

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

@@ -79,12 +79,47 @@ export class ClothInstance {
      * @type {Int32Array|null}
      */
     node_parent: Int32Array | null;
+    /**
+     * The {@link ClothRig} beside the {@link Cloth}, or `null` for a cloth that
+     * simulates its own entity subtree.
+     *
+     * This is the discriminator, and it is a component's presence rather than
+     * an enum (§3.1). Held here rather than looked up per step because it is
+     * what says which seeder ran and therefore which of the two sets of arrays
+     * below is the live one.
+     * @type {ClothRig|null}
+     */
+    rig: ClothRig | null;
     /**
      * Live `Transform64` per node — the component instance, held so the step
-     * does not go through the dataset per node per frame.
+     * does not go through the dataset per node per frame. **Entity path only.**
      * @type {Transform64[]}
      */
     node_transform: Transform64[];
+    /**
+     * Live `Node3D` per node — the joint each node drives. **Rig path only**,
+     * and node 0 is the anchor joint, which is not simulated.
+     *
+     * A joint rather than an entity because a skinned model's joints are not
+     * entities and will not be (D47): they are `Node3D`s inside the entity's
+     * `SceneBundleInstance`, and the only writable handle is
+     * `Node3D.transform_local`.
+     * @type {Node3D[]}
+     */
+    node_joint: Node3D[];
+    /**
+     * The anchor joint's **world** pose, evaluated on the CPU each step from the
+     * clips the entity is playing. **Rig path only.**
+     *
+     * Evaluated rather than read: a joint of an animated skeleton is under
+     * `TransformAuthority.GPU`, so its own `transform_global` is not maintained
+     * on the CPU at all and reading it would place the garment wherever the node
+     * was last posed by hand. `pose_evaluate_world` is the sanctioned answer and
+     * the one a socket on the same skeleton gets, which is what keeps a cape on
+     * the shoulder a scabbard hangs from.
+     * @type {Transform64}
+     */
+    anchor_pose: Transform64;
     /**
      * Live `TransformAttachment` per node; `null` for the anchor.
      *
@@ -309,6 +344,78 @@ export class ClothInstance {
      * @type {number}
      */
     blend_seen: number;
+    /**
+     * The colliders overlapping this cloth this step, packed in **its own
+     * frame** rather than the world's — the same layout `ClothColliderIndex`
+     * uses, in `Float32` rather than `Float64` because a cloth-local coordinate
+     * is garment-sized (§12).
+     *
+     * Grown, never shrunk, and rewritten every step by
+     * `cloth_gather_colliders`. It lives on the instance rather than inside
+     * {@link state}'s buffer because its size is a property of the *world* — how
+     * many colliders happen to be near this cloth right now — and `ClothState`'s
+     * one allocation is sized from the cloth. §12 puts it in the shared buffer
+     * when M5 needs it there.
+     * @type {Float32Array|null}
+     */
+    collider_table: Float32Array | null;
+    /**
+     * The index handle behind each record in {@link collider_table}. A record
+     * index is this step's; a handle is the collider's, and it is what a
+     * transient contact's multiplier is warm-started on.
+     * @type {Int32Array|null}
+     */
+    collider_key: Int32Array | null;
+    /**
+     * Live records in {@link collider_table}.
+     * @type {number}
+     */
+    collider_count: number;
+    /**
+     * Which particle pairs a self-collision row must never be built on, because
+     * a persistent row already governs them (§9). CSR, sorted, built at seed and
+     * replaced by a re-seed — it depends only on the row tables, so nothing about
+     * a `ClothDynamics` change can invalidate it short of the rows themselves
+     * changing, and those changes all go through `cloth_build_rows`.
+     * @type {{offset: Int32Array, partner: Int32Array}|null}
+     */
+    self_exclusions: {
+        offset: Int32Array;
+        partner: Int32Array;
+    } | null;
+    /**
+     * How close two particles get in the **bind pose** with no row between them,
+     * metres — or `Infinity` when nothing is within reach of anything.
+     *
+     * The ceiling on a self-collision row's radius, and the reason it is a
+     * measured length rather than a multiple of {@link shortest_row}: on a
+     * triangulated sheet the two agree, and on a rigged garment — strips with
+     * nothing joining one to the next — they do not agree at all.
+     * `CLOTH_SELF_RADIUS_MAX_RATIO` and `MEASUREMENTS.md` §37.
+     * @type {number}
+     */
+    closest_free_pair: number;
+    /**
+     * Self-collision pairs the last step found. Diagnostic, and the one to
+     * watch: a garment pinned at `CLOTH_SELF_PAIRS_PER_PARTICLE` per particle is
+     * one whose pairs are being dropped.
+     * @type {number}
+     */
+    self_pairs: number;
+    /**
+     * Contact rows the last step created. Diagnostic — a garment whose contact
+     * count is pinned at four per particle is one whose collider set has more
+     * overlap than `CLOTH_CONTACT_SLOTS` can express.
+     * @type {number}
+     */
+    contact_count: number;
+    /**
+     * `true` once the system has said why this cloth will not seed and stopped
+     * asking. A proxy that does not fit its skin will not start fitting it, and a
+     * warning a frame is a log nobody reads.
+     * @type {boolean}
+     */
+    refused: boolean;
     /**
      * How many times this cloth has been re-seeded by a teleport. Diagnostic:
      * a cloth resetting every few seconds is being driven by something that
@@ -317,5 +424,6 @@ export class ClothInstance {
      */
     teleport_count: number;
 }
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
 import { ClothDynamics } from "./ClothDynamics.js";
 //# sourceMappingURL=ClothInstance.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ClothInstance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothInstance.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAEI;;;OAGG;IACH,QAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,OAFU,QAAM,IAAI,CAEP;IAEb;;;OAGG;IACH,WAFU,cAAY,IAAI,CAET;IAEjB;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,QAFU,OAAO,CAEF;IAEf;;OAEG;IACH,OAFU,aAAW,IAAI,CAEZ;IAEb;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,aAFU,UAAU,GAAC,IAAI,CAEN;IAEnB;;;OAGG;IACH,aAFU,UAAU,GAAC,IAAI,CAEN;IAEnB;;;;OAIG;IACH,gBAFU,aAAa,CAEH;IAEpB;;;;;;;;;;;OAWG;IACH,iBAFU,qBAAqB,CAEV;IAErB;;;;OAIG;IACH,qBAFU,YAAY,GAAC,IAAI,CAEA;IAE3B;;;OAGG;IACH,qBAFU,YAAY,GAAC,IAAI,CAEA;IAE3B;;;OAGG;IACH,mBAFU,UAAU,GAAC,IAAI,CAEA;IAEzB;;;OAGG;IACH,YAFU,UAAU,GAAC,IAAI,CAEP;IAElB;;;;;;;;;OASG;IACH,eAFU,UAAU,GAAC,IAAI,CAEJ;IAErB;;;OAGG;IACH,eAFU,UAAU,GAAC,IAAI,CAEJ;IAErB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,kBAFU,aAAa,CAED;IAEtB;;;;OAIG;IACH,mBAFU,qBAAqB,CAER;IAEvB;;;OAGG;IACH,kBAFU,UAAU,GAAC,IAAI,CAED;IAExB;;;;;;;;OAQG;IACH,UAFU,YAAY,GAAC,IAAI,CAEX;IAEhB;;;;;;;;;;;OAWG;IACH,mBAFU,YAAY,GAAC,IAAI,CAEF;IAEzB;;;OAGG;IACH,mBAFU,YAAY,GAAC,IAAI,CAEF;IAEzB;;;;;;;;;;OAUG;IACH,kBAFU,YAAY,GAAC,IAAI,CAEH;IAExB;;;;;;;;;OASG;IACH,kBAFU,YAAY,GAAC,IAAI,CAEH;IAExB;;;;;OAKG;IACH,WAFU,UAAU,GAAC,IAAI,CAER;IAEjB;;;OAGG;IACH,YAFU,UAAU,GAAC,IAAI,CAEP;IAElB;;;OAGG;IACH,UAFU,UAAU,GAAC,IAAI,CAET;IAEhB;;;OAGG;IACH,YAFU,UAAU,GAAC,IAAI,CAEP;IAElB;;;;OAIG;IACH,UAFU,UAAU,GAAC,IAAI,CAET;IAEhB;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;;OASG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,oBAFU,YAAY,CAEmB;IAEzC;;;OAGG;IACH,iBAFU,YAAY,CAE2B;IAEjD;;;;;OAKG;IACH,cAFU,OAAO,CAEI;IAErB;;;;;OAKG;IACH,eAFU,aAAa,CAEa;IAEpC;;;;;OAKG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;;;;OAQG;IACH,QAFU,OAAO,CAEF;IAEf;;;;;;;;OAQG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,gBAFU,MAAM,CAEG;CACtB;8BA1W6B,oBAAoB"}
+{"version":3,"file":"ClothInstance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothInstance.js"],"names":[],"mappings":"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"}