@woosh/meep-engine 3.24.0 → 3.25.0

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

@@ -343,32 +343,27 @@ export class ClothInstance {
      */
     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).
+     * Whether {@link state}'s buffer must be a `SharedArrayBuffer`.
      *
-     * 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}
+     * Set by {@link WorkerClothSystem} when the instance is linked, and read by
+     * `cloth_build_rows` every time the state is built — which is at seed and
+     * again at every re-seed, so a cloth that gains a link or changes a
+     * `ClothDynamics` field the rows depend on comes back shared without
+     * anything having to remember to ask.
+     * @type {boolean}
      */
-    collider_key: Int32Array | null;
+    shared_state: boolean;
     /**
-     * Live records in {@link collider_table}.
-     * @type {number}
+     * `true` once this cloth has said its collider table overflowed.
+     *
+     * M5 moved that table into {@link state}'s buffer — §12's own layout, and
+     * what lets a worker step the cloth without being told about a new array
+     * every time the broadphase returns more. A fixed region has a capacity, and
+     * a cloth that overlaps more colliders than `CLOTH_COLLIDER_SLOTS` drops the
+     * remainder; this is how it says so once rather than once a frame.
+     * @type {boolean}
      */
-    collider_count: number;
+    collider_overflow_reported: boolean;
     /**
      * 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
@@ -414,6 +409,25 @@ export class ClothInstance {
      * @type {boolean}
      */
     refused: boolean;
+    /**
+     * The air at the cloth's centre the last time a step applied it, world-space
+     * metres per second (§10).
+     *
+     * What §7 P5's "wake on a wind change" compares against. It is the last
+     * **applied** air rather than the last sampled one, so a gust that builds
+     * slowly still wakes a sleeping banner instead of being reset by every step
+     * that declined to act on it.
+     * @type {Float64Array}
+     */
+    air_seen: Float64Array;
+    /**
+     * Whether the last step sampled the air per particle rather than once for
+     * the whole cloth — that is, whether a fluid field actually reached it.
+     * Diagnostic, and the one the playground shows: it is the difference
+     * between §10's simulated wake and its ambient fallback.
+     * @type {boolean}
+     */
+    air_varies: 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

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":"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"}
+{"version":3,"file":"ClothInstance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothInstance.js"],"names":[],"mappings":"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"}

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

