Struct PhysicsWorld 

pub struct PhysicsWorld {

    pub gravity: Vec3,
    pub integration_parameters: IntegrationParameters,
    pub physics_pipeline: PhysicsPipeline,
    pub collision_pipeline: CollisionPipeline,
    pub islands: IslandManager,
    pub broad_phase: BroadPhaseBvh,
    pub narrow_phase: NarrowPhase,
    pub bodies: RigidBodySet,
    pub colliders: ColliderSet,
    pub impulse_joints: ImpulseJointSet,
    pub multibody_joints: MultibodyJointSet,
    pub soft_bodies: SoftBodySet,
    pub ccd_solver: CCDSolver,
}

A convenience wrapper that bundles all the Rapier physics state into a single struct.

Rapier intentionally splits its state across many structs (RigidBodySet, ColliderSet, NarrowPhase, etc.) to give you fine-grained control over borrowing. This is important for advanced use cases, but it makes simple setups verbose.

PhysicsWorld gives you a single struct for the common case. All fields are pub, so you can always reach in and borrow individual fields when the borrow checker requires it.

Example

let mut world = PhysicsWorld::default();

// Create a ground plane
let (_ground, _) = world.insert(
    RigidBodyBuilder::fixed(),
    ColliderBuilder::cuboid(10.0, 0.1, 10.0),
);

// Create a falling ball
let (ball, _) = world.insert(
    RigidBodyBuilder::dynamic().translation(Vector::new(0.0, 5.0, 0.0)),
    ColliderBuilder::ball(0.5),
);

// Simulate 100 steps
for _ in 0..100 {
    world.step();
}

println!("Ball position: {:?}", world.bodies[ball].translation());

Fields

gravity: Vec3

Gravity applied to all dynamic bodies each step.

integration_parameters: IntegrationParameters

Parameters controlling the simulation (timestep, solver iterations, etc.).

physics_pipeline: PhysicsPipeline

The main simulation pipeline that orchestrates each physics step.

collision_pipeline: CollisionPipeline

Workspace for collision-only updates that do not integrate positions or solve constraints.

islands: IslandManager

Manages active/sleeping body groups (islands) for efficient simulation.

broad_phase: BroadPhaseBvh

The broad-phase acceleration structure for fast spatial queries.

narrow_phase: NarrowPhase

Precise contact and intersection detection between collider pairs.

bodies: RigidBodySet

All rigid bodies in this world.

colliders: ColliderSet

All colliders (collision shapes) in this world.

impulse_joints: ImpulseJointSet

All impulse-based joints (hinges, springs, ropes, etc.).

multibody_joints: MultibodyJointSet

All multibody joints (kinematic chains, articulations).

soft_bodies: SoftBodySet

All soft bodies (deformable particle bodies).

ccd_solver: CCDSolver

The continuous collision detection solver.

Workspace only: not part of a snapshot (see the type docs).

Implementations

impl PhysicsWorld

pub fn new() -> PhysicsWorld

Creates a new physics world with default parameters and gravity (0, -9.81, 0).

pub fn step(&mut self)

Advance the simulation by one timestep, using no hooks and no event handler.

This is the simplest way to step. If you need collision events or physics hooks, use step_with_events.

pub fn step_with_events( &mut self, hooks: &dyn PhysicsHooks, events: &dyn EventHandler, )

Advance the simulation by one timestep with custom physics hooks and event handling.

Example

let (collision_send, collision_recv) = channel();
let (contact_force_send, contact_force_recv) = channel();
let (soft_body_tear_send, soft_body_tear_recv) = channel();
let event_handler =
    ChannelEventCollector::new(collision_send, contact_force_send, soft_body_tear_send);

world.step_with_events(&(), &event_handler);

while let Ok(event) = collision_recv.try_recv() {
    println!("Collision event: {:?}", event);
}

pub fn detect_collisions( &mut self, hooks: &dyn PhysicsHooks, events: &dyn EventHandler, )

Update broad-phase and narrow-phase collision detection without advancing simulation.

