What Parameters Are Required for a planck.js Prismatic Joint?

Setting up a Prismatic Joint in planck.js requires defining a specific set of parameters and configuration properties to constrain two rigid bodies to move along a single linear axis of translation without rotating relative to each other. This article provides a comprehensive breakdown of the essential initialization parameters—including the body references, local anchor points, and the world axis vector—as well as the optional control parameters like joint limits and motor settings.

Essential Initialization Parameters

A Prismatic Joint constrains two bodies so they can only slide relative to one another along a specified axis. To initialize this joint using planck.PrismaticJoint(def), or via the shortcut world.createJoint(planck.PrismaticJoint(def)), you must populate a joint definition object with several foundational parameters.

1. Body References

Like all joints in planck.js, you must explicitly state which two physics bodies are being linked.

• bodyA: The first rigid body (often considered the base or the parent body).
• bodyB: The second rigid body (the piece that slides relative to bodyA).

2. Anchor Points

Anchor points define the exact location where the joint is attached on each body.

• localAnchorA: The position on bodyA where the joint axis is attached, defined in bodyA’s local coordinate system.
• localAnchorB: The position on bodyB where the joint axis is attached, defined in bodyB’s local coordinate system.

3. The Axis of Motion

• localAxisA: A directional vector (Vec2) representing the linear axis of motion, fixed in the local coordinate system of bodyA. This dictates the precise direction along which bodyB is allowed to slide.

4. Reference Angle

• referenceAngle: The constrained angle between the two bodies, measured in radians. This ensures that bodyB does not rotate relative to bodyA. It is usually calculated as the initial angle of bodyB minus the initial angle of bodyA.

The PrismaticJointDef.initialize Helper

Manually calculating local anchors and axes can be tedious. To simplify setup, planck.js provides a helper function that automatically calculates these local coordinates based on world coordinates:

// Function signature
PrismaticJointDef.initialize(bodyA, bodyB, anchor, axis);

When using this method, the required parameters are:

• bodyA: The first physics body.
• bodyB: The second physics body.
• anchor: A single world-coordinate point (Vec2) where the joint is conceptually pinned initially. The helper translates this into localAnchorA and localAnchorB.
• axis: A world-coordinate vector (Vec2) indicating the direction of allowed sliding. The helper translates this into the required localAxisA.

Optional Control Parameters

Once the fundamental structural parameters are set, you can optionally configure limits and motor properties within the definition object to control the behavior of the joint.

Motion Limits

To prevent the sliding body from traveling infinitely along the axis, you can restrict its range of motion.

• enableLimit: A boolean flag (true or false) to turn translation limits on or off.
• lowerTranslation: The minimum allowed distance between the anchor points along the axis (typically in meters).
• upperTranslation: The maximum allowed distance between the anchor points along the axis (typically in meters).

Motor Settings

The Prismatic Joint includes a built-in linear motor that can apply force to drive the sliding motion automatically.

• enableMotor: A boolean flag to activate or deactivate the joint motor.
• motorSpeed: The target linear velocity for the motor (in meters per second). A positive value moves it along the axis, while a negative value moves it backward.
• maxMotorForce: The maximum force (usually in Newtons) that the motor is permitted to exert to achieve the target motorSpeed. This prevents the motor from generating unrealistic infinite force when blocked by obstacles.