Struct bevy_xpbd_3d::plugins::collision::Collider

pub struct Collider { /* private fields */ }

A collider used for detecting collisions and generating contacts.

Creation

Collider has tons of methods for creating colliders of various shapes:

// Create a ball collider with a given radius
commands.spawn(Collider::sphere(0.5));
// Create a capsule collider with a given height and radius
commands.spawn(Collider::capsule(2.0, 0.5));

Colliders on their own only detect contacts and generate collision events. To make colliders apply contact forces, they have to be attached to rigid bodies:

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

// Spawn a dynamic body that falls onto a static platform
fn setup(mut commands: Commands) {
    commands.spawn((
        RigidBody::Dynamic,
        Collider::sphere(0.5),
        TransformBundle::from_transform(Transform::from_xyz(0.0, 2.0, 0.0)),
    ));
    commands.spawn((RigidBody::Static, Collider::cuboid(5.0, 0.5, 5.0)));
}

Colliders can be further configured using various components like Friction, Restitution, Sensor, and CollisionLayers.

In addition, Bevy XPBD automatically adds some other components for colliders, like the following:

• ColliderParent
• ColliderAabb
• CollidingEntities
• ColliderDensity
• ColliderMassProperties

Colliders can also be generated automatically from meshes and scenes. See AsyncCollider and AsyncSceneCollider.

Multiple colliders

It can often be useful to attach multiple colliders to the same rigid body.

This can be done in two ways. Either use Collider::compound to have one collider that consists of many shapes, or for more control, spawn several collider entities as the children of a rigid body:

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn setup(mut commands: Commands) {
    // Spawn a rigid body with one collider on the same entity and two as children
    commands
        .spawn((RigidBody::Dynamic, Collider::sphere(0.5)))
        .with_children(|children| {
            // Spawn the child colliders positioned relative to the rigid body
            children.spawn((
                Collider::sphere(0.5),
                TransformBundle::from_transform(Transform::from_xyz(2.0, 0.0, 0.0)),
            ));
            children.spawn((
                Collider::sphere(0.5),
                TransformBundle::from_transform(Transform::from_xyz(-2.0, 0.0, 0.0)),
            ));
        });
}

Colliders can be arbitrarily nested and transformed relative to the parent. The rigid body that a collider is attached to can be accessed using the ColliderParent component.

The benefit of using separate entities for the colliders is that each collider can have its own friction, restitution, collision layers, and other configuration options, and they send separate collision events.

See more

• Rigid bodies
• Density
• Friction and restitution (bounciness)
• Collision layers
• Sensors
• Creating colliders from meshes with AsyncCollider and AsyncSceneCollider
• Get colliding entities
• Collision events
• Accessing, filtering and modifying collisions
• Manual contact queries

Advanced usage

Internally, Collider uses the shapes provided by parry. If you want to create a collider using these shapes, you can simply use Collider::from(SharedShape::some_method()).

To get a reference to the internal SharedShape, you can use the Collider::shape() or Collider::shape_scaled() methods.

Implementations

impl Collider

pub fn shape(&self) -> &SharedShape

Returns the raw unscaled shape of the collider.

pub fn shape_scaled(&self) -> &SharedShape

Returns the shape of the collider with the scale from its GlobalTransform applied.

pub fn set_shape(&mut self, shape: SharedShape)

Sets the unscaled shape of the collider. The collider’s scale will be applied to this shape.

pub fn scale(&self) -> Vector

Returns the global scale of the collider.

pub fn set_scale(&mut self, scale: Vector, num_subdivisions: u32)

Set the global scaling factor of this shape.

If the scaling factor is not uniform, and the scaled shape can’t be represented as a supported shape, the shape is approximated as a convex polygon or polyhedron using num_subdivisions.

For example, if a ball was scaled to an ellipse, the new shape would be approximated.

pub fn project_point( &self, translation: impl Into<Position>, rotation: impl Into<Rotation>, point: Vector, solid: bool ) -> (Vector, bool)

