@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -189,6 +189,39 @@ export const CLOTH_SELF_RADIUS_MIN_RATIO: number;
  * @type {number}
  */
 export const CLOTH_SELF_RADIUS_MAX_RATIO: number;
+/**
+ * How many collider records one cloth's per-step table holds.
+ *
+ * The table is the broadphase's answer for this step, written by
+ * `cloth_gather_colliders` and read by the contact search and the vertex
+ * update. M4 kept it on the instance and grew it on demand; M5 moved it into
+ * {@link ClothState}'s single buffer, which is where §12's table always put it
+ * — and a region inside one allocation has to be sized rather than grown.
+ *
+ * **A capacity rather than a growth policy is the point.** The worker steps a
+ * cloth out of shared memory, and memory whose size can change mid-run is
+ * memory the worker has to be told about again before it can be named — a
+ * cold-plane round trip in the middle of a step. Fixing the size makes
+ * `ClothSystem` and `WorkerClothSystem` read the same bytes by construction
+ * instead of by agreement, which is what the §12 parity gate is.
+ *
+ * **The number is a scene bound rather than a garment bound**, which is what the
+ * measurement changed about it. A garment's query box is its own bounds fattened
+ * by a step's travel, so what lands in the table is *every collider on every
+ * character standing inside it* — one ten-part body fills ten slots, two fill
+ * twenty, three fill twenty-eight (`MEASUREMENTS.md` §41). Sizing this to a
+ * garment would have been sizing it to the wrong thing.
+ *
+ * Sixty-four, so a cloth can be inside six characters' collider sets before it
+ * drops anything, against M2's twenty-collider scene and §41's measured
+ * twenty-eight for three. A cloth past that keeps what the index returned first,
+ * which is **arbitrary among the overflow** — the index answers in its own
+ * order, not in order of how much a collider matters — so the capacity is set
+ * well clear of a plausible scene rather than tightly against it, and the drop
+ * warns once. Nine kilobytes a cloth, 1.4% of the §17 workload's state.
+ * @type {number}
+ */
+export const CLOTH_COLLIDER_SLOTS: number;
 /**
  * The five constants as one frozen object, which is what {@link cloth_step}
  * takes. A sweep passes its own; nothing else should.

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_solver_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solver_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH;;;GAGG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;GAIG;AACH,yBAFU,MAAM,CAEc;AAE9B;;;GAGG;AACH,0BAFU,MAAM,CAEa;AAE7B;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;;;;;;GASG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;GAIG;AACH,kCAFU,SAAS;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAAC,CAQvG"}
+{"version":3,"file":"cloth_solver_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solver_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH;;;GAGG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;GAIG;AACH,yBAFU,MAAM,CAEc;AAE9B;;;GAGG;AACH,0BAFU,MAAM,CAEa;AAE7B;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;;;;;;GASG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,mCAFU,MAAM,CAEuB;AAEvC;;;;GAIG;AACH,kCAFU,SAAS;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAAC,CAQvG"}

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

@@ -199,6 +199,40 @@ export const CLOTH_SELF_RADIUS_MIN_RATIO = 0.5;
  */
 export const CLOTH_SELF_RADIUS_MAX_RATIO = 0.4;
 
