collider_restitution

Restitution controls how elastic (aka. bouncy) a contact is. The elasticity of a contact is controlled by the restitution coefficient. A restitution coefficient set to 1 (fully elastic contact) implies that the exit velocity at a contact has the same magnitude as the entry velocity along the contact normal: it is as if you drop a bouncing ball and it gets back to the same height after the bounce. A restitution coefficient set to 0 implies that the exit velocity at a contact will be zero along the contact normal: it's as if you drop a ball but it doesn't bounce at all.

note

The friction and restitution coefficients are both managed in very similar ways: with the CoefficientCombineRulecombine rules or with contact modification. The paragraph below is almost identical to the paragraph about friction.

Each collider has its own restitution coefficient. This means that when two colliders are in contact, we need to apply a rule that combines the restitution coefficients of these two colliders into a single coefficient that will be used for the contact. This rule is described by the CoefficientCombineRule enumthe R3_COMBINE_* constants:

CoefficientCombineRule::AverageCoefficientCombineRule.AverageR3_COMBINE_AVERAGECoefficientCombineRule.AVERAGE: the average of the two coefficients is used for the contact.
CoefficientCombineRule::MinCoefficientCombineRule.MinR3_COMBINE_MINCoefficientCombineRule.MIN: the minimum among the two coefficients is used for the contact.
CoefficientCombineRule::MultiplyCoefficientCombineRule.MultiplyR3_COMBINE_MULTIPLYCoefficientCombineRule.MULTIPLY: the product of the two coefficients is used for the contact.
CoefficientCombineRule::MaxCoefficientCombineRule.MaxR3_COMBINE_MAXCoefficientCombineRule.MAX: the maximum among the two coefficients is used for the contact.

CoefficientCombineRule::ClampedSum: the sum of the two coefficients, clamped to $[0, 1]$ , is used for the contact.
CoefficientCombineRule::GeometricMean: the square root of the product of the two coefficients is used for the contact. It is stricter than the average (a coefficient of zero results in zero) but less aggressive than the product.

R3_COMBINE_CLAMPED_SUM: the sum of the two coefficients, clamped to $[0, 1]$ , is used for the contact.
R3_COMBINE_GEOMETRIC_MEAN: the square root of the product of the two coefficients is used for the contact. It is stricter than the average (a coefficient of zero results in zero) but less aggressive than the product.

CoefficientCombineRule.CLAMPED_SUM: the sum of the two coefficients, clamped to $[0, 1]$ , is used for the contact.
CoefficientCombineRule.GEOMETRIC_MEAN: the square root of the product of the two coefficients is used for the contact. It is stricter than the average (a coefficient of zero results in zero) but less aggressive than the product.

By default, the AverageR3_COMBINE_AVERAGE rule is used. Each collider can be given its own restitution combine rule. When two colliders are in contact, we need to select one of their combine rule. The following precedence is used: GeometricMean > ClampedSum > Max > Multiply > Min > Average. R3_COMBINE_GEOMETRIC_MEAN > R3_COMBINE_CLAMPED_SUM > R3_COMBINE_MAX > R3_COMBINE_MULTIPLY > R3_COMBINE_MIN > R3_COMBINE_AVERAGE, i.e., the rule with the greatest value wins.

For example if one collider with the Multiply restitution combine rule is in contact with a collider with the Average restitution combine rule, then the Multiply rule will be applied for the restitution coefficient of this contact (i.e. the coefficients of both colliders will be multiplied to obtain the coefficient used by the contact).

info

The CoefficientCombineRulecombine rule system exists to cover a wide variety of use-cases efficiently. If this is not flexible enough, it is possible to get full control over the selection of restitution coefficients for each contact point using contact modification. For example, contact modification allows the simulation of colliders with non-uniform restitution coefficients.

The restitution coefficient and restitution combine rule can both be set when the collider is created or after its creation:

/* Set the restitution coefficient and restitution combine rule
when the collider is created. */
let collider = ColliderBuilder::ball(0.5)
    .restitution(0.7)
    .restitution_combine_rule(CoefficientCombineRule::Min)
    .build();

/* Set the restitution coefficient and restitution combine rule
after the collider creation. */
let collider = &mut world.colliders[collider_handle];
collider.set_restitution(0.7);
collider.set_restitution_combine_rule(CoefficientCombineRule::Min);
assert_eq!(collider.restitution(), 0.7);
assert_eq!(
    collider.restitution_combine_rule(),
    CoefficientCombineRule::Min
);

/* Set the restitution coefficient and restitution combine rule
when the collider is created. */
commands.spawn(Collider::ball(0.5)).insert(Restitution {
    coefficient: 0.7,
    combine_rule: CoefficientCombineRule::Min,
});

/* Set the restitution coefficient and restitution combine rule
inside of a system. */
fn modify_collider_restitution(mut restitutions: Query<&mut Restitution>) {
    for mut restitution in restitutions.iter_mut() {
        restitution.coefficient = 0.7;
        restitution.combine_rule = CoefficientCombineRule::Min;
    }
}

/* Set the restitution coefficient and restitution combine rule
  when the collider is created. */
let colliderDesc = RAPIER.ColliderDesc.ball(0.5)
    .setRestitution(0.7)
    .setRestitutionCombineRule(RAPIER.CoefficientCombineRule.Min);
let collider = world.createCollider(colliderDesc);

/* Set the restitution coefficient and restitution combine rule
   after the collider creation. */
collider.setRestitution(0.7);
collider.setRestitutionCombineRule(RAPIER.CoefficientCombineRule.Min);

/* Set the restitution coefficient and restitution combine rule
when the collider is created. */
R2ColliderDesc collider = r2BallColliderDesc(0.5);
collider.restitution = 0.7;
collider.restitutionCombineRule = R2_COMBINE_MIN;

/* Set the restitution coefficient and restitution combine rule
after the collider creation. */
r2Collider_SetRestitution(collider_handle, 0.7);
r2Collider_SetRestitutionCombineRule(collider_handle, R2_COMBINE_MIN);
assert(r2Collider_Restitution(collider_handle) == (R2Real)0.7);
assert(r2Collider_RestitutionCombineRule(collider_handle) == R2_COMBINE_MIN);

# Set the restitution coefficient and restitution combine rule
# when the collider is created.
collider = (
    rp.Collider.ball(0.5)
    .restitution(0.7)
    .restitution_combine_rule(rp.CoefficientCombineRule.MIN)
    .build()
)

# Set the restitution coefficient and restitution combine rule
# after the collider creation.
collider = world.colliders[collider_handle]
collider.restitution = 0.7
collider.restitution_combine_rule = rp.CoefficientCombineRule.MIN
assert math.isclose(collider.restitution, 0.7, rel_tol=1.0e-6)
assert collider.restitution_combine_rule == rp.CoefficientCombineRule.MIN