@woosh/meep-engine 3.24.0 → 3.26.0

package/src/engine/physics/cloth/ecs/cloth_dynamics_map.d.ts

@@ -31,6 +31,36 @@ export function cloth_bend_ratio(bend: number): number;
  * @returns {number}
  */
 export function cloth_velocity_limit(shortest_row: number, substeps: number, iterations: number, dt: number): number;
+/**
+ * §10's aerodynamic coupling as the **per-step response** the step multiplies
+ * the relative flow by, 1/s.
+ *
+ * Not a rate, and the difference is a stability argument rather than a
+ * convenience. The step holds one acceleration for the whole fixed step, so an
+ * explicit `rate·(u − v)` changes the velocity by `rate·dt·(u − v)` — which
+ * overshoots the air once `rate·dt > 1` and diverges past 2. §1's first
+ * commitment is "not at 5 fps", which is a `dt` of 0.2 s and a rate of 10.
+ *
+ * The exact solution of the same linear ODE has no such boundary:
+ *
+ *     Δv = (1 − e^(−rate·dt))·(u − v)
+ *
+ * closes a fraction of the gap that is strictly below one for every `rate` and
+ * every `dt`, so the drag can never push a particle past the air it is
+ * relaxing toward. Dividing by `dt` turns it back into the acceleration the
+ * solver wants, and the exponential is evaluated **once per cloth per step** on
+ * the main thread rather than per particle.
+ *
+ * It is also the same step `GlobalFluidEffector` takes for the air itself —
+ * both are relaxations toward a velocity, and a cloth and the air around it
+ * reaching their common answer by the same arithmetic is a symmetry worth
+ * having.
+ *
+ * @param {number} drag `[0, 1]`
+ * @param {number} dt fixed step, seconds
+ * @returns {number} 1/s; `0` when there is no coupling at all
+ */
+export function cloth_drag_response(drag: number, dt: number): number;
 /**
  * Fraction of a particle's velocity surviving one fixed step. §7 P5, and see
  * {@link ClothDynamics#damping} for why this is a correctness mechanism rather
@@ -219,12 +249,64 @@ export const CLOTH_TELEPORT_FLOOR: number;
  */
 export const CLOTH_STABILISE_STEPS: number;
 /**
- * Speed below which a particle counts as still, as a fraction of the cloth's
- * reach per second. A metre-long rope sleeps once nothing on it is moving
- * faster than a millimetre a second.
+ * Aerodynamic relaxation rate at `drag = 1`, per second (§10).
+ *
+ * ## Linear, not log
+ *
+ * `bend` is log-mapped because a stiffness spans decades and an author needs
+ * the whole range to be useful. Drag does not: the library's own entries run
+ * from leather at 0.05 to silk at 0.45, a factor of nine, and a linear map is
+ * the one that keeps that factor of nine meaning a factor of nine. It is also
+ * exactly zero at zero without a special case, which a log map cannot be.
+ *
+ * ## Sixty, because that is "the cloth goes where the air goes"
+ *
+ * The rate is a reciprocal time constant, so what `drag = 1` has to mean is a
+ * cloth with no aerodynamic memory at all — one that takes the air's velocity
+ * within a step. At 60 Hz, a rate of 60 closes 63% of the gap to the air every
+ * step and has a time constant of 17 ms, which is that. The library then reads:
+ * silk 27/s (37 ms), hair 18/s, cotton 12/s (83 ms), rope 7.2/s, denim 4.8/s
+ * (0.21 s), leather and chain 3/s (0.33 s) — a light banner that answers a gust
+ * within a couple of frames and an armour skirt that takes a third of a second
+ * to notice one, which is the ordering the fabrics already claimed.
+ *
+ * Raising it further buys nothing: {@link cloth_drag_response} saturates at
+ * `1/dt` by construction, so past about `1/dt` the whole range compresses into
+ * "the cloth is a streamer". `MEASUREMENTS.md` §48.
+ * @type {number}
+ */
+export const CLOTH_DRAG_RATE_MAX: number;
+/**
+ * Speed below which the air counts as unchanged, as a fraction of the cloth's
+ * reach per second — §10's wake test, which asks whether a gust has arrived.
+ *
+ * This was the sleep test's own threshold until the sleep test stopped reading
+ * a speed; see {@link CLOTH_SLEEP_DISPLACEMENT_RATIO} for why.
  * @type {number}
  */
 export const CLOTH_SLEEP_SPEED_RATIO: number;
