Why Do Bodies Fall Asleep in Matter.js?

In Matter.js, a physics body "falls asleep" when the engine detects that its motion has dropped below a specific threshold for a sustained period, temporarily removing it from active physics calculations to optimize performance. This article explains the technical reasons a body enters this state, the underlying mechanics of the sleeping module, and how motion thresholds control the transition.

Performance Optimization via the Sleeping Module

The primary reason a body falls asleep is computational efficiency. Simulating collision detection, resolution, and numerical integration across dozens or hundreds of moving bodies consumes substantial CPU resources. Matter.js includes a built-in Matter.Sleeping module that suspends simulation updates for objects that are completely still or barely moving. When a body is asleep, the engine skips expensive broadphase and narrowphase collision checks for it unless an awake body collides with it.

The Engine Sleeping Configuration

A body will only fall asleep automatically if the feature is explicitly enabled on the engine instance:

engine.enableSleeping = true;

If enableSleeping is set to false (which is often the default behavior depending on how the engine is instantiated), bodies will remain permanently awake regardless of how stationary they are, constantly consuming simulation cycles.

Velocity and Motion Thresholds

Matter.js tracks the kinetic state of each body through its internal motion property. This value is a smoothed, decaying measure of the body's combined linear and angular velocity.

A body falls asleep under the following operational conditions:

1. Low Kinetic Energy: As a body slows down due to friction, air resistance, or collisions, its linear velocity (body.velocity) and angular velocity (body.angularVelocity) approach zero.
2. Motion Calculation: The engine calculates body.motion as an exponential moving average based on changes in position and rotation over consecutive frames.
3. Threshold Traversal: If body.motion remains below the sleep threshold (defined by body.sleepThreshold, which defaults to 60 update cycles), the body transitions its state, setting body.isSleeping = true.

Stable Contact and Resting States

Bodies frequently fall asleep when they reach a stable resting contact with other bodies, such as resting flat on the ground or coming to a halt within a stack. When forces balance out, kinetic energy dissipates through solver iterations. Once microscopic vibrations cease and the contact constraints are satisfied without net movement, the motion value decreases steadily, leading directly to sleep.

Programmatic Triggers

A body may also fall asleep because your code—or a third-party plugin—explicitly commanded it to do so. Matter.js exposes functions to alter sleep states directly:

• Matter.Sleeping.set(body, true): Forces the target body to sleep immediately.
• Setting body.isSleeping = true during initial definition or property mutation.

How a Sleeping Body Wakes Up

A sleeping body remains inactive until external factors disrupt its equilibrium. A body automatically wakes up (isSleeping returns to false) if an awake body collides with it, if forces or impulses are applied via Body.applyForce(), or if its position or velocity is manually modified.