@woosh/meep-engine 2.143.0 → 2.145.0

package/src/engine/graphics/render/buffer/simple-fx/ao/SAOShader.js

@@ -199,8 +199,6 @@ const SAOShader = {
 		// Roberts' R3 low-discrepancy additive recurrence: ( 1/g, 1/g^2, 1/g^3 ), g^4 = g + 1
 		const vec3 R3 = vec3( 0.8191725134, 0.6710436067, 0.5497004779 );
 
-		const float INV_NUM_SAMPLES = 1.0 / float( NUM_SAMPLES );
-
 		// normal-bias as a fraction of kernelRadius: lifts the sample origin off the surface to avoid
 		// self-occlusion. Larger removes acne but lets near-surface contact occlusion leak.
 		const float SURFACE_BIAS = 0.05;
@@ -246,6 +244,7 @@ const SAOShader = {
 			float falloffAdd   = falloffFrom / falloffRange + 1.0;
 
 			float occlusion = 0.0;
+			float weightSum = 0.0;
 
 			for ( int i = 0; i < NUM_SAMPLES; i ++ ) {
 				// fixed R3 low-discrepancy point; per-pixel variation comes from the rotated frame
@@ -260,6 +259,10 @@ const SAOShader = {
 				// sampleDistributionPower) so the near occluders that dominate AO are favoured
 				float radius = pow( fract( q.z + noise.y ), sampleDistributionPower );
 
+				// falloff weight from the probe's own distance -- defined for every sample, so the
+				// weighted normaliser is well posed; distant probes are less reliable (GTAO)
+				float weight = saturate( radius * kernelRadius * falloffMul + falloffAdd );
+
 				vec3 samplePositionVS = sampleOrigin + dir * ( radius * kernelRadius );
 
 				// project the sample into screen space
@@ -283,6 +286,9 @@ const SAOShader = {
 					continue;
 				}
 
+				// a valid (on-screen) sample contributes its weight to the normaliser, occluded or not
+				weightSum += weight;
+
 				float sampleDepth = getDepth( sampleUv );
 
 				// skip the sky / far plane
@@ -302,17 +308,16 @@ const SAOShader = {
 				// ...and the tapped surface must actually be within the sampling radius, otherwise we
 				// have hit distant geometry through the depth buffer that does not occlude this point
 				vec3 occluderVS = getViewPosition( sampleUv, sampleDepth, sceneViewZ );
-				float sampleDist = distance( centerViewPosition, occluderVS );
-				if ( sampleDist > kernelRadius ) {
+				if ( distance( centerViewPosition, occluderVS ) > kernelRadius ) {
 					continue;
 				}
 
-				// distant samples contribute less: linear fade from full weight at falloffFrom to zero
-				// at the radius (GTAO)
-				occlusion += saturate( sampleDist * falloffMul + falloffAdd );
+				// occluded: add this sample's weight to the numerator
+				occlusion += weight;
 			}
 
-			return occlusion * INV_NUM_SAMPLES;
+			// weighted occlusion fraction; off-screen samples were excluded so screen borders are unbiased
+			return weightSum > 0.0 ? occlusion / weightSum : 0.0;
 		}
 
 		void main() {
@@ -323,7 +328,11 @@ const SAOShader = {
 
 			float centerDepth = getDepth( centerUv );
 			if( centerDepth >= ( 1.0 - EPSILON ) ) {
-				discard;
+				// background / far plane is fully visible. Write white rather than discarding, so the
+				// half-res buffer never leaves the clear value for the upscale to read back as occlusion
+				// (that is the foreground-edge halo over background).
+				out_occlusion = 1.0;
+				return;
 			}
 
 			float centerViewZ = getViewZ( centerDepth );

package/src/engine/physics/PLAN.md

@@ -169,21 +169,35 @@ Architectural references for design choices:
   kinematic bodies (character controllers, AOE selection).
 
 ### Standalone narrowphase utilities
+- `deepest_pair_penetration(out_normal, shapeA, posA, rotA, shapeB, posB,
+  rotB)` (exported from `narrowphase_step.js`) — runs the **same**
+  `dispatch_pair` the contact solver consumes for one posed shape pair and
+  returns the DEEPEST contact's depth + world normal (B → A). The single
+  source of truth for "minimum-translation between two posed shapes", reused by
+  `compute_penetration` (and available to any other query).
 - `compute_penetration(out_direction, shape_a, pos_a, rot_a, shape_b,
   pos_b, rot_b)` — non-system geometry primitive: positive penetration
   depth + outward direction (B → A convention) on overlap, 0 otherwise.
-  Convex × convex uses GJK + EPA. Convex × concave uses per-triangle
-  half-space test (`convex.support(-face_normal)` projected onto each
-  triangle's plane), aggregated deepest-wins. The half-space approach
-  sidesteps `Triangle3D`'s degenerate support along face-normal axes
-  (the same issue that makes per-triangle GJK return false positives
-  on clearly non-overlapping sphere-above-flat configurations).
-  Concave × concave throws (M×N triangle pairs is out of scope).
-  Naturally handles "body inside the concave solid" — reports the depth
-  needed to push back through the nearest face. Documented limitation:
-  closed meshes can over-report on side faces whose 2D extent the
-  convex shape's flank crosses; a future closed-form triangle-vs-X
-  solver fixes this.
+  **Hardened** — delegates to `deepest_pair_penetration`, so it is correct
+  (not "correct sometimes") for every shape pair the engine can build:
+    - sphere / box / capsule pairs → exact closed-form (box-box via SAT, so a
+      small body resting on a large floor reports the few-cm near-face overlap,
+      NOT the metres-deep "exit through the far side" that MPR's centroid-seeded
+      portal used to return);
+    - general convex pairs → GJK + EPA (exact for polytopes; curved shapes never
+      reach it — they have closed forms);
+    - convex × concave → triangle decomposition + the closed-form per-triangle
+      solvers, bounded to each triangle's true 2-D extent (the old closed-mesh
+      side-face over-report is gone).
+  The previous per-triangle half-space test is retained ONLY as a recovery
+  fallback for the one case the one-sided closed forms can't resolve: a convex
+  shape that has fully tunnelled to the *inner* side of a concave surface (a
+  depenetration query must still push it back out — exact for heightmap terrain,
+  a valid outward push for closed meshes). Concave × concave throws (M×N
+  triangle pairs out of scope). The spec asserts an "applying out_direction ×
+  depth separates the shapes" invariant across every convex+convex pair type and
+  convex+concave, plus exact per-type depths and the small-box-on-huge-floor
+  regression (3 m → 0.05 m).
 
 ### Determinism
 - Direct typed-array writes on hot paths (bypassing `Vector3#set`'s observer
@@ -224,11 +238,14 @@ Architectural references for design choices:
 
 ## Limitations / Known caveats
 
-- **Multi-collider material precision**: solver reads friction/restitution
-  from the first-attached collider of each body. Mixed-material compound
-  bodies lose accuracy here. The contact-filter callback's `colliderA/B`
-  arguments are similarly the body's primary collider, not the specific
-  collider in contact.
+- **Multi-collider material precision** — *resolved for contact materials.* The
+  narrowphase now combines the specific source-collider pair's friction /
+  restitution per contact and stores them in the manifold (CONTACT_STRIDE
+  offsets 14/15); the solver reads them per contact, so mixed-material compound
+  bodies are accurate (regression test: an asymmetric-friction body yaws when
+  shoved). Still primary-collider only: the contact-filter callback's
+  `colliderA/B` arguments and the body-level sensor / concave-dispatch flags —
+  a smaller follow-up.
 - **EPA on smooth shapes**: degenerates (no flat face to converge on).
   Mitigated by closed-form paths for sphere/cube/capsule pairs and by the
   **MPR fallback** on EPA non-convergence; exotic convex shapes vs spheres can
@@ -239,12 +256,20 @@ Architectural references for design choices:
   for those primitives, so a sphere/box/capsule on a heightmap or mesh decelerates
   and settles correctly; the `narrowphase_concave.spec.js` "drop and settle"
   cases and the mesh torus-knot settle test are **un-skipped**. Per-triangle
-  GJK+EPA remains only as the fallback for *other* convex shapes vs triangles
-  (and `compute_penetration` still uses the half-space pre-test there).
+  GJK+EPA remains only as the fallback for *other* convex shapes vs triangles.
+  (`compute_penetration` now routes through that same dispatch via
+  `deepest_pair_penetration` — see *Standalone narrowphase utilities* — instead
+  of its old half-space pre-test; the half-space test survives only as a
+  tunnel-recovery fallback.)
 - **Box-box edge-edge contact**: a single point at the true closest-pair of the
   two edges (P3.2), not the old body-centre midpoint. This is geometrically
-  correct for a true edge-edge crossing; **multi-point** edge contacts (for
-  near-parallel edges) remain a backlog refinement.
+  correct — and an empirical SAT-source sweep confirms the edge-cross branch
+  *only* fires for **transverse** edge crossings (inter-edge angle ≈ 83-90°),
+  where two skew lines meet at a unique point. Near-parallel edge contacts
+  cannot reach this branch (a near-parallel `edgeA × edgeB` never wins the SAT
+  minimum) — they resolve through the multi-point face-clipping path. So the
+  once-planned "multi-point edge contact for near-parallel edges" refinement is
+  **moot**; see the resolved Stability backlog entry.
 - **CCD floor only**: speculative margin via the fattened AABB prevents
   most tunnelling. No per-body swept shape-cast for very fast objects.
 - **Cross-runtime determinism is not guaranteed**: `Math.sin/cos/exp/log`
@@ -530,28 +555,93 @@ scaffolding is in place.
       those primitives. Un-skipped the `narrowphase_concave.spec.js` ball-on-
       heightmap / mesh-cube settle tests and the `PhysicsSystem.spec.js`
       torus-knot test. Per-triangle GJK+EPA remains only as the fallback for
-      *other* convex shapes vs triangles; `compute_penetration` keeps its
-      half-space pre-test there (its closed-mesh over-report caveat stands for
-      that fallback path).
-- [ ] **Edge-edge multi-point manifold** for near-parallel box edge contacts
-      (the single closest-pair point from P3.2 is correct for a true edge-edge
-      crossing; this is the multi-point refinement).
-- [ ] **Per-contact source-collider tracking** so multi-material compound
-      bodies get accurate per-contact friction/restitution. Requires
-      stashing the collider identity in the manifold contact stride.
+      *other* convex shapes vs triangles. `compute_penetration` now routes
+      through the shared narrowphase dispatch (`deepest_pair_penetration`), so it
+      uses the closed-form per-triangle solvers too — the old closed-mesh
+      over-report is gone; the half-space test is retained only as a
+      tunnel-recovery fallback.
+- [x] **Edge-edge multi-point manifold** — *resolved by design (no code
+      change needed).* An empirical SAT-source sweep over a wide range of
+      box-box orientations shows the single-point edge-cross branch only ever
+      wins for **transverse** edge crossings (inter-edge angle ≈ 83-90°), where
+      a single closest-pair point is geometrically exact. A near-parallel edge
+      pair gives a near-degenerate `edgeA × edgeB` that never becomes the SAT
+      minimum, so near-parallel ("line") edge contacts resolve through the
+      multi-point **face-clipping** path instead — confirmed by regression
+      tests in `box_box_manifold.spec.js` (near-parallel tilted boxes → ≥ 2
+      points; transverse crossing → exactly 1 exact point). The originally
+      planned refinement targeted a case the geometry can't produce, so it is
+      closed rather than implemented.
+- [x] **Per-contact source-collider tracking (materials)** — multi-material
+      compound bodies now get accurate per-contact friction / restitution. The
+      narrowphase combines the specific (colliderA, colliderB) pair's
+      coefficients at dispatch time (the only place that knows the source
+      collider on each side — `contact/combine_material.js`) and stamps them
+      into the manifold (CONTACT_STRIDE grown 14 → 16, offsets 14/15); the
+      solver reads them per contact instead of from the body's primary collider.
+      Regression test: an asymmetric-friction compound body yaws when shoved
+      (the grippy collider drags), and a symmetric control does not. Still
+      primary-collider-only: the contact-filter callback's collider args and the
+      body-level sensor / concave flags (smaller follow-up).
+- [ ] **Joint-aware island sleep (ragdoll settle quality).** A draped,
+      self-colliding 10-joint ragdoll does not fully sleep in 10 s — surfaced by
+      a 1000-seed Monte-Carlo sweep (`PhysicsSystem.ragdoll.spec.js`, `.skip`):
+      for unlucky seeds a distal limb sustains a settled limit cycle (settled
+      finite-difference accel up to ~1094 m/s² / ~1479 rad/s² at a limb end vs a
+      ~55 m/s² median — bounded, non-growing, penetration-free, so a quality gap
+      not a divergence). The sleep test today is per-body `|v|²+|ω|²`; an island
+      over-constrained by cone-twist limits + self-contacts keeps small residual
+      jiggle above the per-body threshold so it never crosses into sleep.
+      Candidate fixes: sleep a jointed/contacting island on its AGGREGATE motion
+      rather than the per-body minimum, and/or a settled-regime relaxation (zero
+      restitution + extra position iterations) once an island's energy is low.
+      The sweep flags the worst seeds for replay. (Test infra also adds
+      per-point kinematics tracking — joint anchors + limb ends, with
+      displacement→velocity→acceleration and the angular equivalents.)
 
 ### Performance / Scale
 - [ ] **Per-body linear CCD shape-cast**: optional opt-in for fast-moving
       bodies where speculative margin isn't enough. The bench's falling
       tower (1km drop onto a 1cm floor) is the concrete reproducer —
       180 / 1000 bodies tunnel.
-- [ ] **Broadphase BVH balance / raycast traversal cost**: the raycast bench
-      (`queries/raycast.bench.spec.js`) shows ~linear-in-N per-ray cost
-      (~50 µs/ray at 500 bodies), i.e. a ray walks most of the tree — the static
-      BVH built by sequential `link` inserts is poorly balanced. Orthogonal to
-      raycast narrowphase (which adds only per-crossed-leaf refine, <1% here);
-      affects every BVH query. Needs a balanced/refitting build (SAH or
-      incremental rotation) on the static tree.
+- [x] **Broadphase BVH balance — SAH rotation.** The dynamic AABB tree
+      (`core/bvh2/bvh3/BVH.js`, a Box2D port) used SAH-cost insertion but a
+      *height-only* AVL rotation (`balance_height`): height-balanced yet not
+      SAH-balanced, so queries walked more nodes than needed. Replaced the
+      rotation in `bubble_up_update` with `balance_rotate` — the Box2D-v3 /
+      Kensler SAH-reducing rotation (for node A with children B, C, evaluate the
+      four child↔grandchild swaps and apply the one that most reduces the
+      surface-area cost). Deterministic; identical pair set.
+        - Measured (same-session A/B, heavy benches): raycast **−9%**
+          (28.2→25.6 µs/ray), falling-tower median **−10%**, settling-grid
+          median **−12%**, and the **990/1000-churn stress −27%**
+          (63.95→46.68 ms mean over 10k ticks) — biggest where the tree churns
+          hardest. Determinism (8-trial bit-identical) holds.
+        - **Insertion cost (measured):** `balance_rotate` does 4 surface-area
+          evaluations per bubble-up level vs `balance_height`'s single height
+          compare, so *pure bulk insertion* is **~1.4–1.5× slower** — the 100k
+          synthetic insert bench (`BVH.spec.js`, drift-controlled interleaved
+          A/B) drops from **~37k → ~25k inserts/sec** (~27→~40 µs/insert). This
+          is the balancer's worst case (insert-only, zero queries/refits to
+          amortise against). It does not show up end-to-end: static trees are
+          built once then queried forever, dynamic bodies insert once then
+          refit/query every frame, and even the 990/1000-swap stress test — the
+          maximal insert-churn workload — is net **−27%**. Accepted.
+        - **Tradeoff (documented):** the contact solver's Gauss-Seidel order
+          follows broadphase traversal order (see `generate_pairs`), so the
+          different tree shape shifts convergence on near-aligned stacks — the
+          synthetic 128-cube wall now sleeps at ~10 s (was ~6.9 s). It still
+          settles, doesn't creep / topple (all bug-guard assertions hold); only
+          the sleep *time* moved (that test's budget was bumped 9→11 s with a
+          note). Random-shape scenes (falling tower) were faster *and* settled
+          fine.
+        - **Follow-up:** decouple the solve order from tree shape — sort the
+          broadphase pair list by `(idA, idB)` before narrowphase so contact
+          order is body-id-deterministic regardless of tree shape. Then no tree
+          change can affect convergence (and the stack settles identically under
+          either balancer). Has a per-step sort cost + wide test re-baseline, so
+          it's its own task. `balance_height` is retained for comparison /
+          fallback.
 - [ ] **Per-island parallel solve**: today's island data layout would
       allow worker-based solving once `SharedArrayBuffer` is available.
       Out-of-scope unless / until SAB is universally usable.
@@ -578,8 +668,19 @@ scaffolding is in place.
 - [ ] **Convex hull shape** with eigen-based principal-axes inertia
       derivation. Hooks `matrix_eigenvalues_in_place` from the existing
       linalg layer.
-- [ ] **Cylinder / cone shapes** (closed-form pairs against the existing
-      family + GJK+EPA fallback for general convex).
+- [~] **Cylinder / cone shapes.**
+    - [x] **`CylinderShape3D`** — Y-aligned solid cylinder (radius + full
+          height, flat caps; the capsule's flat-cap sibling). Exact `support`,
+          capped-cylinder SDF, bounds, `contains` / `nearest_point` /
+          volume-sampling, equals/hash, `'cylinder'` JSON tag, `isCylinderShape3D`
+          marker. Convex → routes through the narrowphase **GJK + EPA** fallback
+          (no marker dispatch needed); spec asserts overlap-detected +
+          MTV-separates vs sphere/box. Closed-form cylinder-vs-X contact pairs
+          are a future refinement (the curved side is the usual smooth-support
+          EPA case — same status as pre-closed-form sphere/capsule).
+    - [ ] Closed-form cylinder contact pairs (cylinder × box / sphere / capsule
+          / plane) for multi-point cap manifolds + stable resting.
+    - [ ] **Cone shape** (+ closed-form / GJK fallback).
 
 ### API polish
 - [x] **`overlap(shape, position, rotation, output, output_offset,
@@ -598,8 +699,11 @@ scaffolding is in place.
 - [x] **`compute_penetration(out_direction, shape_a, pos_a, rot_a,
       shape_b, pos_b, rot_b)`** — standalone geometry primitive (no
       PhysicsSystem) for resolving overlap between two shapes at given
-      poses. Returns depth + outward direction. Convex × convex via
-      GJK + EPA; convex × concave via per-triangle half-space test.
+      poses. Returns depth + outward direction. **Hardened** to route through
+      the shared narrowphase dispatch (`deepest_pair_penetration`): exact
+      closed-form for sphere/box/capsule pairs (box-box via SAT), GJK+EPA for
+      general convex, closed-form per-triangle for convex × concave; the
+      half-space test is retained only for tunnel recovery.
 
 ### Raycast narrowphase (done)
 

package/src/engine/physics/contact/ManifoldStore.d.ts

@@ -19,11 +19,19 @@ export const MAX_CONTACTS_PER_MANIFOLD: number;
  *   13    : feature_id (uint32 packed as f64 — stable cross-frame ID of the
  *                       geometric feature pair that produced this contact;
  *                       0 means "no info, fall back to position matching")
+ *   14    : friction   (already-combined coefficient for THIS contact's
+ *                       specific source-collider pair — see combine_material)
+ *   15    : restitution(already-combined coefficient for this contact)
  *
  * Solver uses `(world_a + world_b) * 0.5` as the application point; storing
  * both surface points enables the per-frame warm-start matcher in the
  * narrowphase to compare contact-point positions when feature_id is 0.
  *
+ * Friction / restitution are stored **per contact** (not per body pair) so a
+ * compound body whose colliders have different materials gets the right
+ * coefficient at each contact: the narrowphase knows the exact source collider
+ * on each side of every contact and combines there.
+ *
  * @type {number}
  */
 export const CONTACT_STRIDE: number;
@@ -166,7 +174,8 @@ export class ManifoldStore {
      * Write a contact point into a slot. Increments contact_count if `idx`
      * exceeds the current count.
      *
-     * Writes geometry (offsets 0..9) and the feature_id at offset 13.
+     * Writes geometry (offsets 0..9), the feature_id at offset 13, and the
+     * per-contact combined friction / restitution at offsets 14 / 15.
      * Deliberately does NOT touch the warm-start impulse fields (offsets
      * 10..12) — the narrowphase match-and-merge pass uses this to refill
      * a slot while preserving the cached impulses that the solver's
@@ -187,8 +196,25 @@ export class ManifoldStore {
      * @param {number} feature_id stable cross-frame identifier of the
      *   geometric feature pair that produced this contact; 0 means
      *   "no info, fall back to position matching"
+     * @param {number} friction combined friction for this contact's specific
+     *   source-collider pair
+     * @param {number} restitution combined restitution for this contact
+     */
+    set_contact(slot: number, idx: number, lax: number, lay: number, laz: number, lbx: number, lby: number, lbz: number, nx: number, ny: number, nz: number, depth: number, feature_id?: number, friction?: number, restitution?: number): void;
+    /**
+     * Read the per-contact combined friction stored at one contact.
+     * @param {number} slot
+     * @param {number} idx
+     * @returns {number}
+     */
+    friction_of(slot: number, idx: number): number;
+    /**
+     * Read the per-contact combined restitution stored at one contact.
+     * @param {number} slot
+     * @param {number} idx
+     * @returns {number}
      */
-    set_contact(slot: number, idx: number, lax: number, lay: number, laz: number, lbx: number, lby: number, lbz: number, nx: number, ny: number, nz: number, depth: number, feature_id?: number): void;
+    restitution_of(slot: number, idx: number): number;
     /**
      * Zero the warm-start impulse fields (j_n, j_t1, j_t2) for one contact
      * index inside a slot. Called by the narrowphase match-and-merge pass

package/src/engine/physics/contact/ManifoldStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ManifoldStore.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/contact/ManifoldStore.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,6BAFU,MAAM,CAEiB;AAEjC;;;;GAIG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH,+BAFU,MAAM,CAE2D;AAyB3E;;;GAGG;AACH,mCAFU,MAAM,CAEuB;AAIvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAEI;;OAEG;IACH,+BAFW,MAAM,EA6BhB;IAzBG,mBAA+C;IAC/C,qBAAqB;IAErB,qBAAkE;IAClE,oBAAiE;IAQjE,0BAAwD;IAExD,4BAA0D;IAG1D,0BAAoD;IACpD,uBAAiD;IAEjD,qBAAqB;IAGrB,yBAAmD;IACnD,qBAAqB;IAGzB;;OAEG;IACH,oBAEC;IAED;;OAEG;IACH,uBAEC;IAED;;;;;;;OAOG;IACH,UAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;;OAQG;IACH,aAJW,MAAM,OACN,MAAM,GACJ,MAAM,CA+BlB;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,uBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,WAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,qBAFW,MAAM,QAQhB;IAED;;;;;;;;;;;;;OAaG;IACH,mBAFW,MAAM,QAKhB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAhBW,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,SACN,MAAM,eACN,MAAM,QAwBhB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,MAAM,OACN,MAAM,QAOhB;IAED;;;;;OAKG;IACH,oBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,EAAE,GAAC,YAAY,cACrB,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED,iEAAiE;IACjE,uBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED,iEAAiE;IACjE,uBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED,iEAAiE;IACjE,oBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;;OAMG;IACH,qCAEC;IAED;;;;;OAKG;IACH,uBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,uBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,sBA6BC;IAED;;;OAGG;IACH,wBAcC;IAED;;;OAGG;IACH,uBAkBC;IAED;;OAEG;IACH,eA+BC;IAED;;;OAGG;IACH,oBAaC;IAED;;;OAGG;IACH,mBAqBC;CACJ;8BA9lBqD,2CAA2C"}
+{"version":3,"file":"ManifoldStore.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/contact/ManifoldStore.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,6BAFU,MAAM,CAEiB;AAEjC;;;;GAIG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH,+BAFU,MAAM,CAE2D;AAyB3E;;;GAGG;AACH,mCAFU,MAAM,CAEuB;AAIvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAEI;;OAEG;IACH,+BAFW,MAAM,EA6BhB;IAzBG,mBAA+C;IAC/C,qBAAqB;IAErB,qBAAkE;IAClE,oBAAiE;IAQjE,0BAAwD;IAExD,4BAA0D;IAG1D,0BAAoD;IACpD,uBAAiD;IAEjD,qBAAqB;IAGrB,yBAAmD;IACnD,qBAAqB;IAGzB;;OAEG;IACH,oBAEC;IAED;;OAEG;IACH,uBAEC;IAED;;;;;;;OAOG;IACH,UAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;;OAQG;IACH,aAJW,MAAM,OACN,MAAM,GACJ,MAAM,CA+BlB;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,uBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,WAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,qBAFW,MAAM,QAQhB;IAED;;;;;;;;;;;;;OAaG;IACH,mBAFW,MAAM,QAKhB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,kBAnBW,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,SACN,MAAM,eACN,MAAM,aAGN,MAAM,gBAEN,MAAM,QAwBhB;IAED;;;;;OAKG;IACH,kBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,qBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,MAAM,OACN,MAAM,QAOhB;IAED;;;;;OAKG;IACH,oBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,EAAE,GAAC,YAAY,cACrB,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED,iEAAiE;IACjE,uBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED,iEAAiE;IACjE,uBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED,iEAAiE;IACjE,oBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;;OAMG;IACH,qCAEC;IAED;;;;;OAKG;IACH,uBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,uBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,sBA6BC;IAED;;;OAGG;IACH,wBAcC;IAED;;;OAGG;IACH,uBAkBC;IAED;;OAEG;IACH,eA+BC;IAED;;;OAGG;IACH,oBAaC;IAED;;;OAGG;IACH,mBAqBC;CACJ;8BAhoBqD,2CAA2C"}

package/src/engine/physics/contact/ManifoldStore.js

@@ -23,14 +23,22 @@ export const MAX_CONTACTS_PER_MANIFOLD = 4;
  *   13    : feature_id (uint32 packed as f64 — stable cross-frame ID of the
  *                       geometric feature pair that produced this contact;
  *                       0 means "no info, fall back to position matching")
+ *   14    : friction   (already-combined coefficient for THIS contact's
+ *                       specific source-collider pair — see combine_material)
+ *   15    : restitution(already-combined coefficient for this contact)
  *
  * Solver uses `(world_a + world_b) * 0.5` as the application point; storing
  * both surface points enables the per-frame warm-start matcher in the
  * narrowphase to compare contact-point positions when feature_id is 0.
  *
+ * Friction / restitution are stored **per contact** (not per body pair) so a
+ * compound body whose colliders have different materials gets the right
+ * coefficient at each contact: the narrowphase knows the exact source collider
+ * on each side of every contact and combines there.
+ *
  * @type {number}
  */
-export const CONTACT_STRIDE = 14;
+export const CONTACT_STRIDE = 16;
 
 /**
  * Per-contact feature_id offset within {@link CONTACT_STRIDE}.
@@ -286,7 +294,8 @@ export class ManifoldStore {
      * Write a contact point into a slot. Increments contact_count if `idx`
      * exceeds the current count.
      *
-     * Writes geometry (offsets 0..9) and the feature_id at offset 13.
+     * Writes geometry (offsets 0..9), the feature_id at offset 13, and the
+     * per-contact combined friction / restitution at offsets 14 / 15.
      * Deliberately does NOT touch the warm-start impulse fields (offsets
      * 10..12) — the narrowphase match-and-merge pass uses this to refill
      * a slot while preserving the cached impulses that the solver's
@@ -307,8 +316,11 @@ export class ManifoldStore {
      * @param {number} feature_id stable cross-frame identifier of the
      *   geometric feature pair that produced this contact; 0 means
      *   "no info, fall back to position matching"
+     * @param {number} friction combined friction for this contact's specific
+     *   source-collider pair
+     * @param {number} restitution combined restitution for this contact
      */
-    set_contact(slot, idx, lax, lay, laz, lbx, lby, lbz, nx, ny, nz, depth, feature_id = 0) {
+    set_contact(slot, idx, lax, lay, laz, lbx, lby, lbz, nx, ny, nz, depth, feature_id = 0, friction = 0, restitution = 0) {
         const off = slot * SLOT_DATA_STRIDE + idx * CONTACT_STRIDE;
         this.__data[off] = lax;
         this.__data[off + 1] = lay;
@@ -322,6 +334,8 @@ export class ManifoldStore {
         this.__data[off + 9] = depth;
         // j_n, j_t1, j_t2 (offsets 10..12) are warm-start; preserved across calls.
         this.__data[off + 13] = feature_id;
+        this.__data[off + 14] = friction;
+        this.__data[off + 15] = restitution;
 
         const meta_off = slot * SLOT_META_STRIDE;
         const count_now = this.__meta[meta_off + 2] & COUNT_MASK;
@@ -330,6 +344,26 @@ export class ManifoldStore {
         }
     }
 
+    /**
+     * Read the per-contact combined friction stored at one contact.
+     * @param {number} slot
+     * @param {number} idx
+     * @returns {number}
+     */
+    friction_of(slot, idx) {
+        return this.__data[slot * SLOT_DATA_STRIDE + idx * CONTACT_STRIDE + 14];
+    }
+
+    /**
+     * Read the per-contact combined restitution stored at one contact.
+     * @param {number} slot
+     * @param {number} idx
+     * @returns {number}
+     */
+    restitution_of(slot, idx) {
+        return this.__data[slot * SLOT_DATA_STRIDE + idx * CONTACT_STRIDE + 15];
+    }
+
     /**
      * Zero the warm-start impulse fields (j_n, j_t1, j_t2) for one contact
      * index inside a slot. Called by the narrowphase match-and-merge pass

package/src/engine/physics/contact/combine_material.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Surface-material combine rules — how the friction / restitution of the two
+ * colliders in contact are merged into the single coefficient the solver uses
+ * for that contact.
+ *
+ * These live in a shared leaf module because the combine happens in the
+ * **narrowphase** (which knows the specific source collider on each side of
+ * every contact, so a compound body's per-collider materials are honoured
+ * per-contact) and the result is stored in the manifold and read by the
+ * **solver**. Both sides import from here, keeping one source of truth for the
+ * policy.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Combine two friction coefficients — geometric mean (Bullet / PhysX default).
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function combine_friction(a: number, b: number): number;
+/**
+ * Combine two restitution coefficients — maximum (Unity / common default).
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function combine_restitution(a: number, b: number): number;
+//# sourceMappingURL=combine_material.d.ts.map

package/src/engine/physics/contact/combine_material.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combine_material.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/contact/combine_material.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,oCAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;GAKG;AACH,uCAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAIlB"}

package/src/engine/physics/contact/combine_material.js

@@ -0,0 +1,35 @@
+/**
+ * Surface-material combine rules — how the friction / restitution of the two
+ * colliders in contact are merged into the single coefficient the solver uses
+ * for that contact.
+ *
+ * These live in a shared leaf module because the combine happens in the
+ * **narrowphase** (which knows the specific source collider on each side of
+ * every contact, so a compound body's per-collider materials are honoured
+ * per-contact) and the result is stored in the manifold and read by the
+ * **solver**. Both sides import from here, keeping one source of truth for the
+ * policy.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Combine two friction coefficients — geometric mean (Bullet / PhysX default).
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function combine_friction(a, b) {
+    return Math.sqrt(a * b);
+}
+
+/**
+ * Combine two restitution coefficients — maximum (Unity / common default).
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function combine_restitution(a, b) {
+    return a > b ? a : b;
+}

package/src/engine/physics/ecs/Collider.d.ts

@@ -84,6 +84,21 @@ export class Collider {
         flags: number;
     };
     fromJSON(json: any): void;
+    /**
+     * Value equality over the shape and the surface material. System-private
+     * fields (`_bvhNode`, `_bodyId`) are excluded. Shapes are compared by value
+     * (`shape.equals`), so two colliders sharing one shape instance or holding
+     * equal shapes both compare equal.
+     *
+     * @param {Collider} other
+     * @returns {boolean}
+     */
+    equals(other: Collider): boolean;
+    /**
+     * Hash over the same state as {@link equals}. Equal colliders hash equal.
+     * @returns {number}
+     */
+    hash(): number;
     /**
      * @readonly
      * @type {boolean}

package/src/engine/physics/ecs/Collider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Collider.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/Collider.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,+BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;GAUG;AACH;IAEI;;;OAGG;IACH,OAFU,eAAe,CAEU;IAEnC;;;;OAIG;IACH,UAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,OAFU,aAAa,GAAC,MAAM,CAEH;IAE3B;;;OAGG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,SAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,cAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;OAGG;IACH,gBAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,aAAa,GAClB,OAAO,CAInB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,aAAa,SACpB,OAAO,QAQjB;IAED;;;;;MAOC;IAED,0BAKC;IASL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAZ5B;;kBAIS,MAAM;;gCA/HgB,gDAAgD;8BAElD,oBAAoB"}
+{"version":3,"file":"Collider.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/Collider.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,+BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;GAUG;AACH;IAEI;;;OAGG;IACH,OAFU,eAAe,CAEU;IAEnC;;;;OAIG;IACH,UAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,OAFU,aAAa,GAAC,MAAM,CAEH;IAE3B;;;OAGG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,SAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,cAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;OAGG;IACH,gBAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,aAAa,GAClB,OAAO,CAInB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,aAAa,SACpB,OAAO,QAQjB;IAED;;;;;MAOC;IAED,0BAKC;IAED;;;;;;;;OAQG;IACH,cAHW,QAAQ,GACN,OAAO,CAWnB;IAED;;;OAGG;IACH,QAFa,MAAM,CASlB;IASL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAZ5B;;kBAIS,MAAM;;gCAhKgB,gDAAgD;8BAElD,oBAAoB"}

package/src/engine/physics/ecs/Collider.js

@@ -1,3 +1,4 @@
+import { computeHashFloat } from "../../../core/primitives/numbers/computeHashFloat.js";
 import { AbstractShape3D } from "../../../core/geom/3d/shape/AbstractShape3D.js";
 import { UnitSphereShape3D } from "../../../core/geom/3d/shape/UnitSphereShape3D.js";
 import { ColliderFlags } from "./ColliderFlags.js";
@@ -121,6 +122,39 @@ export class Collider {
         if (json.density !== undefined) this.density = json.density;
         if (json.flags !== undefined) this.flags = json.flags;
     }
+
+    /**
+     * Value equality over the shape and the surface material. System-private
+     * fields (`_bvhNode`, `_bodyId`) are excluded. Shapes are compared by value
+     * (`shape.equals`), so two colliders sharing one shape instance or holding
+     * equal shapes both compare equal.
+     *
+     * @param {Collider} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (other === this) return true;
+        if (other === null || other === undefined || other.isCollider !== true) return false;
+
+        return this.friction === other.friction
+            && this.restitution === other.restitution
+            && this.density === other.density
+            && this.flags === other.flags
+            && this.shape.equals(other.shape);
+    }
+
+    /**
+     * Hash over the same state as {@link equals}. Equal colliders hash equal.
+     * @returns {number}
+     */
+    hash() {
+        let h = this.shape.hash() | 0;
+        h = (h * 31 + computeHashFloat(this.friction)) | 0;
+        h = (h * 31 + computeHashFloat(this.restitution)) | 0;
+        h = (h * 31 + computeHashFloat(this.density)) | 0;
+        h = (h * 31 + (this.flags | 0)) | 0;
+        return h;
+    }
 }
 
 /**

package/src/engine/physics/ecs/Joint.d.ts

@@ -280,6 +280,24 @@ export class Joint {
      * @returns {Joint} this
      */
     setAngularSpring(axis: number, stiffness: number, damping: number): Joint;
+    /**
+     * Value equality over the configurable / persistent state — the same field
+     * set that {@link JointSerializationAdapter} writes: the two anchor
+     * entities, the local anchor points and basis frames, the swing-twist flag,
+     * and the six per-DOF mode + limit / spring / motor arrays. Transient
+     * solver state (`dofImpulse`) and the system-resolved handles (`_bodyIdA`,
+     * `_bodyIdB`, `_jointId`) are excluded.
+     *
+     * @param {Joint} other
+     * @returns {boolean}
+     */
+    equals(other: Joint): boolean;
+    /**
+     * Hash over the same persistent state as {@link equals}. Equal joints hash
+     * equal.
+     * @returns {number}
+     */
+    hash(): number;
     /**
      * @readonly
      * @type {boolean}