Struct ColliderBuilder 

pub struct ColliderBuilder {

    pub shape: SharedShape,
    pub mass_properties: ColliderMassProps,
    pub friction: f32,
    pub friction_combine_rule: CoefficientCombineRule,
    pub restitution: f32,
    pub restitution_combine_rule: CoefficientCombineRule,
    pub position: Isometry<f32>,
    pub is_sensor: bool,
    pub active_collision_types: ActiveCollisionTypes,
    pub active_hooks: ActiveHooks,
    pub active_events: ActiveEvents,
    pub user_data: u128,
    pub collision_groups: InteractionGroups,
    pub solver_groups: InteractionGroups,
    pub enabled: bool,
    pub contact_force_event_threshold: f32,
    pub contact_skin: f32,
}

A builder for creating colliders with custom shapes and properties.

This builder lets you create collision shapes and configure their physical properties (friction, bounciness, density, etc.) before adding them to your world.

Common shapes

• ball(radius) - Sphere (3D) or circle (2D)
• cuboid(hx, hy, hz) - Box with half-extents
• capsule_y(half_height, radius) - Pill shape (great for characters)
• trimesh(vertices, indices) - Triangle mesh for complex geometry
• heightfield(...) - Terrain from height data

Example

// Create a bouncy ball
let collider = ColliderBuilder::ball(0.5)
    .restitution(0.9)       // Very bouncy
    .friction(0.1)          // Low friction (slippery)
    .density(2.0);           // Heavy material
colliders.insert_with_parent(collider, body_handle, &mut bodies);

Fields

shape: SharedShape

The shape of the collider to be built.

mass_properties: ColliderMassProps

Controls the way the collider’s mass-properties are computed.

friction: f32

The friction coefficient of the collider to be built.

friction_combine_rule: CoefficientCombineRule

The rule used to combine two friction coefficients.

restitution: f32

The restitution coefficient of the collider to be built.

restitution_combine_rule: CoefficientCombineRule

The rule used to combine two restitution coefficients.

position: Isometry<f32>

The position of this collider.

is_sensor: bool

Is this collider a sensor?

active_collision_types: ActiveCollisionTypes

Contact pairs enabled for this collider.

active_hooks: ActiveHooks

Physics hooks enabled for this collider.

active_events: ActiveEvents

Events enabled for this collider.

user_data: u128

The user-data of the collider being built.

collision_groups: InteractionGroups

The collision groups for the collider being built.

solver_groups: InteractionGroups

The solver groups for the collider being built.

enabled: bool

Will the collider being built be enabled?

contact_force_event_threshold: f32

The total force magnitude beyond which a contact force event can be emitted.

contact_skin: f32

An extra thickness around the collider shape to keep them further apart when colliding.

Implementations

impl ColliderBuilder

pub fn new(shape: SharedShape) -> Self

Initialize a new collider builder with the given shape.

pub fn compound(shapes: Vec<(Isometry<f32>, SharedShape)>) -> Self

Initialize a new collider builder with a compound shape.

pub fn ball(radius: f32) -> Self

Creates a sphere (3D) or circle (2D) collider.

The simplest and fastest collision shape. Use for:

• Balls and spheres
• Approximate round objects
• Projectiles
• Particles

Parameters

• radius - The sphere’s radius

pub fn halfspace(outward_normal: Unit<Vector<f32>>) -> Self

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

pub fn voxels(voxel_size: Vector<f32>, voxels: &[Point<i32>]) -> Self

Initializes a shape made of voxels.

Each voxel has the size voxel_size and grid coordinate given by voxels. The primitive_geometry controls the behavior of collision detection at voxels boundaries.

For initializing a voxels shape from points in space, see Self::voxels_from_points. For initializing a voxels shape from a mesh to voxelize, see Self::voxelized_mesh.

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

Initializes a collider made of voxels.

Each voxel has the size voxel_size and contains at least one point from centers. The primitive_geometry controls the behavior of collision detection at voxels boundaries.

pub fn voxelized_mesh( vertices: &[Point<f32>], indices: &[[u32; 2]], voxel_size: f32, fill_mode: FillMode, ) -> Self

Initializes a voxels obtained from the decomposition of the given trimesh (in 3D) or polyline (in 2D) into voxelized convex parts.

pub fn cuboid(hx: f32, hy: f32) -> Self

Initialize a new collider builder with a cuboid shape defined by its half-extents.

pub fn round_cuboid(hx: f32, hy: f32, border_radius: f32) -> Self

Initialize a new collider builder with a round cuboid shape defined by its half-extents and border radius.