Projects the given point onto self transformed by translation and rotation. The returned tuple contains the projected point and whether it is inside the collider.

If solid is true and the given point is inside of the collider, the projection will be at the point. Otherwise, the collider will be treated as hollow, and the projection will be at the collider’s boundary.

pub fn distance_to_point( &self, translation: impl Into<Position>, rotation: impl Into<Rotation>, point: Vector, solid: bool ) -> Scalar

Computes the minimum distance between the given point and self transformed by translation and rotation.

If solid is true and the given point is inside of the collider, the returned distance will be 0.0. Otherwise, the collider will be treated as hollow, and the distance will be the distance to the collider’s boundary.

pub fn contains_point( &self, translation: impl Into<Position>, rotation: impl Into<Rotation>, point: Vector ) -> bool

Tests whether the given point is inside of self transformed by translation and rotation.

pub fn cast_ray( &self, translation: impl Into<Position>, rotation: impl Into<Rotation>, ray_origin: Vector, ray_direction: Vector, max_time_of_impact: Scalar, solid: bool ) -> Option<(Scalar, Vector)>

Computes the time of impact and normal between the given ray and self transformed by translation and rotation.

The returned tuple is in the format (time_of_impact, normal).

Arguments

• ray_origin: Where the ray is cast from.
• ray_direction: What direction the ray is cast in.
• max_time_of_impact: The maximum distance that the ray can travel.
• solid: If true and the ray origin is inside of a collider, the hit point will be the ray origin itself. Otherwise, the collider will be treated as hollow, and the hit point will be at the collider’s boundary.

pub fn intersects_ray( &self, translation: impl Into<Position>, rotation: impl Into<Rotation>, ray_origin: Vector, ray_direction: Vector, max_time_of_impact: Scalar ) -> bool

Tests whether the given ray intersects self transformed by translation and rotation.

Arguments

• ray_origin: Where the ray is cast from.
• ray_direction: What direction the ray is cast in.
• max_time_of_impact: The maximum distance that the ray can travel.

pub fn compound( shapes: Vec<(impl Into<Position>, impl Into<Rotation>, impl Into<Collider>)> ) -> Self

Creates a collider with a compound shape defined by a given vector of colliders with a position and a rotation.

Especially for dynamic rigid bodies, compound shape colliders should be preferred over triangle meshes and polylines, because convex shapes typically provide more reliable results.

If you want to create a compound shape from a 3D triangle mesh or 2D polyline, consider using the Collider::convex_decomposition method.

pub fn sphere(radius: Scalar) -> Self

Creates a collider with a sphere shape defined by its radius.

pub fn ball(radius: Scalar) -> Self

👎Deprecated since 0.4.0: please use Collider::sphere instead

Creates a collider with a ball shape defined by its radius.

pub fn cuboid(x_length: Scalar, y_length: Scalar, z_length: Scalar) -> Self

Creates a collider with a cuboid shape defined by its extents.

pub fn round_cuboid( x_length: Scalar, y_length: Scalar, z_length: Scalar, border_radius: Scalar ) -> Self

Creates a collider with a cuboid shape defined by its extents and rounded corners.

pub fn cylinder(height: Scalar, radius: Scalar) -> Self

Creates a collider with a cylinder shape defined by its height along the Y axis and its radius on the XZ plane.

pub fn cone(height: Scalar, radius: Scalar) -> Self

Creates a collider with a cone shape defined by its height along the Y axis and the radius of its base on the XZ plane.

pub fn capsule(height: Scalar, radius: Scalar) -> Self

Creates a collider with a capsule shape defined by its height along the Y axis and its radius.

pub fn capsule_endpoints(a: Vector, b: Vector, radius: Scalar) -> Self

Creates a collider with a capsule shape defined by its end points a and b and its radius.

pub fn halfspace(outward_normal: Vector) -> Self

Creates a collider with a half-space shape defined by the outward normal of its planar boundary.

