Can a Matter.js Composite Contain Other Composites?

In Matter.js, a Composite can indeed contain other Composites, allowing developers to create nested, hierarchical structures of physics objects. This article explains how nesting works within the Matter.js physics engine, demonstrates how to add child composites to a parent composite using the core API, and highlights key functions for managing and traversing nested physics hierarchies.

Understanding Composites in Matter.js

A Matter.Composite is a container object designed to hold collections of rigid bodies (Matter.Body), constraints (Matter.Constraint), and other composites (Matter.Composite).

In fact, the root environment in any Matter.js simulation—the engine.world—is itself a top-level composite. Because composites can hold other composites, the entire physics scene graph is structured as a tree.

How to Add a Composite to Another Composite

Nesting composites is handled using the standard Matter.Composite.add method. You pass the parent composite as the first argument and the child composite as the second argument.

const { Engine, Composite, Bodies, Constraint } = Matter;

// Create an engine (engine.world is the root composite)
const engine = Engine.create();

// Create a parent composite and a child composite
const carComposite = Composite.create({ label: 'Car' });
const wheelComposite = Composite.create({ label: 'Wheels' });

// Add bodies to the child composite
const wheelA = Bodies.circle(100, 200, 20);
const wheelB = Bodies.circle(150, 200, 20);
Composite.add(wheelComposite, [wheelA, wheelB]);

// Add the child composite to the parent composite
Composite.add(carComposite, wheelComposite);

// Finally, add the parent composite to the root world composite
Composite.add(engine.world, carComposite);

Accessing and Traversing Nested Objects

When composites are nested, you do not need to manually iterate through every child layer to interact with the underlying bodies. Matter.js provides recursive utility methods on the Composite module:

• Composite.allBodies(composite): Recursively searches the composite and all nested child composites, returning a flat array of all bodies.
• Composite.allConstraints(composite): Recursively retrieves all constraints from the composite and any nested composites.
• Composite.allComposites(composite): Returns a flat array containing all nested composites within the hierarchy.

Removing Nested Composites

To remove a nested composite from its parent, use Composite.remove:

// Removes the child composite and all its contents from the parent
Composite.remove(carComposite, wheelComposite);

When you remove a composite, all bodies, constraints, and subsequent child composites contained within it are automatically removed from the physics simulation update loop.

Practical Benefits of Nesting Composites

1. Modularity: Complex structures like ragdolls, vehicles, rope bridges, or destructible terrain can be packaged as standalone composite modules and easily added or removed as single units.
2. Organization: Large simulations stay organized by grouping related game elements together rather than dumping hundreds of individual bodies directly into engine.world.
3. Bulk Operations: Moving, scaling, or clearing specific object groups is much easier when entire assemblies are isolated within their own sub-composites.