pub fn capsule_from_endpoints(a: Point<f32>, b: Point<f32>, radius: f32) -> Self

Initialize a new collider builder with a capsule defined from its endpoints.

See also ColliderBuilder::capsule_x, ColliderBuilder::capsule_y, (and ColliderBuilder::capsule_z in 3D only) for a simpler way to build capsules with common orientations.

pub fn capsule_x(half_height: f32, radius: f32) -> Self

Initialize a new collider builder with a capsule shape aligned with the x axis.

pub fn capsule_y(half_height: f32, radius: f32) -> Self

Creates a capsule (pill-shaped) collider aligned with the Y axis.

Capsules are cylinders with hemispherical caps. Excellent for characters because:

• Smooth collision (no getting stuck on edges)
• Good for upright objects (characters, trees)
• Fast collision detection

Parameters

• half_height - Half the height of the cylindrical part (not including caps)
• radius - Radius of the cylinder and caps

Example: capsule_y(1.0, 0.5) creates a 3.0 tall capsule (1.0×2 cylinder + 0.5×2 caps)

pub fn segment(a: Point<f32>, b: Point<f32>) -> Self

Creates a line segment collider between two points.

Useful for thin barriers, edges, or 2D line-based collision. Has no thickness - purely a mathematical line.

pub fn triangle(a: Point<f32>, b: Point<f32>, c: Point<f32>) -> Self

Creates a single triangle collider.

Use for simple 3-sided shapes or as building blocks for more complex geometry.

pub fn round_triangle( a: Point<f32>, b: Point<f32>, c: Point<f32>, border_radius: f32, ) -> Self

Initializes a collider builder with a triangle shape with round corners.

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

Initializes a collider builder with a polyline shape defined by its vertex and index buffers.

pub fn trimesh( vertices: Vec<Point<f32>>, indices: Vec<[u32; 3]>, ) -> Result<Self, TriMeshBuilderError>

Creates a triangle mesh collider from vertices and triangle indices.

Use for complex, arbitrary shapes like:

• Level geometry and terrain
• Imported 3D models
• Custom irregular shapes

Performance note: Triangle meshes are slower than primitive shapes (balls, boxes, capsules). Consider using compound shapes or simpler approximations when possible.

Parameters

• vertices - Array of 3D points
• indices - Array of triangles, each is 3 indices into the vertex array

Example

use rapier3d::prelude::*;
use nalgebra::Point3;

let vertices = vec![
    Point3::new(0.0, 0.0, 0.0),
    Point3::new(1.0, 0.0, 0.0),
    Point3::new(0.0, 1.0, 0.0),
];
let triangle: [u32; 3] = [0, 1, 2];
let indices = vec![triangle];  // One triangle
let collider = ColliderBuilder::trimesh(vertices, indices)?;

pub fn trimesh_with_flags( vertices: Vec<Point<f32>>, indices: Vec<[u32; 3]>, flags: TriMeshFlags, ) -> Result<Self, TriMeshBuilderError>

Initializes a collider builder with a triangle mesh shape defined by its vertex and index buffers and flags controlling its pre-processing.

pub fn converted_trimesh( vertices: Vec<Point<f32>>, indices: Vec<[u32; 3]>, converter: MeshConverter, ) -> Result<Self, MeshConverterError>

Initializes a collider builder with a shape converted from the given triangle mesh index and vertex buffer.

All the conversion variants could be achieved with other constructors of ColliderBuilder but having this specified by an enum can occasionally be easier or more flexible (determined at runtime).

pub fn convex_decomposition( vertices: &[Point<f32>], indices: &[[u32; 2]], ) -> Self

Creates a compound collider by decomposing a mesh/polyline into convex pieces.

Concave shapes (like an ‘L’ or ‘C’) are automatically broken into multiple convex parts for efficient collision detection. This is often faster than using a trimesh.

Uses the V-HACD algorithm. Good for imported models that aren’t already convex.

pub fn round_convex_decomposition( vertices: &[Point<f32>], indices: &[[u32; 2]], border_radius: f32, ) -> Self

Initializes a collider builder with a compound shape obtained from the decomposition of the given trimesh (in 3D) or polyline (in 2D) into convex parts dilated with round corners.

pub fn convex_decomposition_with_params( vertices: &[Point<f32>], indices: &[[u32; 2]], params: &VHACDParameters, ) -> Self

Initializes a collider builder with a compound shape obtained from the decomposition of the given trimesh (in 3D) or polyline (in 2D) into convex parts.

