rigid_body_creation_and_insertion

A rigid-body is created from a R3RigidBodyDesc description. This plain structure must first be initialized by one of its constructors (which set the default value of every field), then any of its fields can be modified before it is inserted into the physics world with r3InsertRigidBody. The world copies the description and returns the R3RigidBodyHandle identifying the new rigid-body, which is then given to every function reading or modifying it.

info

The following example shows several fields that can be set to customize the rigid-body being built. The input values are just random so using this example as-is will not lead to a useful result.

Example 2D

// The world that will contain our rigid-bodies.
R2World *world = r2NewWorld();

// Description of a fixed rigid-body.
R2RigidBodyDesc fixed_desc = r2FixedRigidBodyDesc();
// Description of a dynamic rigid-body.
R2RigidBodyDesc dynamic_desc = r2DynamicRigidBodyDesc();
// Description of a kinematic rigid-body controlled at the velocity level.
R2RigidBodyDesc kinematic_velocity_desc = r2KinematicVelocityBasedRigidBodyDesc();
// Description of a kinematic rigid-body controlled at the position level.
R2RigidBodyDesc kinematic_position_desc = r2KinematicPositionBasedRigidBodyDesc();

R2RigidBodyDesc rigid_body = r2DynamicRigidBodyDesc();
// The body type: R2_DYNAMIC, R2_FIXED, R2_KINEMATIC_VELOCITY_BASED, or R2_KINEMATIC_POSITION_BASED.
// Default: the type of the constructor used to initialize the description.
rigid_body.bodyType = R2_DYNAMIC;
// The rigid body translation.
// Default: zero vector.
rigid_body.position.translation = r2Vector(0.0, 5.0);
// The rigid body rotation.
// Default: no rotation.
rigid_body.position.rotation = r2Rotation(5.0);
// The rigid body position. Will override the translation and rotation set above.
// Default: the identity pose.
rigid_body.position = r2Pose(r2Vector(1.0, 2.0), r2Rotation(0.4));
// The linear velocity of this body.
// Default: zero velocity.
rigid_body.linvel = r2Vector(1.0, 2.0);
// The angular velocity of this body.
// Default: zero velocity.
rigid_body.angvel = 2.0;
// The scaling factor applied to the gravity affecting the rigid-body.
// Default: 1.0
rigid_body.gravityScale = 0.5;
// Whether or not this body can sleep.
// Default: 1
rigid_body.canSleep = 1;
// Whether or not CCD is enabled for this rigid-body.
// Default: 0
rigid_body.ccdEnabled = 0;
// All done, actually create the rigid-body and insert it into the world.
R2RigidBodyHandle rigid_body_handle = r2InsertRigidBody(world, &rigid_body);

Example 3D

// The world that will contain our rigid-bodies.
R3World *world = r3NewWorld();

// Description of a fixed rigid-body.
R3RigidBodyDesc fixed_desc = r3FixedRigidBodyDesc();
// Description of a dynamic rigid-body.
R3RigidBodyDesc dynamic_desc = r3DynamicRigidBodyDesc();
// Description of a kinematic rigid-body controlled at the velocity level.
R3RigidBodyDesc kinematic_velocity_desc = r3KinematicVelocityBasedRigidBodyDesc();
// Description of a kinematic rigid-body controlled at the position level.
R3RigidBodyDesc kinematic_position_desc = r3KinematicPositionBasedRigidBodyDesc();

R3RigidBodyDesc rigid_body = r3DynamicRigidBodyDesc();
// The body type: R3_DYNAMIC, R3_FIXED, R3_KINEMATIC_VELOCITY_BASED, or R3_KINEMATIC_POSITION_BASED.
// Default: the type of the constructor used to initialize the description.
rigid_body.bodyType = R3_DYNAMIC;
// The rigid body translation.
// Default: zero vector.
rigid_body.position.translation = r3Vector(0.0, 5.0, 1.0);
// The rigid body rotation.
// Default: no rotation.
rigid_body.position.rotation = r3RotationFromAxisAngle(r3Vector(0.0, 0.0, 1.0), 5.0);
// The rigid body position. Will override the translation and rotation set above.
// Default: the identity pose.
rigid_body.position = r3Pose(r3Vector(1.0, 3.0, 2.0), r3RotationFromAxisAngle(r3Vector(0.0, 0.0, 1.0), 0.4));
// The linear velocity of this body.
// Default: zero velocity.
rigid_body.linvel = r3Vector(1.0, 3.0, 4.0);
// The angular velocity of this body.
// Default: zero velocity.
rigid_body.angvel = r3Vector(3.0, 0.0, 1.0);
// The scaling factor applied to the gravity affecting the rigid-body.
// Default: 1.0
rigid_body.gravityScale = 0.5;
// Whether or not this body can sleep.
// Default: 1
rigid_body.canSleep = 1;
// Whether or not CCD is enabled for this rigid-body.
// Default: 0
rigid_body.ccdEnabled = 0;
// All done, actually create the rigid-body and insert it into the world.
R3RigidBodyHandle rigid_body_handle = r3InsertRigidBody(world, &rigid_body);

All the fields are optional. The only calls that are required are r3DynamicRigidBodyDesc(), r3FixedRigidBodyDesc(), r3KinematicVelocityBasedRigidBodyDesc(), or r3KinematicPositionBasedRigidBodyDesc(), to initialize the description, and r3InsertRigidBody to actually create the rigid-body. The rigid-body is removed from the world with r3RemoveRigidBody: its last argument indicates if its colliders must be removed as well (if it is 0, they are kept as colliders without parent).

info

Typically, the inertia and center of mass are automatically set to the inertia and center of mass resulting from the shapes of the colliders attached to the rigid-body. But they can also be set manually.