Struct RigidBodySet 

pub struct RigidBodySet { /* private fields */ }

The collection that stores all rigid bodies in your physics world.

This is where you add, remove, and access all your physics objects. Think of it as a “database” of all rigid bodies, where each body gets a unique handle for fast lookup.

Why use handles?

Instead of storing bodies directly, you get back a RigidBodyHandle when inserting. This handle is lightweight (just an index + generation) and remains valid even if other bodies are removed, protecting you from use-after-free bugs.

Example

let mut bodies = RigidBodySet::new();

// Add a dynamic body
let handle = bodies.insert(RigidBodyBuilder::dynamic());

// Access it later
if let Some(body) = bodies.get_mut(handle) {
    body.apply_impulse(vector![0.0, 10.0, 0.0], true);
}

Implementations

impl RigidBodySet

pub fn new() -> Self

Creates a new empty collection of rigid bodies.

Call this once when setting up your physics world. The collection will automatically grow as you add more bodies.

pub fn with_capacity(capacity: usize) -> Self

Creates a new collection with pre-allocated space for the given number of bodies.

Use this if you know approximately how many bodies you’ll need, to avoid multiple reallocations as the collection grows.

Example

// You know you'll have ~1000 bodies
let mut bodies = RigidBodySet::with_capacity(1000);

pub fn len(&self) -> usize

Returns how many rigid bodies are currently in this collection.

pub fn is_empty(&self) -> bool

Returns true if there are no rigid bodies in this collection.

pub fn contains(&self, handle: RigidBodyHandle) -> bool

Checks if the given handle points to a valid rigid body that still exists.

Returns false if the body was removed or the handle is invalid.

pub fn insert(&mut self, rb: impl Into<RigidBody>) -> RigidBodyHandle

Adds a rigid body to the world and returns its handle for future access.

The handle is how you’ll refer to this body later (to move it, apply forces, etc.). Keep the handle somewhere accessible - you can’t get the body back without it!

Example

let handle = bodies.insert(
    RigidBodyBuilder::dynamic()
        .translation(vector![0.0, 5.0, 0.0])
        .build()
);
// Store `handle` to access this body later

pub fn remove( &mut self, handle: RigidBodyHandle, islands: &mut IslandManager, colliders: &mut ColliderSet, impulse_joints: &mut ImpulseJointSet, multibody_joints: &mut MultibodyJointSet, remove_attached_colliders: bool, ) -> Option<RigidBody>

Removes a rigid body from the world along with all its attached colliders and joints.

This is a complete cleanup operation that removes:

• The rigid body itself
• All colliders attached to it (if remove_attached_colliders is true)
• All joints connected to this body

Returns the removed body if it existed, or None if the handle was invalid.

Parameters

• remove_attached_colliders - If true, removes all colliders attached to this body. If false, the colliders are detached and become independent.

Example

// Remove a body and everything attached to it
if let Some(body) = bodies.remove(
    handle,
    &mut islands,
    &mut colliders,
    &mut impulse_joints,
    &mut multibody_joints,
    true  // Remove colliders too
) {
    println!("Removed body at {:?}", body.translation());
}

pub fn get_unknown_gen(&self, i: u32) -> Option<(&RigidBody, RigidBodyHandle)>

Gets a rigid body by its index without knowing the generation number.

⚠️ Advanced/unsafe usage - prefer get() instead!

This bypasses the generation check that normally protects against the ABA problem (where an index gets reused after removal). Only use this if you’re certain the body at this index is the one you expect.

Returns both the body and its current handle (with the correct generation).

pub fn get_unknown_gen_mut( &mut self, i: u32, ) -> Option<(&mut RigidBody, RigidBodyHandle)>

Gets a mutable reference to a rigid body by its index without knowing the generation.

⚠️ Advanced/unsafe usage - prefer get_mut() instead!

This bypasses the generation check. See get_unknown_gen() for more details on when this is appropriate (rarely).

