How to Enable Joint Motor and Set Torque in Planck.js?

Planck.js, a 2D physics engine rewritten in JavaScript for cross-platform games and simulations, allows developers to dynamically control physics joints using built-in motors. This article provides a straightforward guide on how to enable a joint motor and configure its maximum torque limits to create controlled, programmatic movements in your physics bodies.

Understanding Planck.js Joint Motors

In Planck.js, certain joints—such as the Revolute Joint and the Prismatic Joint—come equipped with an integrated motor. Instead of relying solely on external forces or gravity, a motor applies a torque or force to achieve a desired target speed. This is incredibly useful for simulating mechanisms like car wheels, robotic arms, or conveyor belts.

To make a motor work properly, you must configure three primary properties:

  1. Motor State: Whether the motor is actively ticking or turned off.
  2. Motor Speed: The target angular velocity (for revolute joints) or linear velocity (for prismatic joints).
  3. Maximum Torque/Force: The power limit. Without a maximum torque, the motor might exert infinite force to reach its target speed, causing chaotic physics glitches.

Step-by-Step Implementation

1. Initialize the Joint Definition

Before creating the joint, you need to define its properties. You can enable the motor and set the torque directly in the joint definition object.

const jointDef = {
  bodyA: wheelAnchorBody,
  bodyB: wheelBody,
  localAnchorA: pl.Vec2(0, 0),
  localAnchorB: pl.Vec2(0, 0),
  
  // Enable the motor here
  enableMotor: true,
  
  // Set the target speed (in radians per second)
  motorSpeed: 5.0,
  
  // Set the maximum torque limit
  maxMotorTorque: 100.0
};

// Create the joint in the world
const joint = world.createJoint(pl.RevoluteJoint(jointDef));

2. Modifying the Motor Dynamically at Runtime

Often, you will want to turn motors on and off or adjust their strength while the simulation is running (for example, when a player presses an acceleration key). Planck.js provides direct setter methods on the joint instance for this purpose.

// Activating or deactivating the motor on the fly
joint.enableMotor(true);  // pass false to disable

// Updating the maximum torque capacity
joint.setMaxMotorTorque(150.0);

// Adjusting the speed (negative values reverse the direction)
joint.setMotorSpeed(-2.5);

Essential Tips for Tuning Motor Torque

Finding the right balance for maxMotorTorque depends heavily on the mass of the bodies attached to the joint.