@@ -391,34 +391,28 @@ export class ClothInstance {
     blend_seen = 1;
 
     /**
-     * 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).
+     * Whether {@link state}'s buffer must be a `SharedArrayBuffer`.
      *
-     * 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 = 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}
+     * Set by {@link WorkerClothSystem} when the instance is linked, and read by
+     * `cloth_build_rows` every time the state is built — which is at seed and
+     * again at every re-seed, so a cloth that gains a link or changes a
+     * `ClothDynamics` field the rows depend on comes back shared without
+     * anything having to remember to ask.
+     * @type {boolean}
      */
-    collider_key = null;
+    shared_state = false;
 
     /**
-     * Live records in {@link collider_table}.
-     * @type {number}
+     * `true` once this cloth has said its collider table overflowed.
+     *
+     * M5 moved that table into {@link state}'s buffer — §12's own layout, and
+     * what lets a worker step the cloth without being told about a new array
+     * every time the broadphase returns more. A fixed region has a capacity, and
+     * a cloth that overlaps more colliders than `CLOTH_COLLIDER_SLOTS` drops the
+     * remainder; this is how it says so once rather than once a frame.
+     * @type {boolean}
      */
-    collider_count = 0;
+    collider_overflow_reported = false;
 
     /**
      * Which particle pairs a self-collision row must never be built on, because
@@ -467,6 +461,27 @@ export class ClothInstance {
      */
     refused = false;
 
+    /**
+     * The air at the cloth's centre the last time a step applied it, world-space
+     * metres per second (§10).
+     *
+     * What §7 P5's "wake on a wind change" compares against. It is the last
+     * **applied** air rather than the last sampled one, so a gust that builds
+     * slowly still wakes a sleeping banner instead of being reset by every step
+     * that declined to act on it.
+     * @type {Float64Array}
+     */
+    air_seen = new Float64Array(3);
+
+    /**
+     * Whether the last step sampled the air per particle rather than once for
+     * the whole cloth — that is, whether a fluid field actually reached it.
+     * Diagnostic, and the one the playground shows: it is the difference
+     * between §10's simulated wake and its ambient fallback.
+     * @type {boolean}
+     */
+    air_varies = false;
+
     /**
      * 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

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

@@ -0,0 +1,84 @@
+/**
+ * # Binary serialization for {@link Cloth}
+ *
+ * The component is authoring data and nothing else, so the whole of it is
+ * written: the {@link ClothDynamics} value object inline, then `blend`, `layer`,
+ * `mask` and `flags`. There is no transient field to exclude — the live binding
+ * between a component and a simulation is a {@link ClothInstance} owned by
+ * `ClothWorld`, and everything world-tied lives over there: the seeded topology,
+ * the `ClothState` buffer, and `blend_seen`, which is what the write-back last
+ * saw rather than what the author asked for. All of it is rebuilt on link, the
+ * same division `RigidBodySerializationAdapter` makes against `_bodyId`.
+ *
+ * ## The dynamics are written **by value**, and that is not the `Collider#shape`
+ * case
+ *
+ * §3.2 sets out the convention for a component pointing at a built, shared,
+ * immutable asset — `Collider#shape`, `ParticleEffect`'s layout and program,
+ * `ClothRig#proxy` — which is that the reference is *not* in the stream and the
+ * asset pipeline wires it up, because what has to be restored is the asset's
+ * **identity**. A `ClothDynamics` is not that. §3.3's library is "a set of
+ * points rather than a mechanism": an entry is frozen and shared as an
+ * allocation optimisation, not because anything downstream refers to it by
+ * name, and a cloth built from `CLOTH_SILK.clone()` with one field moved has no
+ * identity to restore at all. Ten scalars are 68 bytes; an identity story for
+ * them would cost more than the bytes and would have to invent a name for every
+ * `clone()`. So the values go in the stream and a loaded cloth is equal to the
+ * saved one under {@link Cloth#equals}, which compares dynamics field-wise.
+ *
+ * ## Deserialize replaces the dynamics rather than writing into them
+ *
+ * Library entries are frozen and the engine is modules, so writing a field on
+ * one **throws** (`ClothDynamics.spec.js` pins that). Deserializing in place
+ * into a `Cloth` that holds `CLOTH_ROPE` — a reset-to-snapshot restore over a
+ * live scene, not a hypothetical — would be exactly that write. So the adapter
+ * builds a fresh instance and hands it over, which is also what
+ * {@link Cloth#fromJSON} does and for the same reason. The two codecs agreeing
+ * on it matters beyond the throw: a scene that round-trips as JSON and a scene
+ * that round-trips as binary must not disagree about whether the loaded cloth
+ * shares its dynamics with anything.
+ *
+ * ## `layer` and `mask` are read back unsigned, unlike the `RigidBody` pair
+ *
+ * `RigidBodySerializationAdapter` normalises those two fields with `| 0`,
+ * because a `RigidBody`'s default mask is the signed `0xFFFFFFFF | 0 === -1`
+ * and reading the raw unsigned value would make a round-tripped body compare
+ * unequal to a fresh one. `Cloth`'s default is the **unsigned** `0xFFFFFFFF`,
+ * and `Cloth.from` asserts `isNonNegativeInteger` on it, so here the same `| 0`
+ * would be the bug rather than the fix: it would hand back a `-1` that fails
+ * the component's own stated contract and compares unequal under
+ * {@link Cloth#equals}. `readUint32` already returns the unsigned value, so the
+ * correct code is the code with nothing in it — which is precisely why this
+ * paragraph exists, since the surrounding adapters all carry the opposite
+ * normalisation and it reads like an omission.
+ *
+ * ## Version 0, and no upgrader
+ *
+ * `RigidBodySerializationUpgrader_0_1` exists because a v0 stream had already
+ * shipped when the sleep fields were added; a first version has no predecessor
+ * stream to upgrade from. Adding a field here is a bump to 1 plus an upgrader
+ * that writes that field's pre-upgrade default, and the exact-size assertion in
+ * the spec is what makes forgetting the bump fail rather than corrupt.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof Cloth;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Cloth} value
+     */
+    serialize(buffer: BinaryBuffer, value: Cloth): void;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Cloth} value
+     */
+    deserialize(buffer: BinaryBuffer, value: Cloth): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { Cloth } from "./Cloth.js";
+//# sourceMappingURL=ClothSerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ClothSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothSerializationAdapter.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH;;IAEI,oBAAc;IAGd;;;;OAIG;IACH,uCAFW,KAAK,QA2Bf;IAED;;;;OAIG;IACH,yCAFW,KAAK,QA8Bf;CACJ;gDA5I+C,gEAAgE;sBAC1F,YAAY"}

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

