How to Configure Hinge Constraints in Ammo.js

This article explains the concept of a hinge constraint in the ammo.js physics engine and provides a clear guide on how to configure its rotation axis. You will learn what a hinge constraint is, how it restricts movement between rigid bodies, and how to define its pivot points and axis vectors using the ammo.js API.

What is a Hinge Constraint?

A hinge constraint (represented by the btHingeConstraint class in ammo.js) is a physics joint that restricts the relative movement of two rigid bodies to a single rotational axis. It behaves exactly like a real-world door hinge, a steering knuckle, or a wheel axle. By applying this constraint, the connected bodies lose all translation degrees of freedom and two rotational degrees of freedom, leaving them free to rotate only around the specified hinge axis.

You can construct a hinge constraint between two active rigid bodies, or between a single rigid body and a fixed point in the global physics world.

Configuring the Rotation Axis in ammo.js

In ammo.js, which is a direct Emscripten port of the Bullet Physics C++ library, you configure the rotation axis by defining local vectors for the pivot points and the axis directions.

There are two primary ways to set up a btHingeConstraint: using local anchors and axes, or using local transformation frames.

Method 1: Using Pivot and Axis Vectors

This is the most common and intuitive method. You define the hinge by specifying where the pivot is located on each body and which direction the rotation axis points relative to each body’s local coordinate system.

The constructor signature for this method is:

var hinge = new Ammo.btHingeConstraint(
    rigidBodyA, 
    rigidBodyB, 
    pivotInA,     // Ammo.btVector3
    pivotInB,     // Ammo.btVector3
    axisInA,      // Ammo.btVector3
    axisInB,      // Ammo.btVector3
    useReferenceFrameA // boolean
);

To configure the rotation axis, you must define axisInA and axisInB as unit vectors (btVector3) representing the axis of rotation in the local space of rigidBodyA and rigidBodyB.

For example, if you want the two bodies to rotate around their local Y-axes (like a spinning top or a door), you define the axes as follows:

// Define the connection points (pivots) in local coordinates
var pivotInA = new Ammo.btVector3(0, -1, 0); 
var pivotInB = new Ammo.btVector3(0, 1, 0);

// Define the rotation axis (Y-axis for both bodies)
var axisInA = new Ammo.btVector3(0, 1, 0); 
var axisInB = new Ammo.btVector3(0, 1, 0);

// Create the constraint
var hingeConstraint = new Ammo.btHingeConstraint(
    bodyA, 
    bodyB, 
    pivotInA, 
    pivotInB, 
    axisInA, 
    axisInB, 
    true
);

// Add the constraint to the physics world
physicsWorld.addConstraint(hingeConstraint, true);

Method 2: Using Transforms (btTransform)

Alternatively, you can define the hinge using local transformation frames (btTransform).

var hinge = new Ammo.btHingeConstraint(
    rigidBodyA, 
    rigidBodyB, 
    localFrameA, // Ammo.btTransform
    localFrameB, // Ammo.btTransform
    useReferenceFrameA // boolean
);

When using transforms, ammo.js implicitly designates the Z-axis of the local frames as the axis of rotation. To configure the rotation axis using this method, you must rotate the localFrameA and localFrameB transforms so that their Z-axes align with your desired physical hinge axis.