Highlight Sleeping Bodies with showSleeping in Matter.js

This article explains how to visually identify inactive bodies in Matter.js by utilizing the showSleeping render configuration alongside custom wireframe colors. You will learn how to enable the sleeping module on the physics engine, activate sleeping visual indicators in the Matter.js renderer, and dynamically modify wireframe stroke colors when rigid bodies enter and exit their sleeping state.

Enabling the Sleeping Module

Matter.js disables body sleeping by default to save computation overhead on state tracking. To allow bodies to sleep when they come to rest, you must set enableSleeping to true when instantiating or configuring the Matter.Engine.

const engine = Matter.Engine.create({
    enableSleeping: true
});

Configuring the Renderer for Sleeping Bodies

The built-in Matter.Render module provides a showSleeping flag within its options object. When using wireframe mode (wireframes: true), enabling showSleeping instructs the renderer to visually alter bodies that have entered the sleeping state by lowering their opacity.

const render = Matter.Render.create({
    element: document.body,
    engine: engine,
    options: {
        width: 800,
        height: 600,
        wireframes: true,
        showSleeping: true
    }
});

Customizing Wireframe Colors on Sleep

While showSleeping: true visually dims sleeping bodies, setting distinct, unique wireframe colors requires listening to engine sleep events. You can listen to sleepStart and sleepEnd on the Matter.Events module to change a body's render.wireframeStrokeStyle property dynamically.

// Change to a unique wireframe color when the body sleeps
Matter.Events.on(engine, 'sleepStart', (event) => {
    const body = event.source;
    
    // Cache the original stroke style if not already saved
    if (!body.render.defaultStrokeStyle) {
        body.render.defaultStrokeStyle = body.render.wireframeStrokeStyle || '#bbb';
    }
    
    // Assign a unique color for the sleeping state
    body.render.wireframeStrokeStyle = '#ff3333'; 
});

// Restore original color when the body wakes up
Matter.Events.on(engine, 'sleepEnd', (event) => {
    const body = event.source;
    body.render.wireframeStrokeStyle = body.render.defaultStrokeStyle;
});

Complete Implementation

Below is a complete script demonstrating an engine with sleeping enabled, renderer options set, and custom wireframe highlighting applied upon sleep:

const { Engine, Render, Runner, Bodies, Composite, Events } = Matter;

// 1. Create engine with sleeping enabled
const engine = Engine.create({
    enableSleeping: true
});

// 2. Create renderer with wireframes and showSleeping enabled
const render = Render.create({
    element: document.body,
    engine: engine,
    options: {
        width: 800,
        height: 600,
        wireframes: true,
        showSleeping: true
    }
});

// 3. Create sample bodies
const ground = Bodies.rectangle(400, 590, 810, 30, { isStatic: true });
const box = Bodies.rectangle(400, 200, 80, 80, {
    restitution: 0.2,
    render: {
        wireframeStrokeStyle: '#2ecc71' // Default awake wireframe color
    }
});

Composite.add(engine.world, [ground, box]);

// 4. Handle unique sleeping wireframe colors
Events.on(engine, 'sleepStart', (event) => {
    event.source.render.wireframeStrokeStyle = '#e74c3c'; // Sleeping wireframe color
});

Events.on(engine, 'sleepEnd', (event) => {
    event.source.render.wireframeStrokeStyle = '#2ecc71'; // Restored wireframe color
});

// 5. Run the engine and renderer
Render.run(render);
Runner.run(Runner.create(), engine);