Uses the prediction distance from this world’s integration parameters. This is useful after editing transforms when contacts and scene queries must be refreshed immediately.

pub fn quarantine(&self) -> &Quarantine

The bodies and colliders automatically disabled during the last step because their state became non-finite; see [Quarantine].

pub fn insert( &mut self, body: impl Into<RigidBody>, collider: impl Into<Collider>, ) -> (RigidBodyHandle, ColliderHandle)

Insert a rigid body with an attached collider, and return both handles.

This bundles the two most common setup steps — creating a body and attaching its collider — into a single call. For the rare case of a rigid body without any collider (typically an anchor body for joints), use insert_body instead. For compound bodies with multiple colliders, pass the first collider here and use insert_collider with Some(body_handle) for the rest.

Example

let (body, collider) = world.insert(
    RigidBodyBuilder::dynamic().translation(Vector::new(0.0, 5.0, 0.0)),
    ColliderBuilder::ball(0.5),
);

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

Insert a rigid body without any collider, and return its handle.

Most bodies should be inserted together with a collider — prefer insert when possible. Use this method for bodies that truly don’t need a collider, such as anchor bodies used purely as joint attachment points.

Example

let anchor = world.insert_body(RigidBodyBuilder::fixed());

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

Remove a rigid body and all its attached colliders and joints.

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

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

Remove a rigid body and its joints, optionally preserving attached colliders.

Preserved colliders become standalone colliders. Returns None for an invalid handle.

pub fn wake_up(&mut self, handle: RigidBodyHandle, strong: bool)

Wake a sleeping body, forcing it back into the active simulation.

Useful after manually moving a body, applying forces, or otherwise wanting to make sure it gets simulated on the next step. No-op for already-awake bodies, and for fixed bodies (which don’t sleep).

Parameters

• strong — if true, the body is guaranteed to stay awake for several frames. If false, it may sleep again immediately if sleep conditions are met.

pub fn wake_up_all(&mut self, strong: bool)

Wake every sleeping body in the world.

pub fn insert_collider( &mut self, collider: impl Into<Collider>, parent: Option<RigidBodyHandle>, ) -> ColliderHandle

Insert a collider, optionally attached to a rigid body, and return its handle.

Pass Some(parent) to attach the collider to a rigid body — its position will then be interpreted relative to its parent. Pass None for a standalone collider, useful for static collision geometry or sensors that don’t need a rigid body.

Example

let body = world.insert_body(RigidBodyBuilder::dynamic());

// Attached collider.
let attached = world.insert_collider(ColliderBuilder::ball(0.5), Some(body));

// Standalone collider (e.g. static geometry).
let standalone = world.insert_collider(ColliderBuilder::cuboid(10.0, 0.1, 10.0), None);

pub fn remove_collider(&mut self, handle: ColliderHandle) -> Option<Collider>

Remove a collider from the world.

Returns the removed collider, or None if the handle was invalid.

pub fn insert_impulse_joint( &mut self, body1: RigidBodyHandle, body2: RigidBodyHandle, joint: impl Into<GenericJoint>, ) -> ImpulseJointHandle

Insert an impulse joint between two bodies and return its handle.

Example

let body1 = world.insert_body(RigidBodyBuilder::dynamic());
let body2 = world.insert_body(RigidBodyBuilder::dynamic());
let joint = world.insert_impulse_joint(body1, body2, RevoluteJointBuilder::new(Vector::Z));

pub fn remove_impulse_joint( &mut self, handle: ImpulseJointHandle, ) -> Option<GenericJoint>

Remove an impulse joint.

Returns the removed joint data, or None if the handle was invalid.

pub fn impulse_joints( &self, ) -> impl Iterator<Item = (ImpulseJointHandle, &ImpulseJoint)>

Iterate over every impulse joint in the world as (handle, &joint) pairs.

pub fn impulse_joints_with( &self, body: RigidBodyHandle, ) -> impl Iterator<Item = (RigidBodyHandle, RigidBodyHandle, ImpulseJointHandle, &ImpulseJoint)>

