Static vs Dynamic Bodies in Matter.js Explained

In Matter.js, rigid bodies represent the physical objects that interact within a simulation, and they fall into two primary categories: static bodies and dynamic bodies. The core difference between the two lies in how they respond to forces, gravity, and collisions. While dynamic bodies move freely, respond to physics forces, and bounce off other objects, static bodies remain completely fixed in place, acting as immovable obstacles or boundaries. Understanding how to configure and utilize these two body types is fundamental to building any realistic physics simulation with the library.

What is a Dynamic Body?

By default, any rigid body created in Matter.js is a dynamic body. Dynamic bodies possess standard physical properties such as mass, density, velocity, restitution (bounciness), and friction.

Key characteristics of dynamic bodies include:

• Response to Gravity: Dynamic bodies naturally accelerate downward when an engine-level gravity force is active.
• Force and Collision Reactions: When another body collides with a dynamic body, momentum is transferred, causing the dynamic body to push, rotate, or bounce based on its mass and velocity.
• Continuous Motion: They update their positions and angles automatically on every tick of the physics engine loop.

Common use cases for dynamic bodies include player-controlled characters, falling crates, bouncing balls, projectiles, or any element meant to simulate natural physical motion.

What is a Static Body?

A static body is created by explicitly setting the isStatic property to true in its configuration options. Conceptually, a static body has infinite mass and infinite inertia within the physics calculation engine.

Key characteristics of static bodies include:

• Immunity to Forces: Static bodies completely ignore gravity, drag, and any applied forces or impulses.
• Immovable in Collisions: When a dynamic body strikes a static body, the static body will not budge or rotate. It reflects forces entirely back onto the colliding dynamic object.
• Manual Repositioning: Although they do not move via physics forces, developers can still move static bodies programmatically using utility methods like Body.setPosition() or Body.setVelocity() to create moving platforms or animated hazards.

Common use cases for static bodies include floors, boundary walls, non-destructible obstacles, and terrain.

Key Differences at a Glance

Code Implementation Example

Configuring whether a body is dynamic or static is handled during body initialization via the options object:

// Creating a dynamic body (default)
const dynamicBox = Matter.Bodies.rectangle(400, 200, 50, 50, {
  restitution: 0.8,
  density: 0.001
});

// Creating a static body
const staticFloor = Matter.Bodies.rectangle(400, 600, 800, 50, {
  isStatic: true
});

// Adding both to the engine world
Matter.Composite.add(engine.world, [dynamicBox, staticFloor]);

You can also dynamically change a body's type during runtime using the Body.setStatic() method:

// Convert a dynamic body into a static body
Matter.Body.setStatic(dynamicBox, true);

// Convert a static body into a dynamic body
Matter.Body.setStatic(staticFloor, false);

Performance Considerations

Static bodies offer performance advantages in Matter.js because the engine does not need to compute collision resolutions or trajectory paths between two static bodies. Keeping non-moving environment pieces strictly static reduces unnecessary collision checks and keeps simulation frame rates smooth.