@woosh/meep-engine 2.138.20 → 2.139.0

package/src/core/math/linalg/eigen/matrix_qr_in_place.d.ts

@@ -2,10 +2,12 @@
  * Perform QR factorization in-place.
  * Subfunction that analyzes eigenvalues by QR decomposition.
  *
- * Single-shift Wilkinson iteration: deflates the trailing subdiagonal one row
- * at a time as it converges. A complex eigenvalue pair leaves a 2×2 trailing
- * block whose inner subdiagonal does not vanish, and this routine will spin
- * on it indefinitely — only safe today for matrices with all-real eigenvalues.
+ * Single-shift Wilkinson iteration with LAPACK-style exceptional shifts:
+ * deflates the trailing subdiagonal one row at a time as it converges. A
+ * complex eigenvalue pair leaves a 2×2 trailing block whose inner subdiagonal
+ * does not vanish — only safe today for matrices with all-real eigenvalues.
+ * If convergence fails within 30·n sweeps (LAPACK convention), the routine
+ * throws rather than spinning.
  *
  * @see http://www-in.aut.ac.jp/~minemura/pub/Csimu/C/QRmethod.html
  * @param {number[]|Float64Array} a Square matrix, column-major flat layout (a[j*n + i] = row i, col j); modified in place (R is left on the upper triangle)

package/src/core/math/linalg/eigen/matrix_qr_in_place.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"matrix_qr_in_place.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_qr_in_place.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,sCAHW,MAAM,EAAE,GAAC,YAAY,KACrB,MAAM,QAkIhB"}
+{"version":3,"file":"matrix_qr_in_place.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_qr_in_place.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,sCAHW,MAAM,EAAE,GAAC,YAAY,KACrB,MAAM,QA8KhB"}

package/src/core/math/linalg/eigen/matrix_qr_in_place.js

@@ -4,10 +4,12 @@ const EPSILON = 1e-10;
  * Perform QR factorization in-place.
  * Subfunction that analyzes eigenvalues by QR decomposition.
  *
- * Single-shift Wilkinson iteration: deflates the trailing subdiagonal one row
- * at a time as it converges. A complex eigenvalue pair leaves a 2×2 trailing
- * block whose inner subdiagonal does not vanish, and this routine will spin
- * on it indefinitely — only safe today for matrices with all-real eigenvalues.
+ * Single-shift Wilkinson iteration with LAPACK-style exceptional shifts:
+ * deflates the trailing subdiagonal one row at a time as it converges. A
+ * complex eigenvalue pair leaves a 2×2 trailing block whose inner subdiagonal
+ * does not vanish — only safe today for matrices with all-real eigenvalues.
+ * If convergence fails within 30·n sweeps (LAPACK convention), the routine
+ * throws rather than spinning.
  *
  * @see http://www-in.aut.ac.jp/~minemura/pub/Csimu/C/QRmethod.html
  * @param {number[]|Float64Array} a Square matrix, column-major flat layout (a[j*n + i] = row i, col j); modified in place (R is left on the upper triangle)
