@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -97,26 +97,24 @@ export class ClothInstance {
      */
     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[]}
+     * The joint entity each node drives. **Rig path only**, and node 0 is the
+     * anchor joint, which is not simulated. A skinned model is a prefab spawned
+     * as entities, so a joint is an entity carrying a `TransformAttachment`,
+     * and that offset is the writable handle; {@link node_attachment} holds it.
+     * @type {Int32Array|number[]}
      */
-    node_joint: Node3D[];
+    node_joint: Int32Array | number[];
     /**
      * 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.
+     * Evaluated rather than read: a joint of an animated skeleton has granted
+     * its offset to the GPU (`GPUStateAuthority`), so the CPU's copy of its
+     * world pose is the rest pose composed under the placement, and reading it
+     * would hang the garment where the character stood before the clip moved
+     * it. `t64_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;
@@ -345,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
@@ -416,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

@@ -112,14 +112,11 @@ export class ClothInstance {
     node_transform = [];
 
     /**
-     * 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[]}
+     * The joint entity each node drives. **Rig path only**, and node 0 is the
+     * anchor joint, which is not simulated. A skinned model is a prefab spawned
+     * as entities, so a joint is an entity carrying a `TransformAttachment`,
+     * and that offset is the writable handle; {@link node_attachment} holds it.
+     * @type {Int32Array|number[]}
      */
     node_joint = [];
 
@@ -127,12 +124,13 @@ export class ClothInstance {
      * 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.
+     * Evaluated rather than read: a joint of an animated skeleton has granted
+     * its offset to the GPU (`GPUStateAuthority`), so the CPU's copy of its
+     * world pose is the rest pose composed under the placement, and reading it
+     * would hang the garment where the character stood before the clip moved
+     * it. `t64_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 = new Transform64();
@@ -393,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
@@ -469,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/ClothRig.d.ts

@@ -15,14 +15,13 @@
  *
  * ## Why there are two cases at all
  *
- * Because the engine has two hierarchies and that is a decision rather than an
- * accident. `shade_node_to_entity_composition` expands a loaded model into
- * entities and gives a `ShadedGeometry` to every node that draws — except a
- * skinned one, which contributes its transform and its name and no geometry,
- * because its vertices deform against a skeleton the renderer owns and the GPU
- * poses. Making those joints entities is a design this program does not do
- * (D47). A rope prop is entities all the way down; a character's cape is not,
- * and never will be.
+ * Because a garment's joints are a skin's, not a subtree's. A prefab spawns a
+ * loaded model as entities — every joint one, with its offset in a
+ * `TransformAttachment` — and a rope prop is a subtree under an anchor entity,
+ * walked. A character's cape is a set of joints named out of a skin that also
+ * has a torso and two arms in it, and what says which of those joints are the
+ * cape is the proxy. The joints it drives are entities either way; the
+ * difference is how they are found.
  *
  * ## A proxy object, not a path
  *

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

@@ -1 +1 @@
-{"version":3,"file":"ClothRig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothRig.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH;IAmBI;;;;;OAKG;IACH;QAHyB,IAAI,GAAlB,MAAM;QACJ,QAAQ,CAkBpB;IAvCD;;;;OAIG;IACH,OAFU,aAAW,IAAI,CAEZ;IAEb;;;;;;;OAOG;IACH,MAFU,MAAM,CAEP;IA0BT;;;OAGG;IACH,cAHW,QAAQ,GACN,OAAO,CAenB;IAED;;OAEG;IACH,QAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH;;MAIC;IAED;;OAEG;IACH,mBAFW,MAAM,QAIhB;IAED,mBAEC;IAGL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAN5B"}
+{"version":3,"file":"ClothRig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothRig.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IAmBI;;;;;OAKG;IACH;QAHyB,IAAI,GAAlB,MAAM;QACJ,QAAQ,CAkBpB;IAvCD;;;;OAIG;IACH,OAFU,aAAW,IAAI,CAEZ;IAEb;;;;;;;OAOG;IACH,MAFU,MAAM,CAEP;IA0BT;;;OAGG;IACH,cAHW,QAAQ,GACN,OAAO,CAenB;IAED;;OAEG;IACH,QAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH;;MAIC;IAED;;OAEG;IACH,mBAFW,MAAM,QAIhB;IAED,mBAEC;IAGL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAN5B"}

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

@@ -18,14 +18,13 @@ import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
  *
  * ## Why there are two cases at all
  *
- * Because the engine has two hierarchies and that is a decision rather than an
- * accident. `shade_node_to_entity_composition` expands a loaded model into
- * entities and gives a `ShadedGeometry` to every node that draws — except a
- * skinned one, which contributes its transform and its name and no geometry,
- * because its vertices deform against a skeleton the renderer owns and the GPU
- * poses. Making those joints entities is a design this program does not do
- * (D47). A rope prop is entities all the way down; a character's cape is not,
- * and never will be.
+ * Because a garment's joints are a skin's, not a subtree's. A prefab spawns a
+ * loaded model as entities — every joint one, with its offset in a
+ * `TransformAttachment` — and a rope prop is a subtree under an anchor entity,
+ * walked. A character's cape is a set of joints named out of a skin that also
+ * has a torso and two arms in it, and what says which of those joints are the
+ * cape is the proxy. The joints it drives are entities either way; the
+ * difference is how they are found.
  *
  * ## A proxy object, not a path
  *

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();
+    }
+}