pub fn round_convex_decomposition_with_params( vertices: &[Point<f32>], indices: &[[u32; 2]], params: &VHACDParameters, border_radius: f32, ) -> Self

Initializes a collider builder with a compound shape obtained from the decomposition of the given trimesh (in 3D) or polyline (in 2D) into convex parts dilated with round corners.

pub fn convex_hull(points: &[Point<f32>]) -> Option<Self>

Creates the smallest convex shape that contains all the given points.

Computes the “shrink-wrap” around a point cloud. Useful for:

• Creating collision shapes from vertex data
• Approximating complex shapes with a simpler convex one

Returns None if the points don’t form a valid convex shape.

Performance: Convex shapes are much faster than triangle meshes!

pub fn round_convex_hull( points: &[Point<f32>], border_radius: f32, ) -> Option<Self>

Initializes a new collider builder with a round 2D convex polygon or 3D convex polyhedron obtained after computing the convex-hull of the given points. The shape is dilated by a sphere of radius border_radius.

pub fn convex_polyline(points: Vec<Point<f32>>) -> Option<Self>

Creates a new collider builder that is a convex polygon formed by the given polyline assumed to be convex (no convex-hull will be automatically computed).

pub fn round_convex_polyline( points: Vec<Point<f32>>, border_radius: f32, ) -> Option<Self>

Creates a new collider builder that is a round convex polygon formed by the given polyline assumed to be convex (no convex-hull will be automatically computed). The polygon shape is dilated by a sphere of radius border_radius.

pub fn heightfield(heights: DVector<f32>, scale: Vector<f32>) -> Self

Initializes a collider builder with a heightfield shape defined by its set of height and a scale factor along each coordinate axis.

pub fn default_friction() -> f32

Returns the default friction value used when not specified (0.5).

pub fn default_density() -> f32

Returns the default density value used when not specified (1.0).

pub fn user_data(self, data: u128) -> Self

Stores custom user data with this collider (128-bit integer).

Use to associate game data (entity ID, type, etc.) with physics objects.

Example

let collider = ColliderBuilder::ball(0.5)
    .user_data(entity_id as u128)
    .build();

pub fn collision_groups(self, groups: InteractionGroups) -> Self

Sets which collision groups this collider belongs to and can interact with.

Use this to control what can collide with what (like collision layers). See InteractionGroups for examples.

Example

// Player bullet: in group 1, only hits group 2 (enemies)
let groups = InteractionGroups::new(Group::GROUP_1, Group::GROUP_2);
let bullet = ColliderBuilder::ball(0.1)
    .collision_groups(groups)
    .build();

pub fn solver_groups(self, groups: InteractionGroups) -> Self

Sets solver groups (advanced collision filtering for contact resolution).

Similar to collision_groups but specifically for the contact solver. Most users should use collision_groups() instead - this is for advanced scenarios where you want collisions detected but not resolved (e.g., one-way platforms).

pub fn sensor(self, is_sensor: bool) -> Self

Makes this collider a sensor (trigger zone) instead of a solid collision shape.

Sensors detect overlaps but don’t create physical collisions. Use for:

• Trigger zones (checkpoints, danger areas)
• Collectible item detection
• Proximity sensors
• Win/lose conditions

You’ll receive collision events when objects enter/exit the sensor.

Example

let trigger = ColliderBuilder::cuboid(5.0, 5.0, 5.0)
    .sensor(true)
    .build();

pub fn active_hooks(self, active_hooks: ActiveHooks) -> Self

Enables custom physics hooks for this collider (advanced).

See ActiveHooks for details on custom collision filtering.

pub fn active_events(self, active_events: ActiveEvents) -> Self

Enables event generation for this collider.

Set to ActiveEvents::COLLISION_EVENTS for start/stop notifications. Set to ActiveEvents::CONTACT_FORCE_EVENTS for force threshold events.

Example

let sensor = ColliderBuilder::ball(1.0)
    .sensor(true)
    .active_events(ActiveEvents::COLLISION_EVENTS)
    .build();

pub fn active_collision_types( self, active_collision_types: ActiveCollisionTypes, ) -> Self

Sets which body type combinations can collide with this collider.

See ActiveCollisionTypes for details. Most users don’t need to change this.

pub fn friction(self, friction: f32) -> Self

Sets the friction coefficient (slipperiness) for this collider.

• 0.0 = ice (very slippery)
• 0.5 = wood on wood
• 1.0 = rubber (high grip)

Default is 0.5.

pub fn friction_combine_rule(self, rule: CoefficientCombineRule) -> Self