@@ -0,0 +1,141 @@
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { Cloth } from "./Cloth.js";
+import { ClothDynamics } from "./ClothDynamics.js";
+
+/**
+ * # Binary serialization for {@link Cloth}
+ *
+ * The component is authoring data and nothing else, so the whole of it is
+ * written: the {@link ClothDynamics} value object inline, then `blend`, `layer`,
+ * `mask` and `flags`. There is no transient field to exclude — the live binding
+ * between a component and a simulation is a {@link ClothInstance} owned by
+ * `ClothWorld`, and everything world-tied lives over there: the seeded topology,
+ * the `ClothState` buffer, and `blend_seen`, which is what the write-back last
+ * saw rather than what the author asked for. All of it is rebuilt on link, the
+ * same division `RigidBodySerializationAdapter` makes against `_bodyId`.
+ *
+ * ## The dynamics are written **by value**, and that is not the `Collider#shape`
+ * case
+ *
+ * §3.2 sets out the convention for a component pointing at a built, shared,
+ * immutable asset — `Collider#shape`, `ParticleEffect`'s layout and program,
+ * `ClothRig#proxy` — which is that the reference is *not* in the stream and the
+ * asset pipeline wires it up, because what has to be restored is the asset's
+ * **identity**. A `ClothDynamics` is not that. §3.3's library is "a set of
+ * points rather than a mechanism": an entry is frozen and shared as an
+ * allocation optimisation, not because anything downstream refers to it by
+ * name, and a cloth built from `CLOTH_SILK.clone()` with one field moved has no
+ * identity to restore at all. Ten scalars are 68 bytes; an identity story for
+ * them would cost more than the bytes and would have to invent a name for every
+ * `clone()`. So the values go in the stream and a loaded cloth is equal to the
+ * saved one under {@link Cloth#equals}, which compares dynamics field-wise.
+ *
+ * ## Deserialize replaces the dynamics rather than writing into them
+ *
+ * Library entries are frozen and the engine is modules, so writing a field on
+ * one **throws** (`ClothDynamics.spec.js` pins that). Deserializing in place
+ * into a `Cloth` that holds `CLOTH_ROPE` — a reset-to-snapshot restore over a
+ * live scene, not a hypothetical — would be exactly that write. So the adapter
+ * builds a fresh instance and hands it over, which is also what
+ * {@link Cloth#fromJSON} does and for the same reason. The two codecs agreeing
+ * on it matters beyond the throw: a scene that round-trips as JSON and a scene
+ * that round-trips as binary must not disagree about whether the loaded cloth
+ * shares its dynamics with anything.
+ *
+ * ## `layer` and `mask` are read back unsigned, unlike the `RigidBody` pair
+ *
+ * `RigidBodySerializationAdapter` normalises those two fields with `| 0`,
+ * because a `RigidBody`'s default mask is the signed `0xFFFFFFFF | 0 === -1`
+ * and reading the raw unsigned value would make a round-tripped body compare
+ * unequal to a fresh one. `Cloth`'s default is the **unsigned** `0xFFFFFFFF`,
+ * and `Cloth.from` asserts `isNonNegativeInteger` on it, so here the same `| 0`
+ * would be the bug rather than the fix: it would hand back a `-1` that fails
+ * the component's own stated contract and compares unequal under
+ * {@link Cloth#equals}. `readUint32` already returns the unsigned value, so the
+ * correct code is the code with nothing in it — which is precisely why this
+ * paragraph exists, since the surrounding adapters all carry the opposite
+ * normalisation and it reads like an omission.
+ *
+ * ## Version 0, and no upgrader
+ *
+ * `RigidBodySerializationUpgrader_0_1` exists because a v0 stream had already
+ * shipped when the sleep fields were added; a first version has no predecessor
+ * stream to upgrade from. Adding a field here is a bump to 1 plus an upgrader
+ * that writes that field's pre-upgrade default, and the exact-size assertion in
+ * the spec is what makes forgetting the bump fail rather than corrupt.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = Cloth;
+    version = 0;
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Cloth} value
+     */
+    serialize(buffer, value) {
+        const dynamics = value.dynamics;
+
+        buffer.writeFloat64(dynamics.stretch);
+        buffer.writeFloat64(dynamics.bend);
+        buffer.writeFloat64(dynamics.damping);
+        buffer.writeFloat64(dynamics.slack);
+        buffer.writeFloat64(dynamics.thickness);
+        buffer.writeFloat64(dynamics.inertia);
+        buffer.writeFloat64(dynamics.drag);
+
+        // A budget, not an enum: `assert.isPositiveInteger` is the whole of the
+        // component's contract on these two, so a u8 would be a silent clamp on
+        // a value the component considers legal. Four bytes each buys the
+        // absence of that.
+        buffer.writeUint32(dynamics.substeps);
+        buffer.writeUint32(dynamics.iterations);
+
+        buffer.writeUint32(dynamics.flags >>> 0);
+
+        buffer.writeFloat64(value.blend);
+
+        buffer.writeUint32(value.layer >>> 0);
+        buffer.writeUint32(value.mask >>> 0);
+        buffer.writeUint32(value.flags >>> 0);
+    }
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Cloth} value
+     */
+    deserialize(buffer, value) {
+        // Fresh rather than in place: the target may hold a frozen library
+        // entry, and a loaded cloth always owns its dynamics — see the class
+        // docblock and Cloth#fromJSON.
+        const dynamics = new ClothDynamics();
+
+        dynamics.stretch = buffer.readFloat64();
+        dynamics.bend = buffer.readFloat64();
+        dynamics.damping = buffer.readFloat64();
+        dynamics.slack = buffer.readFloat64();
+        dynamics.thickness = buffer.readFloat64();
+        dynamics.inertia = buffer.readFloat64();
+        dynamics.drag = buffer.readFloat64();
+
+        dynamics.substeps = buffer.readUint32();
+        dynamics.iterations = buffer.readUint32();
+
+        dynamics.flags = buffer.readUint32();
+
+        value.dynamics = dynamics;
+
+        value.blend = buffer.readFloat64();
+
+        // Unsigned, deliberately — the `| 0` the RigidBody adapter applies
+        // would break this component's non-negative contract. Class docblock.
+        value.layer = buffer.readUint32();
+        value.mask = buffer.readUint32();
+        value.flags = buffer.readUint32();
+    }
+}

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

