How to Rotate a Composite in Matter.js

This article explains how to rotate a composite structure in the Matter.js 2D physics engine. You will learn how to use the built-in Matter.Composite.rotate function, how to specify a center pivot point, how to apply rotations in an active game loop, and how to handle composite bounds when rotating multiple grouped bodies.

Using the Composite.rotate Method

Matter.js provides a native method within the Composite module designed specifically for transforming groups of bodies. The signature for the method is:

Matter.Composite.rotate(composite, rotation, point, [recursive=true])

Step-by-Step Implementation

1. Create the Composite and Bodies

Define your bodies and group them inside a single composite structure:

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

const engine = Engine.create();
const world = engine.world;

// Create individual bodies
const boxA = Bodies.rectangle(400, 200, 80, 80);
const boxB = Bodies.rectangle(450, 200, 80, 80);

// Create a composite and add the bodies
const myComposite = Composite.create();
Composite.add(myComposite, [boxA, boxB]);

// Add the composite to the simulation world
Composite.add(world, myComposite);

2. Determine the Pivot Point

To rotate a composite, you must provide the coordinates of the pivot point. This can be the center of one specific body or the center point between all bodies:

// Option A: Rotate around a specific body's position
const pivotPoint = boxA.position;

// Option B: Rotate around a custom coordinate in space
const fixedPivot = { x: 400, y: 200 };

If you want to rotate around the geometric center of the entire composite, calculate the center using composite bounds:

const bounds = Composite.bounds(myComposite);
const centerPivot = {
    x: (bounds.min.x + bounds.max.x) / 2,
    y: (bounds.min.y + bounds.max.y) / 2
};

3. Apply the Rotation

Call Composite.rotate with the desired angle in radians:

// Rotate the composite by 45 degrees (Math.PI / 4 radians)
const angleInRadians = Math.PI / 4;
Composite.rotate(myComposite, angleInRadians, centerPivot);

Continuous Rotation in the Simulation Loop

If you want the composite to rotate continuously over time (such as for an obstacle or rotating platform), apply the rotation inside the beforeUpdate engine event:

const { Events } = Matter;

const rotationSpeed = 0.02; // Radians per frame
const pivot = { x: 400, y: 200 };

Events.on(engine, 'beforeUpdate', () => {
    Composite.rotate(myComposite, rotationSpeed, pivot);
});

Important Considerations