What Does isStatic True Do in Matter.js

Setting isStatic: true on a body in Matter.js converts a dynamic physical entity into an immovable object, commonly used for environmental elements like floors, walls, and fixed platforms. This article covers the internal engine modifications that take place when enabling this property, including how it alters mass, velocity, collision detection, and performance within a 2D simulation.

Infinite Mass and Inertia

When a body is declared static, Matter.js recalculates its physical properties to represent an object with infinite mass. Under the hood, the engine sets body.mass to Infinity and body.inverseMass to 0. Similarly, rotational properties are updated so that body.inertia becomes Infinity and body.inverseInertia becomes 0. Because physics solvers calculate acceleration using inverse mass (\(a = F \cdot m^{-1}\)), multiplying any force by zero results in zero acceleration, preventing the body from translating or rotating.

Immunity to Forces and Gravity

Because the inverse mass is zero, a static body completely ignores environmental forces, applied impulses, and global engine gravity. Calling methods such as Matter.Body.applyForce() on a static body will have no effect. The engine’s integration step, which typically updates positions and velocities based on current forces, skips static bodies entirely.

Reset of Velocities

Setting isStatic: true zeroes out the body's movement metrics:

Collision Behavior and Interaction

When a dynamic body collides with a static body, the collision resolver treats the static body as an unyielding boundary. The dynamic body absorbs all resulting impulse forces, causing it to bounce, slide, or stop depending on its restitution and friction coefficients. The static body itself remains entirely unaffected by the impact.

Additionally, Matter.js optimizes broadphase collision detection: static bodies do not test for collisions against other static bodies. Since static objects never move on their own, calculating interactions between them is unnecessary, which significantly improves simulation performance.

Manual Transformation

While the physics engine will not move a static body, it can still be moved manually through direct code. Developers can use Matter.Body.setPosition() or Matter.Body.setAngle() to relocate or rotate the body. When moved this way, the body instantly teleports to the target coordinates without generating realistic momentum or velocity-based impacts on dynamic bodies unless manually handled by updating the body's position incrementally over frames.