pub fn segment(a: Vector, b: Vector) -> Self

Creates a collider with a segment shape defined by its endpoints a and b.

pub fn triangle(a: Vector, b: Vector, c: Vector) -> Self

Creates a collider with a triangle shape defined by its points a, b and c.

pub fn polyline(vertices: Vec<Vector>, indices: Option<Vec<[u32; 2]>>) -> Self

Creates a collider with a polyline shape defined by its vertices and optionally an index buffer.

pub fn trimesh(vertices: Vec<Vector>, indices: Vec<[u32; 3]>) -> Self

Creates a collider with a triangle mesh shape defined by its vertex and index buffers.

pub fn trimesh_with_config( vertices: Vec<Vector>, indices: Vec<[u32; 3]>, flags: TriMeshFlags ) -> Self

Creates a collider with a triangle mesh shape defined by its vertex and index buffers and flags controlling the preprocessing.

pub fn convex_decomposition( vertices: Vec<Vector>, indices: Vec<[u32; 3]> ) -> Self

Creates a collider shape with a compound shape obtained from the decomposition of a given trimesh defined by its vertex and index buffers.

pub fn convex_decomposition_with_config( vertices: Vec<Vector>, indices: Vec<[u32; 3]>, params: &VHACDParameters ) -> Self

Creates a collider shape with a compound shape obtained from the decomposition of a given trimesh defined by its vertex and index buffers. The given VHACDParameters are used for configuring the decomposition process.

pub fn convex_hull(points: Vec<Vector>) -> Option<Self>

Creates a collider with a convex polyhedron shape obtained after computing the convex hull of the given points.

pub fn heightfield(heights: Vec<Vec<Scalar>>, scale: Vector) -> Self

Creates a collider with a heightfield shape.

A 3D heightfield is a rectangle on the XZ plane, subdivided in a grid pattern at regular intervals.

heights is a matrix indicating the altitude of each subdivision point. The number of rows indicates the number of subdivisions along the X axis, while the number of columns indicates the number of subdivisions along the Z axis.

scale indicates the size of each rectangle on the XZ plane.

pub fn trimesh_from_mesh(mesh: &Mesh) -> Option<Self>

Creates a collider with a triangle mesh shape from a Mesh.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn setup(mut commands: Commands, mut meshes: ResMut<Assets<Mesh>>) {
    let mesh = Mesh::from(Cuboid::default());
    commands.spawn((
        Collider::trimesh_from_mesh(&mesh).unwrap(),
        PbrBundle {
            mesh: meshes.add(mesh),
            ..default()
        },
    ));
}

pub fn trimesh_from_mesh_with_config( mesh: &Mesh, flags: TriMeshFlags ) -> Option<Self>

Creates a collider with a triangle mesh shape from a Mesh using the given TriMeshFlags for controlling the preprocessing.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn setup(mut commands: Commands, mut meshes: ResMut<Assets<Mesh>>) {
    let mesh = Mesh::from(Cuboid::default());
    commands.spawn((
        Collider::trimesh_from_mesh_with_config(&mesh, TriMeshFlags::all()).unwrap(),
        PbrBundle {
            mesh: meshes.add(mesh),
            ..default()
        },
    ));
}

pub fn convex_hull_from_mesh(mesh: &Mesh) -> Option<Self>

Creates a collider with a convex polygon shape obtained from the convex hull of a Mesh.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn setup(mut commands: Commands, mut meshes: ResMut<Assets<Mesh>>) {
    let mesh = Mesh::from(Cuboid::default());
    commands.spawn((
        Collider::convex_hull_from_mesh(&mesh).unwrap(),
        PbrBundle {
            mesh: meshes.add(mesh),
            ..default()
        },
    ));
}

pub fn convex_decomposition_from_mesh(mesh: &Mesh) -> Option<Self>

