Skip to main content

rigid_body_locking_translations_rotations

It is sometimes useful to prevent a rigid-body from rotating or translating. One typical use-case for locking rotations is to prevent a player modeled as a dynamic rigid-body from tilting. These kind of degree-of-freedom restrictions could be achieved by joints, but locking translations/rotations of a single rigid-body wrt. the cartesian coordinate axes can be done in a much more efficient and numerically stable way. That's why rigid-bodies have dedicated methodsflagsmethodsflagsflags for this.

/* Lock translations/rotations when the rigid-body is created. */
let rigid_body = RigidBodyBuilder::dynamic()
    .lock_translations() // prevent translations along along all axes.
    .lock_rotations() // prevent rotations.
    .build();
/* Lock translations/rotations after the rigid-body creation. */
let rigid_body = &mut world.bodies[rigid_body_handle];
// The last `true` argument makes sure the rigid-body is awake.
rigid_body.lock_translations(true, true);
rigid_body.lock_rotations(true, true);
 
/* Lock translations and/or rotations when the rigid-body bundle is created. */
commands
    .spawn(RigidBody::Dynamic)
    .insert(LockedAxes::TRANSLATION_LOCKED);
/* Lock translations and/or rotations inside of a system. */
fn modify_body_locked_flags(mut locked_axes: Query<&mut LockedAxes>) {
    for mut locked_axes in locked_axes.iter_mut() {
        *locked_axes = LockedAxes::ROTATION_LOCKED;
    }
}
 
/* Lock translations/rotations when the rigid-body is created. */
let rigidBodyDesc = RAPIER.RigidBodyDesc.dynamic()
    .lockTranslations() // prevent translations along along all axes.
    .lockRotations();   // prevent rotations.
let rigidBody = world.createRigidBody(rigidBodyDesc);
/* Lock translations/rotations after the rigid-body creation. */
// The last `true` argument makes sure the rigid-body is awake.
rigidBody.lockTranslations(true, true);
rigidBody.lockRotations(true, true);

The locked axes are given by a bitmask combining the R3_LOCK_TRANSLATION_X, R3_LOCK_TRANSLATION_Y, R3_LOCK_TRANSLATION_Z, R3_LOCK_ROTATION_X, R3_LOCK_ROTATION_Y, and R3_LOCK_ROTATION_Z flags (in 2D, only the translations along X and Y, and the rotation around Z, are relevant). It is set with the lockedAxes field of R3RigidBodyDesc when the rigid-body is created, or with r3RigidBody_SetLockedAxes afterwards (and read with r3RigidBody_LockedAxes). The r3RigidBody_SetTranslationsLocked and r3RigidBody_SetRotationsLocked functions lock (or unlock) all the translations or all the rotations at once.

/* Lock translations/rotations when the rigid-body is created. */
R2RigidBodyDesc rigid_body = r2DynamicRigidBodyDesc();
rigid_body.lockedAxes = R2_LOCK_TRANSLATION_X | R2_LOCK_TRANSLATION_Y // prevent translations along all axes.
                        | R2_LOCK_ROTATION_Z;                         // prevent rotations.
/* Lock translations/rotations after the rigid-body creation. */
// The last `1` argument makes sure the rigid-body is awake.
r2RigidBody_SetTranslationsLocked(rigid_body_handle, 1, 1);
r2RigidBody_SetRotationsLocked(rigid_body_handle, 1, 1);

The locked axes are given by a LockedAxes value combining, with the | operator, the TRANSLATION_LOCKED_X, TRANSLATION_LOCKED_Y, TRANSLATION_LOCKED_Z, ROTATION_LOCKED_X, ROTATION_LOCKED_Y, and ROTATION_LOCKED_Z flags (or TRANSLATION_LOCKED and ROTATION_LOCKED to lock all the translations or all the rotations at once). It is set with RigidBodyBuilder.locked_axes when the rigid-body is created, or with the RigidBody.locked_axes property afterwards. Alternatively, the enabled_translations and enabled_rotations builder methods and properties take a tuple of three booleans indicating, for each axis, if the corresponding translation or rotation is allowed.

# Lock translations/rotations when the rigid-body is created.
rigid_body = (
    rp.RigidBody.dynamic()
    # Prevent translations along all axes, and rotations around all axes.
    .locked_axes(rp.LockedAxes.TRANSLATION_LOCKED | rp.LockedAxes.ROTATION_LOCKED)
    # Only enable rotations around the X axis.
    .enabled_rotations((True, False, False))
    .build()
)
# Lock translations/rotations after the rigid-body creation.
rigid_body = world.rigid_bodies[rigid_body_handle]
# Setting these properties automatically wakes the rigid-body up.
rigid_body.locked_axes = rp.LockedAxes.TRANSLATION_LOCKED | rp.LockedAxes.ROTATION_LOCKED
# Only enable rotations around the X axis.
rigid_body.enabled_rotations = (True, False, False)