Matter.js Velocity Iterations: Speed vs Accuracy

In Matter.js, the physics engine relies on an iterative solver to calculate how rigid bodies interact, bounce, and transfer momentum. Tuning the engine.velocityIterations property creates a direct trade-off between execution speed and physical realism: lowering the number of iterations reduces the computational workload per frame to achieve higher performance, but it also causes incomplete velocity resolution, leading to physical artifacts like jittering, incorrect bounces, and object overlap.

How Velocity Iterations Work

Matter.js uses an iterative impulse solver to calculate realistic motion during collisions. When multiple rigid bodies collide or connect through constraints, their ideal outgoing velocities cannot be solved instantly in a single pass because resolving one collision inevitably affects another.

To solve this, the engine applies multiple passes—known as velocity iterations—within each update cycle:

1. The engine detects all active collisions and contact points.
2. It calculates impulses to correct the relative velocities along collision normals.
3. It repeats this process sequentially for the number of times defined by velocityIterations.

With each pass, the simulation gets closer to mathematical equilibrium, ensuring all interacting bodies receive proper momentum adjustments.

Why Limiting Iterations Increases Speed

The primary cost in a 2D physics simulation is solving collisions and constraints. The mathematical complexity per tick scales directly with the number of iterations:

\[\text{Total Calculations} \approx \text{Active Collisions} \times \text{Iterations}\]

Reducing velocityIterations directly cuts the number of CPU cycles spent inside the solver loops for every frame. On devices with limited processing power or in scenes with hundreds of simultaneous dynamic bodies, decreasing this value frees up execution time on the main JavaScript thread. This prevents frame drops, reduces simulation lag, and preserves smooth rendering performance.

Why Limiting Iterations Reduces Accuracy

Physics engines approximate real-world behavior through convergence. When you prematurely stop the solver by setting low velocity iterations, the equations never fully converge, resulting in physical inaccuracies:

• Unstable Stacking: In stacks of objects, forces must propagate from the bottom body to the top. Low iterations prevent impulses from traveling all the way through the stack within a single frame, causing towers to wobble, sink into one another, or collapse spontaneously.
• Inaccurate Rebound and Momentum: Colliding bodies may not bounce with the correct restitution. Kinetic energy can either be inadvertently lost or artificially introduced, making collisions feel sluggish or unpredictably explosive.
• Tunneling and Ghost Collisions: Fast-moving bodies depend on accurate velocity calculations to avoid passing through other surfaces. With insufficient iterations, bodies can clip through boundaries or trigger collision responses too late.
• Joint and Constraint Stretching: Springs, ropes, and stiff constraints depend on velocity solving to maintain their target distances. Fewer iterations cause constraints to act rubbery or fail to hold attached bodies in place.

Striking the Right Balance

Matter.js sets velocityIterations to a default value of 4 (alongside a default of 6 for positionIterations).

• Decrease iterations (e.g., 1 to 3) if you are building mobile-friendly games, ambient particle systems, or games with fast-moving, non-stacking entities where frame rate takes priority over strict realism.
• Increase iterations (e.g., 6 to 10+) if your simulation relies on structural stability, precise physical puzzles, or complex systems of interconnected constraints and joints where any physical error ruins the user experience.