Sets how friction coefficients are combined when two colliders touch.

Options: Average, Min, Max, Multiply. Default is Average. Most games can ignore this and use the default.

pub fn restitution(self, restitution: f32) -> Self

Sets the restitution coefficient (bounciness) for this collider.

• 0.0 = no bounce (clay, soft)
• 0.5 = moderate bounce
• 1.0 = perfect elastic bounce
• >1.0 = super bouncy (gains energy!)

Default is 0.0.

pub fn restitution_combine_rule(self, rule: CoefficientCombineRule) -> Self

Sets the rule to be used to combine two restitution coefficients in a contact.

pub fn density(self, density: f32) -> Self

Sets the density (mass per unit volume) of this collider.

Mass will be computed as: density × volume. Common densities:

• 1000.0 = water
• 2700.0 = aluminum
• 7850.0 = steel

⚠️ Use either density() OR mass(), not both (last call wins).

Example

let steel_ball = ColliderBuilder::ball(0.5).density(7850.0).build();

pub fn mass(self, mass: f32) -> Self

Sets the total mass of this collider directly.

Angular inertia is computed automatically from the shape and mass.

⚠️ Use either mass() OR density(), not both (last call wins).

Example

// 10kg ball regardless of its radius
let collider = ColliderBuilder::ball(0.5).mass(10.0).build();

pub fn mass_properties(self, mass_properties: MassProperties) -> Self

Sets the mass properties of the collider this builder will build.

This will be overridden by a call to Self::density or Self::mass so it only makes sense to call either Self::density or Self::mass or Self::mass_properties.

pub fn contact_force_event_threshold(self, threshold: f32) -> Self

Sets the force threshold for triggering contact force events.

When total contact force exceeds this value, a ContactForceEvent is generated (if ActiveEvents::CONTACT_FORCE_EVENTS is enabled).

Use for detecting hard impacts, breaking objects, or damage systems.

Example

let glass = ColliderBuilder::cuboid(1.0, 1.0, 0.1)
    .active_events(ActiveEvents::CONTACT_FORCE_EVENTS)
    .contact_force_event_threshold(1000.0)  // Break at 1000N
    .build();

pub fn translation(self, translation: Vector<f32>) -> Self

Sets where the collider sits relative to its parent body.

For attached colliders, this is the offset from the body’s origin. For standalone colliders, this is the world position.

Example

// Collider offset 2 units to the right of the body
let collider = ColliderBuilder::ball(0.5)
    .translation(vector![2.0, 0.0, 0.0])
    .build();

pub fn rotation(self, angle: AngVector<f32>) -> Self

Sets the collider’s rotation relative to its parent body.

For attached colliders, this rotates the collider relative to the body. For standalone colliders, this is the world rotation.

pub fn position(self, pos: Isometry<f32>) -> Self

Sets the collider’s full pose (position + rotation) relative to its parent.

For attached colliders, this is relative to the parent body. For standalone colliders, this is the world pose.

pub fn position_wrt_parent(self, pos: Isometry<f32>) -> Self

👎Deprecated: Use .position instead.

Sets the initial position (translation and orientation) of the collider to be created, relative to the rigid-body it is attached to.

pub fn delta(self, delta: Isometry<f32>) -> Self

👎Deprecated: Use .position instead.

Set the position of this collider in the local-space of the rigid-body it is attached to.

pub fn contact_skin(self, skin_thickness: f32) -> Self

Sets the contact skin of the collider.

The contact skin acts as if the collider was enlarged with a skin of width skin_thickness around it, keeping objects further apart when colliding.

A non-zero contact skin can increase performance, and in some cases, stability. However it creates a small gap between colliding object (equal to the sum of their skin). If the skin is sufficiently small, this might not be visually significant or can be hidden by the rendering assets.

pub fn enabled(self, enabled: bool) -> Self

Sets whether this collider starts enabled or disabled.

Default is true (enabled). Set to false to create a disabled collider.

pub fn build(&self) -> Collider

Finalizes the collider and returns it, ready to be added to the world.

Example

let collider = ColliderBuilder::ball(0.5)
    .friction(0.7)
    .build();
colliders.insert_with_parent(collider, body_handle, &mut bodies);

Trait Implementations

impl Clone for ColliderBuilder

fn clone(&self) -> ColliderBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ColliderBuilder

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

Formats the value using the given formatter.

impl Default for ColliderBuilder

fn default() -> Self

Returns the “default value” for a type.

impl From<ColliderBuilder> for Collider

fn from(val: ColliderBuilder) -> Collider

Converts to this type from the input type.