Ammo.js Contact Threshold vs Resting Distance

This article explains the differences between the contact processing threshold and resting contact distances in the ammo.js physics engine. We will explore how these two distinct parameters affect collision detection, simulation performance, and physical stability so you can eliminate jitter and optimize your 3D web applications.

What is the Contact Processing Threshold?

The contact processing threshold (contactProcessingThreshold) is a performance-focused parameter in ammo.js (and the underlying Bullet Physics engine). It determines the maximum distance at which the physics engine will keep and process existing contact points between two rigid bodies.

When two objects collide, ammo.js creates a “contact manifold” containing the points where the objects touch. If the objects begin to separate, ammo.js does not instantly destroy these contact points. Instead, it keeps them active as long as the distance between the objects remains below the contact processing threshold.

• Purpose: It prevents the engine from constantly creating and destroying contact manifolds when objects are slightly moving or sliding against each other.
• Impact: Setting this threshold too low can cause objects to “snag” or jitter because contact points are discarded prematurely and recalculated. Setting it too high wastes CPU cycles processing contact points for objects that are already too far apart to interact.

What is the Resting Contact Distance?

The resting contact distance (often influenced by the collision margin and solver settings in ammo.js) defines the ideal physical separation or allowable penetration depth when two rigid bodies are at rest.

In real-time physics engines, perfect rigid-body contact is mathematically difficult to sustain without objects sinking into each other or vibrating. To solve this, ammo.js allows a tiny, almost invisible amount of penetration between resting objects. The resting contact distance acts as a target value for the constraint solver:

• Purpose: It establishes the equilibrium state where gravity pulling an object down perfectly balances the restorative forces pushing it up.
• Impact: If the resting distance is too deep, objects will noticeably clip into one another. If it is too shallow (or zero), the constraint solver will aggressively push the objects apart the millisecond they touch, causing constant bouncing, sliding, or jittering on flat surfaces.

Key Differences

While both parameters deal with the distance between colliding rigid bodies, they serve entirely different roles in the simulation pipeline:

How to Configure Them in Ammo.js

In ammo.js, you can adjust these properties directly on individual rigid bodies depending on your simulation scale.

// Example: Configuring a rigid body in ammo.js
const rbInfo = new Ammo.btRigidBodyConstructionInfo(...);
const body = new Ammo.btRigidBody(rbInfo);

// Set the contact processing threshold
body.setContactProcessingThreshold(0.02); // Distance in meters/units

// Adjust collision margin to manage resting contact distance
const shape = body.getCollisionShape();
shape.setMargin(0.04); // Default is often 0.04; smaller margins allow closer resting contact

By balancing these two values, you can achieve both high performance and visually stable simulations. Keep your contact processing threshold slightly larger than your resting contact distances to ensure that contacts are maintained smoothly until the objects have clearly separated.