Matter.js Default Restitution Value Explained

This article covers the default restitution setting for rigid bodies in the Matter.js 2D physics engine, details what the property controls, and explains how to customize it to achieve realistic collision behavior in your web-based physics simulations.

The Default Restitution Value

In Matter.js, the default value for restitution in any newly created body is 0.

Restitution governs the bounciness or elasticity of a rigid body during collisions. A value of 0 means the body undergoes a completely inelastic collision by default, absorbing impact force without bouncing.

How Restitution Works in Matter.js

Restitution is defined as a floating-point number typically ranging between 0 and 1:

• 0 (Default): Perfectly inelastic. The body will not bounce upon impact.
• 0.1 to 0.9: Semi-elastic. The body bounces while losing a portion of its kinetic energy with each collision.
• 1: Perfectly elastic. The body rebounds with the same kinetic energy it had prior to impact, bouncing indefinitely without energy loss (assuming zero friction and air resistance).
• Greater than 1: Hyper-elastic. The body gains energy upon collision, bouncing higher or faster with each impact.

Collision Resolution Between Two Bodies

When two bodies collide in Matter.js, the resulting bounce is not an average of both bodies' properties. Instead, the engine takes the maximum restitution value between the two colliding entities:

restitution = Math.max(bodyA.restitution, bodyB.restitution);

Because of this calculation, if a bouncing ball with a restitution of 0.8 collides with a floor that has the default restitution of 0, the collision will still use 0.8, resulting in a bounce.

How to Change Restitution

You can set the restitution when instantiating a body using an options object, or you can modify the property directly on an existing body instance.

Setting Restitution on Creation

const bouncingBall = Matter.Bodies.circle(100, 100, 20, {
    restitution: 0.8 // Custom bounciness
});

Updating Restitution Dynamically

const box = Matter.Bodies.rectangle(200, 200, 50, 50);

// Default is 0
console.log(box.restitution); // Output: 0

// Modify the property
box.restitution = 0.5;