Matter.js Contact Point Object Explained

In Matter.js, collision handling relies on contact points to track and resolve physical interactions between colliding rigid bodies. When two bodies intersect, the engine generates contact pairs that contain an array of individual contact objects. This article breaks down the exact properties stored inside each contact point object in Matter.js, explaining how the engine uses these values to calculate collision responses, restitution, and friction.

The Structure of a Matter.js Contact Object

At its core, a contact point object in Matter.js is lightweight and instantiated via the internal Contact.create() method. Each contact object maintains three primary properties:

• vertex: A direct reference to the specific body vertex involved in the contact. This is not merely a coordinate pair; it is a full Matter.js Vertex object that contains:
  • x and y: The current spatial coordinates of the contact point in the world space.
  • index: The index of the vertex within the parent body's vertex array.
  • body: A reference back to the parent Body to which this vertex belongs.
  • isInternal: A boolean flag indicating whether the vertex sits on an internal edge of a decomposed concave shape.
• normalImpulse: A floating-point number representing the accumulated impulse applied perpendicular to the collision surface (along the collision normal). Matter.js uses this value across frames to prevent objects from sinking into one another and to support warm-starting the iterative solver.
• tangentImpulse: A floating-point number representing the accumulated impulse applied parallel to the collision surface. This property tracks and resolves friction, determining whether bodies stick or slide against each other.

How Matter.js Utilizes Contact Points

During the narrow-phase collision detection stage, the engine determines the overlap geometry and extracts support vertices. For every active contact between two colliding bodies, a contact point object is created or updated and placed inside the contacts array of a collision Pair object (pair.contacts).

During the constraint resolution and integration phases, the physics engine iterates over these contacts. Instead of recalculating forces from scratch every step, Matter.js checks the stored normalImpulse and tangentImpulse. By persisting and updating these impulse values across engine ticks, the engine maintains stability in resting contacts, avoids jitter, and accurately simulates friction and bouncing behavior.