Friction vs FrictionStatic vs FrictionAir in Matter.js

Matter.js provides three distinct properties to control resistance and deceleration for rigid bodies: friction, frictionStatic, and frictionAir. While all three parameters restrict an object's motion, they govern completely different physical interactions—specifically kinetic surface friction, static contact adhesion, and atmospheric drag. Understanding how each property operates allows developers to create precise, realistic physics behaviors ranging from frictionless ice slides to heavy, high-drag movement.

Friction (Kinetic Friction)

The friction property represents kinetic or dynamic friction. It defines the resistance between two rigid bodies that are already in motion while sliding against one another.

• Default Value: 0.1
• Range: Typically 0 to 1
• Behavior: A value of 0 creates a completely frictionless surface where bodies slide indefinitely upon contact (similar to wet ice). A value of 1 creates high resistance, causing moving objects to halt rapidly when touching another body.
• Mechanism: When two bodies collide and slide, Matter.js calculates effective friction using Math.min(bodyA.friction, bodyB.friction).

FrictionStatic (Static Friction)

The frictionStatic property defines the resistance an object must overcome to start moving from a complete standstill while in contact with another surface.

• Default Value: 0.5
• Range: 0 and above
• Behavior: This property keeps stationary objects anchored on slopes or prevents stacked items from immediately slipping. A higher static friction requires a larger force or a steeper angle to initiate sliding.
• Mechanism: As long as the body is stationary, frictionStatic takes precedence. Once the applied force exceeds this static threshold and the body begins to slide, Matter.js transitions to calculating resistance using the dynamic friction property.

FrictionAir (Air Resistance)

The frictionAir property models linear drag or atmospheric resistance acting on a body as it travels through space, independent of any surface contact.

• Default Value: 0.01
• Range: 0 to 1 (usually values below 0.1)
• Behavior: Unlike surface friction, frictionAir affects the object at all times during translation. A value of 0 simulates a vacuum where objects preserve their velocity indefinitely unless acted upon by forces or collisions. Higher values simulate movement through dense mediums like water or thick gel, causing bodies to lose momentum quickly and limiting their terminal velocity under gravity.

Key Differences Summary

• Surface vs. Space: friction and frictionStatic require physical contact between two bodies to have an effect. frictionAir acts on an individual body constantly, even when suspended in free air.
• Movement State: frictionStatic applies only when a body is at rest against a surface, whereas friction applies only when that body is sliding along the surface.
• Primary Use Cases: Use frictionAir to adjust floating speed, falling speed, and overall inertia. Use friction to simulate material roughness like ice, wood, or rubber. Use frictionStatic to control whether objects slip down ramps or hold their position under low forces.