Broad-Phase Collision Detection in Matter.js

Matter.js fully supports broad-phase collision detection to optimize performance in 2D physics simulations. This article explains how Matter.js utilizes broad-phase algorithms to filter out distant objects, the specific data structures and bounding methods it employs, and how this initial phase integrates with narrow-phase collision resolution to maintain high frame rates even with numerous active bodies.

How Broad-Phase Detection Works in Matter.js

In any physics simulation involving multiple objects, checking every body against every other body creates an \(O(n^2)\) computational bottleneck. Broad-phase collision detection solves this problem by rapidly identifying which pairs of bodies are potentially overlapping, eliminating impossible collisions before expensive mathematical checks take place.

Matter.js implements broad-phase collision detection by default through its internal collision detection pipeline, primarily driven by the Matter.Detector module.

Axis-Aligned Bounding Boxes (AABB)

The primary mechanism Matter.js uses in the broad phase is Axis-Aligned Bounding Box (AABB) overlap testing.

  1. Bounds Calculation: Every rigid body in Matter.js updates its bounds property whenever it moves, rotates, or scales. The bounds represent the smallest non-rotated rectangle that completely encloses the body.
  2. Overlap Testing: The broad-phase algorithm checks for intersections between these rectangular bounds. Because checking whether two axis-aligned rectangles overlap requires only simple numerical comparisons along the X and Y axes, this check is computationally lightweight.
  3. Pair Generation: Only pairs of bodies whose bounding boxes overlap are flagged as candidate pairs and added to the collision list.

Spatial Partitioning and Grid Structures

To avoid testing every bounding box against every other bounding box, Matter.js can utilize spatial partitioning techniques. In earlier versions, Matter.Grid divided the simulation space into discrete cells, mapping bodies to specific regions of the canvas.

In modern versions, Matter.js optimizes broad-phase detection directly inside the Detector and Pairs modules. These modules track active pairs across frames, caching persistent contacts and rapidly sorting bodies along axes to minimize redundant overlap checks.

Collision Filtering

Matter.js also optimizes the broad phase through built-in collision filtering. Each body possesses a collisionFilter property that defines its category, mask, and group.

Before any spatial or geometric overlap calculations occur, the broad-phase detector evaluates these bitmasks. If two bodies belong to non-colliding categories or groups, the engine discards the pair immediately, saving CPU cycles.

Transition to the Narrow Phase

Once the broad-phase algorithm isolates the candidate pairs whose bounding boxes overlap and whose collision filters allow contact, it forwards these pairs to the narrow phase.

Matter.js uses the Separating Axis Theorem (SAT) during the narrow phase to test the actual vertex geometry of the shapes. SAT determines the exact points of contact, penetration depth, and normal vectors necessary for realistic collision resolution. By filtering out non-colliding bodies during the broad phase, Matter.js ensures that heavy SAT calculations run only when collisions are genuinely imminent.