@@ -1,12 +1,16 @@
 /**
- * # The system — gather, step, write back
+ * # The system — gather, step, write back, all on this thread
  *
- * One {@link ClothInstance} per {@link Cloth} component, stepped at the fixed
- * rate. Per step, per cloth: move the local frame with the anchor, point the
- * leash rows at where they measure from, step, and put the result back on the
- * subtree. The animated pose the leashes are measured against is not recomposed
- * per step — in the entity path it is constant in the anchor's own frame, and
- * `cloth_seed_subtree.js` bakes it.
+ * Every cloth in the scene stepped inline at the fixed rate. The work itself
+ * lives in {@link ClothWorld}, which this shares with {@link WorkerClothSystem}
+ * so that §12's "`ClothSystem` and `WorkerClothSystem` must produce bit-identical
+ * results" is a property of there being one copy rather than of two copies
+ * agreeing. What is left here is a `System`'s own surface — what it depends on,
+ * what it accesses, and the loop.
+ *
+ * This is the fallback where `SharedArrayBuffer` is unavailable, and it is **not
+ * a degraded mode**: it is the same solver over the same data in the same
+ * order, and the only thing the worker buys is which thread pays for it.
  *
  * ## Where in the frame this runs
  *
@@ -37,29 +41,6 @@
  * it before `TransformAttachmentSystem`, which is right: cloth writes the local
  * transforms and the attachment system is their reader.
  *
- * ## The local frame and the inertia model — §7 P7
- *
- * Particles live in the anchor's own frame. When the anchor moves, the cloth is
- * asked how much of that motion it would like to feel:
- * `ClothDynamics#inertia = 1` keeps every particle's **world** position and
- * velocity, so a cape trails a sprinting character; `0` keeps their **local**
- * ones, so the cloth rides the anchor as though it were standing still. The
- * blend between the two is a lerp in the local frame, which is all the frame
- * change is.
- *
- * The felt motion is limited before the blend, which is what makes "character
- * sprints, cape behaves" a default rather than a tuning exercise, and the limits
- * are derived from the cloth's own reach rather than authored.
- *
- * ## Teleport — §7 P6
- *
- * Anchor motion past a threshold is not locomotion and is not treated as any
- * amount of it. `ClothFlags.TeleportKeep` carries the shape across, which in a
- * local frame is literally doing nothing; the default re-seeds at the animated
- * pose with zero velocity and opens a stabilisation window in which the
- * velocity limit ramps back from nothing, so the first steps after a reset
- * cannot produce a whip.
- *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -68,59 +49,58 @@ export class ClothSystem extends System<any> {
     dependencies: (typeof Transform64 | typeof Cloth)[];
     components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof ClothCollider> | ResourceAccessSpecification<typeof Cloth> | ResourceAccessSpecification<typeof ClothExclude> | ResourceAccessSpecification<typeof ClothRig>)[];
     /**
-     * World gravity, m/s². Rotated into each cloth's local frame per step.
+     * @type {ClothWorld}
+     */
+    world: ClothWorld;
+    /**
+     * One cloth's step parameters, reused for every cloth in turn because the
+     * step follows immediately.
+     *
+     * The same block {@link WorkerClothSystem} writes into the shared command
+     * region — one layout, written by one function, so the inline path and the
+     * worker path cannot be handed different numbers.
      * @type {Float64Array}
+     * @private
      */
