Skip to main content

collider_creation_and_insertion

A collider is created by a ColliderBuilder structure that is based on the builder pattern. Then it needs to be inserted into the ColliderSet that will be processed by the physics-pipeline, collision-pipeline, or query-pipeline.

info

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

use rapier2d::prelude::*;
use std::f32::consts::PI;

// The set that will contain our colliders.
let mut collider_set = ColliderSet::new();

// Builder for a ball-shaped collider.
let _ = ColliderBuilder::ball(0.5);
// Builder for a cuboid-shaped collider.
let _ = ColliderBuilder::cuboid(0.5, 0.2);
// Builder for a capsule-shaped collider. The capsule principal axis is the `x` coordinate axis.
let _ = ColliderBuilder::capsule_x(0.5, 0.2);
// Builder for a capsule-shaped collider. The capsule principal axis is the `y` coordinate axis.
let _ = ColliderBuilder::capsule_y(0.5, 0.2);
// Builder for a triangle-mesh-shaped collider.
let _ = ColliderBuilder::trimesh(vertices, indices);
// Builder for a heightfield-shaped collider.
let _ = ColliderBuilder::heightfield(heights, scale);
// Builder for a collider with the given shape.
let collider = ColliderBuilder::new(SharedShape::ball(0.5))
    // The collider translation wrt. the body it is attached to.
    // Default: the zero vector.
    .translation(vector![1.0, 2.0])
    // The collider rotation wrt. the body it is attached to.
    // Default: the identity rotation.
    .rotation(PI)
    // The collider position wrt. the body it is attached to.
    // Default: the identity isometry.
    .position(Isometry::new(vector![1.0, 2.0], PI))
    // The collider density. If non-zero the collider's mass and angular inertia will be added
    // to the inertial properties of the body it is attached to.
    // Default: 1.0
    .density(1.3)
    // The friction coefficient of this collider.
    // Default: ColliderBuilder::default_friction() == 0.5
    .friction(0.8)
    // Whether this collider is a sensor.
    // Default: false
    .sensor(true)
    // All done, actually build the collider.
    .build();

// Insert the collider into the set, without attaching it to a rigid-body.
let collider_handle = collider_set.insert(collider.clone());

let mut rigid_body_set = RigidBodySet::new();
let rigid_body_handle = rigid_body_set.insert(RigidBodyBuilder::dynamic().build());
// Or insert the collider into the set and attach it to a rigid-body.
let handle = collider_set.insert_with_parent(collider, rigid_body_handle, &mut rigid_body_set);

A collider is created by adding the Collider component. Other components like Transform, Sensor, Friction, etc. can be added to customize the collider.

info

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

use bevy_rapier2d::prelude::*;

commands
    .spawn(Collider::cuboid(1.0, 2.0))
    .insert(Sensor)
    .insert(TransformBundle::from(Transform::from_xyz(2.0, 0.0, 0.0)))
    .insert(Friction::coefficient(0.7))
    .insert(Restitution::coefficient(0.3))
    .insert(ColliderMassProperties::Density(2.0));

A collider can optionally be attached to a rigid-body. Attaching a collider to a rigid-body will result in the rigid-body being affected by collisions. The collider's position will be automatically updated from the position of the rigid-body it is attached to. There are two ways of attaching a collider to a rigid-body. The second way allows you to attach multiple colliders to the same rigid-body:

  1. Attach the Collider to the same entity as the RigidBody.
  2. Attach the Collider to an entity that is a child of the entity containing the RigidBody.
// Attach a single collider to a rigid-body.
commands
    .spawn(RigidBody::Dynamic)
    .insert(Collider::ball(0.5));

// Attach a multiple colliders to a rigid-body.
commands
    .spawn((RigidBody::Dynamic, GlobalTransform::default()))
    .with_children(|children| {
        children
            .spawn(Collider::ball(0.5))
            // Position the collider relative to the rigid-body.
            .insert(TransformBundle::from(Transform::from_xyz(0.0, 0.0, -1.0)));
        children
            .spawn(Collider::ball(0.5))
            // Position the collider relative to the rigid-body.
            .insert(TransformBundle::from(Transform::from_xyz(0.0, 0.0, 1.0)));
    });

A collider is created by a World.createCollider method. The initial state of the collider to create is described by an instance of the ColliderDesc class.

Each collider create by the physics world is given an integer identifier. This identifier is guaranteed to the different from any identifier of colliders still existing in the physics world. However, the identifier may be equal to the identifier of an older collider that has already been removed from the physics world with World.removeCollider.

info

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

// The physics world.
let world = new RAPIER.World({ x: 0.0, y: -9.81 });

// Builder for a ball-shaped collider.
let example1 = RAPIER.ColliderDesc.ball(0.5);
// Builder for a cuboid-shaped collider.
let example2 = RAPIER.ColliderDesc.cuboid(0.5, 0.2);
// Builder for a capsule-shaped collider. The capsule principal axis is the `y` coordinate axis.
let example3 = RAPIER.ColliderDesc.capsule(0.5, 0.2);
// Builder for a triangle-mesh-shaped collider.
let example4 = RAPIER.ColliderDesc.trimesh(vertices, indices);
// Builder for a heightfield-shaped collider.
let example5 = RAPIER.ColliderDesc.heightfield(heights, scale);
// Builder for a collider with the given shape.
let colliderDesc = new RAPIER.ColliderDesc(new RAPIER.Ball(0.5))
    // The collider translation wrt. the body it is attached to.
    // Default: the zero vector.
    .setTranslation(1.0, 2.0)
    // The collider rotation wrt. the body it is attached to.
    // Default: the identity rotation.
    .setRotation(3.14)
    // The collider density. If non-zero the collider's mass and angular inertia will be added
    // to the inertial properties of the body it is attached to.
    // Default: 1.0
    .setDensity(1.3)
    // The friction coefficient of this collider.
    // Default: 0.5
    .setFriction(0.8)
    // Whether this collider is a sensor.
    // Default: false
    .setSensor(true);

// Create the collider, without attaching it to a rigid-body.
let handle = world.createCollider(colliderDesc);
// Or create the collider and attach it to a rigid-body.
let rigidBody = world.createRigidBody(RAPIER.RigidBodyDesc.dynamic());
let collider = world.createCollider(colliderDesc, rigidBody);