Matter.js Composite vs Compound Body Explained

In Matter.js, both compound bodies and composites are used to group elements together, but they serve entirely different architectural and physical purposes. A compound body is a single rigid physical body constructed from multiple shapes that move together as an indivisible unit, whereas a composite is an organizational container used to hold and manage multiple independent bodies, constraints, and even other composites. Understanding the distinction between the two is essential for managing physics simulations, collision behavior, and performance in Matter.js.

What Is a Compound Body?

A compound body is an instance of Matter.Body formed by combining multiple smaller body parts into one rigid object using Matter.Body.create({ parts: [...] }).

• Single Rigid Entity: The individual parts lose their independent physical properties. They share a single center of mass, total mass, velocity, inertia, and angle.
• Zero Internal Flexibility: The relative positions of the parts are permanently locked. They cannot bend, stretch, or rotate independently of each other.
• Complex Geometry: Matter.js handles concave polygons poorly on their own; compound bodies solve this by allowing you to construct complex, concave shapes out of multiple convex shapes.
• Collision Behavior: When any part of a compound body collides with an external object, the impact forces apply to the entire compound entity as a whole.

What Is a Composite?

A composite (Matter.Composite) is a high-level data structure designed to group multiple simulation objects. In fact, the top-level simulation environment (engine.world) is itself a composite.

• Collection Container: A composite does not represent a physical object itself. Instead, it contains arrays of bodies, constraints, and nested composites.
• Independent Physics: The bodies inside a composite retain their own mass, velocity, collisions, and individual physical behaviors.
• Flexible Connections: Bodies within a composite can move independently or be linked dynamically using Matter.Constraint objects (such as springs, joints, or elastic bands).
• Hierarchical Structure: Composites can be nested inside other composites, making them ideal for managing complex, multi-part systems.

Key Differences

1. Rigidity vs. Flexibility

A compound body is strictly rigid. If you build a vehicle as a compound body, the chassis and wheels are welded together permanently, meaning the wheels cannot rotate around an axle. In contrast, building a vehicle using a composite allows you to create the chassis and wheels as separate bodies connected by constraints, enabling wheel rotation and suspension movement.

2. Collision and Physics Processing

In a compound body, internal parts do not collide with one another. Matter.js calculates collision vertices for all parts and treats the outcome as an interaction with a single body. In a composite, every body inside the container is treated as an individual actor in the broadphase and narrowphase collision pipeline, meaning they can collide with each other unless explicitly disabled via collision filters.

3. Management and Manipulation

You apply forces, torques, and velocities directly to a compound body, and all constituent parts react instantly in unison. With a composite, you cannot directly apply a single physical force to the composite itself; you must apply forces to individual bodies within the composite or iterate over its collection.

When to Use Which

• Use a Compound Body when: You need a single, unbreakable, rigid object with a complex shape (such as an L-shaped block, a hollow container, or a complex concave game obstacle).
• Use a Composite when: You need to model articulated systems with moving parts (such as ragdolls, ropes, cloth simulations, or vehicles with functional wheels), or when organizing game levels into modular, manageable groups.