Struct 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 radius and height
commands.spawn(Collider::capsule(0.5, 2.0));

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 avian3d::prelude::*;
use bevy::prelude::*;

// Spawn a dynamic body that falls onto a static platform
fn setup(mut commands: Commands) {
    commands.spawn((
        RigidBody::Dynamic,
        Collider::sphere(0.5),
        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, CollisionLayers, CollisionMargin, and ColliderDensity.

If you need to specify the shape of the collider statically, use ColliderConstructor and build your collider with the Collider::try_from_constructor method. This can also be done automatically by simply placing the ColliderConstructor on an entity.

Colliders can also be generated automatically for meshes and scenes. See ColliderConstructor and ColliderConstructorHierarchy.

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 avian3d::prelude::*;
use bevy::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), Transform::from_xyz(2.0, 0.0, 0.0)));
            children.spawn((Collider::sphere(0.5), 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 ColliderOf 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
• Collision margins for adding extra thickness to colliders
• Generating colliders for meshes and scenes with ColliderConstructor and ColliderConstructorHierarchy
• Get colliding entities
• Collision events
• Accessing collision data
• Filtering and modifying contacts with hooks
• 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.

Collider is currently not Reflect. If you need to reflect it, you can use ColliderConstructor as a workaround.

Implementations

impl Collider

pub fn shape(&self) -> &SharedShape

Returns the raw unscaled shape of the collider.

pub fn shape_mut(&mut self) -> &mut SharedShape

Returns a mutable reference to 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_distance: Scalar, solid: bool, ) -> Option<(Scalar, Vector)>

Computes the distance and normal between the given ray and self transformed by translation and rotation.

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

Arguments

• ray_origin: Where the ray is cast from.
• ray_direction: What direction the ray is cast in.
• max_distance: The maximum distance 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_distance: 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_distance: The maximum distance 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 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(radius: Scalar, height: Scalar) -> Self

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

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

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

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

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

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

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

pub fn half_space(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.

Note that the resulting collider will be hollow and have no interior. This makes it more prone to tunneling and other collision issues.

The CollisionMargin component can be used to add thickness to the shape if needed. For thin shapes like triangle meshes, it can help improve collision stability and performance.

Panics

Panics if the given vertex and index buffers do not contain any triangles, there are duplicate vertices, or if at least two adjacent triangles have opposite orientations.

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

Tries to create a collider with a triangle mesh shape defined by its vertex and index buffers.

Note that the resulting collider will be hollow and have no interior. This makes it more prone to tunneling and other collision issues.

The CollisionMargin component can be used to add thickness to the shape if needed. For thin shapes like triangle meshes, it can help improve collision stability and performance.

Errors

Returns a TrimeshBuilderError if the given vertex and index buffers do not contain any triangles, there are duplicate vertices, or if at least two adjacent triangles have opposite orientations.

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.

Note that the resulting collider will be hollow and have no interior. This makes it more prone to tunneling and other collision issues.

The CollisionMargin component can be used to add thickness to the shape if needed. For thin shapes like triangle meshes, it can help improve collision stability and performance.

Panics

Panics if after preprocessing the given vertex and index buffers do not contain any triangles, there are duplicate vertices, or if at least two adjacent triangles have opposite orientations.

pub fn try_trimesh_with_config( vertices: Vec<Vector>, indices: Vec<[u32; 3]>, flags: TrimeshFlags, ) -> Result<Self, TrimeshBuilderError>

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

Note that the resulting collider will be hollow and have no interior. This makes it more prone to tunneling and other collision issues.

The CollisionMargin component can be used to add thickness to the shape if needed. For thin shapes like triangle meshes, it can help improve collision stability and performance.

Errors

Returns a TrimeshBuilderError if after preprocessing the given vertex and index buffers do not contain any triangles, there are duplicate vertices, or if at least two adjacent triangles have opposite orientations.

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 voxels(voxel_size: Vector, grid_coordinates: &[IVector]) -> Self

Creates a collider shape made of voxels.

Each voxel has the size voxel_size and grid coordinate given by grid_coordinates.

pub fn voxels_from_points(voxel_size: Vector, points: &[Vector]) -> Self

Creates a collider shape made of voxels.

Each voxel has the size voxel_size and contains at least one point from points.

pub fn voxelized_trimesh( vertices: &[Vector], indices: &[[u32; 3]], voxel_size: Scalar, fill_mode: FillMode, ) -> Self

Creates a voxel collider obtained from the decomposition of the given trimesh into voxelized convex parts.

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

Creates a collider with a compound shape obtained from the decomposition of the given trimesh into voxelized convex parts.

pub fn voxelized_convex_decomposition_with_config( vertices: &[Vector], indices: &[[u32; 3]], parameters: &VhacdParameters, ) -> Vec<Self>

Creates a collider with a compound shape obtained from the decomposition of the given trimesh into voxelized convex parts.

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 controls the scaling factor along each axis.

pub fn try_from_constructor( collider_constructor: ColliderConstructor, ) -> Option<Self>

Attempts to create a collider with the given ColliderConstructor. By using this, you can serialize and deserialize the collider’s creation method separately from the collider itself via the ColliderConstructor enum.

Returns None if creating the collider from the given ColliderConstructor failed.

Trait Implementations

impl AnyCollider for Collider

type Context = ()

A type providing additional context for collider operations.

fn aabb_with_context( &self, position: Vector, rotation: impl Into<Rotation>, _: AabbContext<'_, '_, '_, Self::Context>, ) -> ColliderAabb

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

fn contact_manifolds_with_context( &self, other: &Self, position1: Vector, rotation1: impl Into<Rotation>, position2: Vector, rotation2: impl Into<Rotation>, prediction_distance: Scalar, manifolds: &mut Vec<ContactManifold>, _: ContactManifoldContext<'_, '_, '_, Self::Context>, )

Computes all ContactManifolds between two colliders.

fn swept_aabb_with_context( &self, start_position: Vector, start_rotation: impl Into<Rotation>, end_position: Vector, end_rotation: impl Into<Rotation>, context: AabbContext<'_, '_, '_, Self::Context>, ) -> 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 duplicate of the value.

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

Performs copy-assignment from source.

impl Component for Collider

where Self: Send + Sync + 'static,

Required Components: ColliderMarker, ColliderAabb, CollisionLayers, ColliderDensity, ColliderMassProperties.

A component’s Required Components are inserted whenever it is inserted. Note that this will also insert the required components of the required components, recursively, in depth-first order.

const STORAGE_TYPE: StorageType = ::bevy::ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

type Mutability = Mutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have [Component<Mutability = Mutable>], while immutable components will instead have [Component<Mutability = Immutable>].

fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.

fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_insert ComponentHook for this Component if one is defined.

fn on_replace() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_replace ComponentHook for this Component if one is defined.

fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_remove ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]

impl ComputeMassProperties3d for Collider

fn mass(&self, density: f32) -> f32

Computes the mass of the object with a given density.

fn unit_principal_angular_inertia(&self) -> Vec3

Computes the principal angular inertia corresponding to a mass of 1.0.

fn principal_angular_inertia(&self, mass: f32) -> Vec3

Computes the principal angular inertia corresponding to the given mass.

fn local_inertial_frame(&self) -> Quat

Computes the orientation of the inertial frame used by the principal axes of inertia in local space.

fn center_of_mass(&self) -> Vec3

Computes the local center of mass relative to the object’s origin.

fn mass_properties(&self, density: f32) -> MassProperties

Computes the MassProperties3d with a given density.

fn unit_angular_inertia_tensor(&self) -> AngularInertiaTensor

Computes the 3x3 AngularInertiaTensor corresponding to a mass of 1.0.

fn angular_inertia_tensor(&self, mass: f32) -> AngularInertiaTensor

Computes the 3x3 AngularInertiaTensor corresponding to the given mass.

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 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 InfinitePlane3d

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 IntoCollider<Collider> for Polyline3d

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.