Iterate over every impulse joint attached to the given rigid body.

Each item is (body1, body2, joint_handle, &joint). body1 and body2 are the joint’s endpoints — one of them is always body, the other is the neighbor.

pub fn insert_multibody_joint( &mut self, body1: RigidBodyHandle, body2: RigidBodyHandle, joint: impl Into<GenericJoint>, ) -> Option<MultibodyJointHandle>

Insert a multibody joint between two bodies and return its handle.

Returns None if the joint would create an invalid kinematic chain (e.g. a cycle).

pub fn remove_multibody_joint(&mut self, handle: MultibodyJointHandle)

Remove a multibody joint.

pub fn multibody_joints( &self, ) -> impl Iterator<Item = (MultibodyJointHandle, &MultibodyLinkId, &Multibody, &MultibodyLink)>

Iterate over every multibody joint in the world.

Each item is (joint_handle, &link_id, &multibody, &link).

pub fn multibody_joints_with( &self, body: RigidBodyHandle, ) -> impl Iterator<Item = (RigidBodyHandle, RigidBodyHandle, MultibodyJointHandle)>

Iterate over every multibody joint attached to the given rigid body.

Each item is (body1, body2, joint_handle). body1 and body2 are the joint’s endpoints — one of them is always body, the other is the neighbor.

pub fn insert_soft_body(&mut self, soft_body: SoftBodyBuilder) -> SoftBodyHandle

Insert a soft body and return its handle; this creates its hidden root rigid body and its colliders (a deformable surface, or one ball per surface particle), which Self::remove_soft_body removes.

pub fn insert_deformable( &mut self, collider: impl Into<Collider>, binding: SoftMeshBinding, parent: RigidBodyHandle, ) -> Result<ColliderHandle, SoftBindingError>

Inserts a collider holding a soft body’s deformable collision mesh, bound to the cluster of parent (a cluster proxy: see ColliderSet::insert_deformable).

pub fn remove_soft_body(&mut self, handle: SoftBodyHandle) -> Option<SoftBody>

Remove a soft body, its root rigid body and its colliders.

pub fn cut_soft_body( &mut self, handle: SoftBodyHandle, blade: &[Vec3; 3], ) -> Option<SoftBodyTearEvent>

Cuts a soft body along a blade (a world segment in 2D, a triangle in 3D) at once, without removing any material (see [SoftBodySet::cut]). Returns the tear event, or None when the cut changed nothing.

pub fn tear_soft_body( &mut self, handle: SoftBodyHandle, edges: &[u32], cells: &[u32], ) -> Option<SoftBodyTearEvent>

Tears a soft body at once along the given edges and through the given cells, without removing any material (see [SoftBodySet::tear] and [SoftBody::tear_edge]). Returns the tear event, or None when nothing changed.

pub fn add_soft_body_cluster( &mut self, handle: SoftBodyHandle, particles: &[u32], ) -> Option<u32>

Adds a cluster to a soft body: a set of its particles backed by a fresh proxy rigid body ([crate::dynamics::RigidBodyType::SoftFrame]) that impulse joints and colliders can attach to. Returns the cluster’s index (see [SoftBodySet::add_cluster]).

pub fn remove_soft_body_cluster( &mut self, handle: SoftBodyHandle, cluster: u32, ) -> Option<SoftClusterRemoval>

Removes a soft body’s cluster, its proxy rigid body, and the particles only that cluster covered (see [SoftBodySet::remove_cluster]). Removing the proxy from the [RigidBodySet] is equivalent.

pub fn soft_bodies(&self) -> impl Iterator<Item = (SoftBodyHandle, &SoftBody)>

Iterate over every soft body in the world.

pub fn query_pipeline(&self) -> QueryPipeline<'_>

Get a [QueryPipeline] for performing spatial queries (raycasts, shape casts, etc.).

Example

