@woosh/meep-engine 3.24.0 → 3.26.0

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

@@ -12,9 +12,12 @@
  * @param {Float32Array|Float64Array} table packed colliders, cloth-local
  * @param {Int32Array} keys index handle per record in `table`
  * @param {number} count records in `table`
+ * @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
  * @returns {number} how many contact rows were created
  */
-export function cloth_contact_find(state: ClothState, table: Float32Array | Float64Array, keys: Int32Array, count: number): number;
+export function cloth_contact_find(state: ClothState, table: Float32Array | Float64Array, keys: Int32Array, count: number, dt: number): number;
 /**
  * # Finding the contacts, once per step
  *
@@ -54,11 +57,30 @@ export function cloth_contact_find(state: ClothState, table: Float32Array | Floa
  * to the reach costs one subtraction per record per step and makes the whole
  * range from 2 to 40 m/s behave the same way. `MEASUREMENTS.md` §20.
  *
+ * **And it has to include how far the *particle* moves**, which M2 left out and
+ * argued its way past. The paragraph that used to stand here said a cloth
+ * approaching faster than half a metre a second is one "the velocity clamp of
+ * §7 P1 is already the bound on". It is not: that clamp is
+ * `shortest_row · substeps · iterations / dt` times four, which for a garment is
+ * about **154 m/s** — three orders of magnitude above the speed at which this
+ * margin stops covering the approach. A collider that does not move is not a
+ * collider a cloth cannot hit. Measured, one particle at 8 mm against a static
+ * 3 cm capsule with no gravity at 2 × 4: at 1 and 2 m/s the rows appear and hold
+ * it; at 3 m/s and above there is **no row on the step it crosses the axis**,
+ * and the row the next step finally makes is on the far side and pushes it the
+ * rest of the way out. So the reach carries `|v_i|·dt` per particle as well —
+ * one square root per particle per step, hoisted out of the record loop.
+ * `MEASUREMENTS.md` §54.
+ *
  * That is also the honest boundary of P3's "swept collision": the *set* is
- * swept by this margin, and the *poses* are swept by `cloth_collider_pose_at`.
- * Both are translation-first — a collider spinning fast enough that a point on
- * its surface travels more than its own radius within one substep is still
- * missed, and more substeps is the answer to that.
+ * swept by both margins, and the *poses* are swept by `cloth_collider_pose_at`.
+ * All of it is translation-first — a collider spinning fast enough that a point
+ * on its surface travels more than its own radius within one substep is still
+ * missed, and more substeps is the answer to that. And the *set* being right is
+ * necessary rather than sufficient: a row that exists is still evaluated at
+ * substep positions, so a particle crossing a whole collider inside one substep
+ * has a row that never sees it touching. That bound is `substeps` and nothing
+ * else, and §54 measures where it lands.
  *
  * ## Warm-starting across the rebuild
  *
@@ -78,9 +100,8 @@ export function cloth_contact_find(state: ClothState, table: Float32Array | Floa
  *
  * One, so a row exists from twice the offset inwards. At a garment's 8 mm that
  * is 8 mm of warning, which at 60 Hz covers half a metre a second of approach
- * before a substep can carry a particle past the discovery — and a cloth moving
- * faster than that relative to a collider is one the velocity clamp of §7 P1 is
- * already the bound on.
+ * on its own — and the rest of the approach, from either side, is what the two
+ * travel terms in {@link cloth_contact_find} add to it.
  * @type {number}
  */
 export const CLOTH_CONTACT_MARGIN: number;

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":"AA8FA;;;;;;;;;;;;;;;GAeG;AACH,6DALW,YAAY,GAAC,YAAY,QACzB,UAAU,SACV,MAAM,GACJ,MAAM,CA4KlB;AAjQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;;;;;;;;;;GAUG;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;;;;;;;;;;;;;;;;;;GAkBG;AACH,6DARW,YAAY,GAAC,YAAY,QACzB,UAAU,SACV,MAAM,MACN,MAAM,GAGJ,MAAM,CAmLlB;AA7RD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAEH;;;;;;;;;GASG;AACH,mCAFU,MAAM,CAEsB"}

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

@@ -60,11 +60,30 @@ import { CLOTH_CONTACT_SLOTS } from "./constraint/cloth_contact_row.js";
  * to the reach costs one subtraction per record per step and makes the whole
  * range from 2 to 40 m/s behave the same way. `MEASUREMENTS.md` §20.
  *
+ * **And it has to include how far the *particle* moves**, which M2 left out and
+ * argued its way past. The paragraph that used to stand here said a cloth
+ * approaching faster than half a metre a second is one "the velocity clamp of
+ * §7 P1 is already the bound on". It is not: that clamp is
+ * `shortest_row · substeps · iterations / dt` times four, which for a garment is
+ * about **154 m/s** — three orders of magnitude above the speed at which this
+ * margin stops covering the approach. A collider that does not move is not a
+ * collider a cloth cannot hit. Measured, one particle at 8 mm against a static
+ * 3 cm capsule with no gravity at 2 × 4: at 1 and 2 m/s the rows appear and hold
+ * it; at 3 m/s and above there is **no row on the step it crosses the axis**,
+ * and the row the next step finally makes is on the far side and pushes it the
+ * rest of the way out. So the reach carries `|v_i|·dt` per particle as well —
+ * one square root per particle per step, hoisted out of the record loop.
+ * `MEASUREMENTS.md` §54.
+ *
  * That is also the honest boundary of P3's "swept collision": the *set* is