pub fn get(&self, handle: RigidBodyHandle) -> Option<&RigidBody>

Gets a read-only reference to the rigid body with the given handle.

Returns None if the handle is invalid or the body was removed.

Use this to read body properties like position, velocity, mass, etc.

pub fn get_mut(&mut self, handle: RigidBodyHandle) -> Option<&mut RigidBody>

Gets a mutable reference to the rigid body with the given handle.

Returns None if the handle is invalid or the body was removed.

Use this to modify body properties, apply forces/impulses, change velocities, etc.

Example

if let Some(body) = bodies.get_mut(handle) {
    body.set_linvel(vector![1.0, 0.0, 0.0], true);
    body.apply_impulse(vector![0.0, 100.0, 0.0], true);
}

pub fn get_pair_mut( &mut self, handle1: RigidBodyHandle, handle2: RigidBodyHandle, ) -> (Option<&mut RigidBody>, Option<&mut RigidBody>)

Gets mutable references to two different rigid bodies at once.

This is useful when you need to modify two bodies simultaneously (e.g., when manually handling collisions between them). If both handles are the same, only the first value will be Some.

Example

let (body1, body2) = bodies.get_pair_mut(handle1, handle2);
if let (Some(b1), Some(b2)) = (body1, body2) {
    // Can modify both bodies at once
    b1.apply_impulse(vector![10.0, 0.0, 0.0], true);
    b2.apply_impulse(vector![-10.0, 0.0, 0.0], true);
}

pub fn iter(&self) -> impl Iterator<Item = (RigidBodyHandle, &RigidBody)>

Iterates over all rigid bodies in this collection.

Each iteration yields a (handle, &RigidBody) pair. Use this to read properties of all bodies (positions, velocities, etc.) without modifying them.

Example

for (handle, body) in bodies.iter() {
    println!("Body {:?} is at {:?}", handle, body.translation());
}

pub fn iter_mut( &mut self, ) -> impl Iterator<Item = (RigidBodyHandle, &mut RigidBody)>

Iterates over all rigid bodies with mutable access.

Each iteration yields a (handle, &mut RigidBody) pair. Use this to modify multiple bodies in one pass.

Example

// Apply gravity manually to all dynamic bodies
for (handle, body) in bodies.iter_mut() {
    if body.is_dynamic() {
        body.add_force(vector![0.0, -9.81 * body.mass(), 0.0], true);
    }
}

pub fn propagate_modified_body_positions_to_colliders( &self, colliders: &mut ColliderSet, )

Updates the positions of all colliders attached to bodies that have moved.

Normally you don’t need to call this - it’s automatically handled by PhysicsPipeline::step. Only call this manually if you’re:

• Moving bodies yourself outside of step()
• Using QueryPipeline for raycasts without running physics simulation
• Need collider positions to be immediately up-to-date for some custom logic

This synchronizes collider world positions based on their parent bodies’ positions.

Trait Implementations

impl Clone for RigidBodySet

fn clone(&self) -> RigidBodySet

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RigidBodySet

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

Formats the value using the given formatter.

impl Default for RigidBodySet

fn default() -> RigidBodySet

Returns the “default value” for a type.

impl Index<Index> for RigidBodySet

type Output = RigidBody

The returned type after indexing.

fn index(&self, index: Index) -> &RigidBody

Performs the indexing (container[index]) operation.

impl Index<RigidBodyHandle> for RigidBodySet

type Output = RigidBody

The returned type after indexing.

fn index(&self, index: RigidBodyHandle) -> &RigidBody

Performs the indexing (container[index]) operation.

impl IndexMut<RigidBodyHandle> for RigidBodySet

Available on non-crate feature dev-remove-slow-accessors only.

fn index_mut(&mut self, handle: RigidBodyHandle) -> &mut RigidBody

Performs the mutable indexing (container[index]) operation.