How Matter.Body.scale Affects Properties in Matter.js

In Matter.js, the Matter.Body.scale(body, scaleX, scaleY, [point]) function alters both the visual footprint and the underlying physical characteristics of a rigid body. When a body is scaled, the physics engine does not simply stretch the render geometry; it recalculates geometric dimensions, mass-related attributes, and collision properties. Understanding these automatic updates is essential for maintaining realistic physics simulation and avoiding unexpected behaviors during runtime.

Geometric and Positional Updates

When Matter.Body.scale is invoked, it directly modifies the structural coordinates of the body:

• Vertices: The coordinates defining the body’s polygon are scaled outward or inward relative to the provided origin point (which defaults to body.position).
• Bounds: The axis-aligned bounding box (body.bounds) is recalculated to wrap around the newly positioned vertices, affecting broadphase collision detection.
• Position: If a custom scaling point is specified that differs from the body's current center of mass, the body's position property will translate accordingly to reflect the geometric transformation.
• Axes: The normal vectors used for Separating Axis Theorem (SAT) collision detection are recomputed to match the orientation of the scaled edges.

Area and Mass Recalculation

By default, Matter.js assumes that a body's material composition remains constant when its size changes:

• Area: The body's area is recalculated using the updated vertex coordinates. Uniform scaling by a factor of \(k\) increases the area by \(k^2\). Non-uniform scaling scales the area proportional to \(scaleX \times scaleY\).
• Mass: Because the density of the body remains unchanged, Matter.Body.scale automatically updates the mass based on the formula: \[\text{mass} = \text{density} \times \text{area}\]
• Inverse Mass: The inverseMass (\(1 / \text{mass}\)) is updated simultaneously. Larger bodies become heavier, requiring greater forces or impulses to accelerate or stop.

Moment of Inertia Updates

A change in size has a dramatic effect on a body's rotational behavior:

• Inertia: Rotational inertia measures resistance to torque and angular acceleration. Matter.js recalculates inertia using the new vertices and the updated mass. Because inertia scales with both mass and the square of distance from the pivot, a body scaled uniformly by a factor of \(k\) experiences an increase in inertia proportional to \(k^4\).
• Inverse Inertia: The inverseInertia (\(1 / \text{inertia}\)) is adjusted to ensure accurate torque responses in the collision and constraint solvers.

Compound Bodies

When scaling a compound body (a body consisting of multiple sub-parts):

• The scaling is recursively applied to each child part.
• Each child part's vertices, area, mass, and inertia are updated.
• The parent body recalculates its total mass, total area, and combined center of mass from the updated parts.

Properties That Remain Unchanged

Matter.Body.scale modifies only geometric and mass-derived values. The following physical parameters remain completely unaffected:

• Density: Preserved at its pre-scale value.
• Friction and Restitution: Surface characteristics, such as static friction, dynamic friction, and bounciness, do not alter.
• Velocities: Both linear velocity (body.velocity) and angular velocity (body.angularVelocity) are preserved, meaning the object continues moving at its current speed immediately after the scale operation.