@woosh/meep-engine 3.43.0 → 3.44.0

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

@@ -1,5 +1,6 @@
 import { assert } from "../../../../core/assert.js";
 import { cloth_collider_pose_at } from "../collider/cloth_collider_sdf.js";
+import { CLOTH_HOLD_LINE_WORDS, cloth_hold_line_fit, cloth_hold_line_turn } from "./cloth_hold_line.js";
 import { cloth_solve_vertex } from "./cloth_solve_vertex.js";
 import {
     CLOTH_CONTACT_K_MIN_RATIO,
@@ -42,6 +43,7 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  *     warm start   λ ← λ·α·γ ;  k ← clamp(k·γ, k_min, k_max)      (hard rows only)
  *     iterate      × iterations:
  *                    for each colour: for each particle: vertex update
+ *                    last iteration, held particles on one line: turn about it
  *                    dual update:  λ ← clamp(k·C + λ, f_min, f_max)
  *                                  k ← min(k + β·|C|, min(k_max, stiffness))
  *     integrate    v  = (x − x_prev)/h
@@ -85,6 +87,21 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  * which is what makes "no wind produces the bytes M5 measured" a fact about the
  * code rather than a claim about floating point.
  *
+ * ## One more block when the holds are a line
+ *
+ * Every vertex update is a 3×3 block of the descent, and a cloth held along one
+ * line has a motion no such block can make: turning about the line as a rigid
+ * body. About a vertical line nothing restores that turn, and the step stopped
+ * at a fabric's iteration count left a moment about it every substep — a flag
+ * turned on its pole for as long as it was run. So the turn is a block of its
+ * own, `cloth_hold_line.js`: one Newton step along it, in the last iteration,
+ * after the sweep and before the dual update.
+ *
+ * Whether the held particles are on a line is decided at every substep, from
+ * where the predict has just carried them. The predict lists them as it goes,
+ * so the question costs a pass over the held particles rather than over the
+ * cloth.
+ *
  * ## What each piece is for
  *
  * **Warm start** carries the multipliers into the next substep so a hard row
@@ -203,13 +220,37 @@ export function cloth_step(
 
     const contacts = collider_table !== null && collider_count > 0 ? collider_table : null;
 
+    if (HELD.length < state.particle_count) {
+        HELD = new Int32Array(state.particle_count);
+    }
+
+    const held = HELD;
+    const line = HOLD_LINE;
+
+    const last_iteration = iterations - 1;
+
     for (let substep = 0; substep < substeps; substep++) {
+        // How many substeps are left, this one included: a held particle covers
+        // an equal share of what remains of its way at each of them.
+        const remaining = substeps - substep;
+
+        let held_count;
+
         if (external === null) {
-            cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z);
+            held_count = cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z, remaining, held);
         } else {
-            cloth_predict_varying(state, h, external);
+            held_count = cloth_predict_varying(state, h, external, remaining, held);
         }
 
+        // Where the held particles are for the rest of the substep: nothing
+        // below moves one.
+        const turn = cloth_hold_line_fit(line, state.position, held, held_count);
+
+        // After the held particles have moved, so a centre measured from one
+        // sits where it is at this substep rather than where it was at the
+        // start of the step.
+        cloth_leash_follow(state);
+
         if (contacts !== null) {
             cloth_collider_pose_at(contacts, collider_count, (substep + 1) / substeps);
         }
@@ -239,6 +280,10 @@ export function cloth_step(
                 }
             }
 
+            if (turn && iteration === last_iteration) {
+                cloth_hold_line_turn(state, line, inverse_h_squared, contacts);
+            }
+
             cloth_stretch_dual_update(state, beta, k_max_ratio, inverse_h_squared);
             cloth_bend_dual_update(state, beta, k_max_ratio, inverse_h_squared);
             cloth_leash_dual_update(state, beta, k_max_ratio, inverse_h_squared);
@@ -262,6 +307,91 @@ export function cloth_step(
     );
 }
 
