@woosh/meep-engine 3.43.0 → 3.45.0

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":"AAiHA;;;;;;;;;;;;;;;;;;;;;;;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

@@ -1,3 +1,4 @@
+import { v3_length } from "../../../../core/geom/vec3/v3_length.js";
 import {
     CCR_AABB_MAX_X,
     CCR_AABB_MAX_Y,
@@ -127,9 +128,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;
@@ -167,7 +173,7 @@ export function cloth_contact_find(state, table, keys, count, dt) {
     for (let record = 0; record < count; record++) {
         const r = record * CCR_STRIDE;
 
-        TRAVEL[record] = Math.hypot(
+        TRAVEL[record] = v3_length(
             table[r + CCR_TX] - table[r + CCR_PREV_TX],
             table[r + CCR_TY] - table[r + CCR_PREV_TY],
             table[r + CCR_TZ] - table[r + CCR_PREV_TZ]
@@ -213,7 +219,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 * v3_length(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,CAqHlB;AArUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH;;;;;;;;;;;;;GAaG;AACH,wCAFU,MAAM,CAEkC;AAElD;;;GAGG;AACH,oCAFU,MAAM,CAEuB"}

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

@@ -0,0 +1,350 @@
+import { cloth_backstop_accumulate } from "./constraint/cloth_backstop_row.js";
+import { cloth_contact_accumulate } from "./constraint/cloth_contact_row.js";
+import { cloth_leash_accumulate } from "./constraint/cloth_leash_row.js";
+import {
+    CVA_F_X,
+    CVA_F_Y,
+    CVA_F_Z,
+    CVA_H_XX,
+    CVA_H_XY,
+    CVA_H_XZ,
+    CVA_H_YY,
+    CVA_H_YZ,
+    CVA_H_ZZ,
+    CVA_STRIDE,
+    cloth_vertex_accumulator_seed
+} from "./cloth_vertex_accumulator.js";
+
+/**
+ * # 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 = 2 ** -16;
+
+/**
+ * Words of a hold line: the origin, then the unit direction.
+ * @type {number}
+ */
+export const CLOTH_HOLD_LINE_WORDS = 6;
+
+/**
+ * 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, position, held, held_count) {
+    if (held_count < 2) {
+        return false;
+    }
+
+    const o = held[0] * 3;
+
+    const ox = position[o];
+    const oy = position[o + 1];
+    const oz = position[o + 2];
+
+    let scale = Math.max(Math.abs(ox), Math.abs(oy), Math.abs(oz));
+
+    let far = o;
+    let far_squared = 0;
+
+    for (let k = 1; k < held_count; k++) {
+        const p = held[k] * 3;
+
+        const x = position[p];
+        const y = position[p + 1];
+        const z = position[p + 2];
+
+        const size_x = Math.abs(x);
+        const size_y = Math.abs(y);
+        const size_z = Math.abs(z);
+
+        if (size_x > scale) {
+            scale = size_x;
+        }
+
+        if (size_y > scale) {
+            scale = size_y;
+        }
+
+        if (size_z > scale) {
+            scale = size_z;
+        }
+
+        const dx = x - ox;
+        const dy = y - oy;
+        const dz = z - oz;
+
+        const d_squared = dx * dx + dy * dy + dz * dz;
+
+        if (d_squared > far_squared) {
+            far_squared = d_squared;
+            far = p;
+        }
+    }
+
+    const tolerance = CLOTH_HOLD_LINE_TOLERANCE * scale;
+
+    const far_distance = Math.sqrt(far_squared);
+
+    if (!(far_distance > tolerance)) {
+        // One point, however many particles are held at it.
+        return false;
+    }
+
+    const inverse = 1 / far_distance;
+
+    const ax = (position[far] - ox) * inverse;
+    const ay = (position[far + 1] - oy) * inverse;
+    const az = (position[far + 2] - oz) * inverse;
+
+    const tolerance_squared = tolerance * tolerance;
+
+    for (let k = 1; k < held_count; k++) {
+        const p = held[k] * 3;
+
+        const rx = position[p] - ox;
+        const ry = position[p + 1] - oy;
+        const rz = position[p + 2] - oz;
+
+        const along = rx * ax + ry * ay + rz * az;
+
+        const qx = rx - along * ax;
+        const qy = ry - along * ay;
+        const qz = rz - along * az;
+
+        if (qx * qx + qy * qy + qz * qz > tolerance_squared) {
+            return false;
+        }
+    }
+
+    line[0] = ox;
+    line[1] = oy;
+    line[2] = oz;
+    line[3] = ax;
+    line[4] = ay;
+    line[5] = az;
+
+    return true;
+}
+
+/**
+ * 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, line, inverse_h_squared, collider_table) {
+    const particle_count = state.particle_count;
+
+    const position = state.position;
+    const inertial = state.inertial;
+    const mass_inverse = state.mass_inverse;
+
+    const ox = line[0];
+    const oy = line[1];
+    const oz = line[2];
+    const ax = line[3];
+    const ay = line[4];
+    const az = line[5];
+
+    const accumulator = ACCUMULATOR;
+
+    let gradient = 0;
+    let curvature = 0;
+    let path = 0;
+
+    for (let i = 0; i < particle_count; i++) {
+        const inverse_mass = mass_inverse[i];
+
+        if (inverse_mass === 0) {
+            continue;
+        }
+
+        const p = i * 3;
+
+        const x = position[p];
+        const y = position[p + 1];
+        const z = position[p + 2];
+
+        const rx = x - ox;
+        const ry = y - oy;
+        const rz = z - oz;
+
+        const tx = ay * rz - az * ry;
+        const ty = az * rx - ax * rz;
+        const tz = ax * ry - ay * rx;
+
+        // The vertex update's assembly, seeded the same way, with only the rows
+        // the turn can see.
+        cloth_vertex_accumulator_seed(accumulator, position, inertial, p, inverse_h_squared / inverse_mass);
+
+        cloth_leash_accumulate(accumulator, state, i);
+        cloth_backstop_accumulate(accumulator, state, i);
+
+        if (collider_table !== null) {
+            cloth_contact_accumulate(accumulator, state, i, collider_table);
+        }
+
+        // `f = −∇E_i`
+        const fx = accumulator[CVA_F_X];
+        const fy = accumulator[CVA_F_Y];
+        const fz = accumulator[CVA_F_Z];
+
+        gradient -= tx * fx + ty * fy + tz * fz;
+
+        const h_xx = accumulator[CVA_H_XX];
+        const h_yy = accumulator[CVA_H_YY];
+        const h_zz = accumulator[CVA_H_ZZ];
+        const h_xy = accumulator[CVA_H_XY];
+        const h_xz = accumulator[CVA_H_XZ];
+        const h_yz = accumulator[CVA_H_YZ];
+
+        curvature += tx * (h_xx * tx + h_xy * ty + h_xz * tz)
+            + ty * (h_xy * tx + h_yy * ty + h_yz * tz)
+            + tz * (h_xz * tx + h_yz * ty + h_zz * tz);
+
+        // `∇E_i·(a(a·r) − r)`, which is `f·r⊥`
+        const along = ax * rx + ay * ry + az * rz;
+
+        path += fx * (rx - along * ax) + fy * (ry - along * ay) + fz * (rz - along * az);
+    }
+
+    if (path > 0) {
+        curvature += path;
+    }
+
+    if (!(curvature > 0)) {
+        // Every free particle is on the axis: there is no turn to take.
+        return 0;
+    }
+
+    const theta = -gradient / curvature;
+
+    if (theta === 0) {
+        return 0;
+    }
+
+    // Rodrigues, about the line through `o`.
+    const cos = Math.cos(theta);
+    const sin = Math.sin(theta);
+    const versine = 1 - cos;
+
+    for (let i = 0; i < particle_count; i++) {
+        if (mass_inverse[i] === 0) {
+            continue;
+        }
+
+        const p = i * 3;
+
+        const rx = position[p] - ox;
+        const ry = position[p + 1] - oy;
+        const rz = position[p + 2] - oz;
+
+        const along = (ax * rx + ay * ry + az * rz) * versine;
+
+        position[p] = ox + rx * cos + (ay * rz - az * ry) * sin + ax * along;
+        position[p + 1] = oy + ry * cos + (az * rx - ax * rz) * sin + ay * along;
+        position[p + 2] = oz + rz * cos + (ax * ry - ay * rx) * sin + az * along;
+    }
+
+    return theta;
+}
+
+/**
+ * The `(f, H)` scratch, laid out as the vertex update's. Module-level and reused.
+ * @type {Float64Array}
+ * @private
+ */
+const ACCUMULATOR = new Float64Array(CVA_STRIDE);

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

@@ -0,0 +1,21 @@
+/**
+ * Total kinetic energy of a cloth's free particles, `Σ ½·|v|²/w` over every
+ * particle with a non-zero inverse mass `w`, in joules.
+ *
+ * A held particle (`w = 0`) is skipped rather than treated as infinitely heavy:
+ * its velocity is whatever its holder gave it, and a cloth hanging still from a
+ * moving hand has come to rest in every sense §7 P5 means. A cloth that has
+ * settled reads zero and a cloth that is ringing does not, which is why the
+ * measurements read this rather than a displacement threshold.
+ *
+ * A diagnostic for specs, measurements and the playgrounds; nothing in the
+ * step reads it.
+ *
+ * @param {ClothState} state
+ * @returns {number} joules
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function cloth_kinetic_energy(state: ClothState): number;
+//# sourceMappingURL=cloth_kinetic_energy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_kinetic_energy.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_kinetic_energy.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,yDALa,MAAM,CA8BlB"}

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

@@ -0,0 +1,45 @@
+/**
+ * Total kinetic energy of a cloth's free particles, `Σ ½·|v|²/w` over every
+ * particle with a non-zero inverse mass `w`, in joules.
+ *
+ * A held particle (`w = 0`) is skipped rather than treated as infinitely heavy:
+ * its velocity is whatever its holder gave it, and a cloth hanging still from a
+ * moving hand has come to rest in every sense §7 P5 means. A cloth that has
+ * settled reads zero and a cloth that is ringing does not, which is why the
+ * measurements read this rather than a displacement threshold.
+ *
+ * A diagnostic for specs, measurements and the playgrounds; nothing in the
+ * step reads it.
+ *
+ * @param {ClothState} state
+ * @returns {number} joules
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function cloth_kinetic_energy(state) {
+    const particle_count = state.particle_count;
+
+    const mass_inverse = state.mass_inverse;
+    const velocity = state.velocity;
+
+    let energy = 0;
+
+    for (let i = 0; i < particle_count; i++) {
+        const w = mass_inverse[i];
+
+        if (w === 0) {
+            continue;
+        }
+
+        const p = i * 3;
+
+        const vx = velocity[p];
+        const vy = velocity[p + 1];
+        const vz = velocity[p + 2];
+
+        energy += 0.5 * (vx * vx + vy * vy + vz * vz) / w;
+    }
+
+    return energy;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * The particle graph a cloth's rows imply: an edge between every two particles
+ * that share a row, as a sorted CSR adjacency.
+ *
+ * A stretch row couples its two endpoints; a bend stencil couples all six pairs
+ * of its four particles, since every one of them appears in the same row. Two
+ * build-time consumers want exactly this set — the colouring, where an edge is
+ * a pair that must not be updated at once (`cloth_color_particles.js`), and the
+ * self-collision exclusions, where it is a pair a row already governs
+ * (`cloth_self_find.js`) — and this is the one place it is built.
+ *
+ * The set is deduplicated, because a garment adds every hinge's shared edge
+ * once as a stretch row and again as a bend pair, so duplicates are the common
+ * case; and a row that names one particle twice couples nothing. Each particle's
+ * partners come out ascending, which is the contract the exclusion scans read.
+ *
+ * Build-time only: it allocates its result and a scratch the size of the
+ * half-edge list.
+ *
+ * @param {number} particle_count
+ * @param {Int32Array|number[]} stretch_particle particle index pairs, 2 per row
+ * @param {number} stretch_count
+ * @param {Int32Array|number[]} bend_particle particle index quads, 4 per row
+ * @param {number} bend_count
+ * @returns {{offset: Int32Array, partner: Int32Array}} `partner[offset[i] .. offset[i + 1])` are the
+ *   particles sharing a row with `i`, ascending, without `i` itself
+ */
+export function cloth_particle_coupling(particle_count: number, stretch_particle: Int32Array | number[], stretch_count: number, bend_particle: Int32Array | number[], bend_count: number): {
+    offset: Int32Array;
+    partner: Int32Array;
+};
+//# sourceMappingURL=cloth_particle_coupling.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_particle_coupling.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_particle_coupling.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wDARW,MAAM,oBACN,UAAU,GAAC,MAAM,EAAE,iBACnB,MAAM,iBACN,UAAU,GAAC,MAAM,EAAE,cACnB,MAAM,GACJ;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CAyGrD"}