@woosh/meep-engine 3.24.0 → 3.26.0

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

@@ -46,13 +46,6 @@ export class ClothInstance {
      * @type {Transform64|null}
      */
     transform: Transform64 | null;
-    /**
-     * How deep the anchor sits in the transform hierarchy. Instances step in
-     * ascending depth so that a `Cloth` nested inside another one reads an
-     * anchor the outer solve has already written this step.
-     * @type {number}
-     */
-    depth: number;
     /**
      * `false` until the subtree has been walked. Seeding is deferred to the
      * first step rather than done at link, because a rope's links arrive as
@@ -343,32 +336,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 +402,90 @@ 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;
+    /**
+     * Seconds of fixed step **this instance** has taken, which is the clock
+     * §10's gust is a function of.
+     *
+     * Per cloth rather than per world, and the difference only shows with more
+     * than one of them. A cloth registered with the worker while another is
+     * already running waits for its memory, and the world's clock moves during
+     * that wait because the other cloth is still being advanced — so the two
+     * systems reach *this* cloth's first step at different world times and hand
+     * it different weather. An age counted in its own steps is the same number
+     * on both sides by construction. `MEASUREMENTS.md` §57.
+     *
+     * Advanced on every step the instance is *offered*, including ones it
+     * sleeps through, because a sleeping cloth still has to be able to ask
+     * whether the air has changed enough to wake it.
+     * @type {number}
+     */
+    age: number;
+    /**
+     * The index handles this cloth last **stepped against**, in the order the
+     * broadphase returned them, and how many of them are meaningful.
+     *
+     * §7 P5's wake test compares each overlapping collider's previous pose with
+     * its current one, and `ClothColliderSystem#link` *places* a new collider —
+     * previous equals current — so a collider spawned around a sleeping cloth
+     * is one that has not moved and never woke it. The set is the other half of
+     * that question: a handle appearing or leaving is a change to the world the
+     * cloth went to sleep in, whatever the poses say.
+     * @type {Int32Array}
+     */
+    collider_keys: Int32Array;
+    /**
+     * @type {number}
+     */
+    collider_key_count: number;
+    /**
+     * The broadphase margin the last gather used, metres. The wake test has to
+     * query with the same one, or it compares a set built under one reach with
+     * a set built under another and wakes on the difference between the two
+     * questions rather than on a change in the world.
+     * @type {number}
+     */
+    gather_reach: number;
+    /**
+     * The joint entities this cloth's rig seeding took `TransformAttachment`
+     * authority from, so that removing the cloth can give it back. `null` on
+     * the entity path and before the first rig seeding.
+     *
+     * Only the ones the revoke actually changed: a joint that was already the
+     * CPU's is not one cloth has anything to hand back.
+     * @type {number[]|null}
+     */
+    revoked_joints: number[] | null;
+    /**
+     * Where every particle was when the current sleep window opened, or `null`
+     * before the first step — §7 P5's sleep test measures displacement from
+     * this rather than an instantaneous speed, because a cloth resting on a
+     * collider sits in a bounded limit cycle whose speed is not small.
+     *
+     * Re-anchored to the live positions whenever a particle leaves the
+     * threshold, so the window is "how far has anything moved since the cloth
+     * last moved" rather than a fixed grid of epochs.
+     * @type {Float32Array|null}
+     */
+    sleep_reference: Float32Array | null;
     /**
      * 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

@@ -1,4 +1,5 @@
 import { Transform64 } from "../../../ecs/transform/Transform64.js";
+import { CLOTH_COLLIDER_SLOTS } from "../solver/cloth_solver_constants.js";
 import { ClothDynamics } from "./ClothDynamics.js";
 
 /**
@@ -53,14 +54,6 @@ export class ClothInstance {
      */
     transform = null;
 
-    /**
-     * How deep the anchor sits in the transform hierarchy. Instances step in
-     * ascending depth so that a `Cloth` nested inside another one reads an
-     * anchor the outer solve has already written this step.
-     * @type {number}
-     */
-    depth = 0;
-
     /**
      * `false` until the subtree has been walked. Seeding is deferred to the
      * first step rather than done at link, because a rope's links arrive as
@@ -391,34 +384,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 +454,98 @@ 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;
+
+    /**
+     * Seconds of fixed step **this instance** has taken, which is the clock
+     * §10's gust is a function of.
+     *
+     * Per cloth rather than per world, and the difference only shows with more
+     * than one of them. A cloth registered with the worker while another is
+     * already running waits for its memory, and the world's clock moves during
+     * that wait because the other cloth is still being advanced — so the two
+     * systems reach *this* cloth's first step at different world times and hand
+     * it different weather. An age counted in its own steps is the same number
+     * on both sides by construction. `MEASUREMENTS.md` §57.
+     *
+     * Advanced on every step the instance is *offered*, including ones it
+     * sleeps through, because a sleeping cloth still has to be able to ask
+     * whether the air has changed enough to wake it.
+     * @type {number}
+     */
+    age = 0;
+
+    /**
+     * The index handles this cloth last **stepped against**, in the order the
+     * broadphase returned them, and how many of them are meaningful.
+     *
+     * §7 P5's wake test compares each overlapping collider's previous pose with
+     * its current one, and `ClothColliderSystem#link` *places* a new collider —
+     * previous equals current — so a collider spawned around a sleeping cloth
+     * is one that has not moved and never woke it. The set is the other half of
+     * that question: a handle appearing or leaving is a change to the world the
+     * cloth went to sleep in, whatever the poses say.
+     * @type {Int32Array}
+     */
+    collider_keys = new Int32Array(CLOTH_COLLIDER_SLOTS);
+
+    /**
+     * @type {number}
+     */
+    collider_key_count = 0;
+
+    /**
+     * The broadphase margin the last gather used, metres. The wake test has to
+     * query with the same one, or it compares a set built under one reach with
+     * a set built under another and wakes on the difference between the two
+     * questions rather than on a change in the world.
+     * @type {number}
+     */
+    gather_reach = 0;
+
+    /**
+     * The joint entities this cloth's rig seeding took `TransformAttachment`
+     * authority from, so that removing the cloth can give it back. `null` on
+     * the entity path and before the first rig seeding.
+     *
+     * Only the ones the revoke actually changed: a joint that was already the
+     * CPU's is not one cloth has anything to hand back.
+     * @type {number[]|null}
+     */
+    revoked_joints = null;
+
+    /**
+     * Where every particle was when the current sleep window opened, or `null`
+     * before the first step — §7 P5's sleep test measures displacement from
+     * this rather than an instantaneous speed, because a cloth resting on a
+     * collider sits in a bounded limit cycle whose speed is not small.
+     *
+     * Re-anchored to the live positions whenever a particle leaves the
+     * threshold, so the window is "how far has anything moved since the cloth
+     * last moved" rather than a fixed grid of epochs.
+     * @type {Float32Array|null}
+     */
+    sleep_reference = null;
+
     /**
      * 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();
+    }
+}