let query_pipeline = world.query_pipeline();
let ray = Ray::new(Vector::new(0.0, 10.0, 0.0), Vector::new(0.0, -1.0, 0.0));
if let Some((handle, toi)) = query_pipeline.cast_ray(&ray, Real::MAX, true) {
    println!("Hit {:?} at distance {}", handle, toi);
}

pub fn query_pipeline_with_filter<'a>( &'a self, filter: QueryFilter<'a>, ) -> QueryPipeline<'a>

Get a [QueryPipeline] with a custom [QueryFilter].

pub fn cast_ray<'a>( &'a self, ray: &Ray, max_toi: f32, solid: bool, filter: QueryFilter<'a>, ) -> Option<(ColliderHandle, f32)>

Cast a ray and return the first collider hit.

Shorthand for world.query_pipeline_with_filter(filter).cast_ray(...).

Returns Some((collider_handle, distance)), or None if nothing was hit. Pass [QueryFilter::default()] to consider every collider.

pub fn cast_ray_and_get_normal<'a>( &'a self, ray: &Ray, max_toi: f32, solid: bool, filter: QueryFilter<'a>, ) -> Option<(ColliderHandle, RayIntersection)>

Cast a ray and return the first hit with surface normal information.

Shorthand for world.query_pipeline_with_filter(filter).cast_ray_and_get_normal(...).

pub fn cast_shape<'a>( &'a self, shape_pos: &Pose3, shape_vel: Vec3, shape: &(dyn Shape + 'static), options: ShapeCastOptions, filter: QueryFilter<'a>, ) -> Option<(ColliderHandle, ShapeCastHit)>

Cast (sweep) a shape through the world and return the first collider hit.

Shorthand for world.query_pipeline_with_filter(filter).cast_shape(...).

pub fn cast_shape_nonlinear<'a>( &'a self, shape_motion: &NonlinearRigidMotion, shape: &(dyn Shape + 'static), start_time: f32, end_time: f32, stop_at_penetration: bool, filter: QueryFilter<'a>, ) -> Option<(ColliderHandle, ShapeCastHit)>

Cast a shape with a nonlinear motion and return the first collider hit.

Shorthand for world.query_pipeline_with_filter(filter).cast_shape_nonlinear(...).

pub fn project_point<'a>( &'a self, point: Vec3, max_dist: f32, solid: bool, filter: QueryFilter<'a>, ) -> Option<(ColliderHandle, PointProjection)>

Find the closest point on any collider to the given point.

Shorthand for world.query_pipeline_with_filter(filter).project_point(...).

pub fn project_point_and_get_feature<'a>( &'a self, point: Vec3, filter: QueryFilter<'a>, max_dist: f32, ) -> Option<(ColliderHandle, PointProjection, FeatureId)>

Project a point onto the closest collider and also return the geometric feature (vertex, edge, or face) that contains the projection.

Shorthand for world.query_pipeline_with_filter(filter).project_point_and_get_feature(...).

pub fn intersect_ray<'a>( &'a self, ray: Ray, max_toi: f32, solid: bool, filter: QueryFilter<'a>, ) -> impl Iterator<Item = (ColliderHandle, &'a Collider, RayIntersection)> + 'a

Iterate over every collider that the given ray passes through.

Unlike cast_ray which stops at the first hit, this yields every collider along the ray’s path. Each item is (handle, &collider, intersection).

pub fn intersect_point<'a>( &'a self, point: Vec3, filter: QueryFilter<'a>, ) -> impl Iterator<Item = (ColliderHandle, &'a Collider)> + 'a

Iterate over every collider that contains the given point.

Each item is (handle, &collider).

pub fn intersect_shape<'a>( &'a self, shape_pos: Pose3, shape: &'a (dyn Shape + 'static), filter: QueryFilter<'a>, ) -> impl Iterator<Item = (ColliderHandle, &'a Collider)> + 'a

Iterate over every collider whose shape intersects the given shape positioned at shape_pos.

Each item is (handle, &collider).

