Matter.js Engine Configuration Options

When building 2D physics simulations with Matter.js, the Engine module serves as the central controller managing world updates, collision detection, and physical behavior. Initializing an engine via Matter.Engine.create([options]) accepts a configuration object that directly impacts simulation accuracy, physics stability, and rendering performance. Below is a complete breakdown of the properties you can define when creating a Matter.js Engine instance.

Solver Iterations

The solver iterations define how many calculation passes the physics engine executes per update step. Increasing these values yields more stable and accurate constraints and collisions, but at the cost of CPU performance.

• positionIterations (Number, Default: 6): Determines the number of position correction passes performed per update. Higher values reduce visual clipping and overlapping when bodies collide at high speeds.
• velocityIterations (Number, Default: 4): Controls the number of velocity iterations per update. Higher values increase the stability of moving contacts and friction calculations.
• constraintIterations (Number, Default: 2): Sets the number of passes used to resolve constraints (such as springs, ropes, or stiff joints). Complex chains of constraints often require a higher value to prevent stretching.

Gravity

Gravity defines the default directional force exerted on all dynamic bodies within the engine's composite world.

• gravity.x (Number, Default: 0): The horizontal component of the gravity vector. Negative values pull bodies to the left; positive values pull to the right.
• gravity.y (Number, Default: 1): The vertical component of the gravity vector. Positive values pull bodies downward.
• gravity.scale (Number, Default: 0.001): The scaling factor applied to the gravity vector. Adjusting this globally weakens or strengthens gravitational acceleration.

Timing and Simulation Speed

The timing object configures how the engine advances the simulation clock.

• timing.timeScale (Number, Default: 1): A multiplier that dictates the speed of the simulation. A value of 0.5 creates slow-motion effects, 2 doubles the speed, and 0 freezes the simulation.
• timing.timestamp (Number, Default: 0): The current internal simulation time in milliseconds.

Performance and Optimization

• enableSleeping (Boolean, Default: false): Enables body sleeping. When set to true, bodies that come to rest are omitted from collision resolution passes until another active body touches them, significantly reducing CPU usage in scenes with many stationary objects.

World and Collision Detection

• world (Matter.Composite, Default: Composite.create()): Allows you to pass a pre-configured Composite instance to act as the root world. If omitted, the engine instantiates an empty root composite automatically.
• detector (Matter.Detector, Default: null): Allows supplying a custom collision detector implementation for broadphase collision detection instead of the default broadphase system.

Example Initialization

const engine = Matter.Engine.create({
  positionIterations: 8,
  velocityIterations: 6,
  constraintIterations: 4,
  enableSleeping: true,
  gravity: {
    x: 0,
    y: 1,
    scale: 0.001
  },
  timing: {
    timeScale: 1
  }
});