@woosh/meep-engine 2.142.0 → 2.144.0

package/src/engine/control/first-person/prototype_first_person_controller.js

@@ -81,6 +81,7 @@ const COLOR_WALLJUMP = 0xaa55ff;
 const COLOR_LEDGE = 0xffaa44;
 const COLOR_SLIDE = 0x44ddee;
 const COLOR_GAP = 0xff66cc;
+const COLOR_STAIRS = 0xeedd44;
 const COLOR_NEUTRAL = 0xaaaaaa;
 
 const eh = new EngineHarness();
@@ -129,6 +130,11 @@ async function main(engine) {
     // player from BVH raycasts). Leaving the flat baseline on would
     // pin the player to y=0 even when standing on a 2 m platform.
     fpsSystem.useBuiltInFlatGround = false;
+    // Collision is resolved by the KinematicMover (recover + unified 3D
+    // sweep-and-slide + ground categorize/stick/slope/stairs) whenever a
+    // PhysicsSystem is present — which it is here. The mover probes the
+    // physics world for ground itself, so no `groundResolver` is wired.
+    // See DESIGN_COLLISION.md.
     await em.addSystem(fpsSystem);
 
     // Sensors system — populates wall/obstacle/ledge probes via
@@ -224,6 +230,7 @@ function buildGym(ecd) {
     buildLedgeGrabStation(ecd);
     buildSlideTunnel(ecd);
     buildGapJumpStation(ecd);
+    buildStairsStation(ecd);
     buildMeshShapeShowcase(ecd);
 }
 
@@ -537,6 +544,64 @@ function buildGapJumpStation(ecd) {
     });
 }
 
+/**
+ * Stairs station — a walkable staircase up to a landing, SW of spawn.
+ * Exercises the KinematicMover's stair handling (DESIGN_COLLISION.md
+ * Phase 3): the player walks up the steps staying grounded (no launch
+ * off each lip) and walks back down staying grounded (stick-to-ground
+ * snaps onto each lower step rather than going airborne).
+ *
+ * Each step rises `RISE` (0.2 m) — comfortably under the controller's
+ * `stepHeight` (0.3 m), so the mover climbs it. A blocking reference
+ * sits beside the stairs: a single 0.5 m riser (> stepHeight) the
+ * player canNOT walk up, for contrast.
+ *
+ * Steps are solid pillars from the ground to each tread height, placed
+ * edge-to-edge so they form a clean staircase profile (no floating
+ * treads, no overlap). The player approaches from the +X (spawn) side
+ * and walks −X up the flight.
+ */
+function buildStairsStation(ecd) {
+    const baseX = SPAWN_X - 11;
+    const baseZ = SPAWN_Z - 11;
+    spawnPad(ecd, baseX, baseZ, COLOR_STAIRS);
+
+    const RISE = 0.2;    // per-step rise — under stepHeight (0.3) → climbable
+    const DEPTH = 0.45;  // tread depth
+    const WIDTH = 4;     // generous width so aiming isn't required
+    const STEPS = 7;     // → 1.4 m top
+    const firstFrontX = baseX - 2; // near (east) edge of the first step
+
+    for (let i = 1; i <= STEPS; i++) {
+        const topY = i * RISE;
+        spawnBox(ecd, {
+            center: new Vector3(firstFrontX - (i - 0.5) * DEPTH, topY / 2, baseZ),
+            size: new Vector3(DEPTH, topY, WIDTH),
+            color: COLOR_STAIRS,
+            roughness: 0.6,
+        });
+    }
+
+    // Landing platform at the top, flush with the last tread.
+    const topY = STEPS * RISE;
+    spawnBox(ecd, {
+        center: new Vector3(firstFrontX - STEPS * DEPTH - 1.5, topY / 2, baseZ),
+        size: new Vector3(3, topY, WIDTH),
+        color: COLOR_STAIRS,
+        roughness: 0.6,
+    });
+
+    // Blocking reference — a single 0.5 m riser (> stepHeight) beside the
+    // flight (offset +Z). Walk into it: the mover blocks rather than
+    // climbing, the contrast to the stairs.
+    spawnBox(ecd, {
+        center: new Vector3(firstFrontX - 1, 0.25, baseZ + WIDTH / 2 + 2),
+        size: new Vector3(3, 0.5, 3),
+        color: COLOR_NEUTRAL,
+        roughness: 0.8,
+    });
+}
+
 // =====================================================================
 // Spawn helpers
 // =====================================================================

