Forces

Applies continuous linear force or torque to a Dynamic body.

Forces are integrated by the simulation over time. Apply them during simulation updates for sustained thrust, springs, drag, or gameplay gravity.

High-Level API#

body.add_force(x, y, z)
body.add_force_at_position(fx, fy, fz, px, py, pz)
body.add_force_local(fx, fy, fz, local_x, local_y, local_z)
body.add_torque(x, y, z)

Coordinate spaces#

The local helper changes only the application point: force direction remains world-space. An off-centre force can produce both linear and angular acceleration. All components must be finite.

Force, mass, and timestep#

For a given force, a heavier body accelerates less. A force is not an instantaneous velocity change; its effect depends on the physics timestep and how long it is applied. With the recommended metre/kilogram convention, force is naturally expressed in newtons and torque in newton-metres.

Example#

// Step event: sustained upward thruster.
body.add_force(0, 0, 45);

// World-space force at a local point on the body.
body.add_force_local(12, 0, 0, 0, -0.5, 0);

// Pure rotational force.
body.add_torque(0, 0, 8);

Low-Level / Advanced API#

Low-level at_position uses a world-space point. add_force_local is a high-level convenience helper.

Setters return true on success and false on invalid input, an invalid or stale body, or an unsupported motion type. Getters return the requested value or undefined when the operation fails. Inspect jolt_get_error() for the high-level error.

Verified operation contracts#

These contracts distinguish units, return values, errors and lifetime according to the current implementation. Check results: false, 0 and undefined can mean different things for different methods.