+/**
+ * How many collider records one cloth's per-step table holds.
+ *
+ * The table is the broadphase's answer for this step, written by
+ * `cloth_gather_colliders` and read by the contact search and the vertex
+ * update. M4 kept it on the instance and grew it on demand; M5 moved it into
+ * {@link ClothState}'s single buffer, which is where §12's table always put it
+ * — and a region inside one allocation has to be sized rather than grown.
+ *
+ * **A capacity rather than a growth policy is the point.** The worker steps a
+ * cloth out of shared memory, and memory whose size can change mid-run is
+ * memory the worker has to be told about again before it can be named — a
+ * cold-plane round trip in the middle of a step. Fixing the size makes
+ * `ClothSystem` and `WorkerClothSystem` read the same bytes by construction
+ * instead of by agreement, which is what the §12 parity gate is.
+ *
+ * **The number is a scene bound rather than a garment bound**, which is what the
+ * measurement changed about it. A garment's query box is its own bounds fattened
+ * by a step's travel, so what lands in the table is *every collider on every
+ * character standing inside it* — one ten-part body fills ten slots, two fill
+ * twenty, three fill twenty-eight (`MEASUREMENTS.md` §41). Sizing this to a
+ * garment would have been sizing it to the wrong thing.
+ *
+ * Sixty-four, so a cloth can be inside six characters' collider sets before it
+ * drops anything, against M2's twenty-collider scene and §41's measured
+ * twenty-eight for three. A cloth past that keeps what the index returned first,
+ * which is **arbitrary among the overflow** — the index answers in its own
+ * order, not in order of how much a collider matters — so the capacity is set
+ * well clear of a plausible scene rather than tightly against it, and the drop
+ * warns once. Nine kilobytes a cloth, 1.4% of the §17 workload's state.
+ * @type {number}
+ */
+export const CLOTH_COLLIDER_SLOTS = 64;
+
 /**
  * The five constants as one frozen object, which is what {@link cloth_step}
  * takes. A sweep passes its own; nothing else should.

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

@@ -39,6 +39,21 @@
  * substep that is the collider's final pose, which is the one a particle must
  * not be inside when the step is over.
  *
+ * ## The external acceleration is per particle when there is wind
+ *
+ * Gravity is one vector for the whole cloth; §10's aerodynamic drag is not —
+ * it depends on the air each particle sits in and on which way that particle's
+ * own surface faces. So the predict and the integrate come in two forms, chosen
+ * once per substep rather than once per particle: the uniform pair, which is
+ * what a cloth with no air runs and what M0 through M5 measured, and a varying
+ * pair that reads `ClothState#external_acceleration` instead.
+ *
+ * Two loops rather than a branch inside one, because the branch would sit in the
+ * innermost per-particle loop of a step that has no wind in it. And the uniform
+ * pair is untouched rather than expressed as a special case of the varying one,
+ * which is what makes "no wind produces the bytes M5 measured" a fact about the
+ * code rather than a claim about floating point.
+ *
  * ## What each piece is for
  *
  * **Warm start** carries the multipliers into the next substep so a hard row
@@ -101,7 +116,8 @@
  *
  * @param {ClothState} state
  * @param {number} dt fixed step length, seconds — divided into `substeps`
- * @param {number} acceleration_x external acceleration, cloth-local, m/s²
+ * @param {number} acceleration_x external acceleration, cloth-local, m/s²; ignored
+ *   when `external` is given
  * @param {number} acceleration_y
  * @param {number} acceleration_z
  * @param {number} substeps
@@ -110,6 +126,9 @@
  *   cloth's own frame, with their contact rows already found
  * @param {number} [collider_count]
  * @param {{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number, self_ratio?: number}} [tuning]
+ * @param {Float32Array|null} [external] per-particle external acceleration,
+ *   cloth-local, 3 each — §10's wind, already carrying gravity. `null` takes the
+ *   uniform path above, which is what a scene with no air in it runs.
  */
 export function cloth_step(state: ClothState, dt: number, acceleration_x: number, acceleration_y: number, acceleration_z: number, substeps: number, iterations: number, collider_table?: Float32Array | Float64Array | null, collider_count?: number, tuning?: {
     alpha: number;
@@ -118,5 +137,5 @@ export function cloth_step(state: ClothState, dt: number, acceleration_x: number
     k_min_ratio: number;
     k_max_ratio: number;
     self_ratio?: number;
-}): void;
+}, external?: Float32Array | null): void;
 //# sourceMappingURL=cloth_step.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_step.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AAEH;;;;;;;;;;;;;;GAcG;AACH,kDAXW,MAAM,kBACN,MAAM,kBACN,MAAM,kBACN,MAAM,YACN,MAAM,cACN,MAAM,mBACN,YAAY,GAAC,YAAY,GAAC,IAAI,mBAE9B,MAAM,WACN;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAC,QA2FrH"}
+{"version":3,"file":"cloth_step.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgHG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,kDAfW,MAAM,kBACN,MAAM,kBAEN,MAAM,kBACN,MAAM,YACN,MAAM,cACN,MAAM,mBACN,YAAY,GAAC,YAAY,GAAC,IAAI,mBAE9B,MAAM,WACN;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAC,aAC3G,YAAY,GAAC,IAAI,QAsG3B"}

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

@@ -70,6 +70,21 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  * substep that is the collider's final pose, which is the one a particle must
  * not be inside when the step is over.
  *
