Understanding the Matter.js collisionStart Event

In Matter.js, the collisionStart event fires at the beginning of a tick when two or more rigid bodies begin colliding. Listening to this event provides access to a comprehensive event payload that details the context of the physics engine at that moment, specifically delivering an array of colliding body pairs alongside geometric collision details, contact coordinates, and physical interaction properties.

Top-Level Event Object Properties

When an event callback is attached via Matter.Events.on(engine, 'collisionStart', callback), the callback receives an event object with the following primary properties:

• name: A string containing the event name, which is "collisionStart".
• source: A reference to the object that triggered the event, typically the Matter.Engine instance.
• timestamp: The engine's internal update timestamp for the step during which the collision was detected.
• pairs: An array of Pair objects. This is the most crucial property, containing individual collision records for every pair of overlapping bodies detected during the current frame.

The pairs Array and Pair Structure

Because multiple collisions can occur in a single physics update step, event.pairs groups all active collisions. Each element in the pairs array represents a distinct interaction between two bodies and contains the following key properties:

• bodyA: A reference to the first Matter.Body involved in the collision.
• bodyB: A reference to the second Matter.Body involved in the collision.
• id: A unique string identifier assigned to this specific pair, usually formed by joining the unique IDs of bodyA and bodyB (e.g., "A1_B2").
• isActive: A boolean flag indicating whether the collision pair is currently intersecting.
• isSensor: A boolean flag indicating if either bodyA or bodyB has its isSensor property set to true. When true, physical resolution (bouncing or sliding) is ignored, but collision detection is still reported.
• timeCreated: The engine timestamp when the collision pair was first instantiated.
• timeUpdated: The engine timestamp when the collision pair was most recently updated.
• separation: The calculated distance value showing the separation between the shapes.

Geometric Collision Data (pair.collision)

Nested within each pair is the collision object, which provides low-level geometric and manifold data calculated by the Separating Axis Theorem (SAT) engine:

• normal: A normalized vector ({ x, y }) representing the direction of the collision force perpendicular to the contact surface.
• penetration: A vector ({ x, y }) indicating the direction and magnitude of the overlap between the two bodies.
• depth: A numeric scalar representing how deeply the two bodies have penetrated each other along the normal axis.
• supports: An array of vertex coordinates on the bodies that are closest to or forming the contact edge.
• tangent: A vector perpendicular to the normal, used for calculating friction and lateral forces.

Contact Points and Dynamics Data

The pair object also includes details regarding the physical resolution parameters determined by combining properties of both bodies:

• contacts: An array containing active contact point objects. Each contact holds vertex data where the two bodies physically touch in world space.
• friction: The calculated dynamic friction coefficient applied to the collision response.
• frictionStatic: The calculated static friction coefficient between the colliding surfaces.
• restitution: The calculated elasticity (bounciness) factor resulting from the restitution values of both bodies.
• slop: The numerical tolerance margin used to prevent computational jitter during continuous collision resolution.