@woosh/meep-engine 3.22.0 → 3.23.0

package/src/engine/physics/cloth/solver/ClothState.d.ts

@@ -42,10 +42,30 @@
  * row, which have the same `C` and differ only in where their centre and
  * radius come from (`cloth_leash_row.js`). §6's strain-limit row needed no new
  * storage at all — it is a stretch row with a longer rest length and a
- * one-sided clamp, which the stretch table already carries. Backstop,
- * collision, friction and self-collision are the same shape and land with
- * their milestones; transient contact rows never enter this structure at all
- * (§5.4 keeps them in a per-particle scratch applied Jacobi-style).
+ * one-sided clamp, which the stretch table already carries. M2 adds the
+ * **backstop**, which is a leash against a plane rather than a point.
+ *
+ * ## Contacts are transient, and they live here anyway
+ *
+ * §5.4 says contact rows "never enter this structure" and are kept in a
+ * per-particle scratch applied Jacobi-style. Half of that is right and half of
+ * it is a solution to a problem a *collider* contact does not have.
+ *
+ * A contact against a collider is **unary** — one particle against a surface
+ * that is fixed for the substep — so it couples no two particles, so there is
+ * no Gauss-Seidel/Jacobi distinction to make and nothing to keep out of the
+ * colouring. It accumulates in the vertex update exactly like a leash row, in
+ * colour order, deterministically. What M4's particle-particle rows need is a
+ * different question and §9 is where it is answered.
+ *
+ * What *is* true is that a contact comes and goes, so it cannot be a CSR table
+ * sized at build time. It is instead a fixed **{@link CLOTH_CONTACT_SLOTS}
+ * slots per particle**, allocated once inside this buffer and rebuilt each
+ * step: an occupied slot names a collider, an empty one holds `-1`. That keeps
+ * §12's one-allocation property, bounds the worst case — a particle inside
+ * thirty colliders gets rows against the four nearest, which is the four that
+ * matter — and makes the accumulation a counted loop over adjacent slots
+ * rather than an indirection.
  *
  * A leash row is **unary** — one particle against a point — which has two
  * pleasant consequences. It adds no edge to the particle graph, so the
