Forces

Apply forces, torques, and generalized forces

Methods for applying external forces and torques to bodies.

applyForce(bodyName, force, point?)

Apply a force to a body at an optional point.

// Push body upward
api.applyForce("block", new THREE.Vector3(0, 0, 10));

// Push at a specific point (creates torque)
api.applyForce("block",
  new THREE.Vector3(5, 0, 0),
  new THREE.Vector3(0.1, 0, 0.05)
);

bodyName · string · required

Name of the body to apply force to.

force · THREE.Vector3 · required

Force vector in world coordinates (Newtons).

point · THREE.Vector3

Application point in world coordinates. If omitted, force is applied at the body’s center of mass.

applyTorque(bodyName, torque)

Apply a pure torque to a body.

api.applyTorque("wheel", new THREE.Vector3(0, 0, 5)); // Spin around Z

bodyName · string · required

Name of the body.

torque · THREE.Vector3 · required

Torque vector in world coordinates (N·m).

setExternalForce(bodyName, force, torque)

Set both force and torque on a body via xfrc_applied.

api.setExternalForce(
  "block",
  new THREE.Vector3(0, 0, 10),  // Force
  new THREE.Vector3(0, 0, 1),   // Torque
);

bodyName · string · required

Name of the body.

force · THREE.Vector3 · required

Force vector (N).

torque · THREE.Vector3 · required

Torque vector (N·m).

xfrc_applied layout per body is [torque(3), force(3)]. This method writes both components.

applyGeneralizedForce(values)

Apply forces in generalized (joint) coordinates.

const forces = new Float64Array(model.nv).fill(0);
forces[0] = 10; // Torque on first joint
api.applyGeneralizedForce(forces);

values · Float64Array | number[] · required

Array of length model.nv with forces/torques in generalized coordinates.

Important: Force Lifecycle

The provider zeros qfrc_applied at the start of each frame. Forces applied via these API methods (or useBeforePhysicsStep) only persist for one physics step.

To apply a continuous force, call it every frame:

useBeforePhysicsStep(() => {
  api.applyForce("block", new THREE.Vector3(0, 0, 9.81 * mass)); // Hover
});

setCtrl(nameOrValues, value?)

Set actuator controls by name or as a batch.

// Single actuator by name
api.setCtrl("gripper", 0.04);

// Multiple actuators at once
api.setCtrl({
  joint1: 0.5,
  joint2: -0.3,
  gripper: 0.04,
});

nameOrValues · string | Record<string, number> · required

Actuator name (with value param) or object mapping names to values.

value · number

Control value (when nameOrValues is a string).

getCtrl()

Get all actuator control values.

const ctrl = api.getCtrl(); // Float64Array of length nu

Returns: Float64Array