+/**
+ * Carry one held particle an equal share of the remaining way to its kinematic
+ * target, and make that its inertial target too.
+ *
+ * Equal shares of what *remains* rather than `(substep + 1)/substeps` of the
+ * whole: the particle is not moved by anything else in between, so the two put
+ * it in the same places, and this form needs no record of where the step began.
+ * It lands on the target exactly at the last substep, and a target equal to the
+ * position moves nothing by exactly nothing — which is what keeps a holder that
+ * rides the frame bit-identical to the fixed anchor it replaced.
+ *
+ * @param {ClothState} state
+ * @param {number} p particle index times three
+ * @param {number} remaining substeps left in the step, this one included
+ * @private
+ */
+function cloth_carry_held(state, p, remaining) {
+    const position = state.position;
+    const inertial = state.inertial;
+    const target = state.kinematic_target;
+
+    const x = position[p] + (target[p] - position[p]) / remaining;
+    const y = position[p + 1] + (target[p + 1] - position[p + 1]) / remaining;
+    const z = position[p + 2] + (target[p + 2] - position[p + 2]) / remaining;
+
+    position[p] = x;
+    position[p + 1] = y;
+    position[p + 2] = z;
+
+    inertial[p] = x;
+    inertial[p + 1] = y;
+    inertial[p + 2] = z;
+}
+
+/**
+ * Re-centre every leash row that is measured from a particle: `position[source]
+ * + offset`, at the substep's own positions.
+ *
+ * @param {ClothState} state
+ * @private
+ */
+function cloth_leash_follow(state) {
+    const count = state.leash_count;
+
+    const source = state.leash_source;
+    const offset = state.leash_offset;
+    const target = state.leash_target;
+    const position = state.position;
+
+    for (let row = 0; row < count; row++) {
+        const s = source[row];
+
+        if (s < 0) {
+            continue;
+        }
+
+        const r = row * 3;
+        const p = s * 3;
+
+        target[r] = position[p] + offset[r];
+        target[r + 1] = position[p + 1] + offset[r + 1];
+        target[r + 2] = position[p + 2] + offset[r + 2];
+    }
+}
+
+/**
+ * A held particle's velocity is the one its holder is moving it at. Nothing in
+ * the step reads it while the hold lasts — it has no inertia and no acceleration
+ * to seed — and it is exactly what the particle carries when it is let go.
+ *
+ * @param {ClothState} state
+ * @param {number} p particle index times three
+ * @param {number} inverse_h
+ * @private
+ */
+function cloth_held_velocity(state, p, inverse_h) {
+    const position = state.position;
+    const position_previous = state.position_previous;
+    const velocity = state.velocity;
+
+    velocity[p] = (position[p] - position_previous[p]) * inverse_h;
+    velocity[p + 1] = (position[p + 1] - position_previous[p + 1]) * inverse_h;
+    velocity[p + 2] = (position[p + 2] - position_previous[p + 2]) * inverse_h;
+}
+
 /**
  * The largest inverse mass in the cloth — the lightest particle, which is the
  * one a shared penalty has to be safe for.
@@ -297,18 +427,22 @@ function max_inverse_mass(state) {
  * Predict: record where the substep started, build the inertial target every
  * vertex update pulls towards, and seed the descent.
  *
- * A pinned particle (zero inverse mass) is held exactly: it does not fall, it
- * does not carry velocity, and its inertial target is its own position, so a
- * row that reaches it sees a fixed anchor rather than a very heavy particle.
+ * A held particle (zero inverse mass) is kinematic: it does not fall, it is
+ * carried towards its {@link ClothState#kinematic_target} by an equal share of
+ * the remaining way, and its inertial target is wherever that puts it, so a row
+ * that reaches it sees a fixed anchor rather than a very heavy particle.
  *
  * @param {ClothState} state
  * @param {number} h
  * @param {number} acceleration_x
  * @param {number} acceleration_y
  * @param {number} acceleration_z
+ * @param {number} remaining substeps left in the step, this one included
+ * @param {Int32Array} held out, every held particle's index, in order
+ * @returns {number} how many particles are held
  * @private
  */
-function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z) {
+function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z, remaining, held) {
     const particle_count = state.particle_count;
 
     const position = state.position;
@@ -324,6 +458,8 @@ function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z)
     const gravity_y = h_squared * acceleration_y;
     const gravity_z = h_squared * acceleration_z;
 
+    let held_count = 0;
+
     for (let i = 0; i < particle_count; i++) {
         const p = i * 3;
 
@@ -336,9 +472,9 @@ function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z)
         position_previous[p + 2] = z;
 
         if (mass_inverse[i] === 0) {
-            inertial[p] = x;
-            inertial[p + 1] = y;
-            inertial[p + 2] = z;
+            cloth_carry_held(state, p, remaining);
+
+            held[held_count++] = i;
 
             continue;
         }