@@ -82,9 +102,12 @@ export class ClothState {
      * @param {Int32Array|number[]} [description.leash_particle] the particle each leash row holds
      * @param {Float32Array|number[]} [description.leash_radius] leash radius per row; its length is
      *   the row count, and the leash centres are written per step rather than here
+     * @param {Int32Array|number[]} [description.backstop_particle] the particle each backstop row holds
+     * @param {Float32Array|number[]} [description.backstop_radius] backstop radius per row; the planes
+     *   themselves are written per step rather than here
      * @returns {ClothState}
      */
-    static from({ position, mass_inverse, stretch_particle, stretch_rest, stretch_stiffness, stretch_force_min, stretch_force_max, bend_particle, bend_weight, bend_stiffness, leash_particle, leash_radius }: {
+    static from({ position, mass_inverse, stretch_particle, stretch_rest, stretch_stiffness, stretch_force_min, stretch_force_max, bend_particle, bend_weight, bend_stiffness, leash_particle, leash_radius, backstop_particle, backstop_radius }: {
         position: Float32Array | number[];
         mass_inverse: Float32Array | number[];
         stretch_particle?: Int32Array | number[];
@@ -97,6 +120,8 @@ export class ClothState {
         bend_stiffness?: Float32Array | number[];
         leash_particle?: Int32Array | number[];
         leash_radius?: Float32Array | number[];
+        backstop_particle?: Int32Array | number[];
+        backstop_radius?: Float32Array | number[];
     }): ClothState;
     /**
      * The single allocation every view below is cut from.
@@ -319,5 +344,183 @@ export class ClothState {
      * @type {Int32Array}
      */
     leash_adjacency: Int32Array;
+    /**
+     * @type {number}
+     */
+    backstop_count: number;
+    /**
+     * Particle each backstop row holds, one per row.
+     * @type {Int32Array}
+     */
+    backstop_particle: Int32Array;
+    /**
+     * The backstop plane per row: origin `b` then unit normal `n`, 6 per row,
+     * in the cloth's own local frame.
+     *
+     * **Written per step by the caller, not baked**, for the same reason
+     * {@link leash_target} is: a backstop is anchored to the *animated* pose —
+     * a point just inside the body with the surface normal there — and neither
+     * is a property of the rest shape. §6's row is
+     * `C = r_b − (x_i − b_i)·n_i`, so the row holds the particle at least
+     * {@link backstop_radius} out along its own normal from that point, which
+     * is what "never inside the body" means when the body is a shape the cloth
+     * does not have a collider for.
+     * @type {Float32Array}
+     */
+    backstop_plane: Float32Array;
+    /**
+     * Backstop radius, one per row.
+     * @type {Float32Array}
+     */
+    backstop_radius: Float32Array;
+    /**
+     * Augmented-Lagrangian multiplier, one per backstop row. Hard, like a leash.
+     * @type {Float32Array}
+     */
+    backstop_lambda: Float32Array;
+    /**
+     * Penalty stiffness `k_c`, one per backstop row.
+     * @type {Float32Array}
+     */
+    backstop_penalty: Float32Array;
+    /**
+     * CSR offsets into {@link backstop_adjacency}, `particle_count + 1` entries.
+     * @type {Int32Array}
+     */
+    backstop_adjacency_offset: Int32Array;
+    /**
+     * Row indices — unary, like a leash.
+     * @type {Int32Array}
+     */
+    backstop_adjacency: Int32Array;
+    /**
+     * Particle radius, metres — `ClothDynamics#thickness`, written by the
+     * caller before each step.
+     *
+     * A scalar rather than the per-particle array §12's table names, because
+     * nothing produces a proxy whose particles differ in size: a garment's
+     * thickness is a property of its fabric. A per-particle radius is what a
+     * decimated proxy with a strongly varying edge length would want, and the
+     * shape of that change is one array and one indexed read.
+     *
+     * It sits outside the buffer because it is a *parameter* rather than state
+     * — the same class of thing as `substeps`, which §12 sends across the
+     * worker boundary through the command region and not through the shared
+     * region.
+     * @type {number}
+     */
+    contact_radius: number;
+    /**
+     * Which collider each contact slot holds, `CLOTH_CONTACT_SLOTS` per
+     * particle. A **record index into the caller's packed collider table**, not
+     * a handle, and `-1` for an empty slot.
+     * @type {Int32Array}
+     */
+    contact_collider: Int32Array;
+    /**
+     * The collider's stable identity for each occupied slot — its handle in the
+     * `ClothColliderIndex`, which unlike the record index survives the table
+     * being rebuilt from a different query. This is the key §12 warm-starts a
+     * transient row on, and a collider that leaves the index drops its slot and
+     * its contacts start cold, which is correct.
+     * @type {Int32Array}
+     */
+    contact_key: Int32Array;
+    /**
+     * Normal-force multiplier per contact slot, carried across steps.
+     * @type {Float32Array}
+     */
+    contact_lambda: Float32Array;
+    /**
+     * Normal-force penalty per contact slot.
+     * @type {Float32Array}
+     */
+    contact_penalty: Float32Array;
+    /**
+     * Friction multiplier per contact slot — the magnitude of the tangential
+     * force, because §6's friction row measures the *magnitude* of the slip and
+     * a magnitude has no sign to be clamped either side of.
+     * @type {Float32Array}
+     */
+    contact_friction_lambda: Float32Array;
+    /**
+     * Friction penalty per contact slot.
+     * @type {Float32Array}
+     */
+    contact_friction_penalty: Float32Array;
+    /**
+     * The radius a self-collision row holds two particles apart at, metres —
+     * **not** {@link contact_radius}, and M4 got that wrong before it measured
+     * its way out.
+     *
+     * §6 writes the row as `‖x_i − x_j‖ − (r_i + r_j)` with the same `r` a
+     * collider contact uses, which is `ClothDynamics#thickness`. A garment's
+     * fabric is 4 to 20 mm thick and a proxy's particles are 2 to 8 cm apart, so
+     * two layers of a fold are almost never within a fabric thickness of each
+     * other — their particles would have to line up, and nothing makes them.
+     *
+     * The radius that works is the **proxy's own resolution**: half the shortest
+     * row, so the row's diameter is one particle spacing. The pairs this row
+     * acts on are by construction the ones no fabric row governs, and the
+     * nearest of those is two hops away — so a diameter of one hop is the
+     * largest that cannot contradict a stretch row. Measured on a folding sheet
+     * at 2 cm spacing and 6 mm thickness, with only the radius moved: at the
+     * fabric's own 6 mm the row removes **21%** of the sheet's
+     * self-intersections, and at half the shortest row **82%**.
+     * `MEASUREMENTS.md` §31.
+     * @type {number}
+     */
+    self_radius: number;
+    /**
+     * Self-collision pairs, 2 per pair, rebuilt every step (§9).
+     *
+     * A **pair** rather than a slot per particle, which is the difference from
+     * the contact table above and follows from the row being binary: a pair is
+     * stored once, with `i < j`, and contributes to both of its particles when
+     * the Jacobi scratch is built. Storing it on each side would double the
+     * memory to save an addition.
+     *
+     * The region is sized at build time — `CLOTH_SELF_PAIRS_PER_PARTICLE` per
+     * particle — and `self_count` says how much of it is live. A garment that
+     * crumples past that keeps what it found first and drops the rest, which is
+     * bounded and visible rather than an allocation per frame.
+     * @type {Int32Array}
+     */
+    self_pair: Int32Array;
+    /**
+     * Live pairs in {@link self_pair}.
+     * @type {number}
+     */
+    self_count: number;
+    /**
+     * The Jacobi scratch's force, 3 per particle — every self-collision row
+     * touching that particle, summed once per iteration from the positions the
+     * previous iteration left.
+     *
+     * §5.4's per-particle scratch, and this is the row kind it was written for:
+     * a pair is what the colouring cannot pre-partition, so applying it inside
+     * the sweep would make the answer depend on the order the sweep was split
+     * in. `MEASUREMENTS.md` §18 has why a *collider* contact needs none of this.
+     * @type {Float32Array}
+     */
+    self_force: Float32Array;
+    /**
+     * The Jacobi scratch's Hessian, 6 per particle — the symmetric 3×3 in the
+     * same order {@link cloth_vertex_accumulator} uses: xx, yy, zz, xy, xz, yz.
+     * @type {Float32Array}
+     */
+    self_hessian: Float32Array;
+    /**
+     * Where the particle last stuck to the collider, 3 per contact slot, in the
+     * **collider's own local frame**.
+     *
+     * That frame rather than the cloth's is the whole of what makes a sliding
+     * collider drag cloth with it: the anchor is stored where the collider will
+     * always agree it is, and read back wherever the collider has moved to. In
+     * the cloth's frame it would be a point in space and the friction row would
+     * hold the cloth still while the body slid out from under it.
+     * @type {Float32Array}
+     */
+    contact_anchor: Float32Array;
 }
 //# sourceMappingURL=ClothState.d.ts.map

package/src/engine/physics/cloth/solver/ClothState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClothState.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/ClothState.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH;IAoQI;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH;QAf8C,QAAQ,EAA3C,YAAY,GAAC,MAAM,EAAE;QACc,YAAY,EAA/C,YAAY,GAAC,MAAM,EAAE;QACa,gBAAgB,GAAlD,UAAU,GAAC,MAAM,EAAE;QACiB,YAAY,GAAhD,YAAY,GAAC,MAAM,EAAE;QACe,iBAAiB,GAArD,YAAY,GAAC,MAAM,EAAE;QACe,iBAAiB,GAArD,YAAY,GAAC,MAAM,EAAE;QACe,iBAAiB,GAArD,YAAY,GAAC,MAAM,EAAE;QACa,aAAa,GAA/C,UAAU,GAAC,MAAM,EAAE;QACiB,WAAW,GAA/C,YAAY,GAAC,MAAM,EAAE;QACe,cAAc,GAAlD,YAAY,GAAC,MAAM,EAAE;QACa,cAAc,GAAhD,UAAU,GAAC,MAAM,EAAE;QACiB,YAAY,GAAhD,YAAY,GAAC,MAAM,EAAE;QAEnB,UAAU,CAmItB;IA/ZD;;;OAGG;IACH,QAFU,WAAW,CAEP;IAEd;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,UAFU,YAAY,CAEN;IAEhB;;;;;OAKG;IACH,mBAFU,YAAY,CAEG;IAEzB;;OAEG;IACH,UAFU,YAAY,CAEN;IAEhB;;;;;OAKG;IACH,UAFU,YAAY,CAEN;IAEhB;;;;;OAKG;IACH,cAFU,YAAY,CAEF;IAEpB;;;;;;;;OAQG;IACH,eAFU,YAAY,CAED;IAErB;;;;OAIG;IACH,eAFU,UAAU,CAEC;IAErB;;;;OAIG;IACH,oBAFU,UAAU,CAEM;IAE1B;;;OAGG;IACH,kBAFU,UAAU,CAEI;IAExB;;;OAGG;IACH,cAFU,YAAY,CAEF;IAEpB;;;;OAIG;IACH,mBAFU,YAAY,CAEG;IAEzB;;;;OAIG;IACH,mBAFU,YAAY,CAEG;IAEzB;;;;;OAKG;IACH,mBAFU,YAAY,CAEG;IAEzB;;;;OAIG;IACH,gBAFU,YAAY,CAEA;IAEtB;;;;OAIG;IACH,iBAFU,YAAY,CAEC;IAEvB;;;OAGG;IACH,0BAFU,UAAU,CAEY;IAEhC;;;;OAIG;IACH,mBAFU,UAAU,CAEK;IAEzB;;;;OAIG;IACH,eAFU,UAAU,CAEC;IAErB;;;;;OAKG;IACH,aAFU,YAAY,CAEH;IAEnB;;;OAGG;IACH,gBAFU,YAAY,CAEA;IAEtB;;;;;;OAMG;IACH,aAFU,YAAY,CAEH;IAEnB;;;;OAIG;IACH,cAFU,YAAY,CAEF;IAEpB;;;OAGG;IACH,uBAFU,UAAU,CAES;IAE7B;;;;OAIG;IACH,gBAFU,UAAU,CAEE;IAEtB;;;OAGG;IACH,gBAFU,UAAU,CAEE;IAEtB;;;;;;;;;;;OAWG;IACH,cAFU,YAAY,CAEF;IAEpB;;;;;OAKG;IACH,cAFU,YAAY,CAEF;IAEpB;;;;;;OAMG;IACH,cAFU,YAAY,CAEF;IAEpB;;;OAGG;IACH,eAFU,YAAY,CAED;IAErB;;;OAGG;IACH,wBAFU,UAAU,CAEU;IAE9B;;;OAGG;IACH,iBAFU,UAAU,CAEG;CAgK1B"}
+{"version":3,"file":"ClothState.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/ClothState.js"],"names":[],"mappings":"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"}

package/src/engine/physics/cloth/solver/ClothState.js

@@ -1,5 +1,7 @@
 import { assert } from "../../../../core/assert.js";
 import { cloth_color_order, cloth_color_particles } from "./cloth_color_particles.js";
+import { CLOTH_SELF_PAIRS_PER_PARTICLE } from "./cloth_self_find.js";
+import { CLOTH_CONTACT_SLOTS } from "./constraint/cloth_contact_row.js";
 
 /**
  * # ClothState — the whole simulated cloth, SoA, over one buffer
@@ -45,10 +47,30 @@ import { cloth_color_order, cloth_color_particles } from "./cloth_color_particle
  * row, which have the same `C` and differ only in where their centre and
  * radius come from (`cloth_leash_row.js`). §6's strain-limit row needed no new
  * storage at all — it is a stretch row with a longer rest length and a
- * one-sided clamp, which the stretch table already carries. Backstop,
- * collision, friction and self-collision are the same shape and land with
- * their milestones; transient contact rows never enter this structure at all
- * (§5.4 keeps them in a per-particle scratch applied Jacobi-style).
+ * one-sided clamp, which the stretch table already carries. M2 adds the
+ * **backstop**, which is a leash against a plane rather than a point.
+ *
+ * ## Contacts are transient, and they live here anyway
+ *
+ * §5.4 says contact rows "never enter this structure" and are kept in a
+ * per-particle scratch applied Jacobi-style. Half of that is right and half of
+ * it is a solution to a problem a *collider* contact does not have.
+ *
+ * A contact against a collider is **unary** — one particle against a surface
+ * that is fixed for the substep — so it couples no two particles, so there is
+ * no Gauss-Seidel/Jacobi distinction to make and nothing to keep out of the
+ * colouring. It accumulates in the vertex update exactly like a leash row, in
+ * colour order, deterministically. What M4's particle-particle rows need is a
+ * different question and §9 is where it is answered.
+ *
+ * What *is* true is that a contact comes and goes, so it cannot be a CSR table
+ * sized at build time. It is instead a fixed **{@link CLOTH_CONTACT_SLOTS}
+ * slots per particle**, allocated once inside this buffer and rebuilt each
+ * step: an occupied slot names a collider, an empty one holds `-1`. That keeps
+ * §12's one-allocation property, bounds the worst case — a particle inside
+ * thirty colliders gets rows against the four nearest, which is the four that
+ * matter — and makes the accumulation a counted loop over adjacent slots
+ * rather than an indirection.
  *
  * A leash row is **unary** — one particle against a point — which has two
  * pleasant consequences. It adds no edge to the particle graph, so the
@@ -318,6 +340,205 @@ export class ClothState {
      */
     leash_adjacency = null;
 
+    /**
+     * @type {number}
+     */
+    backstop_count = 0;
+
+    /**
+     * Particle each backstop row holds, one per row.
+     * @type {Int32Array}
+     */
+    backstop_particle = null;
+
+    /**
+     * The backstop plane per row: origin `b` then unit normal `n`, 6 per row,
+     * in the cloth's own local frame.
+     *
+     * **Written per step by the caller, not baked**, for the same reason
+     * {@link leash_target} is: a backstop is anchored to the *animated* pose —
+     * a point just inside the body with the surface normal there — and neither
+     * is a property of the rest shape. §6's row is
+     * `C = r_b − (x_i − b_i)·n_i`, so the row holds the particle at least
+     * {@link backstop_radius} out along its own normal from that point, which
+     * is what "never inside the body" means when the body is a shape the cloth
+     * does not have a collider for.
+     * @type {Float32Array}
+     */
+    backstop_plane = null;
+
+    /**
+     * Backstop radius, one per row.
+     * @type {Float32Array}
+     */
+    backstop_radius = null;
+
+    /**
+     * Augmented-Lagrangian multiplier, one per backstop row. Hard, like a leash.
+     * @type {Float32Array}
+     */
+    backstop_lambda = null;
+
+    /**
+     * Penalty stiffness `k_c`, one per backstop row.
+     * @type {Float32Array}
+     */
+    backstop_penalty = null;
+
+    /**
+     * CSR offsets into {@link backstop_adjacency}, `particle_count + 1` entries.
+     * @type {Int32Array}
+     */
+    backstop_adjacency_offset = null;
+
+    /**
+     * Row indices — unary, like a leash.
+     * @type {Int32Array}
+     */
+    backstop_adjacency = null;
+
+    /**
+     * Particle radius, metres — `ClothDynamics#thickness`, written by the
+     * caller before each step.
+     *
+     * A scalar rather than the per-particle array §12's table names, because
+     * nothing produces a proxy whose particles differ in size: a garment's
+     * thickness is a property of its fabric. A per-particle radius is what a
+     * decimated proxy with a strongly varying edge length would want, and the
+     * shape of that change is one array and one indexed read.
+     *
+     * It sits outside the buffer because it is a *parameter* rather than state
+     * — the same class of thing as `substeps`, which §12 sends across the
+     * worker boundary through the command region and not through the shared
+     * region.
+     * @type {number}
+     */
+    contact_radius = 0;
+
+    /**
+     * Which collider each contact slot holds, `CLOTH_CONTACT_SLOTS` per
+     * particle. A **record index into the caller's packed collider table**, not
+     * a handle, and `-1` for an empty slot.
+     * @type {Int32Array}
+     */
+    contact_collider = null;
+
+    /**
+     * The collider's stable identity for each occupied slot — its handle in the
+     * `ClothColliderIndex`, which unlike the record index survives the table
+     * being rebuilt from a different query. This is the key §12 warm-starts a
+     * transient row on, and a collider that leaves the index drops its slot and
+     * its contacts start cold, which is correct.
+     * @type {Int32Array}
+     */
+    contact_key = null;
+
+    /**
+     * Normal-force multiplier per contact slot, carried across steps.
+     * @type {Float32Array}
+     */
+    contact_lambda = null;
+
+    /**
+     * Normal-force penalty per contact slot.
+     * @type {Float32Array}
+     */
+    contact_penalty = null;
+
+    /**
+     * Friction multiplier per contact slot — the magnitude of the tangential
+     * force, because §6's friction row measures the *magnitude* of the slip and
+     * a magnitude has no sign to be clamped either side of.
+     * @type {Float32Array}
+     */
+    contact_friction_lambda = null;
+
+    /**
+     * Friction penalty per contact slot.
+     * @type {Float32Array}
+     */
+    contact_friction_penalty = null;
+
+    /**
+     * The radius a self-collision row holds two particles apart at, metres —
+     * **not** {@link contact_radius}, and M4 got that wrong before it measured
+     * its way out.
+     *
+     * §6 writes the row as `‖x_i − x_j‖ − (r_i + r_j)` with the same `r` a
+     * collider contact uses, which is `ClothDynamics#thickness`. A garment's
+     * fabric is 4 to 20 mm thick and a proxy's particles are 2 to 8 cm apart, so
+     * two layers of a fold are almost never within a fabric thickness of each
+     * other — their particles would have to line up, and nothing makes them.
+     *
+     * The radius that works is the **proxy's own resolution**: half the shortest
+     * row, so the row's diameter is one particle spacing. The pairs this row
+     * acts on are by construction the ones no fabric row governs, and the
+     * nearest of those is two hops away — so a diameter of one hop is the
+     * largest that cannot contradict a stretch row. Measured on a folding sheet
+     * at 2 cm spacing and 6 mm thickness, with only the radius moved: at the
+     * fabric's own 6 mm the row removes **21%** of the sheet's
+     * self-intersections, and at half the shortest row **82%**.
+     * `MEASUREMENTS.md` §31.
+     * @type {number}
+     */
+    self_radius = 0;
+
+    /**
+     * Self-collision pairs, 2 per pair, rebuilt every step (§9).
+     *
+     * A **pair** rather than a slot per particle, which is the difference from
+     * the contact table above and follows from the row being binary: a pair is
+     * stored once, with `i < j`, and contributes to both of its particles when
+     * the Jacobi scratch is built. Storing it on each side would double the
+     * memory to save an addition.
+     *
+     * The region is sized at build time — `CLOTH_SELF_PAIRS_PER_PARTICLE` per
+     * particle — and `self_count` says how much of it is live. A garment that
+     * crumples past that keeps what it found first and drops the rest, which is
+     * bounded and visible rather than an allocation per frame.
+     * @type {Int32Array}
+     */
+    self_pair = null;
+
+    /**
+     * Live pairs in {@link self_pair}.
+     * @type {number}
+     */
+    self_count = 0;
+
+    /**
+     * The Jacobi scratch's force, 3 per particle — every self-collision row
+     * touching that particle, summed once per iteration from the positions the
+     * previous iteration left.
+     *
+     * §5.4's per-particle scratch, and this is the row kind it was written for:
+     * a pair is what the colouring cannot pre-partition, so applying it inside
+     * the sweep would make the answer depend on the order the sweep was split
+     * in. `MEASUREMENTS.md` §18 has why a *collider* contact needs none of this.
+     * @type {Float32Array}
+     */
+    self_force = null;
+
+    /**
+     * The Jacobi scratch's Hessian, 6 per particle — the symmetric 3×3 in the
+     * same order {@link cloth_vertex_accumulator} uses: xx, yy, zz, xy, xz, yz.
+     * @type {Float32Array}
+     */
+    self_hessian = null;
+
+    /**
+     * Where the particle last stuck to the collider, 3 per contact slot, in the
+     * **collider's own local frame**.
+     *
+     * That frame rather than the cloth's is the whole of what makes a sliding
+     * collider drag cloth with it: the anchor is stored where the collider will
+     * always agree it is, and read back wherever the collider has moved to. In
+     * the cloth's frame it would be a point in space and the friction row would
+     * hold the cloth still while the body slid out from under it.
+     * @type {Float32Array}
+     */
+    contact_anchor = null;
+
     /**
      * Build a cloth from a rest configuration and its rows.
      *
@@ -344,6 +565,9 @@ export class ClothState {
      * @param {Int32Array|number[]} [description.leash_particle] the particle each leash row holds
      * @param {Float32Array|number[]} [description.leash_radius] leash radius per row; its length is
      *   the row count, and the leash centres are written per step rather than here
+     * @param {Int32Array|number[]} [description.backstop_particle] the particle each backstop row holds
+     * @param {Float32Array|number[]} [description.backstop_radius] backstop radius per row; the planes
+     *   themselves are written per step rather than here
      * @returns {ClothState}
      */
     static from({
@@ -358,12 +582,15 @@ export class ClothState {
         bend_weight = EMPTY_FLOAT32,
         bend_stiffness = EMPTY_FLOAT32,
         leash_particle = EMPTY_INT32,
-        leash_radius = EMPTY_FLOAT32
+        leash_radius = EMPTY_FLOAT32,
+        backstop_particle = EMPTY_INT32,
+        backstop_radius = EMPTY_FLOAT32
     }) {
         const particle_count = mass_inverse.length;
         const stretch_count = stretch_rest.length;
         const bend_count = bend_stiffness.length;
         const leash_count = leash_radius.length;
+        const backstop_count = backstop_radius.length;
 
         assert.equal(position.length, particle_count * 3, 'position.length');
         assert.equal(stretch_particle.length, stretch_count * 2, 'stretch_particle.length');
@@ -371,6 +598,7 @@ export class ClothState {
         assert.equal(bend_particle.length, bend_count * 4, 'bend_particle.length');
         assert.equal(bend_weight.length, bend_count * 4, 'bend_weight.length');
         assert.equal(leash_particle.length, leash_count, 'leash_particle.length');
+        assert.equal(backstop_particle.length, backstop_count, 'backstop_particle.length');
 
         const colors = cloth_color_particles(
             particle_count,
@@ -389,7 +617,7 @@ export class ClothState {
 
         const state = new ClothState();
 
-        allocate(state, particle_count, stretch_count, bend_count, leash_count, colour_count);
+        allocate(state, particle_count, stretch_count, bend_count, leash_count, backstop_count, colour_count);
 
         state.colour_offset.set(colour_offset);
         state.source_of_particle.set(order);
@@ -474,6 +702,31 @@ export class ClothState {
             state.leash_particle, leash_count, particle_count
         );
 
+        for (let row = 0; row < backstop_count; row++) {
+            const particle = particle_of_source[backstop_particle[row]];
+
+            state.backstop_particle[row] = particle;
+            state.backstop_radius[row] = backstop_radius[row];
+
+            // Seeded at the particle with an upward normal, where `C` is
+            // `radius` and the row is *violated* rather than inactive — so an
+            // unwritten backstop is visible as a row doing something, rather
+            // than as a plane through the origin that looks plausible. The
+            // caller writes the real plane before the first step.
+            state.backstop_plane[row * 6] = state.position[particle * 3];
+            state.backstop_plane[row * 6 + 1] = state.position[particle * 3 + 1];
+            state.backstop_plane[row * 6 + 2] = state.position[particle * 3 + 2];
+            state.backstop_plane[row * 6 + 4] = 1;
+        }
+
+        build_unary_adjacency(
+            state.backstop_adjacency_offset, state.backstop_adjacency,
+            state.backstop_particle, backstop_count, particle_count
+        );
+
+        state.contact_collider.fill(-1);
+        state.contact_key.fill(-1);
+
         return state;
     }
 }
@@ -503,7 +756,10 @@ const EMPTY_FLOAT32 = new Float32Array(0);
  * @param {number} colour_count
  * @private
  */
-function allocate(state, particle_count, stretch_count, bend_count, leash_count, colour_count) {
+function allocate(state, particle_count, stretch_count, bend_count, leash_count, backstop_count, colour_count) {
+    const contact_count = particle_count * CLOTH_CONTACT_SLOTS;
+    const self_capacity = particle_count * CLOTH_SELF_PAIRS_PER_PARTICLE;
+
     const sizes = [
         particle_count * 3,     // position
         particle_count * 3,     // position_previous
@@ -535,7 +791,24 @@ function allocate(state, particle_count, stretch_count, bend_count, leash_count,
         leash_count,            // leash_lambda
         leash_count,            // leash_penalty
         particle_count + 1,     // leash_adjacency_offset
-        leash_count             // leash_adjacency
+        leash_count,            // leash_adjacency
+        backstop_count,         // backstop_particle
+        backstop_count * 6,     // backstop_plane
+        backstop_count,         // backstop_radius
+        backstop_count,         // backstop_lambda
+        backstop_count,         // backstop_penalty
+        particle_count + 1,     // backstop_adjacency_offset
+        backstop_count,         // backstop_adjacency
+        contact_count,          // contact_collider
+        contact_count,          // contact_key
+        contact_count,          // contact_lambda
+        contact_count,          // contact_penalty
+        contact_count,          // contact_friction_lambda
+        contact_count,          // contact_friction_penalty
+        contact_count * 3,      // contact_anchor
+        self_capacity * 2,      // self_pair
+        particle_count * 3,     // self_force
+        particle_count * 6      // self_hessian
     ];
 
     let total = 0;
@@ -565,6 +838,7 @@ function allocate(state, particle_count, stretch_count, bend_count, leash_count,
     state.stretch_count = stretch_count;
     state.bend_count = bend_count;
     state.leash_count = leash_count;
+    state.backstop_count = backstop_count;
     state.colour_count = colour_count;
 
     state.position = cut(Float32Array, particle_count * 3);
@@ -602,6 +876,26 @@ function allocate(state, particle_count, stretch_count, bend_count, leash_count,
     state.leash_adjacency_offset = cut(Int32Array, particle_count + 1);
     state.leash_adjacency = cut(Int32Array, leash_count);
 
+    state.backstop_particle = cut(Int32Array, backstop_count);
+    state.backstop_plane = cut(Float32Array, backstop_count * 6);
+    state.backstop_radius = cut(Float32Array, backstop_count);
+    state.backstop_lambda = cut(Float32Array, backstop_count);
+    state.backstop_penalty = cut(Float32Array, backstop_count);
+    state.backstop_adjacency_offset = cut(Int32Array, particle_count + 1);
+    state.backstop_adjacency = cut(Int32Array, backstop_count);
+
+    state.contact_collider = cut(Int32Array, contact_count);
+    state.contact_key = cut(Int32Array, contact_count);
+    state.contact_lambda = cut(Float32Array, contact_count);
+    state.contact_penalty = cut(Float32Array, contact_count);
+    state.contact_friction_lambda = cut(Float32Array, contact_count);
+    state.contact_friction_penalty = cut(Float32Array, contact_count);
+    state.contact_anchor = cut(Float32Array, contact_count * 3);
+
+    state.self_pair = cut(Int32Array, self_capacity * 2);
+    state.self_force = cut(Float32Array, particle_count * 3);
+    state.self_hessian = cut(Float32Array, particle_count * 6);
+
     assert.equal(cursor, total, 'buffer cursor at end of allocation');
 }