@woosh/meep-engine 3.42.0 → 3.44.0

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

@@ -39,6 +39,8 @@ 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.leash_source] source particle per leash row, `−1`
+     *   for a row whose centre the caller writes outright; default all `−1`
      * @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
@@ -49,7 +51,7 @@ export class ClothState {
      *   back private memory would make both threads mutate copies of it.
      * @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, backstop_particle, backstop_radius, shared }: {
+    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, leash_source, backstop_particle, backstop_radius, shared }: {
         position: Float32Array | number[];
         mass_inverse: Float32Array | number[];
         stretch_particle?: Int32Array | number[];
@@ -62,6 +64,7 @@ export class ClothState {
         bend_stiffness?: Float32Array | number[];
         leash_particle?: Int32Array | number[];
         leash_radius?: Float32Array | number[];
+        leash_source?: Int32Array | number[];
         backstop_particle?: Int32Array | number[];
         backstop_radius?: Float32Array | number[];
         shared?: boolean;
@@ -278,15 +281,36 @@ export class ClothState {
      * The point each leash row is measured from, 3 per row, in the cloth's own
      * local frame.
      *
-     * **Written per step by the caller, not baked.** A slack row's centre is
-     * the particle's animated position and a tether row's is the anchor's, and
-     * neither is a property of the rest shape. Storing a point per row rather
-     * than an index into a shared table costs three floats a row and removes an
-     * indirection from the inner loop, which is the trade this structure makes
-     * everywhere else too.
+     * **Written per step by the caller, not baked** — or, for a row with a
+     * {@link leash_source}, per substep by the step itself. A slack row's centre
+     * is the particle's animated position and a tether row's is the held
+     * particle it hangs from, and neither is a property of the rest shape.
+     * Storing a point per row rather than an index into a shared table costs
+     * three floats a row and removes an indirection from the inner loop, which
+     * is the trade this structure makes everywhere else too.
      * @type {Float32Array}
      */
     leash_target: Float32Array;
+    /**
+     * The particle each leash row is measured from, or `−1` for a row whose
+     * centre the caller writes outright.
+     *
+     * **A held particle moves inside a step** — it is carried an equal share of
+     * the way to where its holder will have it at each substep — so a centre
+     * written once per step is a step behind the particle it is supposed to sit
+     * on, and a hard row measured from a stale point fights the hold it hangs
+     * from. A row with a source is re-centred at every substep, after the held
+     * particles have moved, at `position[source] + leash_offset`.
+     * @type {Int32Array}
+     */
+    leash_source: Int32Array;
+    /**
+     * Where a sourced leash row's centre sits relative to its source particle,
+     * 3 per row, cloth-local. Zero for a tether; the animated pose's offset from
+     * the held particle for a slack row. Written by the caller per step.
+     * @type {Float32Array}
+     */
+    leash_offset: Float32Array;
     /**
      * Leash radius, one per row: `slack·d_geo,i` for a slack row, `d_geo,i` for
      * a tether. Zero is a weld (§3.4 — the pin is a leash of no radius, not a
@@ -541,6 +565,20 @@ export class ClothState {
      * @type {Float32Array}
      */
     air_velocity: Float32Array;
+    /**
+     * Where each **held** particle — inverse mass zero — is to be at the end of
+     * the step, 3 per particle, cloth-local.
+     *
+     * Written by the caller; read by the predict, which carries a held particle
+     * an equal share of the remaining way at every substep so that it arrives
+     * here exactly at the last one. That is how a holder that moves relative to
+     * the cloth's frame moves its particles *through* the step rather than at
+     * its start, which is the same thing §8.2 does for colliders — and Chaos
+     * Cloth does for its kinematic particles. Seeded at the rest position, so a
+     * held particle nobody writes a target for stays where it is, bit for bit.
+     * @type {Float32Array}
+     */
+    kinematic_target: Float32Array;
     /**
      * Gravity plus §10's aerodynamic drag, 3 per particle, cloth-local, m/s².
      *

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":"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"}
+{"version":3,"file":"ClothState.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/ClothState.js"],"names":[],"mappings":";;;8BAkHU,MAAM;;;;;;AAkBhB;;;GAGG;AACH,sCAFU,MAAM,CAEyB;AAEzC;IAyjBI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH;QAzB8C,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;QAEa,YAAY,GAA9C,UAAU,GAAC,MAAM,EAAE;QAEe,iBAAiB,GAAnD,UAAU,GAAC,MAAM,EAAE;QACiB,eAAe,GAAnD,YAAY,GAAC,MAAM,EAAE;QAEC,MAAM,GAA5B,OAAO;QAKL,UAAU,CA4KtB;IAkCD;;;;;;;;;;;;OAYG;IACH,wCAJW;QAAC,MAAM,EAAE,iBAAiB,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QACpF,UAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAC,GAC9E,UAAU,CAiBtB;IAr0BD;;;;;;OAMG;IACH,QAFU,WAAW,GAAC,iBAAiB,CAEzB;IAEd;;;OAGG;IACH,QAFU,YAAY,CAER;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;;;;;;;;;;;;OAYG;IACH,cAFU,YAAY,CAEF;IAEpB;;;;;;;;;;;OAWG;IACH,cAFU,UAAU,CAEA;IAEpB;;;;;OAKG;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;IAEvB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,mBAFU,UAAU,CAEK;IAEzB;;;;;;;;;;;;;OAaG;IACH,gBAFU,YAAY,CAEA;IAEtB;;;OAGG;IACH,iBAFU,YAAY,CAEC;IAEvB;;;OAGG;IACH,iBAFU,YAAY,CAEC;IAEvB;;;OAGG;IACH,kBAFU,YAAY,CAEE;IAExB;;;OAGG;IACH,2BAFU,UAAU,CAEa;IAEjC;;;OAGG;IACH,oBAFU,UAAU,CAEM;IAE1B;;;;;;;;;;;;;;;OAeG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;;;;;;;;;OAYG;IACH,gBAFU,YAAY,CAEA;IAEtB;;;;;OAKG;IACH,cAFU,UAAU,CAEA;IAEpB;;;;OAIG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;;OAKG;IACH,kBAFU,UAAU,CAEI;IAExB;;;;;;;OAOG;IACH,aAFU,UAAU,CAED;IAEnB;;;OAGG;IACH,gBAFU,YAAY,CAEA;IAEtB;;;OAGG;IACH,iBAFU,YAAY,CAEC;IAEvB;;;;;OAKG;IACH,yBAFU,YAAY,CAES;IAE/B;;;OAGG;IACH,0BAFU,YAAY,CAEU;IAEhC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;;;;;;;;;;OAcG;IACH,WAFU,UAAU,CAEH;IAEjB;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;OAUG;IACH,YAFU,YAAY,CAEJ;IAElB;;;;OAIG;IACH,cAFU,YAAY,CAEF;IAEpB;;;;;;;;;;OAUG;IACH,gBAFU,YAAY,CAEA;IAEtB;;;;;;;;;;;;;;;;;OAiBG;IACH,cAFU,YAAY,CAEF;IAEpB;;;;;;;;;;;;OAYG;IACH,kBAFU,YAAY,CAEE;IAExB;;;;;;;;;;OAUG;IACH,uBAFU,YAAY,CAEO;IAoN7B;;OAEG;IACH,kBAFa,OAAO,CAInB;IAED;;;;;;;;;;OAUG;IACH,uBAHa;QAAC,MAAM,EAAE,iBAAiB,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QACtF,UAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAC,CAc1F;CA+BJ"}

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

@@ -360,16 +360,39 @@ export class ClothState {
      * The point each leash row is measured from, 3 per row, in the cloth's own
      * local frame.
      *
-     * **Written per step by the caller, not baked.** A slack row's centre is
-     * the particle's animated position and a tether row's is the anchor's, and
-     * neither is a property of the rest shape. Storing a point per row rather
-     * than an index into a shared table costs three floats a row and removes an
-     * indirection from the inner loop, which is the trade this structure makes
-     * everywhere else too.
+     * **Written per step by the caller, not baked** — or, for a row with a
+     * {@link leash_source}, per substep by the step itself. A slack row's centre
+     * is the particle's animated position and a tether row's is the held
+     * particle it hangs from, and neither is a property of the rest shape.
+     * Storing a point per row rather than an index into a shared table costs
+     * three floats a row and removes an indirection from the inner loop, which
+     * is the trade this structure makes everywhere else too.
      * @type {Float32Array}
      */
     leash_target = null;
 
+    /**
+     * The particle each leash row is measured from, or `−1` for a row whose
+     * centre the caller writes outright.
+     *
+     * **A held particle moves inside a step** — it is carried an equal share of
+     * the way to where its holder will have it at each substep — so a centre
+     * written once per step is a step behind the particle it is supposed to sit
+     * on, and a hard row measured from a stale point fights the hold it hangs
+     * from. A row with a source is re-centred at every substep, after the held
+     * particles have moved, at `position[source] + leash_offset`.
+     * @type {Int32Array}
+     */
+    leash_source = null;
+
+    /**
+     * Where a sourced leash row's centre sits relative to its source particle,
+     * 3 per row, cloth-local. Zero for a tether; the animated pose's offset from
+     * the held particle for a slack row. Written by the caller per step.
+     * @type {Float32Array}
+     */
+    leash_offset = null;
+
     /**
      * Leash radius, one per row: `slack·d_geo,i` for a slack row, `d_geo,i` for
      * a tether. Zero is a weld (§3.4 — the pin is a leash of no radius, not a
@@ -654,6 +677,21 @@ export class ClothState {
      */
     air_velocity = null;
 
+    /**
+     * Where each **held** particle — inverse mass zero — is to be at the end of
+     * the step, 3 per particle, cloth-local.
+     *
+     * Written by the caller; read by the predict, which carries a held particle
+     * an equal share of the remaining way at every substep so that it arrives
+     * here exactly at the last one. That is how a holder that moves relative to
+     * the cloth's frame moves its particles *through* the step rather than at
+     * its start, which is the same thing §8.2 does for colliders — and Chaos
+     * Cloth does for its kinematic particles. Seeded at the rest position, so a
+     * held particle nobody writes a target for stays where it is, bit for bit.
+     * @type {Float32Array}
+     */
+    kinematic_target = null;
+
     /**
      * Gravity plus §10's aerodynamic drag, 3 per particle, cloth-local, m/s².
      *
@@ -693,6 +731,8 @@ 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.leash_source] source particle per leash row, `−1`
+     *   for a row whose centre the caller writes outright; default all `−1`
      * @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
@@ -716,6 +756,7 @@ export class ClothState {
         bend_stiffness = EMPTY_FLOAT32,
         leash_particle = EMPTY_INT32,
         leash_radius = EMPTY_FLOAT32,
+        leash_source = undefined,
         backstop_particle = EMPTY_INT32,
         backstop_radius = EMPTY_FLOAT32,
         shared = false
@@ -732,6 +773,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.ok(leash_source === undefined || leash_source.length === leash_count, 'leash_source.length');
         assert.equal(backstop_particle.length, backstop_count, 'backstop_particle.length');
 
         const colors = cloth_color_particles(
@@ -774,6 +816,7 @@ export class ClothState {
         // and the first step's `v = (x − x_prev)/h` reads zero.
         state.position_previous.set(state.position);
         state.inertial.set(state.position);
+        state.kinematic_target.set(state.position);
 
         for (let row = 0; row < stretch_count; row++) {
             state.stretch_particle[row * 2] = particle_of_source[stretch_particle[row * 2]];
@@ -828,6 +871,10 @@ export class ClothState {
             state.leash_target[row * 3] = state.position[particle * 3];
             state.leash_target[row * 3 + 1] = state.position[particle * 3 + 1];
             state.leash_target[row * 3 + 2] = state.position[particle * 3 + 2];
+
+            state.leash_source[row] = leash_source === undefined || leash_source[row] < 0
+                ? -1
+                : particle_of_source[leash_source[row]];
         }
 
         build_adjacency(
@@ -1028,6 +1075,8 @@ function allocate(
         bend_count * 4,         // bend_adjacency
         leash_count,            // leash_particle
         leash_count * 3,        // leash_target
+        leash_count,            // leash_source
+        leash_count * 3,        // leash_offset
         leash_count,            // leash_radius
         leash_count,            // leash_lambda
         leash_count,            // leash_penalty
@@ -1053,7 +1102,8 @@ function allocate(
         particle_count * 3,     // self_force
         particle_count * 6,     // self_hessian
         particle_count * 3,     // air_velocity
-        particle_count * 3      // external_acceleration
+        particle_count * 3,     // external_acceleration
+        particle_count * 3      // kinematic_target
     ];
 
     let total = 0;
@@ -1119,6 +1169,8 @@ function allocate(
 
     state.leash_particle = cut(Int32Array, leash_count);
     state.leash_target = cut(Float32Array, leash_count * 3);
+    state.leash_source = cut(Int32Array, leash_count);
+    state.leash_offset = cut(Float32Array, leash_count * 3);
     state.leash_radius = cut(Float32Array, leash_count);
     state.leash_lambda = cut(Float32Array, leash_count);
     state.leash_penalty = cut(Float32Array, leash_count);
@@ -1157,6 +1209,10 @@ function allocate(
     state.air_velocity = cut(Float32Array, particle_count * 3);
     state.external_acceleration = cut(Float32Array, particle_count * 3);
 
+    // Held particles only, and a cloth whose holders ride its frame never
+    // changes it: the cold end.
+    state.kinematic_target = cut(Float32Array, particle_count * 3);
+
     assert.equal(cursor, total, 'buffer cursor at end of allocation');
 }
 

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

@@ -15,9 +15,14 @@
  * @param {number} dt seconds, the fixed step the discovered rows will be used
  *   across — how far a particle carries its current velocity before anything
  *   gets a chance to stop it
+ * @param {number} kinematic_travel metres, the furthest any held particle is
+ *   carried this step. A cloth at rest that a holder yanks has no velocity to
+ *   reach with and still moves, dragged by the particles it hangs from, so every
+ *   free particle reaches this much further. Zero for a cloth whose holders ride
+ *   its frame.
  * @returns {number} how many contact rows were created
  */
-export function cloth_contact_find(state: ClothState, table: Float32Array | Float64Array, keys: Int32Array, count: number, dt: number): number;
+export function cloth_contact_find(state: ClothState, table: Float32Array | Float64Array, keys: Int32Array, count: number, dt: number, kinematic_travel: number): number;
 /**
  * # Finding the contacts, once per step
  *

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_contact_find.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_contact_find.js"],"names":[],"mappings":"AAgHA;;;;;;;;;;;;;;;;;;GAkBG;AACH,6DARW,YAAY,GAAC,YAAY,QACzB,UAAU,SACV,MAAM,MACN,MAAM,GAGJ,MAAM,CAwLlB;AAlSD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAEH;;;;;;;;;GASG;AACH,mCAFU,MAAM,CAEsB"}
+{"version":3,"file":"cloth_contact_find.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_contact_find.js"],"names":[],"mappings":"AAgHA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,6DAbW,YAAY,GAAC,YAAY,QACzB,UAAU,SACV,MAAM,MACN,MAAM,oBAGN,MAAM,GAKJ,MAAM,CAwLlB;AAvSD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAEH;;;;;;;;;GASG;AACH,mCAFU,MAAM,CAEsB"}

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

@@ -127,9 +127,14 @@ export const CLOTH_CONTACT_MARGIN = 1;
  * @param {number} dt seconds, the fixed step the discovered rows will be used
  *   across — how far a particle carries its current velocity before anything
  *   gets a chance to stop it
+ * @param {number} kinematic_travel metres, the furthest any held particle is
+ *   carried this step. A cloth at rest that a holder yanks has no velocity to
+ *   reach with and still moves, dragged by the particles it hangs from, so every
+ *   free particle reaches this much further. Zero for a cloth whose holders ride
+ *   its frame.
  * @returns {number} how many contact rows were created
  */
-export function cloth_contact_find(state, table, keys, count, dt) {
+export function cloth_contact_find(state, table, keys, count, dt, kinematic_travel) {
     const particle_count = state.particle_count;
 
     const collider = state.contact_collider;
@@ -213,7 +218,7 @@ export function cloth_contact_find(state, table, keys, count, dt) {
         // How far this particle carries its current velocity across the step.
         // Hoisted out of the record loop: it is a property of the particle, and
         // the loop below is the hot one.
-        const travel = dt * Math.hypot(velocity[p], velocity[p + 1], velocity[p + 2]);
+        const travel = dt * Math.hypot(velocity[p], velocity[p + 1], velocity[p + 2]) + kinematic_travel;
 
         let found = 0;
 

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

@@ -0,0 +1,114 @@
+/**
+ * Whether the held particles lie on one line, and which: written to `line` as
+ * the origin then the unit direction.
+ *
+ * The origin is the first held particle and the direction runs to the one
+ * furthest from it, which spans at least half of the set. Every held particle is
+ * then measured off that line.
+ *
+ * @param {Float64Array} line out, {@link CLOTH_HOLD_LINE_WORDS}
+ * @param {Float32Array} position
+ * @param {Int32Array} held particle indices
+ * @param {number} held_count
+ * @returns {boolean} `false` when there are fewer than two distinct held points
+ *   or they are not on one line; `line` is then not written
+ */
+export function cloth_hold_line_fit(line: Float64Array, position: Float32Array, held: Int32Array, held_count: number): boolean;
+/**
+ * Take one Newton step of the substep's energy along the turn about `line`, and
+ * turn every free particle by the angle it gives — see the module docblock.
+ *
+ * @param {ClothState} state
+ * @param {Float64Array} line from {@link cloth_hold_line_fit}
+ * @param {number} inverse_h_squared `1/h²` for the substep in progress
+ * @param {Float32Array|Float64Array|null} collider_table as the vertex update
+ *   takes it; `null` skips the contact rows
+ * @returns {number} the angle turned, radians; `0` when there is nothing to turn
+ */
+export function cloth_hold_line_turn(state: ClothState, line: Float64Array, inverse_h_squared: number, collider_table: Float32Array | Float64Array | null): number;
+/**
+ * # The turn about a hold line — one more block of the descent
+ *
+ * VBD is block coordinate descent on the step's energy, one 3×3 block per
+ * particle. A cloth whose held particles lie on one line has a motion no such
+ * block can make: turning the whole cloth about that line as a rigid body. Every
+ * internal row is unchanged by it — its ends turn together, or one of them is on
+ * the axis — so the only parts of the energy that see the turn are the inertial
+ * term and the rows measured from outside the cloth. When the line is vertical
+ * nothing outside restores it either, because gravity is parallel to the axis.
+ *
+ * A vertex update moves one particle, so every update adds `x_i × m·Δx_i` of
+ * angular momentum about the line, and the step stopped at a fabric's iteration
+ * count leaves a residual whose moment about it is not zero. The warm start keeps
+ * a quarter of each hard multiplier (§5.2), so a cloth at rest re-solves three
+ * quarters of its weight every substep, is never a fixed point, and leaves that
+ * residual every substep. A flag on a pole turned at ten degrees a second for as
+ * long as it was run (PLAN §18, `MEASUREMENTS.md` §63).
+ *
+ * So the turn gets a block of its own: **one Newton step of the substep's energy
+ * along the rotation about the hold line**, then every free particle turned by
+ * the angle it gives. It is a descent step on the same energy as the vertex
+ * updates, so §5.3 is untouched, and it changes no row, multiplier or constant.
+ *
+ * ## What enters
+ *
+ * With `a` the line's unit direction, `r_i` a particle's offset from the line's
+ * origin and `t_i = a × r_i` its velocity under a unit turn, along the path
+ * `x_i(θ) = o + R(θ)·r_i`:
+ *
+ *     g = dE/dθ   = Σ t_i·∇E_i
+ *     H = d²E/dθ² = Σ t_iᵀ·H_i·t_i + Σ ∇E_i·(a(a·r_i) − r_i)
+ *     θ = −g/H
+ *
+ * - `∇E_i` and `H_i` are the vertex update's own assembly with the internal rows
+ *   left out: the inertial term `(m/h²)(x − y)`, the leash rows, the backstop
+ *   rows and the contacts. Stretch, bend and self-collision rows are invariant
+ *   under the turn: a row's energy does not change along the path, so its share
+ *   of `g` is zero and its two shares of `H` cancel, and leaving it out is
+ *   leaving out a zero. A tether is invariant too, since it is measured from a
+ *   held particle and that is on the axis, but it shares its accumulation with
+ *   the slack row, which is not. It enters, and it can only shorten the step.
+ * - The last sum is the path's own curvature, `d²x/dθ² = −r⊥`. About a vertical
+ *   axis gravity has no part in it and what is left is close to zero; about a
+ *   horizontal one it is the pendulum's gravity stiffness. It is added only where
+ *   it is positive, which keeps `H` at least the first sum, positive definite
+ *   through the mass term: a step no longer than the one without it.
+ *
+ * ## When it runs
+ *
+ * When the held particles lie on one line **at this substep**, at two or more
+ * distinct points — a fact about the holds the predict already has in hand,
+ * since it carries every held particle. A single held point has three free turns
+ * and a cloth nothing holds has six; this block is the line's, and neither of
+ * those is handled here. It runs on a line gravity restores too, a horizontal
+ * one included, and there it has slowed some sleeps and kept one cloth awake
+ * (PLAN §18).
+ *
+ * It runs once a substep, in the **last** iteration, after the sweep and before
+ * that iteration's dual update. Run in every iteration it measured no better on
+ * a flag and cost 9–19% of a step rather than 3–9% (`MEASUREMENTS.md` §66).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * How far a held particle may sit off the line and still be on it, as a
+ * fraction of the largest coordinate among the held particles.
+ *
+ * Relative, because what it separates is rounding from geometry, and rounding is
+ * a proportion of magnitude. Held positions are `Float32` and are carried through
+ * the step in double and stored again at each substep. A flag turned off every
+ * axis, whose hoist is straight in exact arithmetic, measured at most 6.3e-8 of
+ * its largest coordinate off its own line — half a unit in the last place —
+ * from the origin out to four kilometres. This is 240 times that, and 15 µm at a
+ * metre. `MEASUREMENTS.md` §66.
+ *
+ * @type {number}
+ */
+export const CLOTH_HOLD_LINE_TOLERANCE: number;
+/**
+ * Words of a hold line: the origin, then the unit direction.
+ * @type {number}
+ */
+export const CLOTH_HOLD_LINE_WORDS: number;
+//# sourceMappingURL=cloth_hold_line.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_hold_line.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_hold_line.js"],"names":[],"mappings":"AAyGA;;;;;;;;;;;;;;GAcG;AACH,0CAPW,YAAY,YACZ,YAAY,QACZ,UAAU,cACV,MAAM,GACJ,OAAO,CAiGnB;AAED;;;;;;;;;;GAUG;AACH,8DANW,YAAY,qBACZ,MAAM,kBACN,YAAY,GAAC,YAAY,GAAC,IAAI,GAE5B,MAAM,CAiIlB;AAjVD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH;;;;;;;;;;;;;GAaG;AACH,wCAFU,MAAM,CAEkC;AAElD;;;GAGG;AACH,oCAFU,MAAM,CAEuB"}