pub fn intersect_aabb_conservative<'a>( &'a self, aabb: Aabb, filter: QueryFilter<'a>, ) -> impl Iterator<Item = (ColliderHandle, &'a Collider)> + 'a

Iterate over every collider whose stored AABB intersects the given AABB.

This is conservative: the AABBs used are the ones in the broad-phase BVH, not freshly recomputed collider AABBs. Useful for cheap, broad-strokes proximity queries.

Each item is (handle, &collider).

pub fn contact_pair( &self, collider1: ColliderHandle, collider2: ColliderHandle, ) -> Option<&ContactPair>

Get the contact pair between two specific colliders, if it exists.

Returns None if the two colliders are not in contact or not neighbors in the broad-phase.

pub fn contact_pairs_with( &self, collider: ColliderHandle, ) -> impl Iterator<Item = &ContactPair>

Iterate over all contact pairs involving the given collider.

pub fn contact_pairs(&self) -> impl Iterator<Item = &ContactPair>

Iterate over all contact pairs in the world.

pub fn intersection_pair( &self, collider1: ColliderHandle, collider2: ColliderHandle, ) -> Option<bool>

Check if two specific colliders are intersecting (for sensor colliders).

Returns None if the pair doesn’t exist, Some(true) if intersecting.

pub fn intersection_pairs_with( &self, collider: ColliderHandle, ) -> impl Iterator<Item = (ColliderHandle, &Collider, ColliderHandle, &Collider, bool)>

Iterate over all intersection pairs involving the given collider.

Each item is (handle_a, &collider_a, handle_b, &collider_b, intersecting).

Mutable access

There is no _mut variant of this method: the same collider may appear in several intersection pairs, so a safe Iterator yielding &mut Collider from a pair iterator isn’t possible in stable Rust. To mutate colliders based on intersection pairs, iterate here to collect the handles you care about, then call ColliderSet::get_pair_mut on self.colliders:

let pairs: Vec<_> = world
    .intersection_pairs_with(collider)
    .map(|(h1, _, h2, _, _)| (h1, h2))
    .collect();
for (h1, h2) in pairs {
    if let (Some(c1), Some(c2)) = world.colliders.get_pair_mut(h1, h2) {
        // mutate c1 and c2…
    }
}

pub fn intersection_pairs( &self, ) -> impl Iterator<Item = (ColliderHandle, &Collider, ColliderHandle, &Collider, bool)>

Iterate over all intersection pairs in the world.

Each item is (handle_a, &collider_a, handle_b, &collider_b, intersecting).

Mutable access

There is no _mut variant of this method: the same collider may appear in several intersection pairs, so a safe Iterator yielding &mut Collider from a pair iterator isn’t possible in stable Rust. To mutate colliders based on intersection pairs, iterate here to collect the handles you care about, then call ColliderSet::get_pair_mut on self.colliders:

let pairs: Vec<_> = world
    .intersection_pairs()
    .map(|(h1, _, h2, _, _)| (h1, h2))
    .collect();
for (h1, h2) in pairs {
    if let (Some(c1), Some(c2)) = world.colliders.get_pair_mut(h1, h2) {
        // mutate c1 and c2…
    }
}

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

Iterate over every rigid body in the world as (handle, &body) pairs.

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

Iterate over every rigid body in the world as (handle, &mut body) pairs.

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

Iterate over only the currently active (awake) rigid bodies.

Sleeping bodies are skipped, as are bodies that never sleep but aren’t part of any active island (e.g. unattached fixed bodies). This is the iterator to use when rendering or syncing transforms, since transforms of sleeping bodies haven’t moved since the last step.

pub fn all_colliders(&self) -> impl Iterator<Item = (ColliderHandle, &Collider)>

Iterate over every collider in the world as (handle, &collider) pairs.

pub fn all_colliders_mut( &mut self, ) -> impl Iterator<Item = (ColliderHandle, &mut Collider)>

Iterate over every collider in the world as (handle, &mut collider) pairs.

Trait Implementations

impl Default for PhysicsWorld

fn default() -> PhysicsWorld

Returns the “default value” for a type.