rapier3d/dynamics/
coefficient_combine_rule.rs

1use crate::math::Real;
2// Provides `sqrt` in no-std builds (same pattern as island_manager/local_split.rs).
3#[allow(unused_imports)]
4use simba::scalar::ComplexField as _;
5
6/// How to combine friction/restitution values when two colliders touch.
7///
8/// When two colliders with different friction (or restitution) values collide, Rapier
9/// needs to decide what the effective friction/restitution should be. Each collider has
10/// a combine rule, and the "stronger" rule wins
11/// (GeometricMean > ClampedSum > Max > Multiply > Min > Average).
12///
13/// ## Combine Rules
14///
15/// **Most games use Average (the default)** and never change this.
16///
17/// - **Average** (default): `(friction1 + friction2) / 2` - Balanced, intuitive
18/// - **Min**: `min(friction1, friction2).abs()` - "Slippery wins" (ice on any surface = ice)
19/// - **Multiply**: `friction1 × friction2` - Both must be high for high friction
20/// - **Max**: `max(friction1, friction2)` - "Sticky wins" (rubber on any surface = rubber)
21/// - **ClampedSum**: `sum(friction1, friction2).clamp(0, 1)` - Sum of both frictions, clamped to range 0, 1.
22/// - **GeometricMean**: `sqrt(friction1 × friction2)` - Between Multiply and Average; zero if either is zero.
23///
24/// ## Example
25/// ```
26/// # use rapier3d::prelude::*;
27/// // Ice collider that makes everything slippery
28/// let ice = ColliderBuilder::cuboid(10.0, 0.1, 10.0)
29///     .friction(0.0)
30///     .friction_combine_rule(CoefficientCombineRule::Min)  // Ice wins!
31///     .build();
32/// ```
33///
34/// ## Priority System
35/// If colliders disagree on rules, the "higher" one wins:
36/// GeometricMean > ClampedSum > Max > Multiply > Min > Average
37#[derive(Default, Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
38#[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
39pub enum CoefficientCombineRule {
40    /// Average the two values (default, most common).
41    #[default]
42    Average = 0,
43    /// Use the smaller value ("slippery/soft wins").
44    Min = 1,
45    /// Multiply the two values (both must be high).
46    Multiply = 2,
47    /// Use the larger value ("sticky/bouncy wins").
48    Max = 3,
49    /// The clamped sum of the two coefficients.
50    ClampedSum = 4,
51    /// The square root of the product of the two values.
52    ///
53    /// A common convention in other engines (e.g. Bullet, PhysX): stricter than Average
54    /// (either value being zero results in zero) but less aggressive than Multiply for
55    /// values below 1.
56    GeometricMean = 5,
57}
58
59impl CoefficientCombineRule {
60    #[allow(dead_code)]
61    pub(crate) fn combine(
62        coeff1: Real,
63        coeff2: Real,
64        rule_value1: CoefficientCombineRule,
65        rule_value2: CoefficientCombineRule,
66    ) -> Real {
67        let effective_rule = rule_value1.max(rule_value2);
68
69        match effective_rule {
70            CoefficientCombineRule::Average => (coeff1 + coeff2) / 2.0,
71            CoefficientCombineRule::Min => {
72                // Even though coeffs are meant to be positive, godot use-case has negative values.
73                // We're following their logic here.
74                // Context: https://github.com/dimforge/rapier/pull/741#discussion_r1862402948
75                coeff1.min(coeff2).abs()
76            }
77            CoefficientCombineRule::Multiply => coeff1 * coeff2,
78            CoefficientCombineRule::Max => coeff1.max(coeff2),
79            CoefficientCombineRule::ClampedSum => (coeff1 + coeff2).clamp(0.0, 1.0),
80            // Negative coefficients are tolerated (see the Min comment above), so clamp
81            // before taking the square root to avoid NaN on a negative product.
82            CoefficientCombineRule::GeometricMean => (coeff1.max(0.0) * coeff2.max(0.0)).sqrt(),
83        }
84    }
85}
86
87#[cfg(test)]
88mod test {
89    use super::CoefficientCombineRule;
90    use crate::math::Real;
91
92    fn combine(c1: Real, c2: Real, rule: CoefficientCombineRule) -> Real {
93        CoefficientCombineRule::combine(c1, c2, rule, rule)
94    }
95
96    #[test]
97    fn geometric_mean_combine() {
98        assert_eq!(
99            combine(0.25, 1.0, CoefficientCombineRule::GeometricMean),
100            0.5
101        );
102        assert_eq!(
103            combine(0.7, 0.0, CoefficientCombineRule::GeometricMean),
104            0.0
105        );
106        // Negative coefficients (tolerated for the godot use-case) must not produce NaN.
107        assert_eq!(
108            combine(-0.5, 0.5, CoefficientCombineRule::GeometricMean),
109            0.0
110        );
111        assert_eq!(
112            combine(-0.5, -0.5, CoefficientCombineRule::GeometricMean),
113            0.0
114        );
115    }
116
117    #[test]
118    fn geometric_mean_wins_rule_priority() {
119        assert_eq!(
120            CoefficientCombineRule::combine(
121                0.25,
122                1.0,
123                CoefficientCombineRule::GeometricMean,
124                CoefficientCombineRule::Average,
125            ),
126            0.5
127        );
128    }
129}
rapier3d/dynamics/coefficient_combine_rule.rs

rapier3d/dynamics/
coefficient_combine_rule.rs
