Impulses

Applies an instantaneous linear or angular momentum change to a Dynamic body.

Use impulses for hits, jumps, explosions, recoil, and one-frame interactions. Unlike a force, an impulse is applied once and is not multiplied by the simulation duration.

High-Level API#

body.add_impulse(x, y, z)
body.add_impulse_at_position(ix, iy, iz, px, py, pz)
body.add_impulse_local(ix, iy, iz, local_x, local_y, local_z)
body.add_angular_impulse(x, y, z)

Coordinate spaces#

The local helper transforms only the point; the impulse vector remains world-space. An off-centre impulse changes both linear and angular velocity. All components must be finite.

Impulse vs. force#

Example#

// One immediate launch.
body.add_impulse(0, 0, 12);

// Add spin by hitting away from the centre.
body.add_impulse_local(8, 0, 3, 0, -0.6, -0.4);

// Direct angular momentum.
body.add_angular_impulse(0, 0, 2.5);

Low-Level / Advanced API#

Low-level at_position uses a world-space point. add_impulse_local is implemented by the high-level wrapper.

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.