From f72adaf252f4c35143d8e059ce3b98c57e52115f Mon Sep 17 00:00:00 2001 From: Quacky2200 Date: Mon, 19 Oct 2026 16:17:05 +0100 Subject: [PATCH] fix: keep friction when the tangent effective-mass matrix is singular The 3D friction solve inverts the 2x2 tangent effective-mass matrix K to solve both friction directions together. When one tangent has no effective mass, K is singular: a body whose z translation and x/y rotations are locked (kept in a plane, as 2D bodies in a 3D world are) has k22 = 0 and k12 = 0. simd_inv(det) then returns 0, so friction along both tangents was dropped and the body slid as if on ice. The shared solve moves into tangent_delta_impulse, used by both ContactConstraintTangentPart (Coulomb) and ContactConstraintTangentPartSlim (Simplified). When det(K) <= 1e-6 * k11 * k22, each tangent is solved on its own (dvel_i / k_ii, a no-op for a zero k_ii); otherwise the result is the same as before. The 2D build and the generic (multibody) constraints already solve per tangent and are unchanged. tests/plane_locked_friction.rs: a plane-locked cuboid shoved at 3 m/s now stops where a free one does (0.91 m); it slid 9 m before. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 9 +++ .../rapier3d/tests/plane_locked_friction.rs | 71 +++++++++++++++++++ .../contact_constraint_element.rs | 42 ++++++----- 3 files changed, 106 insertions(+), 16 deletions(-) create mode 100644 crates/rapier3d/tests/plane_locked_friction.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index a3d611b29..b4a1132fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,12 @@ +## Unreleased + +### Fixed + +- 3D friction no longer vanishes for a body locked to a plane (a locked translation with both + rotations across it locked, e.g. 2D bodies simulated in a 3D world): the friction solve falls + back to one tangent at a time when its 2×2 effective-mass matrix is singular, instead of dropping + friction along both tangents. + ## v0.36.1 (4 October 2026) ### Added diff --git a/crates/rapier3d/tests/plane_locked_friction.rs b/crates/rapier3d/tests/plane_locked_friction.rs new file mode 100644 index 000000000..fcd1edc71 --- /dev/null +++ b/crates/rapier3d/tests/plane_locked_friction.rs @@ -0,0 +1,71 @@ +//! A body locked to a plane (no movement along z, no turning about x or y) must keep its +//! friction. That lock keeps 3D bodies in a plane, and is how 2D bodies are run inside a 3D +//! world. The locked tangent has no effective mass, which made the 2×2 tangent matrix +//! singular; the coupled solve then zeroed friction along both tangents and the body slid as +//! if on ice. + +use rapier3d::prelude::*; + +/// How far a unit cube resting on a floor slides after a 3 m/s shove along x. +fn slide(locked_to_plane: bool, model: FrictionModel, settle_first: bool) -> f32 { + let mut world = PhysicsWorld::new(); + world.integration_parameters.friction_model = model; + + let ground = world + .bodies + .insert(RigidBodyBuilder::fixed().translation(Vector::new(0.0, -0.5, 0.0))); + world.colliders.insert_with_parent( + ColliderBuilder::cuboid(20.0, 0.5, 20.0).friction(0.5), + ground, + &mut world.bodies, + ); + + let mut body = RigidBodyBuilder::dynamic().translation(Vector::new(0.0, 0.5, 0.0)); + if !settle_first { + body = body.linvel(Vector::new(3.0, 0.0, 0.0)); + } + if locked_to_plane { + body = body + .enabled_translations(true, true, false) + .enabled_rotations(false, false, true); + } + let handle = world.bodies.insert(body); + world.colliders.insert_with_parent( + ColliderBuilder::cuboid(0.5, 0.5, 0.5).friction(0.5), + handle, + &mut world.bodies, + ); + + if settle_first { + for _ in 0..30 { + world.step(); + } + world.bodies[handle].set_linvel(Vector::new(3.0, 0.0, 0.0), true); + } + for _ in 0..180 { + world.step(); + } + world.bodies[handle].translation().x +} + +#[test] +fn plane_locked_body_keeps_its_friction() { + // Report every case before judging, to see which ones break. + let mut bad = Vec::new(); + for model in [FrictionModel::Simplified, FrictionModel::Coulomb] { + for settle_first in [true, false] { + let free = slide(false, model, settle_first); + let locked = slide(true, model, settle_first); + println!( + "{model:?} settle_first={settle_first}: free {free:.2} m, locked {locked:.2} m" + ); + // v² / (2μg) ≈ 0.92 m; both stop well before 2 m. + if free >= 2.0 || locked >= 2.0 || (free - locked).abs() >= 0.25 { + bad.push(format!( + "{model:?} settle_first={settle_first}: free {free} m, locked {locked} m" + )); + } + } + } + assert!(bad.is_empty(), "{bad:#?}"); +} diff --git a/src/dynamics/solver/contact_constraint/contact_constraint_element.rs b/src/dynamics/solver/contact_constraint/contact_constraint_element.rs index 011d81dcf..3d2539bf5 100644 --- a/src/dynamics/solver/contact_constraint/contact_constraint_element.rs +++ b/src/dynamics/solver/contact_constraint/contact_constraint_element.rs @@ -13,6 +13,30 @@ use simba::simd::SimdValue; #[cfg(feature = "block-solver")] pub(crate) const BLOCK_SOLVER_MIN_CONDITION: crate::math::Real = 0.01; +/// The friction impulse change `K⁻¹·dvel` for the two tangents, from `r = [k11, k22, 2·k12]` +/// (the tangent effective-mass matrix `K`). +/// +/// A tangent with no effective mass (a body that can neither move along it nor turn across +/// it, e.g. one locked to a plane) makes `K` singular: inverting it would zero the friction +/// along *both* tangents, so such a body slides as if on ice. Each tangent is then solved on +/// its own instead, so the free one keeps its friction and the massless one stays a no-op. +#[cfg(feature = "dim3")] +#[inline] +fn tangent_delta_impulse(r: [N; 3], dvel_0: N, dvel_1: N) -> na::Vector2 { + let k11 = r[0]; + let k22 = r[1]; + let k12 = r[2] * N::splat(0.5); + let det = k11 * k22 - k12 * k12; + let inv_det = crate::utils::simd_inv(det); + let singular = det.simd_le(N::splat(1.0e-6) * k11 * k22); + na::vector![ + (dvel_0 * crate::utils::simd_inv(k11)) + .select(singular, (k22 * dvel_0 - k12 * dvel_1) * inv_det), + (dvel_1 * crate::utils::simd_inv(k22)) + .select(singular, (k11 * dvel_1 - k12 * dvel_0) * inv_det) + ] +} + #[derive(Copy, Clone, Debug)] pub(crate) struct ContactConstraintTangentPart { pub torque_dir1: [N::AngVector; DIM - 1], @@ -143,14 +167,7 @@ impl ContactConstraintTangentPart { // `K` the tangent effective-mass matrix. A 1D solve along `dvel` leaves an // orthogonal residual when `K` is anisotropic; iterating it rotates energy between // the tangents and pumps the friction-only mode of large stacks into ejection. - let k11 = self.r[0]; - let k22 = self.r[1]; - let k12 = self.r[2] * N::splat(0.5); - let inv_det = crate::utils::simd_inv(k11 * k22 - k12 * k12); - let delta_impulse = na::vector![ - (k22 * dvel_0 - k12 * dvel_1) * inv_det, - (k11 * dvel_1 - k12 * dvel_0) * inv_det - ]; + let delta_impulse = tangent_delta_impulse(self.r, dvel_0, dvel_1); let new_impulse = self.impulse - delta_impulse; let new_impulse = { let _disable_fe_except = @@ -676,14 +693,7 @@ where // Exact coupled 2×2 solve — see `ContactConstraintTangentPart::solve` // for why the directional approximation must not be used here. - let k11 = self.r[0]; - let k22 = self.r[1]; - let k12 = self.r[2] * N::splat(0.5); - let inv_det = crate::utils::simd_inv(k11 * k22 - k12 * k12); - let delta_impulse = na::vector![ - (k22 * dvel_0 - k12 * dvel_1) * inv_det, - (k11 * dvel_1 - k12 * dvel_0) * inv_det - ]; + let delta_impulse = tangent_delta_impulse(self.r, dvel_0, dvel_1); let new_impulse = self.impulse - delta_impulse; let new_impulse = { let _disable_fe_except =