Struct RapierPlugin 

pub struct RapierPlugin { /* private fields */ }

User-facing handle to a Rapier physics simulation running inside viewport-lib.

Holds an Arc<Mutex<RapierState>> shared with the two RuntimePlugin implementors returned by into_plugins. Cloning the handle is cheap.

All methods on this handle take the state mutex. They block while the simulate plugin is running; keep handle calls off the hot path or batch them between frames.

Mutex poisoning: if a previous holder of the lock panicked (most commonly: a closure passed to with_body_mut / with_state_mut panicked), every subsequent lock acquisition transparently recovers the underlying state and continues. The plugin never panics on a poisoned mutex.

Usage

use rapier_viewport_plugin::{RapierPlugin, rapier3d::prelude::*};

let mut rapier = RapierPlugin::new();

// Build bodies and colliders using rapier's own builders.
let floor_body = RigidBodyBuilder::fixed().build();
let floor_collider = ColliderBuilder::halfspace(Vector::z_axis()).build();
rapier.add_body(floor_id, floor_body, floor_collider);

let box_body = RigidBodyBuilder::dynamic()
    .translation(glam::Vec3::new(0.0, 0.0, 5.0))
    .build();
let box_collider = ColliderBuilder::cuboid(0.5, 0.5, 0.5)
    .restitution(0.4)
    .active_events(ActiveEvents::COLLISION_EVENTS)
    .build();
rapier.add_body(box_id, box_body, box_collider);

let (prepare, simulate) = rapier.clone().into_plugins();

For anything not in the curated API (joints, locked axes, sensor flags, collision groups, the query pipeline, etc.) use the escape hatches: with_body_mut, with_collider_mut, with_state_mut, and with_state.

Implementations

impl RapierPlugin

pub fn new() -> Self

Create with Earth-like gravity (-9.81 m/s^2 on the Z axis, Z-up world).

pub fn with_gravity(self, g: Vec3) -> Self

pub fn add_body(&mut self, node_id: NodeId, body: RigidBody, collider: Collider)

Register a body and its collider, binding both to a scene node.

Construct body and collider with rapier’s RigidBodyBuilder and ColliderBuilder. Initial transform, mass, restitution, friction, collision groups, sensor flag, CCD, locked axes, and every other rapier property are set on the builders.

pub fn remove_body(&mut self, node_id: NodeId)

Remove the body bound to node_id. No-op if the node was never registered.

pub fn clear_bodies(&mut self)

Remove every registered body and collider.

pub fn body_handle(&self, node_id: NodeId) -> Option<RigidBodyHandle>

Look up the rapier RigidBodyHandle for a registered body.

pub fn collider_handle(&self, node_id: NodeId) -> Option<ColliderHandle>

Look up the rapier ColliderHandle for a registered body.

pub fn with_body_mut<R>( &mut self, node_id: NodeId, f: impl FnOnce(&mut RigidBody) -> R, ) -> Option<R>

Run a closure with mutable access to a registered body’s RigidBody. Returns None if the node has no body.

plugin.with_body_mut(id, |b| {
    b.apply_impulse(glam::Vec3::Z * 5.0, true);
    b.lock_translations(true, true);
});

pub fn with_collider_mut<R>( &mut self, node_id: NodeId, f: impl FnOnce(&mut Collider) -> R, ) -> Option<R>

Run a closure with mutable access to a registered body’s Collider. Returns None if the node has no collider.

pub fn with_state_mut<R>(&mut self, f: impl FnOnce(&mut RapierState) -> R) -> R

Run a closure with mutable access to the entire RapierState. Use this for anything the curated API does not cover: joints, spatial queries against the broad phase, character controllers, etc.

Note: the internal mutex is held for the duration of f. Do not call back into other RapierPlugin methods from inside the closure – that will deadlock.

pub fn with_state<R>(&self, f: impl FnOnce(&RapierState) -> R) -> R

Read-only counterpart to with_state_mut.

pub fn into_plugins(self) -> (RapierPreparePlugin, RapierSimulatePlugin)

Split into the two RuntimePlugin objects the runtime needs. Bodies can still be added or removed at runtime through the cloned handle after this is called.

Trait Implementations

impl Clone for RapierPlugin

fn clone(&self) -> RapierPlugin

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for RapierPlugin

fn default() -> Self

Returns the “default value” for a type.