Why Do Velocity Iterations Matter in planck.js?

This article explores the critical role of velocity iterations during a planck.js world step, explaining how they calculate object movements, resolve collisions, and impact both physics accuracy and CPU performance.

Understanding the World Step in planck.js

In planck.js (a JavaScript 2D physics engine based on Box2D), the physics simulation progresses over time using the world.step(timeStep, velocityIterations, positionIterations) method. While timeStep determines how much time moves forward, the iteration parameters determine how accurately the forces, collisions, and joints within the world are computed during that slice of time.

The Role of Velocity Iterations

Velocity iterations are specifically responsible for calculating the correct velocities of rigid bodies after accounting for forces, impulses, and collisions.

When bodies collide or are joined together by constraints, the engine cannot solve all overlapping forces perfectly in a single pass. Instead, it uses a sequential impulse solver that loops through all contacts and constraints multiple times to find a stable solution.

• Collision Resolution: Velocity iterations determine how forcefully overlapping objects push away from each other and how kinetic energy is transferred.
• Constraint and Joint Stability: They ensure that joints (like distance or revolute joints) maintain their limits without stretching or breaking unrealistically.
• Friction and Restitution: The solver uses these iterations to apply proper friction forces and bounce effects based on the materials involved.

Balancing Performance and Accuracy

Choosing the right number of velocity iterations is a direct trade-off between physical realism and computational performance.

High Velocity Iterations

Increasing the number of iterations (e.g., 8 or 10) results in a more stable and accurate simulation. Jittering is reduced, fast-moving objects are less likely to clip through walls, and complex joint mechanisms behave predictably. However, this demands significantly more CPU power per frame.

Low Velocity Iterations

Decreasing the iterations (e.g., 2 or 3) speeds up execution, making it ideal for low-powered mobile devices or games with hundreds of active bodies. The downside is that constraints may appear “mushy” or elastic, collisions might feel soft, and objects might glitch through boundaries.

Recommended Baseline: A standard starting point for most 2D web games is 6 velocity iterations, which generally offers a solid balance of realistic collision responses and smooth frame rates.