Listen to beforeRender and afterRender in Matter.js

Matter.js provides built-in lifecycle hooks that allow developers to execute custom code during the canvas drawing loop. By using the Matter.Events.on method on the Render module instance, you can subscribe to beforeRender and afterRender events to clear frames, draw custom graphics, manage camera positions, or layer UI elements directly on top of the physics simulation canvas.

Subscribing to Render Events

Matter.js uses an event module (Matter.Events) to bind callbacks to engine and renderer operations. To listen for rendering phases, attach your event listeners directly to your Render instance rather than the Engine instance.

Here is a practical setup:

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

// Create engine and renderer
const engine = Engine.create();
const render = Render.create({
    element: document.body,
    engine: engine,
    options: {
        width: 800,
        height: 600,
        wireframes: false
    }
});

// Run engine and renderer
Render.run(render);
const runner = Runner.create();
Runner.run(runner, engine);

// 1. Listen for beforeRender
Events.on(render, 'beforeRender', function(event) {
    const context = render.context;
    
    // Custom actions before physics bodies are drawn
    // Example: Drawing a custom background
    context.fillStyle = '#1e1e1e';
    context.fillRect(0, 0, render.canvas.width, render.canvas.height);
});

// 2. Listen for afterRender
Events.on(render, 'afterRender', function(event) {
    const context = render.context;

    // Custom actions after physics bodies are drawn
    // Example: Drawing a custom UI overlay or HUD
    context.font = '16px Arial';
    context.fillStyle = '#ffffff';
    context.fillText('Custom Layer: Simulation Active', 20, 30);
});

Understanding beforeRender

The beforeRender event triggers on every frame immediately after the canvas is cleared by the built-in renderer, but before any bodies, constraints, or wireframes are drawn.

Common use cases for beforeRender include:

• Applying custom canvas transformations, such as zooming, panning, or camera tracking offsets.
• Drawing custom backgrounds, parallax layers, or decorative environment sprites beneath the physics bodies.
• Pre-calculating custom visual styles based on updated body positions.

Understanding afterRender

The afterRender event triggers once the renderer has finished drawing all bodies, constraints, and debug information for that specific frame.

Common use cases for afterRender include:

• Drawing custom health bars, text labels, or targeting reticles over specific physics bodies.
• Rendering custom particle effects, trails, or lighting overlays that should sit on top of the physical objects.
• Displaying head-up displays (HUD), frame rates, and debug statistics.

Accessing Context and Canvas

Within both callbacks, the render object exposes render.context (the HTML5 2D rendering context) and render.canvas (the DOM canvas element). This provides direct access to native CanvasRenderingContext2D methods like save(), restore(), beginPath(), and drawImage() to render visuals synchronized with the Matter.js internal tick.