Why Sleeping Bodies Wake Up in Matter.js

In Matter.js, the sleeping mechanism optimizes physics simulations by halting updates for rigid bodies that have settled into a resting state, significantly reducing computational overhead. However, sleeping bodies can unexpectedly wake up due to subtle physics events, manual state manipulations, or constraint dynamics. This article outlines the primary causes of accidental wake-ups in Matter.js—including resting penetration resolution, constraint forces, manual body mutations, and engine-level threshold settings—and provides straightforward methods to prevent them.

Collisions and Bounding Box Overlaps

The most frequent cause of an unintended wake-up is interaction with another body. Matter.js automatically wakes a sleeping body if an active (awake) body touches its collision bounds. Even if the visual overlap is invisible or negligible, broadphase collision detection triggers a pair check. If tiny micro-penetrations or continuous resting contacts are resolved with active forces, the sleeping body is forced awake to respond to the incoming impulse.

Manual Property Changes via Matter.Body

Modifying a body directly bypasses the typical sleep check and forces the body to wake. Using utility functions such as:

• Matter.Body.setPosition()
• Matter.Body.setVelocity()
• Matter.Body.setAngle()
• Matter.Body.applyForce()

internally invokes Sleeping.set(body, false). If you update properties on sleeping bodies inside a render loop or update cycle, they will wake immediately on that frame.

Active Constraints and Springs

Constraints attached between a sleeping body and an active body will wake the sleeping entity whenever tension, compression, or movement occurs. If a constraint has stiffness less than 1 (behaving like an elastic spring), minute oscillations between linked bodies can transmit forces continuously, preventing the sleeping body from remaining inactive or triggering an immediate state change.

Sub-Threshold Velocity and Micro-Jitter

Matter.js monitors a body's kinetic energy and tracks how many consecutive frames it remains below a motion threshold. If ambient forces—such as gravity, resting friction adjustments, or collision sorting—introduce micro-movements exceeding the engine's motion threshold, the body's internal idle counter resets, waking it up before it can fully settle.

Low sleepThreshold Configurations

The sleepThreshold parameter defines how many update ticks a body must remain below the motion limit before it transitions to sleep. If the threshold on engine.enableSleeping is too low, bodies may rapidly flicker between sleeping and waking states. Conversely, if ambient scene vibration keeps the motion variable just high enough, minor external movements will cause a premature wake-up event.

Modifying the World Structure

Adding, removing, or re-indexing composite bodies in an active Matter.Composite can force broadphase spatial recalculations. When spatial partitioning grids rebuild, pairs are re-evaluated, and connected or adjacent resting bodies may be woken up to verify equilibrium.

How to Keep Bodies Asleep

To prevent sleeping bodies from waking unexpectedly:

• Use Static Bodies: If a resting body does not need to react to physics forces, set body.isStatic = true instead of relying on the sleeping state.
• Tune the Sleep Threshold: Increase engine.sleepThreshold (default is 60 frames) to ensure bodies only sleep when completely motionless.
• Avoid Direct Mutations: Do not alter velocities or coordinates of sleeping bodies unless you explicitly want them active.
• Isolate Constraints: Ensure bodies linked by Matter.Constraint reach resting equilibrium at the same time, or break the constraint when a body enters the sleep state.