Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
71 changes: 71 additions & 0 deletions crates/rapier3d/tests/plane_locked_friction.rs
Original file line number Diff line number Diff line change
@@ -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:#?}");
}
Original file line number Diff line number Diff line change
Expand Up @@ -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<N: ScalarType>(r: [N; 3], dvel_0: N, dvel_1: N) -> na::Vector2<N> {
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<N: ScalarType> {
pub torque_dir1: [N::AngVector; DIM - 1],
Expand Down Expand Up @@ -143,14 +167,7 @@ impl<N: ScalarType> ContactConstraintTangentPart<N> {
// `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 =
Expand Down Expand Up @@ -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 =
Expand Down
Loading