Understanding Matter.Bounds.translate in Matter.js

This article explains the function of Matter.Bounds.translate and its specific impact on bounding box hierarchies within the Matter.js physics engine. In short, the method applies a linear spatial offset to an individual Axis-Aligned Bounding Box (AABB) by mutating its minimum and maximum coordinates. However, it operates strictly on the targeted Bounds instance in isolation, meaning it does not automatically synchronize or propagate updates through nested parts, parent composites, or spatial acceleration structures.

Direct Functionality of Matter.Bounds.translate

At its core, Matter.Bounds.translate takes two arguments: an existing bounds object (defined by min and max vector vertices) and a translation vector ({ x, y }).

The function modifies the target bounds object in-place by adding the translation coordinates:

• bounds.min.x += vector.x
• bounds.max.x += vector.x
• bounds.min.y += vector.y
• bounds.max.y += vector.y

This linearly shifts the spatial region defined by the bounding box along the specified X and Y axes without altering its dimensions or orientation.

Impact on Bounding Box Hierarchies

In Matter.js, hierarchies typically appear in two ways: compound bodies (bodies composed of multiple sub-parts) and broadphase spatial partitioning structures (such as grids or bounding volume trees used for collision detection).

When applied within these hierarchies, Matter.Bounds.translate behaves with the following consequences:

1. Lack of Recursive Propagation

Matter.Bounds.translate has no inherent awareness of body graphs, parent-child hierarchies, or composite structures. If you invoke it directly on the bounding box of a parent body, the bounds of individual sub-parts (body.parts) remain at their original coordinates. Conversely, translating a child part's bounding box will not update the enclosing parent bounds.

2. Spatial Desynchronization with Geometry

A Bounds object is a spatial abstraction derived from actual geometry (body.vertices). Using Matter.Bounds.translate directly shifts the bounding boundaries without moving the underlying vertices of the body or its children. This creates a desynchronization where the physics body's actual collision shapes are no longer correctly framed by the bounding box.

3. Broadphase Inconsistencies

Matter.js collision detection relies on bounds during the broadphase check to quickly discard non-colliding pairs before computing expensive narrowphase vertex intersections. If a bounding box in a hierarchy is manually translated without a corresponding geometric update:

• False Negatives: If the bounds move away from the body's actual vertices, other objects may visually collide with the body without triggering a collision event.
• False Positives: If the bounds overlap another object but the body's actual shape has not moved, unnecessary narrowphase computations occur.

Recommended Hierarchy Handling

To translate an entire hierarchy correctly, avoid modifying Bounds directly. Instead:

• Use Matter.Body.translate(body, translation), which automatically traverses body.parts, updates vertex positions, translates all corresponding bounds, and maintains broadphase integrity.
• If manually recalculating hierarchical bounds, invoke Matter.Bounds.update(bounds, vertices, velocity) to recalculate bounding limits from transformed vertices rather than applying arbitrary translations.