Skip to main content

rigid_body_creation_and_insertion

A rigid-body is created by a RigidBodyBuilder structure that is based on the builder pattern. Then it needs to be inserted into the RigidBodySet that will be processed by the physics-pipeline or query-pipeline.

info

The following example shows several setters that can be called 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.

use rapier2d::prelude::*;

// The set that will contain our rigid-bodies.
let mut rigid_body_set = RigidBodySet::new();

// Builder for a fixed rigid-body.
let _ = RigidBodyBuilder::fixed();
// Builder for a dynamic rigid-body.
let _ = RigidBodyBuilder::dynamic();
// Builder for a kinematic rigid-body controlled at the velocity level.
let _ = RigidBodyBuilder::kinematic_velocity_based();
// Builder for a kinematic rigid-body controlled at the position level.
let _ = RigidBodyBuilder::kinematic_position_based();
// Builder for a body with a status specified by an enum.
let rigid_body = RigidBodyBuilder::new(RigidBodyType::Dynamic)
    // The rigid body translation.
    // Default: zero vector.
    .translation(vector![0.0, 5.0])
    // The rigid body rotation.
    // Default: no rotation.
    .rotation(5.0)
    // The rigid body position. Will override `.translation(...)` and `.rotation(...)`.
    // Default: the identity isometry.
    .position(Isometry::new(vector![1.0, 2.0], 0.4))
    // The linear velocity of this body.
    // Default: zero velocity.
    .linvel(vector![1.0, 2.0])
    // The angular velocity of this body.
    // Default: zero velocity.
    .angvel(2.0)
    // The scaling factor applied to the gravity affecting the rigid-body.
    // Default: 1.0
    .gravity_scale(0.5)
    // Whether or not this body can sleep.
    // Default: true
    .can_sleep(true)
    // Whether or not CCD is enabled for this rigid-body.
    // Default: false
    .ccd_enabled(false)
    // All done, actually build the rigid-body.
    .build();
// Insert the rigid-body into the set.
let rigid_body_handle = rigid_body_set.insert(rigid_body);

All the properties are optional. The only calls that are required are RigidBodyBuilder::new(status), RigidBodyBuilder::fixed(), RigidBodyBuilder::dynamic(), RigidBodyBuilder::kinematic_velocity_based(), or RigidBodyBuilder::kinematic_position_based(), to initialize the builder, and .build() to actually build the rigid-body.

A rigid-body is created by adding the RigidBody component to an entity. Other components like Transform, Velocity, Ccd, etc. can be added for further customization of the rigid-body.

info

The following example shows several initialization of components to customize rigid-body being built. The input values are just random so using this example as-is will not lead to a useful result.

use bevy::prelude::*;
use bevy_rapier2d::prelude::*;

commands
    .spawn(RigidBody::Dynamic)
    .insert(TransformBundle::from(Transform::from_xyz(0.0, 5.0, 0.0)))
    .insert(Velocity {
        linvel: Vec2::new(1.0, 2.0),
        angvel: 0.2,
    })
    .insert(GravityScale(0.5))
    .insert(Sleeping::disabled())
    .insert(Ccd::enabled());

A rigid-body is created by a World.createRigidBody method. The initial state of the rigid-body to create is described by an instance of the RigidBodyDesc class.

Each rigid-body create by the physics world is given an integer identifier rigidBody.handle. This identifier is guaranteed to the different from any identifier of rigid-bodies still existing (or that existed) in the physics world.

info

The following example shows several setters that can be called 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.

// The world that will contain our rigid-bodies.
let world = new RAPIER.World({ x: 0.0, y: -9.81 });

// Builder for a fixed rigid-body.
let example1 = RAPIER.RigidBodyDesc.fixed();
// Builder for a dynamic rigid-body.
let example2 = RAPIER.RigidBodyDesc.dynamic();
// Builder for a kinematic rigid-body controlled at the velocity level.
let example3 = RAPIER.RigidBodyDesc.kinematicVelocityBased();
// Builder for a kinematic rigid-body controlled at the position level.
let example4 = RAPIER.RigidBodyDesc.kinematicPositionBased();
// Builder for a body with a status specified by an enum.
let rigidBodyDesc = new RAPIER.RigidBodyDesc(RAPIER.RigidBodyType.Dynamic)
    // The rigid body translation.
    // Default: zero vector.
    .setTranslation(0.0, 5.0)
    // The rigid body rotation.
    // Default: no rotation.
    .setRotation(5.0)
    // The linear velocity of this body.
    // Default: zero velocity.
    .setLinvel(1.0, 2.0)
    // The angular velocity of this body.
    // Default: zero velocity.
    .setAngvel(2.0)
    // The scaling factor applied to the gravity affecting the rigid-body.
    // Default: 1.0
    .setGravityScale(0.5)
    // Whether or not this body can sleep.
    // Default: true
    .setCanSleep(true)
    // Whether or not CCD is enabled for this rigid-body.
    // Default: false
    .setCcdEnabled(false);

// All done, actually build the rigid-body.
let rigidBody = world.createRigidBody(rigidBodyDesc);
// The integer handle of the rigid-body can be read from the `handle` field. 
let rigidBodyHandle = rigidBody.handle;
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.