@woosh/meep-engine 3.20.0 → 3.22.0

package/src/engine/physics/REVIEW_002.md

@@ -1,151 +0,0 @@
-# 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

@@ -1,166 +0,0 @@
-# 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/shade/descriptor/util/optional_clone.d.ts

@@ -1,7 +0,0 @@
-/**
- * @template T
- * @param {T} obj
- * @return {T}
- */
-export function optional_clone<T>(obj: T): T;
-//# sourceMappingURL=optional_clone.d.ts.map

package/src/shade/descriptor/util/optional_clone.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"optional_clone.d.ts","sourceRoot":"","sources":["../../../../../src/shade/descriptor/util/optional_clone.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,6CAcC"}

package/src/shade/descriptor/util/optional_equality.d.ts

@@ -1,10 +0,0 @@
-/**
- * @template {{equals(T):boolean}} T
- * @param {undefined|T} a
- * @param {undefined|T} b
- * @return {boolean}
- */
-export function optional_equality<T extends {
-    equals(T: any): boolean;
-}>(a: T, b: T): boolean;
-//# sourceMappingURL=optional_equality.d.ts.map

package/src/shade/descriptor/util/optional_equality.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"optional_equality.d.ts","sourceRoot":"","sources":["../../../../../src/shade/descriptor/util/optional_equality.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;oBALyB,OAAO;gBAGpB,OAAO,CAsBlB"}

package/src/shade/descriptor/util/optional_hash.d.ts

@@ -1,9 +0,0 @@
-/**
- * @template {{hash():number}} T
- * @param {T|undefined} thing
- * @return {number}
- */
-export function optional_hash<T extends {
-    hash(): number;
-}>(thing: T): number;
-//# sourceMappingURL=optional_hash.d.ts.map

package/src/shade/descriptor/util/optional_hash.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"optional_hash.d.ts","sourceRoot":"","sources":["../../../../../src/shade/descriptor/util/optional_hash.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH;YAJsB,MAAM;cAEhB,MAAM,CAYjB"}