- * swept by this margin, and the *poses* are swept by `cloth_collider_pose_at`.
- * Both are translation-first — a collider spinning fast enough that a point on
- * its surface travels more than its own radius within one substep is still
- * missed, and more substeps is the answer to that.
+ * swept by both margins, and the *poses* are swept by `cloth_collider_pose_at`.
+ * All of it is translation-first — a collider spinning fast enough that a point
+ * on its surface travels more than its own radius within one substep is still
+ * missed, and more substeps is the answer to that. And the *set* being right is
+ * necessary rather than sufficient: a row that exists is still evaluated at
+ * substep positions, so a particle crossing a whole collider inside one substep
+ * has a row that never sees it touching. That bound is `substeps` and nothing
+ * else, and §54 measures where it lands.
  *
  * ## Warm-starting across the rebuild
  *
@@ -85,9 +104,8 @@ import { CLOTH_CONTACT_SLOTS } from "./constraint/cloth_contact_row.js";
  *
  * One, so a row exists from twice the offset inwards. At a garment's 8 mm that
  * is 8 mm of warning, which at 60 Hz covers half a metre a second of approach
- * before a substep can carry a particle past the discovery — and a cloth moving
- * faster than that relative to a collider is one the velocity clamp of §7 P1 is
- * already the bound on.
+ * on its own — and the rest of the approach, from either side, is what the two
+ * travel terms in {@link cloth_contact_find} add to it.
  * @type {number}
  */
 export const CLOTH_CONTACT_MARGIN = 1;
@@ -106,9 +124,12 @@ export const CLOTH_CONTACT_MARGIN = 1;
  * @param {Float32Array|Float64Array} table packed colliders, cloth-local
  * @param {Int32Array} keys index handle per record in `table`
  * @param {number} count records in `table`
+ * @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
  * @returns {number} how many contact rows were created
  */
-export function cloth_contact_find(state, table, keys, count) {
+export function cloth_contact_find(state, table, keys, count, dt) {
     const particle_count = state.particle_count;
 
     const collider = state.contact_collider;
@@ -120,6 +141,7 @@ export function cloth_contact_find(state, table, keys, count) {
     const anchor = state.contact_anchor;
 
     const position = state.position;
+    const velocity = state.velocity;
     const mass_inverse = state.mass_inverse;
 
     const radius = state.contact_radius;
@@ -188,12 +210,18 @@ export function cloth_contact_find(state, table, keys, count) {
         const y = position[p + 1];
         const z = position[p + 2];
 
+        // 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]);
+
         let found = 0;
 
         for (let record = 0; record < count; record++) {
             const r = record * CCR_STRIDE;
 
-            const reach = (radius + table[r + CCR_INFLATION]) * (1 + CLOTH_CONTACT_MARGIN) + TRAVEL[record];
+            const reach = (radius + table[r + CCR_INFLATION]) * (1 + CLOTH_CONTACT_MARGIN)
+                + TRAVEL[record] + travel;
 
             if (x + reach < table[r + CCR_AABB_MIN_X] || x - reach > table[r + CCR_AABB_MAX_X]) {
                 continue;

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

@@ -37,8 +37,18 @@
  * two clear of divergence.** γ is left at 1 because its second job — decaying
  * the penalty — has nothing to do while the band is a single point, so putting
  * the whole decay in α, whose only job is the multiplier, is the truthful
- * placement. When M2's contacts make the band real again, γ becomes live and
- * has to be re-measured.
+ * placement.
+ *
+ * **γ is the one unmeasured constant in this file, and that is now a decision.**
+ * The sentence above used to end "when M2's contacts make the band real again, γ
+ * becomes live and has to be re-measured". M2 made the band real — a contact's
+ * floor is {@link CLOTH_CONTACT_K_MIN_RATIO} and its ceiling is
+ * {@link CLOTH_K_MAX_RATIO} — and the sweep was never run. Nothing measured
+ * since has asked for a decaying penalty; what a `γ < 1` *would* reach is the
+ * one thing PLAN §18 records as a coupling rather than a bug, which is that a
+ * contact's penalty ramps to the ceiling and never comes back down. Sweeping it
+ * means re-measuring every hard row in the system against `α·γ`, because the two
+ * act only through their product and `α` is the one that was measured.
  *
  * **`k_min` and `k_max` are equal, which disables the ramp.** Pinning the
  * penalty at the top of the band measured as good as or better than every
@@ -189,6 +199,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;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

@@ -37,8 +37,18 @@
  * two clear of divergence.** γ is left at 1 because its second job — decaying
  * the penalty — has nothing to do while the band is a single point, so putting
  * the whole decay in α, whose only job is the multiplier, is the truthful
- * placement. When M2's contacts make the band real again, γ becomes live and
- * has to be re-measured.
+ * placement.
+ *
+ * **γ is the one unmeasured constant in this file, and that is now a decision.**
+ * The sentence above used to end "when M2's contacts make the band real again, γ
+ * becomes live and has to be re-measured". M2 made the band real — a contact's
+ * floor is {@link CLOTH_CONTACT_K_MIN_RATIO} and its ceiling is
+ * {@link CLOTH_K_MAX_RATIO} — and the sweep was never run. Nothing measured
+ * since has asked for a decaying penalty; what a `γ < 1` *would* reach is the
+ * one thing PLAN §18 records as a coupling rather than a bug, which is that a
+ * contact's penalty ramps to the ceiling and never comes back down. Sweeping it
+ * means re-measuring every hard row in the system against `α·γ`, because the two
+ * act only through their product and `α` is the one that was measured.
  *
  * **`k_min` and `k_max` are equal, which disables the ramp.** Pinning the
  * penalty at the top of the band measured as good as or better than every
@@ -199,6 +209,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"}