-    gravity: Float64Array;
+    private __params;
     /**
-     * Live cloths, ordered so that an instance whose anchor sits inside another
-     * instance's subtree steps after it.
-     * @type {ClothInstance[]}
+     * @param {Float64Array} value
      */
-    instances: ClothInstance[];
+    set gravity(value: Float64Array);
     /**
-     * @type {Map<number, ClothInstance>}
-     * @private
+     * World gravity, m/s². Rotated into each cloth's local frame per step.
+     * @returns {Float64Array}
      */
-    private __by_entity;
+    get gravity(): Float64Array;
     /**
-     * @type {TransformAttachmentSystem|null}
-     * @private
+     * @param {AbstractClothWind|null} value
      */
-    private __attachments;
+    set wind(value: any);
     /**
-     * Where a skinned model instance comes from. Anything that answers
-     * `instance_of(entity)` with a `PrefabInstance` — skins whose joints
-     * are entities — will do, and {@link MeshSystem} is what does in a
-     * running engine.
-     *
-     * Public and assignable because a garment's joints are a *rendering*
-     * structure and `MeshSystem` needs a graphics engine, a scene and a loader
-     * to exist — so a spec that wants joints without a renderer sets this
-     * instead, and gets exactly the interface the system uses.
-     *
-     * `null` means no rig can seed, which is the same additive shape the
-     * collider index has: a scene without one gets M1's cloth rather than an
-     * error.
-     * @type {{instance_of: function(number): (PrefabInstance|null)}|null}
+     * Where the air comes from — see {@link ClothWorld#wind}. `null` by default,
+     * which is a scene with no wind in it.
+     * @returns {AbstractClothWind|null}
      */
-    models: {
-        instance_of: (arg0: number) => (PrefabInstance | null);
-    } | null;
+    get wind(): any;
     /**
-     * The collider index's owner, or `null` when the manager has none — in
-     * which case cloth simply does not collide, which is exactly M1's
-     * behaviour and is what makes the collision layer additive rather than a
-     * new requirement on every scene.
-     * @type {ClothColliderSystem|null}
-     * @private
+     * Live cloths, ordered so that an instance whose anchor sits inside another
+     * instance's subtree steps after it.
+     * @returns {ClothInstance[]}
      */
-    private __colliders;
+    get instances(): ClothInstance[];
     /**
-     * @type {boolean}
-     * @private
+     * @param {{instance_of: function(number): (PrefabInstance|null)}|null} value
      */
