What Happens When an Ammo.js Constraint Breaks

When a physics constraint in ammo.js (the JavaScript port of the Bullet physics engine) breaks, the structural link holding two rigid bodies together is severed, fundamentally altering their behavior in the simulation. This article explains the immediate physical consequences on the connected rigid bodies, how the physics engine processes this separation, and how developers can handle constraint breakage in their code.

Immediate Loss of Restraint

The primary consequence of a broken constraint is that the connected rigid bodies instantly lose all restricted degrees of freedom. Whether the bodies were linked by a hinge, a slider, or a point-to-point (ball-and-socket) constraint, they immediately stop influencing each other’s motion through that link.

From the moment of the break, the bodies behave as completely independent physical entities. They will respond individually to gravity, wind, collisions, and other external forces acting upon them in the physics world.

Retention of Velocity and Momentum

When the constraint breaks, ammo.js obeys the laws of conservation of motion. The rigid bodies do not stop or instantly reset. Instead, they retain the exact linear and angular velocities they possessed at the precise frame the constraint was broken.

For example, if a wrecking ball’s chain constraint breaks while swinging, the ball will fly off tangentially to its arc of rotation, continuing with the velocity it had at the moment of release.

Reactivation of Collisions

When creating a constraint in ammo.js, developers often choose to disable collisions between the two linked rigid bodies to prevent clipping or jittering.

Once the constraint breaks and is removed from the physics world, this collision exemption is typically removed. If the bodies are still overlapping when the constraint breaks, the physics engine will detect a sudden collision and attempt to resolve it. This can result in a violent “explosion” or rapid separation as the engine forces the overlapping meshes apart. To prevent this, developers must manage collision groups or manually adjust the bodies’ positions upon breakage.

How to Handle Constraint Breaking in Code

In ammo.js, constraints do not automatically destroy themselves when they break. Instead, you must configure and manage the breakage programmatically.

Setting the Breaking Threshold

To allow a constraint to break under stress, you must set a breaking impulse threshold:

// Set the maximum impulse the constraint can withstand
constraint.setBreakingImpulseThreshold(expectedForceThreshold);

Detecting the Break

During your physics loop, you must check whether the constraint has been disabled by the engine due to exceeding this threshold:

if (!constraint.isEnabled()) {
    // The constraint has broken
    physicsWorld.removeConstraint(constraint);
    Ammo.destroy(constraint);
}

Once isEnabled() returns false, the constraint no longer applies forces to the bodies. Removing it from the physics world and destroying the pointer prevents memory leaks and ensures the simulation runs efficiently.