What Is Restitution in Matter.js?

In Matter.js, the term restitution defines the elasticity or "bounciness" of a rigid body during a collision. This article covers how restitution works within the Matter.js 2D physics engine, how its numerical values govern the conservation of kinetic energy, how collisions between two bodies are resolved, and how to implement this property in your code.

The Physics of Restitution

Restitution in Matter.js is an implementation of the physical coefficient of restitution. It determines how much kinetic energy is retained after a collision occurs between two bodies. When a moving body hits another object, restitution dictates whether the body stops dead on impact, rebounds with partial energy, or bounces back with full velocity.

Restitution Value Ranges

The restitution property is a floating-point number assigned to a rigid body's options:

• restitution: 0 (Inelastic Collision): The body will not bounce at all. All kinetic energy perpendicular to the collision surface is dissipated upon impact, causing the object to stop instantly against the colliding surface.
• 0 < restitution < 1 (Partially Elastic Collision): This is the typical range for realistic physical simulations. The body rebounds, but loses a portion of its velocity and kinetic energy on each bounce until it eventually comes to rest.
• restitution: 1 (Perfectly Elastic Collision): The body retains 100% of its kinetic energy. In the absence of air resistance or other opposing forces, an object dropped onto a flat surface will bounce back to the exact height from which it was released indefinitely.
• restitution > 1 (Hyper-Elastic Collision): The body gains kinetic energy with every collision, bouncing away faster than its incoming velocity. While physically unrealistic, this can be used intentionally for arcade-style mechanics like pinball bumpers.

How Matter.js Resolves Collisions

When two bodies collide, Matter.js must calculate a single restitution value for the impact point. By default, the engine uses the maximum restitution value between the two colliding entities:

\[\text{Collision Restitution} = \max(\text{bodyA.restitution}, \text{bodyB.restitution})\]

Because the engine selects the higher value, a ball with a restitution of 0.8 hitting a floor with a restitution of 0 will still rebound with a coefficient of 0.8. To achieve a completely inelastic collision where no bouncing occurs, both colliding bodies must have their restitution set to 0.

Setting Restitution in Code

You can define restitution when instantiating a body or modify it dynamically at runtime:

// Setting restitution during body creation
const bouncyBall = Matter.Bodies.circle(100, 100, 20, {
    restitution: 0.8
});

// Setting restitution on a static floor
const ground = Matter.Bodies.rectangle(400, 600, 810, 60, { 
    isStatic: true,
    restitution: 0.5 
});

// Updating restitution dynamically
bouncyBall.restitution = 0.2;

Key Considerations

While restitution controls bounciness, real-world bounce behavior in Matter.js is also influenced by other properties:

• friction and frictionAir: Air resistance and surface friction can decelerate a body even if restitution is set to 1.
• slop and Sleeping: Very low-energy bounces might be cut off early by the physics engine's sleep threshold to optimize performance and prevent infinite micro-jittering when bodies come to rest.