package/src/engine/graphics/render/buffer/simple-fx/ao/AmbientOcclusionPostProcessEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AmbientOcclusionPostProcessEffect.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/render/buffer/simple-fx/ao/AmbientOcclusionPostProcessEffect.js"],"names":[],"mappings":"AAoBA;IAIQ,WAA0C;IAI1C,2BAQE;IAyBF;;;;OAIG;IACH,sBAA0B;IAE1B;;;;OAIG;IACH,2BAA6B;IAG7B;;;;OAIG;IACH,yBAA4B;IAE5B;;;;OAIG;IACH,wBAA2B;IAE3B,8CAUE;IAEF;;;;OAIG;IACH,uBAAwB;IAExB;;;;;OAKG;IACH,2BASE;IAKF;;;;OAIG;IACH,0BAAwD;IAK5D;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,oBAeC;IAED,iBAEC;IAED,2BAkCC;IAED,uBASC;IAED;;;OAGG;IACH,iBAwBC;IAED;;;OAGG;IACH,4BAFW,OAAO,QAiCjB;IAED;;;;OAIG;IACH,gCASC;IAED;;;;OAIG;IACH,mCAUC;IAGD,oCAcC;IAED,wBA2CC;IAED,yBAiBC;CAEJ;6BA/Y4B,uCAAuC;+BAD7D,OAAO;6CAAP,OAAO"}
+{"version":3,"file":"AmbientOcclusionPostProcessEffect.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/render/buffer/simple-fx/ao/AmbientOcclusionPostProcessEffect.js"],"names":[],"mappings":"AAoBA;IAIQ,WAA0C;IAI1C,2BAQE;IAyBF;;;;OAIG;IACH,sBAA0B;IAE1B;;;;OAIG;IACH,2BAA6B;IAG7B;;;;OAIG;IACH,yBAA4B;IAE5B;;;;OAIG;IACH,wBAA2B;IAE3B,8CAUE;IAEF;;;;OAIG;IACH,uBAAwB;IAExB;;;;;OAKG;IACH,2BASE;IAKF;;;;OAIG;IACH,0BAAwD;IAK5D;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,oBAeC;IAED,iBAEC;IAED,2BAoCC;IAED,uBASC;IAED;;;OAGG;IACH,iBAwBC;IAED;;;OAGG;IACH,4BAFW,OAAO,QAiCjB;IAED;;;;OAIG;IACH,gCASC;IAED;;;;OAIG;IACH,mCAUC;IAGD,oCAcC;IAED,wBA2CC;IAED,yBAiBC;CAEJ;6BAjZ4B,uCAAuC;+BAD7D,OAAO;6CAAP,OAAO"}

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

@@ -187,7 +187,9 @@ export class AmbientOcclusionPostProcessEffect extends EnginePlugin {
 
         const camera = this.__render_camera;
 
-        uniforms.size.value.set(this.__render_target.width, this.__render_target.height);
+        // AO renders at half-res but samples the full-res depth buffer, so `size` is the full (depth)
+        // resolution -- all texel math then lands on depth texel centres rather than texel boundaries
+        uniforms.size.value.set(this.__composit_layer.renderTarget.width, this.__composit_layer.renderTarget.height);
 
         // setup camera
         const near = camera.near;

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;
@@ -217,8 +215,8 @@ const SAOShader = {
 		// radius over which an occluder's contribution fades to zero at the edge. Must be in [0, 1]. (GTAO)
 		const float GTAO_EFFECT_FALLOFF_RANGE = 0.615;
 
-		float getOccludedFraction( const in vec3 centerViewPosition ) {
-			vec3 centerViewNormal = getViewNormal( centerViewPosition, vUv );
+		float getOccludedFraction( const in vec3 centerViewPosition, const in vec2 centerUv ) {
+			vec3 centerViewNormal = getViewNormal( centerViewPosition, centerUv );
 
 			// sample origin lifted slightly off the surface along the normal (see SURFACE_BIAS)
 			vec3 sampleOrigin = centerViewPosition + centerViewNormal * ( kernelRadius * SURFACE_BIAS );
@@ -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
@@ -267,7 +270,7 @@ const SAOShader = {
 				vec2 sampleUv = ( clip.xy / clip.w ) * 0.5 + 0.5;
 
 				// screen-space offset from the centre, in pixels
-				vec2 offsetPixels = ( sampleUv - vUv ) * size;
+				vec2 offsetPixels = ( sampleUv - centerUv ) * size;
 
 				// push forward along the screen direction by the self-occlusion margin (extends the
 				// screen-space radius), then snap to the nearest pixel centre so the depth fetch is
@@ -276,13 +279,16 @@ const SAOShader = {
 				offsetPixels += offsetPixels / max( offsetLength, EPSILON ) * SELF_OCCLUSION_MARGIN_PIXELS;
 				offsetPixels = round( offsetPixels );
 
-				sampleUv = vUv + offsetPixels / size;
+				sampleUv = centerUv + offsetPixels / size;
 
 				// samples outside the screen have no depth to test against
 				if ( sampleUv.x < 0.0 || sampleUv.x > 1.0 || sampleUv.y < 0.0 || sampleUv.y > 1.0 ) {
 					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,29 +308,37 @@ 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() {
-			float centerDepth = getDepth( vUv );
+			// snap to the centre of the full-res depth texel we sample. The half-res pass otherwise
+			// lands on texel boundaries, where NEAREST biases consistently to one side and the
+			// reconstructed position disagrees with the sampled depth -> asymmetric edge self-occlusion.
+			vec2 centerUv = ( floor( vUv * size ) + 0.5 ) / size;
+
+			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 );
-			vec3 viewPosition = getViewPosition( vUv, centerDepth, centerViewZ );
+			vec3 viewPosition = getViewPosition( centerUv, centerDepth, centerViewZ );
 
-			float occlusion = getOccludedFraction( viewPosition );
+			float occlusion = getOccludedFraction( viewPosition, centerUv );
 
 			// intensity is an artistic power: 1.0 leaves the physical estimate untouched, higher
 			// darkens occluded areas while leaving fully-lit areas at 1.0

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,15 +555,49 @@ 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
@@ -598,8 +657,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"}