@woosh/meep-engine 2.140.0 → 2.142.0

package/src/engine/physics/REVIEW_002.md

@@ -0,0 +1,151 @@
+# REVIEW_002 — TGS solver, contact robustness, and constraints
+
+Retrospective on the "competent → great" push: promoting the solver from
+single-step PGS to substepped TGS, fixing the contact-robustness issues that
+surfaced, and standing up the 6-DOF constraint subsystem. Companion to the
+engine-comparison docs (`CANNON_REVIEW`, `RAPIER_REVIEW`, `JOLT_REVIEW`,
+`BULLET_REVIEW`); this one is a build retrospective, not a comparison.
+
+Scope: the work tracked in `PLAN.md` under "Solver quality" + "Constraints /
+joints". What landed, the hard-won lessons, where the implementation
+deviated from the original plan and why, and what's deferred.
+
+---
+
+## What landed
+
+**TGS (Temporal Gauss-Seidel), Phases 1–3.** The solver is now a staged
+pipeline driven by a substep loop:
+`prepare → per substep [redetect-concave / refresh-convex → warm-start →
+solve-velocity → solve-position] → restitution`. Defaults: 4 substeps, 4
+velocity + 1 position iteration per substep. Split-impulse position
+correction (pseudo-velocity folded into the pose, never into real velocity);
+one-shot restitution; SPOOK compliance as the soft-constraint dial.
+
+**Contact robustness.**
+- Box-box SAT reference tie-break deadband → aligned cube stacks 4–10 high
+  settle to zero velocity and sleep.
+- Per-substep concave re-detection → a dynamic concave mesh body (torus knot)
+  settles instead of rocking.
+
+**Constraints — 6-DOF configurable joint** (PhysX D6 / Jolt SixDOF model):
+one constraint type, each of 3 linear + 3 angular DOFs independently
+locked/free/limited/spring/motor. Landed modes: LOCKED linear (ball-socket)
+and LOCKED angular (hinge, weld). Solved as a parallel row set inside the
+same substep loop; island-integrated; generation-checked against stale body
+references.
+
+Coverage went ~698 → 720+ physics tests, all green. Falling-tower bench
+unchanged (~48 ms / 1000 active bodies).
+
+---
+
+## Hard-won lessons
+
+These cost real debugging and are the reason the code looks the way it does.
+
+1. **Per-substep warm-start is mandatory under substepping.** The first
+   substep attempt warm-started once per outer step and applied gravity per
+   substep. That mismatch — replaying a *full-frame* impulse against a
+   *single substep* of gravity — over-pushes resting contacts and **explodes**
+   deep stacks (a 10-cube stack hit 9 m of drift / 13 m/s). The fix: gravity
+   per substep **and** warm-start per substep, so each substep's gravity and
+   each substep's replayed impulse cancel exactly at rest. A resting body
+   holds at `v = 0`, `j_n ≈ m·g·h`.
+
+2. **Restitution must gate on the running-max normal impulse, not the
+   end-of-loop value.** With per-substep warm-start, a transient collision's
+   accumulated `j_n` relaxes back to ~0 by the end of the loop (no sustained
+   load to hold it), so gating restitution on the final `j_n` silently killed
+   every bounce. Tracking `maxNormalImpulse` over the whole step (Box2D-v3's
+   trick) is what makes restitution fire.
+
+3. **Analytic separation re-derivation is great for convex, wrong for
+   dynamic concave.** Re-deriving each substep's penetration from frozen
+   witness anchors + current pose (no narrowphase re-run) is cheap and exact
+   *while the contact feature is stable* — true for a convex primitive under
+   the small per-step motion. For a concave body rocking on a mesh, the
+   supporting triangle (and its normal) genuinely changes mid-step, so
+   freezing it pumps energy in. Resolution: convex pairs use the cheap
+   analytic refresh; concave-involved pairs re-run narrowphase geometry each
+   substep (`redetect_concave_contacts`). Hybrid, gated by collider convexity.
+
+4. **The aligned-stack instability was not the solver.** Cube stacks crept
+   and toppled; the instinct was "solver convergence". Dumping
+   `box_box_manifold` across a settling pair showed the normal and contact
+   *count* were stable, but the *reference face* flip-flopped between A and B
+   each frame (their SAT overlaps are exactly equal for aligned boxes, so
+   float noise from a sub-degree wobble decided the winner). That reordered
+   the contacts → flipped the Gauss-Seidel sweep order → alternating bias →
+   creep. A 6-line relative+absolute tie-break deadband (bias ties toward the
+   earlier-tested axis) fixed stacks 4–10. **Lesson: diagnose the manifold
+   before blaming the solver.**
+
+5. **Granularity is everything for dynamic concave.** The first instinct
+   ("decompose the mesh into the exact Delaunay tets we already have") is
+   wrong: a Suzanne is ~8000 tets → ~8000 colliders → ~8000 dynamic-BVH
+   leaves refit every frame. Tet meshing is a *volumetric* (FEM/soft-body)
+   tool. Rigid collision wants the *fewest* convex pieces — a single convex
+   hull for most dynamic objects, or a few-hull (V-HACD-style) decomposition.
+   Recorded as the long-term path; the per-substep re-detection is the
+   interim.
+
+6. **One configurable 6-DOF constraint beats N joint types.** The row math is
+   contact-shaped (Jacobian + effective mass + bias + bounds), so it slots
+   into the existing solver. Concrete joints become *config*: ball-socket =
+   lock 3 linear; hinge = lock 3 linear + 2 angular; weld = lock 6. This
+   minimises distinct code paths — the whole point.
+
+7. **Sign conventions: linear A−B, angular B−A.** The linear rows use
+   "A minus B" (impulse +to A); the angular rows use "B minus A" (impulse
+   +to B). Each is internally consistent — the body-order difference just
+   folds the sign in. Derived carefully against the SPOOK Baumgarte target
+   (`dC/dt = vrel`); both worked first try once written down.
+
+---
+
+## Deviations from the original plan (and why)
+
+- **Joints run as a parallel row set, not by porting contacts onto a shared
+  constraint base.** The plan floated either. Porting the working,
+  well-tuned contact path carried regression risk for no immediate benefit;
+  running joints as a second row family in the same substep loop gets the
+  coupling (shared warm-start / islands / substep cadence) at far lower risk.
+  Unifying remains optional.
+
+- **Convex contacts use analytic refresh, not per-substep match-and-merge.**
+  The plan said "substeps refresh contacts via match-and-merge". Analytic
+  re-derivation is cheaper and avoids manifold-lifecycle churn for the convex
+  majority; match-and-merge-style re-detection is reserved for the concave
+  minority (lesson 3).
+
+- **Dynamic concave: per-substep re-detection now, convex proxies later** —
+  not the tet-compound idea first sketched (lesson 5).
+
+---
+
+## Deferred (with rationale)
+
+- **Constraints**: prismatic (needs frame-basis linear rows — today's linear
+  locks use world axes, exact only when all 3 are locked), limits, motors,
+  springs (SPOOK soft), swing-twist (ragdoll cone), the raycast-vehicle
+  layer, and extras (pulley/gear/conveyor/breakable). Sequenced in `PLAN.md`.
+- **Trajectory accuracy**: gravity is substepped, so ballistic integration is
+  at the substep rate — good. No higher-order integrator pursued.
+- **Per-island parallel solve / CCD shape-cast / closed-form
+  triangle-vs-primitive remainder**: unchanged backlog items.
+- **Convex hull builder + few-hull decomposition**: the production answer for
+  dynamic concave (lesson 5), not yet built.
+
+---
+
+## Bottom line
+
+The engine moved from "competent PGS" to a substepped TGS solver with stable
+stacks, accurate restitution, robust mass ratios, settling dynamic concave
+bodies, and a working 6-DOF constraint (ball-socket / hinge / weld) — i.e.
+chains, ropes, and the structural joints for ragdolls and mechanisms. The
+costliest mistakes were all about *substepping invariants* (warm-start and
+restitution-gating cadence) and *not trusting assumptions* (the stack bug was
+narrowphase, not the solver). The remaining constraint work is incremental
+on a validated framework.