@@ -22,40 +24,81 @@ export function matrix_qr_in_place(a, n) {
 
     let i, j, k;
 
+    // LAPACK convention: ~30 QR sweeps per eigenvalue. Hitting this means
+    // we're stuck (typically a complex eigenvalue pair the single-shift can't
+    // deflate) — fail loudly rather than spin forever.
+    const MAX_SWEEPS = 30 * n;
+    let sweeps = 0;
+    // Sweeps since the last deflation. Drives exceptional-shift fallbacks
+    // when the standard Wilkinson shift stalls (typical pathology: a trailing
+    // block with near-symmetric ±λ eigenvalues — the shift oscillates and
+    // single-shift QR converges only linearly without a perturbation).
+    let sweeps_since_deflation = 0;
+
     while (m > 1) {
         // a[m-1, m-2] in column-major: (m-2)*n + (m-1)
         const a10_index = (m - 2) * n + (m - 1);
 
         const a10 = a[a10_index];
 
-        //   Convergence test
-        if (Math.abs(a10) < EPSILON) {
+        // Relative convergence test (LAPACK xLAHQR convention): subdiagonal
+        // is "small" when it falls below EPSILON × the magnitude of the
+        // surrounding 2×2 diagonal. Scales correctly with matrix magnitude.
+        // Falls back to the absolute EPSILON when both diagonal entries
+        // collapse to zero, so we don't refuse to deflate a zero block.
+        const a00_abs = Math.abs(a[(m - 2) * n + (m - 2)]);
+        const a11_abs = Math.abs(a[(m - 1) * n + (m - 1)]);
+        const diagScale = a00_abs + a11_abs;
+        const convTol = diagScale > 0 ? EPSILON * diagScale : EPSILON;
+
+        if (Math.abs(a10) <= convTol) {
             m = m - 1;
+            sweeps_since_deflation = 0;
             continue;
         }
 
-        //   Origin movement mu (compute Wilkinson's shift)
+        if (++sweeps > MAX_SWEEPS) {
+            throw new Error(`matrix_qr_in_place: failed to converge after ${MAX_SWEEPS} sweeps (likely complex eigenvalue pair; single-shift QR only handles real spectra)`);
+        }
+        sweeps_since_deflation++;
+
         const a00 = a[(m - 2) * n + (m - 2)];
         const a01 = a[(m - 1) * n + (m - 2)];
         const a11 = a[(m - 1) * n + (m - 1)];
 
-        sum1 = a00 + a11;
-        sum2 = a00 * a11 - a01 * a10;
-
-        wa = sum1 * sum1 - 4.0 * sum2;
-        if (wa < 0.0) {
-            wa = 0.0;
+        if (sweeps_since_deflation === 10 || sweeps_since_deflation === 20) {
+            // Exceptional Rayleigh-quotient shift. The standard Wilkinson
+            // shift can stall on a trailing 2×2 with near-symmetric (±λ)
+            // eigenvalues: it keeps picking whichever root happens to be
+            // closer to a11 that sweep, and the QR step doesn't make
+            // progress. Falling back to mu = a11 alone breaks the symmetry
+            // and gets convergence moving again (LAPACK xLAHQR does an
+            // analogous fallback for the double-shift case at iter 10/20).
+            mu = a11;
         } else {
-            wa = Math.sqrt(wa);
-        }
+            // Standard Wilkinson shift from the trailing 2×2 block.
+            sum1 = a00 + a11;
+            sum2 = a00 * a11 - a01 * a10;
 
-        const lam1 = 0.5 * (sum1 + wa);
-        const lam2 = sum2 / lam1;
+            wa = sum1 * sum1 - 4.0 * sum2;
+            if (wa < 0.0) {
+                wa = 0.0;
+            } else {
+                wa = Math.sqrt(wa);
+            }
 
-        if (Math.abs(a11 - lam1) < Math.abs(a11 - lam2)) {
-            mu = a11 - lam1;
-        } else {
-            mu = a11 - lam2;
+            // Match the sign of wa to sum1 so we form the root with the
+            // larger magnitude first; otherwise sum1 < 0, sum2 ≈ 0 makes
+            // lam1 cancel to zero and lam2 = 0/0 = NaN poisons mu. Guard
+            // the divide too for the degenerate sum1=0, sum2=0 case.
+            const lam1 = 0.5 * (sum1 + (sum1 >= 0 ? wa : -wa));
+            const lam2 = lam1 !== 0 ? sum2 / lam1 : 0;
+
+            if (Math.abs(a11 - lam1) < Math.abs(a11 - lam2)) {
+                mu = a11 - lam1;
+            } else {
+                mu = a11 - lam2;
+            }
         }
 
         // Subtract mu from diagonal
@@ -78,9 +121,12 @@ export function matrix_qr_in_place(a, n) {
 
             sum1 = Math.sqrt(diag * diag + subdiag * subdiag);
 
-            if (Math.abs(sum1) < EPSILON) {
+            if (sum1 < EPSILON) {
+                // Both diag and subdiag ≈ 0 — column already zero in these
+                // two rows. Rotation is the identity (NOT the zero matrix,
+                // which would annihilate rows i and i+1 across all j > i).
                 sinx = 0.0;
-                cosx = 0.0;
+                cosx = 1.0;
             } else {
                 sinx = subdiag / sum1;
                 cosx = diag / sum1;

package/src/engine/EngineHarness.d.ts

@@ -97,8 +97,9 @@ export class EngineHarness {
      * @param {Vector3} [param.sunDirection]
      * @param {Color} [param.ambient]
      * @param {number} [param.ambientIntensity]
+     * @param {number} [param.sunShadowDistance] Maximum draw distance for sun's shadow. Allows better use of shadowmap resolution.
      */
-    static buildLights({ engine, ecd, shadowmapResolution, castShadow, sun, sunIntensity, sunDirection, ambient, ambientIntensity }: {
+    static buildLights({ engine, ecd, shadowmapResolution, castShadow, sun, sunIntensity, sunDirection, sunShadowDistance, ambient, ambientIntensity }: {
         engine: Engine;
         ecd?: EntityComponentDataset;
         shadowmapResolution?: number;
@@ -108,6 +109,7 @@ export class EngineHarness {
         sunDirection?: Vector3;
         ambient?: Color;
         ambientIntensity?: number;
+        sunShadowDistance?: number;
     }): Promise<void>;
     /**
      * @param {Object} param

package/src/engine/EngineHarness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EngineHarness.d.ts","sourceRoot":"","sources":["../../../src/engine/EngineHarness.js"],"names":[],"mappings":"AA6DA;IAmBI;;;;OAIG;IACH,8CAHmB,mBAAmB,UAAQ,MAAM,WACxC,QAAQ,MAAM,CAAC,CAM1B;IAED;;;OAGG;IACH,6BAFW,MAAM,QAYhB;IAkED;;;;;;;;;;;;;OAaG;IACH;QAZyB,MAAM,EAApB,MAAM;QACyB,GAAG;QAClB,MAAM,GAAtB,OAAO;QACQ,QAAQ,GAAvB,MAAM;QACS,KAAK,GAApB,MAAM;QACS,GAAG,GAAlB,MAAM;QACU,QAAQ,GAAxB,OAAO;QACQ,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACJ,MAAM,CA+DlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QApB0B,MAAM,EAArB,MAAM;QACgC,KAAK,GAA3C;YAAC,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAA;SAAC;QACrB,SAAS;QACT,WAAW;QACF,KAAK,GAArB,MAAM;QACU,GAAG,GAAnB,MAAM;QACU,QAAQ,GAAxB,MAAM;QACwB,WAAW,GAAzC;YAAC,CAAC,EAAC,MAAM,CAAC;YAAC,CAAC,EAAC,MAAM,CAAA;SAAC;QACJ,iBAAiB,GAAjC,MAAM;QACW,WAAW,GAA5B,OAAO;QACU,aAAa,GAA9B,OAAO;QACU,YAAY,GAA7B,OAAO;QACU,aAAa,GAA9B,OAAO;QACS,iBAAiB,GAAjC,MAAM;QACU,iBAAiB,GAAjC,MAAM;QACW,gBAAgB,GAAjC,OAAO;QACU,cAAc,GAA/B,OAAO;QACS,mBAAmB,GAAnC,MAAM;QACW,OAAO,GAAxB,OAAO;sBA0EjB;IAGD;;;;;;;;;;;OAWG;IACH;QAVyB,MAAM,EAApB,MAAM;QACyB,GAAG;QACnB,mBAAmB,GAAlC,MAAM;QACU,UAAU,GAA1B,OAAO;QACO,GAAG,GAAjB,KAAK;QACU,YAAY,GAA3B,MAAM;QACU,YAAY,GAA5B,OAAO;QACO,OAAO,GAArB,KAAK;QACU,gBAAgB,GAA/B,MAAM;sBAqDhB;IAED;;;;;;;OAOG;IACH;QAN0B,YAAY,GAA3B,MAAM;QACQ,MAAM,EAApB,MAAM;QACS,WAAW,GAA1B,MAAM;QACyB,GAAG;QAChC,QAAQ,MAAM,CAAC,CA2C3B;IAGD;;;;;;;;;;OAUG;IACH,sFATW,MAAM,GAOJ,OAAO,CAsDnB;IA9cG;;;OAGG;IACH,QAFU,MAAM,CAEiC;IAMjD;;;OAGG;IACH,YAFU,eAAQ,IAAI,CAET;IA8BjB;;;;;OAKG;IACH;iCAJmB,mBAAmB,UAAQ,MAAM;8BACzC,OAAO;QACL,QAAQ,MAAM,CAAC,CA0D3B;CAqWJ;;IAID;;;OAGG;IACH,uCAMC;;mBA7gBkB,aAAa;oCACI,0BAA0B;oBAX1C,yBAAyB;mBAK1B,iBAAiB;sBATd,wBAAwB;oBAW1B,8BAA8B"}
+{"version":3,"file":"EngineHarness.d.ts","sourceRoot":"","sources":["../../../src/engine/EngineHarness.js"],"names":[],"mappings":"AA6DA;IAmBI;;;;OAIG;IACH,8CAHmB,mBAAmB,UAAQ,MAAM,WACxC,QAAQ,MAAM,CAAC,CAM1B;IAED;;;OAGG;IACH,6BAFW,MAAM,QAYhB;IAkED;;;;;;;;;;;;;OAaG;IACH;QAZyB,MAAM,EAApB,MAAM;QACyB,GAAG;QAClB,MAAM,GAAtB,OAAO;QACQ,QAAQ,GAAvB,MAAM;QACS,KAAK,GAApB,MAAM;QACS,GAAG,GAAlB,MAAM;QACU,QAAQ,GAAxB,OAAO;QACQ,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACJ,MAAM,CA+DlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QApB0B,MAAM,EAArB,MAAM;QACgC,KAAK,GAA3C;YAAC,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAA;SAAC;QACrB,SAAS;QACT,WAAW;QACF,KAAK,GAArB,MAAM;QACU,GAAG,GAAnB,MAAM;QACU,QAAQ,GAAxB,MAAM;QACwB,WAAW,GAAzC;YAAC,CAAC,EAAC,MAAM,CAAC;YAAC,CAAC,EAAC,MAAM,CAAA;SAAC;QACJ,iBAAiB,GAAjC,MAAM;QACW,WAAW,GAA5B,OAAO;QACU,aAAa,GAA9B,OAAO;QACU,YAAY,GAA7B,OAAO;QACU,aAAa,GAA9B,OAAO;QACS,iBAAiB,GAAjC,MAAM;QACU,iBAAiB,GAAjC,MAAM;QACW,gBAAgB,GAAjC,OAAO;QACU,cAAc,GAA/B,OAAO;QACS,mBAAmB,GAAnC,MAAM;QACW,OAAO,GAAxB,OAAO;sBA0EjB;IAGD;;;;;;;;;;;;OAYG;IACH;QAXyB,MAAM,EAApB,MAAM;QACyB,GAAG;QACnB,mBAAmB,GAAlC,MAAM;QACU,UAAU,GAA1B,OAAO;QACO,GAAG,GAAjB,KAAK;QACU,YAAY,GAA3B,MAAM;QACU,YAAY,GAA5B,OAAO;QACO,OAAO,GAArB,KAAK;QACU,gBAAgB,GAA/B,MAAM;QACS,iBAAiB,GAAhC,MAAM;sBAuDhB;IAED;;;;;;;OAOG;IACH;QAN0B,YAAY,GAA3B,MAAM;QACQ,MAAM,EAApB,MAAM;QACS,WAAW,GAA1B,MAAM;QACyB,GAAG;QAChC,QAAQ,MAAM,CAAC,CA2C3B;IAGD;;;;;;;;;;OAUG;IACH,sFATW,MAAM,GAOJ,OAAO,CAsDnB;IAjdG;;;OAGG;IACH,QAFU,MAAM,CAEiC;IAMjD;;;OAGG;IACH,YAFU,eAAQ,IAAI,CAET;IA8BjB;;;;;OAKG;IACH;iCAJmB,mBAAmB,UAAQ,MAAM;8BACzC,OAAO;QACL,QAAQ,MAAM,CAAC,CA0D3B;CAwWJ;;IAID;;;OAGG;IACH,uCAMC;;mBAhhBkB,aAAa;oCACI,0BAA0B;oBAX1C,yBAAyB;mBAK1B,iBAAiB;sBATd,wBAAwB;oBAW1B,8BAA8B"}

package/src/engine/EngineHarness.js

@@ -354,6 +354,7 @@ export class EngineHarness {
      * @param {Vector3} [param.sunDirection]
      * @param {Color} [param.ambient]
      * @param {number} [param.ambientIntensity]
+     * @param {number} [param.sunShadowDistance] Maximum draw distance for sun's shadow. Allows better use of shadowmap resolution.
      */
     static async buildLights({
                                  engine,
@@ -363,6 +364,7 @@ export class EngineHarness {
                                  sun = DEFAULT_SUNLIGHT_COLOR,
                                  sunIntensity = 0.9,
                                  sunDirection = new Vector3(0.17, -1, 0.17),
+                                 sunShadowDistance = 1000,
                                  ambient = Color.white,
                                  ambientIntensity = 0.1
                              }) {
@@ -381,6 +383,7 @@ export class EngineHarness {
         const key = new Light();
         key.type.set(Light.Type.DIRECTION);
         key.color.copy(sun);
+        key.maxShadowDistance.set(sunShadowDistance);
         key.intensity.set(sunIntensity);
         key.castShadow.set(castShadow);
 

package/src/engine/control/first-person/DESIGN.md

@@ -470,14 +470,38 @@ f = config.bob.stepFreqAtWalk
 ```
 At rest `f → 0` and bob amplitude clamps to 0, so the player stops bobbing when they stop.
 
-**Bob shape** (vertical uses `|sin|` so each footfall is a trough; horizontal uses half-rate sine so left/right alternate):
+**Bob shape**:
+
+`stridePhase ∈ [0, 1)` wraps once per stride (= 2 footsteps).
+
+Lateral and roll alternate ONCE per stride (head shifts right during right-foot midstance, left during left-foot midstance):
+```
+phase    = stridePhase * 2π                       // one full cycle per stride (= 2 steps)
+lateral  =  A_l * sin(phase) * intensity          // 1 full L↔R cycle per stride
+roll     =  A_r * sin(phase) * intensity          // in phase with lateral
+```
+
+Vertical is modeled as an **impulse-driven under-damped spring** rather than a sinusoid — the smooth `|sin|` curve we initially specified didn't match real gait dynamics (head is *highest* at midstance, *dips* at footfall under loading response, then is *pushed back up* by the standing leg). At each footfall event:
+```
+verticalImpactSpring.velocity -= A_v * impactKickMultiplier * intensity
 ```
-phase    = stridePhase * 2π                                  // one full cycle per 2 steps
-vert     = -A_v * |sin(phase)|        * speedNormalized
-lateral  =  A_l * sin(phase / 2)      * speedNormalized      // half-rate
-roll     =  A_r * sin(phase / 2)      * speedNormalized      // in phase with lateral
+Then each fixed step the spring damps toward zero with `halfLife ≈ 0.14 s`, `ζ ≈ 0.5`:
 ```
-Sign on `vert` is negative so the eye dips on footfall — this is what reads as "weight".
+verticalOffset = verticalImpactSpring.value     // negative during impact dip,
+                                                // positive during overshoot/push
+```
+
+The under-damped response produces the four-phase curve:
+1. **Impact** — sharp dip below neutral as the foot arrests the head's fall
+2. **Recovery** — value rises back through neutral
+3. **Push** — overshoot above neutral, modeling energy injection from the standing leg
+4. **Settle** — back toward neutral until the next footfall kicks it again
+
+At fast cadence (sprint) the spring barely settles between footfalls and the head oscillates continuously. At slow cadence (back-pedal) each impact is more punctuated, with visible settling between steps. This emerges from the dynamics — no separate handling needed.
+
+**Intensity envelope.** The `intensity` factor used by the lateral/roll/kick amplitudes is itself a critically damped spring around `max(speedNormalized, backwardness)` (or zero when airborne), with `halfLife ≈ 0.22 s`. This is what prevents the "whiplash" of stopping motion — bob amplitudes fade smoothly to zero instead of being cut off when speed drops below the stride threshold.
+
+> An even earlier draft of this doc used `sin(phase / 2)` for lateral and roll, intending a "half-rate" oscillation. That formula actually produces only the first *half* of a sine wave per stridePhase cycle (range [0, π) of sin → all non-negative), which manifested as a one-sided sustained offset for the duration of one stride. The current `sin(phase)` formulation alternates correctly.
 
 **Footstep detection**: emit `onFootStep` when `stridePhase` crosses `0` (right foot) or `0.5` (left foot), but only if `state.grounded && speed > minStepSpeed`. The boundary check uses the *previous* phase so it fires exactly once even at huge dt.