+ * ## The external acceleration is per particle when there is wind
+ *
+ * Gravity is one vector for the whole cloth; §10's aerodynamic drag is not —
+ * it depends on the air each particle sits in and on which way that particle's
+ * own surface faces. So the predict and the integrate come in two forms, chosen
+ * once per substep rather than once per particle: the uniform pair, which is
+ * what a cloth with no air runs and what M0 through M5 measured, and a varying
+ * pair that reads `ClothState#external_acceleration` instead.
+ *
+ * Two loops rather than a branch inside one, because the branch would sit in the
+ * innermost per-particle loop of a step that has no wind in it. And the uniform
+ * pair is untouched rather than expressed as a special case of the varying one,
+ * which is what makes "no wind produces the bytes M5 measured" a fact about the
+ * code rather than a claim about floating point.
+ *
  * ## What each piece is for
  *
  * **Warm start** carries the multipliers into the next substep so a hard row
@@ -133,7 +148,8 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  *
  * @param {ClothState} state
  * @param {number} dt fixed step length, seconds — divided into `substeps`
- * @param {number} acceleration_x external acceleration, cloth-local, m/s²
+ * @param {number} acceleration_x external acceleration, cloth-local, m/s²; ignored
+ *   when `external` is given
  * @param {number} acceleration_y
  * @param {number} acceleration_z
  * @param {number} substeps
@@ -142,6 +158,9 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  *   cloth's own frame, with their contact rows already found
  * @param {number} [collider_count]
  * @param {{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number, self_ratio?: number}} [tuning]
+ * @param {Float32Array|null} [external] per-particle external acceleration,
+ *   cloth-local, 3 each — §10's wind, already carrying gravity. `null` takes the
+ *   uniform path above, which is what a scene with no air in it runs.
  */
 export function cloth_step(
     state,
@@ -151,7 +170,8 @@ export function cloth_step(
     iterations,
     collider_table = null,
     collider_count = 0,
-    tuning = CLOTH_SOLVER_TUNING
+    tuning = CLOTH_SOLVER_TUNING,
+    external = null
 ) {
     assert.isPositiveInteger(substeps, 'substeps');
     assert.isPositiveInteger(iterations, 'iterations');
@@ -184,7 +204,11 @@ export function cloth_step(
     const contacts = collider_table !== null && collider_count > 0 ? collider_table : null;
 
     for (let substep = 0; substep < substeps; substep++) {
-        cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z);
+        if (external === null) {
+            cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z);
+        } else {
+            cloth_predict_varying(state, h, external);
+        }
 
         if (contacts !== null) {
             cloth_collider_pose_at(contacts, collider_count, (substep + 1) / substeps);
@@ -225,7 +249,11 @@ export function cloth_step(
             }
         }
 
-        cloth_integrate(state, inverse_h, acceleration_x, acceleration_y, acceleration_z);
+        if (external === null) {
+            cloth_integrate(state, inverse_h, acceleration_x, acceleration_y, acceleration_z);
+        } else {
+            cloth_integrate_varying(state, inverse_h, external);
+        }
     }
 
     assert.equal(
@@ -331,6 +359,70 @@ function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z)
     }
 }
 
