Matter.js Compound Body Relative Part Movement

In Matter.js, parts belonging to a compound body cannot move relative to one another during the physics simulation because compound bodies are strictly rigid structures. When you group multiple shapes into a single compound body, their relative positions, angles, and offsets become permanently fixed to the parent body's center of mass. To achieve relative movement—such as articulation, rotating joints, or sliding mechanisms—developers must connect separate rigid bodies using constraints rather than relying on a compound body, or manually reconstruct the compound body via programmatic updates.

Why Compound Body Parts Are Rigid

When you create a compound body using Body.create({ parts: [...] }), Matter.js calculates a unified mass, moment of inertia, and center of mass for the entire structure. The physics engine treats the entire collection of shapes as a single polygon mesh.

Forces, torques, and collisions applied to any sub-part immediately affect the entire structure as a whole. Matter.js does not calculate independent velocities, friction, or collision responses for sub-parts. Because of this architectural design, internal relative movement within a compound body cannot happen organically through the physics pipeline.

The Solution: Using Constraints for Relative Motion

If your project requires components that articulate, pivot, or slide relative to each other (such as a ragdoll, a vehicle suspension, or a door hinge), you must use Constraints (Matter.Constraint) between individual bodies rather than defining a compound body.

To build an articulated mechanism:

1. Create each component as an independent Matter.Body.
2. Connect them using Matter.Constraint.create().
3. Configure the constraint's properties, such as stiffness, length, and pointA/pointB anchor offsets.

This approach allows each part to maintain its own velocity, orientation, and physics calculations while remaining tethered to the other parts.

Programmatically Modifying Compound Parts

If you must use a compound body—for example, to optimize performance or simplify collision handling—the only way to adjust relative part positions is to modify them manually outside the continuous simulation step.

You can reposition a part by changing its position or angle and then calling Matter.Body.setParts(parentBody, updatedParts).

While this technique alters the shape of the body, it has significant drawbacks:

• It forces Matter.js to recalculate the parent body's center of mass, inertia, and bounds on every update.
• It can cause visual jitter, physics instability, or objects clipping through one another if changes occur while colliding.
• It does not produce natural physical forces; movements are purely kinematic and teleport the vertices.

For realistic interactions and interactive mechanisms, use constraints between individual bodies instead of attempting to move parts inside a compound body.