Creates a compound shape obtained from the decomposition of a Mesh.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn setup(mut commands: Commands, mut meshes: ResMut<Assets<Mesh>>) {
    let mesh = Mesh::from(Cuboid::default());
    commands.spawn((
        Collider::convex_decomposition_from_mesh(&mesh).unwrap(),
        PbrBundle {
            mesh: meshes.add(mesh),
            ..default()
        },
    ));
}

pub fn convex_decomposition_from_mesh_with_config( mesh: &Mesh, parameters: &VHACDParameters ) -> Option<Self>

Creates a compound shape obtained from the decomposition of a Mesh with the given VHACDParameters passed to the decomposition algorithm.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn setup(mut commands: Commands, mut meshes: ResMut<Assets<Mesh>>) {
    let mesh = Mesh::from(Cuboid::default());
    let config = VHACDParameters {
        convex_hull_approximation: false,
        ..default()
    };
    commands.spawn((
        Collider::convex_decomposition_from_mesh_with_config(&mesh, &config).unwrap(),
        PbrBundle {
            mesh: meshes.add(mesh),
            ..default()
        },
    ));
}

Trait Implementations

impl AnyCollider for Collider

fn aabb(&self, position: Vector, rotation: impl Into<Rotation>) -> ColliderAabb

Computes the Axis-Aligned Bounding Box of the collider with the given position and rotation.

fn mass_properties(&self, density: Scalar) -> ColliderMassProperties

Computes the collider’s mass properties based on its shape and a given density.

fn contact_manifolds( &self, other: &Self, position1: Vector, rotation1: impl Into<Rotation>, position2: Vector, rotation2: impl Into<Rotation>, prediction_distance: Scalar ) -> Vec<ContactManifold>

Computes all ContactManifolds between two colliders.

fn swept_aabb( &self, start_position: Vector, start_rotation: impl Into<Rotation>, end_position: Vector, end_rotation: impl Into<Rotation> ) -> ColliderAabb

Computes the swept Axis-Aligned Bounding Box of the collider. This corresponds to the space the shape would occupy if it moved from the given start position to the given end position.

impl Clone for Collider

fn clone(&self) -> Collider

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Component for Collider

where Self: Send + Sync + 'static,

type Storage = TableStorage

A marker type indicating the storage type used for this component. This must be either [TableStorage] or [SparseStorage].

impl Debug for Collider

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Collider

fn default() -> Self

Returns the “default value” for a type.

impl From<SharedShape> for Collider

fn from(value: SharedShape) -> Self

Converts to this type from the input type.

impl<T: IntoCollider<Collider>> From<T> for Collider

fn from(value: T) -> Self

Converts to this type from the input type.

impl IntoCollider<Collider> for BoxedPolyline3d

fn collider(&self) -> Collider

Creates a collider from self.

impl IntoCollider<Collider> for Capsule3d

fn collider(&self) -> Collider

Creates a collider from self.

impl IntoCollider<Collider> for Cone

fn collider(&self) -> Collider

Creates a collider from self.

impl IntoCollider<Collider> for Cuboid

fn collider(&self) -> Collider

Creates a collider from self.

impl IntoCollider<Collider> for Cylinder

fn collider(&self) -> Collider

Creates a collider from self.

impl IntoCollider<Collider> for Line3d

fn collider(&self) -> Collider

Creates a collider from self.

impl IntoCollider<Collider> for Plane3d

fn collider(&self) -> Collider

Creates a collider from self.

impl<const N: usize> IntoCollider<Collider> for Polyline3d<N>

fn collider(&self) -> Collider

Creates a collider from self.

impl IntoCollider<Collider> for Segment3d

fn collider(&self) -> Collider

Creates a collider from self.

impl IntoCollider<Collider> for Sphere

fn collider(&self) -> Collider

Creates a collider from self.

impl ScalableCollider for Collider

fn scale(&self) -> Vector

Returns the global scaling factor of the collider.

fn set_scale(&mut self, scale: Vector, detail: u32)

Sets the global scaling factor of the collider.

fn scale_by(&mut self, factor: Vector, detail: u32)

Scales the collider by the given scaling factor.