@@ -357,22 +493,26 @@ function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z)
         position[p + 1] = y + drift_y + blend * gravity_y;
         position[p + 2] = z + drift_z + blend * gravity_z;
     }
+
+    return held_count;
 }
 
 /**
  * {@link cloth_predict} with a per-particle external acceleration — §10's wind,
  * with gravity already folded in by `cloth_wind_accelerate`.
  *
- * Identical in every other respect, including the pinned-particle rule: a pin is
- * held exactly, so the air does not move it and its inertial target is its own
- * position.
+ * Identical in every other respect, including the held-particle rule: the air
+ * does not move a held particle, its holder does.
  *
  * @param {ClothState} state
  * @param {number} h
  * @param {Float32Array} external 3 per particle, cloth-local, m/s²
+ * @param {number} remaining substeps left in the step, this one included
+ * @param {Int32Array} held out, every held particle's index, in order
+ * @returns {number} how many particles are held
  * @private
  */
-function cloth_predict_varying(state, h, external) {
+function cloth_predict_varying(state, h, external, remaining, held) {
     const particle_count = state.particle_count;
 
     const position = state.position;
@@ -384,6 +524,8 @@ function cloth_predict_varying(state, h, external) {
 
     const h_squared = h * h;
 
+    let held_count = 0;
+
     for (let i = 0; i < particle_count; i++) {
         const p = i * 3;
 
@@ -396,9 +538,9 @@ function cloth_predict_varying(state, h, external) {
         position_previous[p + 2] = z;
 
         if (mass_inverse[i] === 0) {
-            inertial[p] = x;
-            inertial[p + 1] = y;
-            inertial[p + 2] = z;
+            cloth_carry_held(state, p, remaining);
+
+            held[held_count++] = i;
 
             continue;
         }
@@ -421,6 +563,8 @@ function cloth_predict_varying(state, h, external) {
         position[p + 1] = y + drift_y + blend * push_y;
         position[p + 2] = z + drift_z + blend * push_z;
     }
+
+    return held_count;
 }
 
 /**
@@ -461,12 +605,14 @@ function cloth_integrate(state, inverse_h, acceleration_x, acceleration_y, accel
     const inverse_acceleration_squared = acceleration_squared > 0 ? 1 / acceleration_squared : 0;
 
     for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
         if (mass_inverse[i] === 0) {
+            cloth_held_velocity(state, p, inverse_h);
+
             continue;
         }
 
-        const p = i * 3;
-
         const next_x = (position[p] - position_previous[p]) * inverse_h;
         const next_y = (position[p + 1] - position_previous[p + 1]) * inverse_h;
         const next_z = (position[p + 2] - position_previous[p + 2]) * inverse_h;
@@ -517,12 +663,14 @@ function cloth_integrate_varying(state, inverse_h, external) {
     const inertia_blend = state.inertia_blend;
 
     for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
         if (mass_inverse[i] === 0) {
+            cloth_held_velocity(state, p, inverse_h);
+
             continue;
         }
 
-        const p = i * 3;
-
         const acceleration_x = external[p];
         const acceleration_y = external[p + 1];
         const acceleration_z = external[p + 2];
@@ -568,3 +716,18 @@ function cloth_integrate_varying(state, inverse_h, external) {
         velocity[p + 2] = next_z;
     }
 }
+
+/**
+ * The held particles' indices, as the predict carries them — grown to the
+ * largest cloth stepped, and only ever read up to the count the predict returns.
+ * @type {Int32Array}
+ * @private
+ */
+let HELD = new Int32Array(0);
+
+/**
+ * The hold line of the substep in progress, from `cloth_hold_line_fit`.
+ * @type {Float64Array}
+ * @private
+ */
+const HOLD_LINE = new Float64Array(CLOTH_HOLD_LINE_WORDS);

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

@@ -31,6 +31,7 @@ export namespace ClothStepParam {
     let COLLIDER_COUNT: number;
     let SELF_COLLISION: number;
     let DRAG_RESPONSE: number;
+    let KINEMATIC_TRAVEL: number;
 }
 /**
  * `Float64` words one cloth's parameter block occupies.

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_step_instance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step_instance.js"],"names":[],"mappings":"AAsIA;;;;;;;;;GASG;AACH,wEANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GAAC,IAAI,UAE9C,YAAY,UACZ,MAAM,GACJ,IAAI,CA4DhB;;;;6BA/IS,MAAM;;;;;;;;;;;;;;;;;AAqEhB;;;GAGG;AACH,sCAFU,MAAM,CAE0B"}
+{"version":3,"file":"cloth_step_instance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step_instance.js"],"names":[],"mappings":"AA4IA;;;;;;;;;GASG;AACH,wEANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GAAC,IAAI,UAE9C,YAAY,UACZ,MAAM,GACJ,IAAI,CA6DhB;;;;6BAtJS,MAAM;;;;;;;;;;;;;;;;;;AA2EhB;;;GAGG;AACH,sCAFU,MAAM,CAE0B"}

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

@@ -123,14 +123,20 @@ export const ClothStepParam = {
      * takes `cloth_step`'s uniform-gravity path, which is the path M0 through
      * M5 measured.
      */
-    DRAG_RESPONSE: 13
+    DRAG_RESPONSE: 13,
+    /**
+     * The furthest any held particle is carried this step, metres — how far a
+     * cloth its holders are dragging moves without a velocity to show for it.
+     * Contact discovery reaches this much further for every free particle.
+     */
+    KINEMATIC_TRAVEL: 14
 };
 
 /**
  * `Float64` words one cloth's parameter block occupies.
  * @type {number}
  */
-export const CLOTH_STEP_PARAM_STRIDE = 14;
+export const CLOTH_STEP_PARAM_STRIDE = 15;
 
 /**
  * Step one cloth.
@@ -159,7 +165,8 @@ export function cloth_step_instance(state, self_exclusions, params, offset) {
     damp(state, params[offset + ClothStepParam.RETENTION]);
 
     const contact_count = cloth_contact_find(
-        state, state.collider_table, state.collider_key, collider_count, dt
+        state, state.collider_table, state.collider_key, collider_count, dt,
+        params[offset + ClothStepParam.KINEMATIC_TRAVEL]
     );
 
     let self_pairs = 0;

package/src/engine/physics/cloth/solver/constraint/cloth_leash_row.d.ts

@@ -11,7 +11,7 @@
  * | | `s` | `r` |
  * |---|---|---|
  * | slack | the particle's **animated position** | `slack · d_geo,i` |
- * | tether (LRA) | the **anchor's** position | `d_geo,i` |
+ * | tether (LRA) | the nearest **held particle's** position | `d_geo,i` |
  *
  * So they are one module, parameterised by mode, exactly as
  * `physics/constraint/solve_constraints.js` does for its 6-DOF joints at the

package/src/engine/physics/cloth/solver/constraint/cloth_leash_row.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_leash_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_leash_row.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH;;;;;;;;;;;GAWG;AACH,+CANW,YAAY,GAAC,MAAM,EAAE,mBACrB,MAAM,0BAEN,MAAM,GACJ,MAAM,CA8BlB;AAED;;;;;;GAMG;AACH,oDAJW,YAAY,+BAEZ,MAAM,QA8GhB;AAED;;;;;;;;;;;;;;GAcG;AACH,iEANW,MAAM,SACN,MAAM,eACN,MAAM,eACN,MAAM,qBACN,MAAM,QA0ChB;AAED;;;;;;;;GAQG;AACH,iEAJW,MAAM,eACN,MAAM,qBACN,MAAM,QA2ChB"}
+{"version":3,"file":"cloth_leash_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_leash_row.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH;;;;;;;;;;;GAWG;AACH,+CANW,YAAY,GAAC,MAAM,EAAE,mBACrB,MAAM,0BAEN,MAAM,GACJ,MAAM,CA8BlB;AAED;;;;;;GAMG;AACH,oDAJW,YAAY,+BAEZ,MAAM,QAqHhB;AAED;;;;;;;;;;;;;;GAcG;AACH,iEANW,MAAM,SACN,MAAM,eACN,MAAM,eACN,MAAM,qBACN,MAAM,QA0ChB;AAED;;;;;;;;GAQG;AACH,iEAJW,MAAM,eACN,MAAM,qBACN,MAAM,QA2ChB"}