+/**
+ * {@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.
+ *
+ * @param {ClothState} state
+ * @param {number} h
+ * @param {Float32Array} external 3 per particle, cloth-local, m/s²
+ * @private
+ */
+function cloth_predict_varying(state, h, external) {
+    const particle_count = state.particle_count;
+
+    const position = state.position;
+    const position_previous = state.position_previous;
+    const velocity = state.velocity;
+    const inertial = state.inertial;
+    const mass_inverse = state.mass_inverse;
+    const inertia_blend = state.inertia_blend;
+
+    const h_squared = h * h;
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        const x = position[p];
+        const y = position[p + 1];
+        const z = position[p + 2];
+
+        position_previous[p] = x;
+        position_previous[p + 1] = y;
+        position_previous[p + 2] = z;
+
+        if (mass_inverse[i] === 0) {
+            inertial[p] = x;
+            inertial[p + 1] = y;
+            inertial[p + 2] = z;
+
+            continue;
+        }
+
+        const drift_x = h * velocity[p];
+        const drift_y = h * velocity[p + 1];
+        const drift_z = h * velocity[p + 2];
+
+        const push_x = h_squared * external[p];
+        const push_y = h_squared * external[p + 1];
+        const push_z = h_squared * external[p + 2];
+
+        inertial[p] = x + drift_x + push_x;
+        inertial[p + 1] = y + drift_y + push_y;
+        inertial[p + 2] = z + drift_z + push_z;
+
+        const blend = inertia_blend[i];
+
+        position[p] = x + drift_x + blend * push_x;
+        position[p + 1] = y + drift_y + blend * push_y;
+        position[p + 2] = z + drift_z + blend * push_z;
+    }
+}
+
 /**
  * Integrate: read velocity back out of the positions the descent produced, and
  * record how much of the resulting acceleration was the external one so the
@@ -399,3 +491,80 @@ function cloth_integrate(state, inverse_h, acceleration_x, acceleration_y, accel
         velocity[p + 2] = next_z;
     }
 }
+
+/**
+ * {@link cloth_integrate} with a per-particle external acceleration.
+ *
+ * The adaptive-initialisation blend is a projection of the realised acceleration
+ * onto the external one, so with wind it is projected onto **that particle's**
+ * external acceleration rather than onto gravity — which is the answer that
+ * keeps its meaning: a particle being carried sideways by a gust is in free fall
+ * along the direction it is actually being accelerated in, and seeding it along
+ * gravity instead would be seeding it against most of what is happening to it.
+ *
+ * @param {ClothState} state
+ * @param {number} inverse_h
+ * @param {Float32Array} external 3 per particle, cloth-local, m/s²
+ * @private
+ */
+function cloth_integrate_varying(state, inverse_h, external) {
+    const particle_count = state.particle_count;
+
+    const position = state.position;
+    const position_previous = state.position_previous;
+    const velocity = state.velocity;
+    const mass_inverse = state.mass_inverse;
+    const inertia_blend = state.inertia_blend;
+
+    for (let i = 0; i < particle_count; i++) {
+        if (mass_inverse[i] === 0) {
+            continue;
+        }
+
+        const p = i * 3;
+
+        const acceleration_x = external[p];
+        const acceleration_y = external[p + 1];
+        const acceleration_z = external[p + 2];
+
+        const acceleration_squared =
+            acceleration_x * acceleration_x +
+            acceleration_y * acceleration_y +
+            acceleration_z * acceleration_z;
+
+        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;
+
+        if (acceleration_squared > 0) {
+            const realised =
+                (next_x - velocity[p]) * acceleration_x +
+                (next_y - velocity[p + 1]) * acceleration_y +
+                (next_z - velocity[p + 2]) * acceleration_z;
+
+            // The reciprocal rather than the division, which is the form
+            // {@link cloth_integrate} uses — the two differ in the last bit, and
+            // a cloth whose external acceleration happens to be exactly gravity
+            // should follow the same trajectory whichever loop stepped it.
+            let blend = realised * inverse_h * (1 / acceleration_squared);
+
+            if (blend < 0) {
+                blend = 0;
+            } else if (blend > 1) {
+                blend = 1;
+            }
+
+            inertia_blend[i] = blend;
+        } else {
+            // No direction to project onto, so nothing to seed. The uniform
+            // path reaches this for the whole cloth at once; here it is a
+            // particle whose air exactly cancels its gravity, which is a real
+            // configuration rather than a degenerate one.
+            inertia_blend[i] = 0;
+        }
+
+        velocity[p] = next_x;
+        velocity[p + 1] = next_y;
+        velocity[p + 2] = next_z;
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Step one cloth.
+ *
+ * @param {ClothState} state the cloth, with its collider table already gathered
+ * @param {{offset: Int32Array, partner: Int32Array}|null} self_exclusions pairs
+ *   a persistent row already governs; `null` when the cloth never self-collides
+ * @param {Float64Array} params
+ * @param {number} offset first word of this cloth's block in `params`
+ * @returns {void}
+ */
+export function cloth_step_instance(state: ClothState, self_exclusions: {
+    offset: Int32Array;
+    partner: Int32Array;
+} | null, params: Float64Array, offset: number): void;
+/**
+ * Words of one cloth's parameter block.
+ */
+export type ClothStepParam = number;
+export namespace ClothStepParam {
+    let ID: number;
+    let DT: number;
+    let GRAVITY_X: number;
+    let GRAVITY_Y: number;
+    let GRAVITY_Z: number;
+    let SUBSTEPS: number;
+    let ITERATIONS: number;
+    let RETENTION: number;
+    let VELOCITY_LIMIT: number;
+    let CONTACT_RADIUS: number;
+    let SELF_RADIUS: number;
+    let COLLIDER_COUNT: number;
+    let SELF_COLLISION: number;
+    let DRAG_RESPONSE: number;
+}
+/**
+ * `Float64` words one cloth's parameter block occupies.
+ * @type {number}
+ */
+export const CLOTH_STEP_PARAM_STRIDE: number;
+//# sourceMappingURL=cloth_step_instance.d.ts.map

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

@@ -0,0 +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"}