package/src/engine/physics/REVIEW_003.md

@@ -0,0 +1,166 @@
+# REVIEW_003 — 6-DOF joints, full DOF-mode set, and the raycast vehicle
+
+Retrospective on the constraints push: completing the 6-DOF joint across every
+per-DOF mode (lock / free / limit / motor / spring), adding accurate cone-twist
+range-of-motion, and building the raycast-vehicle layer on top. Companion to
+`REVIEW_002` (TGS solver + contact robustness + the first joint modes); this one
+covers `PLAN.md` → "Constraints / joints" phases 3–7.
+
+Scope: what landed, the hard-won lessons, where the build deviated from the plan
+and why, and what's deferred.
+
+---
+
+## What landed
+
+**One mode-agnostic constraint row.** The joint solver resolves every DOF —
+linear or angular — through a single scalar velocity row parameterised by
+`(effective mass, bias, impulse clamp, regularisation γ)`. The `DofMode` only
+chooses those parameters:
+
+- **LOCKED** — bilateral, `bias = β/h · C`, clamp `(−∞, +∞)`. Ball-socket /
+  hinge / weld / prismatic are configurations of locked vs free DOFs.
+- **LIMITED** — a *speculative (β=1) one-sided* velocity constraint: `bias =
+  (pos − bound)/h`, clamp one-sided. Slider end-stops and joint ROM.
+- **MOTOR** — `bias = −targetVelocity`, clamp `±maxForce·h`. Powered doors,
+  wheel drive, pistons.
+- **SPRING** — a regularised (compliant) row: `γ = 1/(h·(c+h·k))`, `bias =
+  (k/denom)·C`, softened mass `1/(K+γ)`, plus the `+γ·λ_accum` term. Suspension,
+  bungees, soft-return.
+
+Adding each mode was a localised change to the row-parameter setup; the
+warm-start and the iteration loop never changed shape. SPRING added exactly one
+term (`+γ·λ_accum`, γ defaulting to 0), so LOCKED/LIMITED/MOTOR stayed
+bit-for-bit identical.
+
+**Frame-basis everything.** Both linear and angular rows resolve in frame A's
+basis axes, clearing the early world-axis linear debt — the solver is fully
+frame-relative.
+
+**Cone-twist (swing-twist).** Opt-in `Joint.swingTwist` switches the angular
+position measure from the per-axis small-angle vector to a swing-twist
+decomposition (X = twist, Y/Z = swing) with *exact* angles, reusing the LIMITED
+/ SPRING rows. Wide ragdoll ROM now holds at the true angle.
+
+**Raycast vehicle.** `vehicle/RaycastVehicle.js` — a chassis body + raycast
+wheels, a controller on the public `raycast` + `applyForceAt`/`applyImpulseAt`
+API. Suspension (spring+damper along the contact normal) + tyre friction
+(lateral grip + drive/brake clamped to a friction circle μ·N) + steering. The
+6-DOF spring+motor is the alternative "simulated wheel" path.
+
+Coverage ~720 → **732 physics tests**, all green. Joint tests 9 → 19; vehicle
+tests +6; one swing-twist micro-bench (`test.skip`).
+
+---
+
+## Hard-won lessons
+
+1. **A limit must not bounce — velocity-Baumgarte injects energy.** The first
+   LIMITED cut waited for the DOF to cross a stop, then pushed back with a
+   Baumgarte bias. On a spin-into-stop with no opposing load the restorative
+   *velocity* it added didn't dissipate — the DOF coasted back through the whole
+   range. This is the same energy injection the contact solver avoids by using
+   split-impulse instead of velocity-Baumgarte. The fix: a **speculative (β=1)
+   one-sided velocity constraint** that removes exactly the approach velocity so
+   the DOF *lands on* the stop (zero penetration → zero rebound), self-gates to
+   a no-op away from the bound, and — because only the push-out side of the bias
+   is clamped — eases a teleport out instead of yanking. A loaded stop (gravity
+   on a slider) rests cleanly: per-substep load and per-substep warm-start
+   cancel, the resting-contact invariant again.
+
+2. **One row, many modes — but only because the *fixed point* is shared.**
+   Folding LOCKED and LIMITED (and later MOTOR/SPRING) into one solve worked
+   because they differ only in `(bias, clamp, γ)`. The proof it was safe was
+   mechanical: LOCKED's prior tests stayed green untouched after each
+   generalisation. Resisting the urge to special-case kept the loop tiny and
+   made every later mode a few lines.
+
+3. **Spring = regularisation, and it reproduces the analytic equilibrium.** The
+   SPOOK soft constraint (`γ` compliance + `(k/denom)·C` bias + softened mass)
+   isn't an approximation to dial in — a vertical strut settles at *exactly*
+   `m·g/k`, an undamped one oscillates and conserves energy, a stiff one stays
+   stable at 4 substeps. Getting the discrete coefficients right (Catto's
+   implicit-Euler form) made it behave like a real spring on the first run.
+
+4. **Swing-twist: exact position, first-order Jacobian.** The win is measuring
+   the limit *position* as a true angle (a 1.2 rad swing stops at 1.2, not the
+   small-angle proxy's ~1.287). The velocity Jacobian stays the cheap `ω·axis`
+   first-order one — PhysX/Jolt do the same. Keeping it opt-in means welds and
+   tight hinges don't pay the `atan2`/`sqrt` cost.
+
+5. **Benchmark before inlining — but inline when it's 5×.** Rather than assume,
+   the swing-twist decomposition was measured inlined (allocation-free scalar
+   math) vs the object-based `Quaternion.computeSwingAndTwist`: ~5× faster than
+   the method with reused out-params, ~10× vs naive fresh allocation (property
+   getters + `normalize` + a quaternion multiply + GC). In a per-substep
+   per-joint hot loop that margin justifies the duplicated math; the Quaternion
+   method stays for general callers. Making all three variants produce identical
+   results (matching sinks) was what made the comparison trustworthy.
+
+6. **The raycast vehicle is a force controller, and its failure modes are
+   physical.** Too much drive on a light, high-CG car wheelies and flips; too
+   much speed into a hard steer rolls it. These aren't solver bugs — they're the
+   model being honest. The tests use a low, heavy car and moderate inputs so the
+   *controller* (suspension equilibrium, grip, drive, steer) is what's under
+   test, not the operator. Spotting "the car launched, went airborne, then slept
+   on its roof" from `contacts=0, y=0.29, sleep=1` saved chasing a non-bug.
+
+7. **An external per-frame controller can't fully honour the substep
+   invariant.** Suspension is applied once per frame as a `dt`-force, but gravity
+   is per-substep — so a resting chassis carries a ~`g·h` end-of-step
+   velocity-sample artifact (it hovers position-stable to sub-cm, but the
+   sampled `v_y` isn't zero the way a resting *contact* body's is). Contacts
+   avoid this because their warm-start cancels each substep's gravity inside the
+   loop; a frame-level controller has no such hook. Documented, not hidden.
+
+---
+
+## Deviations from the plan (and why)
+
+- **LIMITED is speculative-velocity, not split-impulse.** The plan sketched
+  limits as bounded rows; the bounce lesson pushed it to a β=1 speculative
+  velocity constraint, which needs no separate position pass and rests cleanly.
+- **Swing-twist is inlined, not `Quaternion.computeSwingAndTwist`.** The note
+  said "reuse the Quaternion method"; the benchmark said inline (lesson 5). The
+  method stays for non-hot callers.
+- **Swing-twist is opt-in (`swingTwist` flag), not the default measure.** Keeps
+  the cheaper small-angle path for welds/hinges and zero regression risk; the
+  flag is a genuine angular-mode choice (PhysX D6 / Jolt SwingTwist), not an
+  auto/override sentinel.
+- **Vehicle is a standalone controller, not an ECS component+system.** It rides
+  the public query+force API exactly as the plan framed it ("on top of the
+  queries"), which keeps it decoupled and matches Bullet/Godot usage.
+
+---
+
+## Deferred (with rationale)
+
+- **Raycast narrowphase refinement** — the suspension ray (and every shape
+  query) currently resolves to the leaf's inflated AABB: exact for axis-aligned
+  box ground, coarse for spheres/capsules/rotated boxes/meshes. This is the next
+  item; it sharpens vehicle ride height and all query accuracy. Tracked
+  separately.
+- **Vehicle extras** — anti-roll bars, engine/gearbox curves, configurable
+  weight transfer / anti-squat, wheel-collision (vs raycast-only). The core is
+  in; these are tuning layers.
+- **Elliptical/conical swing limit** — the cone is currently box-shaped
+  (independent Y/Z swing limits). A single combined swing-magnitude row would
+  give a circular/elliptical cone.
+- **Per-substep joint warm-start for the vehicle** — would remove the `g·h`
+  velocity-sample artifact, at the cost of running the controller inside the
+  substep loop.
+- Carried from REVIEW_002: convex-hull / few-hull decomposition for production
+  dynamic concave; per-island parallel solve; shape-cast CCD.
+
+---
+
+## Bottom line
+
+The 6-DOF joint now spans the whole taxonomy from one row solve — ball-socket,
+hinge, weld, prismatic, slider/ROM end-stops, powered doors/wheels, springs/
+suspension, and accurate ragdoll cone-twist — and the raycast vehicle sits on
+top of it and the query API. The costliest lessons were again about *not
+injecting energy* (the limit bounce, mirroring the contact split-impulse
+rationale) and *measuring before optimising* (the swing-twist inline bench). The
+constraints plan (phases 1–7) is complete; the highest-leverage next step is
+raycast narrowphase, which every query — and the vehicle — would sharpen.

package/src/engine/physics/constraint/DofMode.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-degree-of-freedom mode for a 6-DOF constraint ({@link Joint }).
+ *
+ * A 6-DOF constraint has 3 linear DOFs (translation of body B's anchor frame
+ * relative to body A's, along A's frame axes) and 3 angular DOFs (relative
+ * rotation, swing-twist decomposed). Each DOF independently takes one of these
+ * modes — which is how a single configurable constraint expresses the whole
+ * joint taxonomy (PhysX D6 / Jolt SixDOF / Bullet Generic6DOF):
+ *
+ *   - ball-socket  = lock 3 linear
+ *   - hinge        = lock 3 linear + 2 angular
+ *   - prismatic    = lock 2 linear + 3 angular
+ *   - weld         = lock all 6
+ *   - cone-twist   = lock 3 linear + limit 3 angular
+ *   - suspension   = spring 1 linear + lock the rest
+ *
+ * Implementation lands mode-by-mode: LOCKED first (covers ball-socket / hinge
+ * / prismatic / weld), then LIMITED, SPRING, MOTOR.
+ */
+export type DofMode = number;
+export namespace DofMode {
+    let LOCKED: number;
+    let FREE: number;
+    let LIMITED: number;
+    let SPRING: number;
+    let MOTOR: number;
+}
+//# sourceMappingURL=DofMode.d.ts.map

package/src/engine/physics/constraint/DofMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DofMode.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/constraint/DofMode.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;sBAqBU,MAAM"}

package/src/engine/physics/constraint/DofMode.js

@@ -0,0 +1,35 @@
+/**
+ * Per-degree-of-freedom mode for a 6-DOF constraint ({@link Joint}).
+ *
+ * A 6-DOF constraint has 3 linear DOFs (translation of body B's anchor frame
+ * relative to body A's, along A's frame axes) and 3 angular DOFs (relative
+ * rotation, swing-twist decomposed). Each DOF independently takes one of these
+ * modes — which is how a single configurable constraint expresses the whole
+ * joint taxonomy (PhysX D6 / Jolt SixDOF / Bullet Generic6DOF):
+ *
+ *   - ball-socket  = lock 3 linear
+ *   - hinge        = lock 3 linear + 2 angular
+ *   - prismatic    = lock 2 linear + 3 angular
+ *   - weld         = lock all 6
+ *   - cone-twist   = lock 3 linear + limit 3 angular
+ *   - suspension   = spring 1 linear + lock the rest
+ *
+ * Implementation lands mode-by-mode: LOCKED first (covers ball-socket / hinge
+ * / prismatic / weld), then LIMITED, SPRING, MOTOR.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @enum {number}
+ */
+export const DofMode = {
+    /** Constrained to zero (relative position/angle held at the rest value). */
+    LOCKED: 0,
+    /** Unconstrained — the DOF moves freely. */
+    FREE: 1,
+    /** Free within `[lower, upper]`, constrained (one-sided) at the limits. */
+    LIMITED: 2,
+    /** A soft spring (stiffness + damping) pulling toward a rest target. */
+    SPRING: 3,
+    /** Driven toward a target velocity, bounded by a maximum force. */
+    MOTOR: 4,
+};

package/src/engine/physics/constraint/solve_constraints.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Swing-twist decomposition of the relative rotation `qD = conj(qA)⊗qB`, giving
+ * the per-frame-axis angular positions used by wide-cone angular DOFs.
+ *
+ * Decomposes `qD = swing ⊗ twist`, with **twist** the rotation about frame
+ * axis X (the bone / twist axis) and **swing** the residual tilt (a rotation
+ * about an axis in the YZ plane that carries X to its new direction). Writes,
+ * into `out`:
+ *   - `out[0]` = signed twist angle about X, in `(−π, π]` — *exact*, so a twist
+ *     limit engages at the true angle, not the `2·sin(θ/2)` small-angle proxy;
+ *   - `out[1]`, `out[2]` = the swing angle distributed over Y and Z
+ *     (`φ·axis`, φ the true swing angle), so independent Y/Z swing limits form
+ *     an accurate (box-shaped) cone that holds at large tilt.
+ * Reduces continuously to the small-angle vector near identity. Pure scratch /
+ * locals — no allocation, suitable for the per-substep hot loop. (The Quaternion
+ * class has an object-based `computeSwingAndTwist`; this is the inlined,
+ * allocation-free form — see the bench that justifies it.)
+ *
+ * @param {number} dx @param {number} dy @param {number} dz @param {number} dw  qD
+ * @param {Float64Array} out  length-3 destination (frame-axis positions)
+ */
+export function swing_twist_error(dx: number, dy: number, dz: number, dw: number, out: Float64Array): void;
+/**
+ * Solve every joint for one substep: recompute geometry at the current poses,
+ * derive each DOF's row parameters from its mode, replay the per-substep
+ * warm-start, and run `iters` velocity iterations.
+ *
+ * Called once per substep from `PhysicsSystem.fixedUpdate`, after the contact
+ * solve so the two share the substep / warm-start cadence.
+ *
+ * @param {Joint[]} joints  live joints (sparse array; holes skipped)
+ * @param {PhysicsSystem} system  reads `__bodies` / `__transforms` / index map
+ * @param {number} dt_sub  substep size in seconds (the SPOOK gain is derived
+ *   from it, matching the contact solver's per-substep position stiffness)
+ * @param {number} iters  velocity iterations
+ */
+export function solve_joints(joints: Joint[], system: PhysicsSystem, dt_sub: number, iters: number): void;
+//# sourceMappingURL=solve_constraints.d.ts.map

package/src/engine/physics/constraint/solve_constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve_constraints.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/constraint/solve_constraints.js"],"names":[],"mappings":"AA+MA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,sCAHW,MAAM,MAAa,MAAM,MAAa,MAAM,MAAa,MAAM,OAC/D,YAAY,QAkCtB;AA0JD;;;;;;;;;;;;;GAaG;AACH,qCANW,OAAO,iCAEP,MAAM,SAEN,MAAM,QAsPhB"}