-    private __order_dirty;
+    set models(value: {
+        instance_of: (arg0: number) => (PrefabInstance | null);
+    });
+    /**
+     * Where a skinned model instance comes from — see {@link ClothWorld#models}.
+     * @returns {{instance_of: function(number): (PrefabInstance|null)}|null}
+     */
+    get models(): {
+        instance_of: (arg0: number) => (PrefabInstance | null);
+    };
     /**
      * @param {EntityManager} entityManager
      * @returns {Promise<void>}
@@ -140,22 +120,12 @@ export class ClothSystem extends System<any> {
     unlink(cloth: Cloth, transform: Transform64, entity: number): void;
     /**
      * Throw away a cloth's binding so the next step walks its subtree again.
-     *
-     * The walk is done once, because a rope's links do not come and go. When
-     * they do — a chain gains a link, a rig is rebuilt — this is how you say so,
-     * and it is the same contract `TransformAttachment#parent` already carries:
-     * the structure is immutable while it is attached, and changing it is an
-     * explicit act rather than something the engine polls for.
-     *
      * @param {number} entity
      * @returns {void}
      */
     reseed(entity: number): void;
     /**
-     * Wake a sleeping cloth. Anchor motion and a `ClothDynamics` change do this
-     * on their own; a caller that has changed the world in some way the cloth
-     * cannot see — M6's wind, for one — says so here.
-     *
+     * Wake a sleeping cloth.
      * @param {number} entity
      * @returns {void}
      */
@@ -165,7 +135,6 @@ export class ClothSystem extends System<any> {
      * @returns {ClothInstance|undefined}
      */
     instanceOf(entity: number): ClothInstance | undefined;
-    #private;
 }
 import { System } from "../../../ecs/System.js";
 import { Transform64 } from "../../../ecs/transform/Transform64.js";
@@ -175,5 +144,5 @@ import { TransformAttachment } from "../../../ecs/transform-attachment/Transform
 import { ClothCollider } from "./ClothCollider.js";
 import { ClothExclude } from "./ClothExclude.js";
 import { ClothRig } from "./ClothRig.js";
-import { ClothInstance } from "./ClothInstance.js";
+import { ClothWorld } from "./ClothWorld.js";
 //# sourceMappingURL=ClothSystem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ClothSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothSystem.js"],"names":[],"mappings":"AA4DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH;;IAEI,oDAAoC;IAEpC,iUAOE;IAEF;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;OAIG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;;OAGG;IACH,oBAAwB;IAExB;;;OAGG;IACH,sBAAqB;IAErB;;;;;;;;;;;;;;;OAeG;IACH,QAFU;QAAC,WAAW,SAAW,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC,CAAA;KAAC,GAAC,IAAI,CAEvD;IAEd;;;;;;;OAOG;IACH,oBAAmB;IAEnB;;;OAGG;IACH,sBAAsB;IAEtB;;;OAGG;IACH,uCAFa,QAAQ,IAAI,CAAC,CAiBzB;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAahB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAgBhB;IAED;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,IAAI,CAahB;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;;CAibJ;uBA3tBsB,wBAAwB;4BAWxC,uCAAuC;sBAUxB,YAAY;4CAtBU,uDAAuD;oCAI5F,0DAA0D;8BAmBnC,oBAAoB;6BAErB,mBAAmB;yBAIvB,eAAe;8BADV,oBAAoB"}
+{"version":3,"file":"ClothSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothSystem.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;;IAEI,oDAAoC;IAEpC,iUAOE;IAEF;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;;;OASG;IACH,iBAAqD;IAUrD;;OAEG;IACH,iCAEC;IAbD;;;OAGG;IACH,4BAEC;IAkBD;;OAEG;IACH,qBAEC;IAdD;;;;OAIG;IACH,gBAEC;IASD;;;;OAIG;IACH,iCAEC;IAUD;;OAEG;IACH;4BAToC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;OAWjE;IAbD;;;OAGG;IACH;4BAFoC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;MAIjE;IASD;;;OAGG;IACH,uCAFa,QAAQ,IAAI,CAAC,CAIzB;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,gBAAc,SAAS,CAInC;CAoCJ;uBArOsB,wBAAwB;4BAInB,uCAAuC;sBAE7C,YAAY;4CAPU,uDAAuD;oCAI5F,0DAA0D;8BAInC,oBAAoB;6BACrB,mBAAmB;yBACvB,eAAe;2BACb,iBAAiB"}