How Matter.Bounds.contains Checks Points in Matter.js

This article explains how the Matter.Bounds.contains method in Matter.js determines whether a given point or screen coordinate falls inside an Axis-Aligned Bounding Box (AABB). It covers the underlying mathematical logic used by the engine, how bounding box data structures are represented, how to properly translate raw screen coordinates into physics world coordinates, and where this method fits within collision detection.

The Axis-Aligned Bounding Box (AABB) in Matter.js

In Matter.js, an AABB is represented by a Bounds object. This structure does not rotate with the body; instead, it expands and contracts to enclose the body's vertices while remaining aligned to the horizontal (\(x\)) and vertical (\(y\)) axes of the world space.

A Bounds object contains two boundary points:

• bounds.min: The upper-left corner of the box, defined by { x: minX, y: minY }.
• bounds.max: The lower-right corner of the box, defined by { x: maxX, y: maxY }.

The Containment Logic

The Matter.Bounds.contains(bounds, point) function performs a constant-time, four-way boundary check. It evaluates whether the given coordinate's horizontal and vertical values lie inclusive of the box's minimum and maximum limits.

The source logic operates as follows:

return (
  point.x >= bounds.min.x &&
  point.x <= bounds.max.x &&
  point.y >= bounds.min.y &&
  point.y <= bounds.max.y
);

If all four conditions evaluate to true, the point resides within the AABB. If any single condition evaluates to false, the check immediately fails and returns false.

Handling Screen Coordinates vs. World Coordinates

When testing screen coordinates—such as mouse clicks or touch events (clientX, clientY)—the raw input values represent viewport space rather than the Matter.js physics world space.

To accurately use Matter.Bounds.contains, screen coordinates must first be transformed if the canvas is scaled, translated, or rendered using a custom camera offset:

1. Canvas Offset: Subtract the canvas's bounding rect offset (e.clientX - canvas.getBoundingClientRect().left).
2. Render Bounds Offset: If render.bounds is active (zooming or panning), add the render's minimum offset (render.bounds.min.x, render.bounds.min.y) and scale according to the viewport zoom ratio.

Example Usage

// Define a point in physics world space
const clickPoint = { x: 150, y: 200 };

// Target body's bounding box
const bodyBounds = body.bounds;

// Check if coordinate is within the AABB
const isInsideAABB = Matter.Bounds.contains(bodyBounds, clickPoint);

if (isInsideAABB) {
  // Point falls within the bounding box
  // Optional: Run Matter.Vertices.contains(body.vertices, clickPoint) for exact polygon checks
}

Role in Collision and Hit Detection

Matter.Bounds.contains is designed for fast, broad-phase evaluation. Because it tests against an axis-aligned rectangle rather than the exact polygon geometry, it may return true for points in the empty space between an irregular or rotated body's edge and its bounding box. For pixel-perfect or vertex-accurate detection, developers typically use Matter.Bounds.contains as a quick rejection filter before executing Matter.Vertices.contains.