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 flags for this.

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.

Example 2D

/* 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);

Example 3D

/* Lock translations/rotations when the rigid-body is created. */
R3RigidBodyDesc rigid_body = r3DynamicRigidBodyDesc();
rigid_body.lockedAxes =
    R3_LOCK_TRANSLATION_X | R3_LOCK_TRANSLATION_Y | R3_LOCK_TRANSLATION_Z // prevent translations along all axes.
    | R3_LOCK_ROTATION_Y | R3_LOCK_ROTATION_Z; // only enable rotations along the X axis.

/* Lock translations/rotations after the rigid-body creation. */
// The last `1` argument makes sure the rigid-body is awake.
r3RigidBody_SetTranslationsLocked(rigid_body_handle, 1, 1);
r3RigidBody_SetRotationsLocked(rigid_body_handle, 1, 1);
// Only enable rotations along the X axis.
uint8_t locked_axes = r3RigidBody_LockedAxes(rigid_body_handle) & ~R3_LOCK_ROTATION_X;
r3RigidBody_SetLockedAxes(rigid_body_handle, locked_axes, 1);