+/**
+ * How far a particle may travel from the window's anchor and still count as
+ * still, as a fraction of the cloth's reach (§7 P5).
+ *
+ * **Displacement rather than speed, and a contact is why.** A cloth resting on
+ * a collider carries contact rows whose penalty `γ = 1` never decays, and the
+ * configuration it settles into is a *bounded limit cycle* rather than a rest
+ * state: measured on an 8-link rope on a floor, a tenth of a millimetre of
+ * travel per step — invisible — at a peak particle speed of 1.5e-2 m/s, which
+ * is eighteen times what the old speed threshold allowed. An instantaneous
+ * speed cannot tell a cloth vibrating in place apart from one going somewhere;
+ * the distance it has covered since the window opened can, and that is what
+ * §7 P5's own text has always described.
+ *
+ * `5e-4` rather than {@link CLOTH_SLEEP_SPEED_RATIO}'s `1e-3` so the gate is no
+ * *looser* than the speed test it replaces: over the {@link CLOTH_SLEEP_STEPS}
+ * window at the engine's 60 Hz fixed step, half a thousandth of a reach is the
+ * same millimetre a second. Every library entry on a floor or a sphere sleeps
+ * inside 961 steps at this value. `MEASUREMENTS.md` §53.
+ * @type {number}
+ */
+export const CLOTH_SLEEP_DISPLACEMENT_RATIO: number;
 /**
  * How many consecutive still steps put a cloth to sleep (§7 P5). Half a second
  * at 60 Hz, which is long enough that a cloth pausing at the top of a swing

package/src/engine/physics/cloth/ecs/cloth_dynamics_map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_dynamics_map.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_dynamics_map.js"],"names":[],"mappings":"AA6MA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;;GAQG;AACH,uCAHW,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;;;GAWG;AACH,mDAPW,MAAM,YAEN,MAAM,cACN,MAAM,MACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;GAQG;AACH,kDAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;AA9QD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;GAKG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;;;;;;;GAWG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;GAKG;AACH,mCAFU,MAAM,CAEyB;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,+CAFU,MAAM,CAEkC;AAElD;;;;;;;;GAQG;AACH,iCAFU,MAAM,CAEqB;AAErC;;;;;;;;;;;;;GAaG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;GAQG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;;;;GAQG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH,oCAFU,MAAM,CAEwB;AAExC;;;;;GAKG;AACH,sCAFU,MAAM,CAE4B;AAE5C;;;;;GAKG;AACH,gCAFU,MAAM,CAEoB"}
+{"version":3,"file":"cloth_dynamics_map.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_dynamics_map.js"],"names":[],"mappings":"AAmQA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;;GAQG;AACH,uCAHW,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;;;GAWG;AACH,mDAPW,MAAM,YAEN,MAAM,cACN,MAAM,MACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,0CAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;;GAQG;AACH,kDAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;AA7WD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;GAKG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;;;;;;;GAWG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;GAKG;AACH,mCAFU,MAAM,CAEyB;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,+CAFU,MAAM,CAEkC;AAElD;;;;;;;;GAQG;AACH,iCAFU,MAAM,CAEqB;AAErC;;;;;;;;;;;;;GAaG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;GAQG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;;;;GAQG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH,oCAFU,MAAM,CAEwB;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH,sCAFU,MAAM,CAE4B;AAE5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,6CAFU,MAAM,CAEmC;AAEnD;;;;;GAKG;AACH,gCAFU,MAAM,CAEoB"}