Crate robocomp_rapier3d

Expand description

§robocomp_rapier3d

Rapier 3D physics integration for robocomp — the physics-agnostic core crate for robot/rigid-body composition in Bevy.

This crate re-exports robocomp, rc, and rd, so you typically depend on robocomp_rapier3d only and get the full robocomp API alongside the Rapier backend.

§Plugins

Plugin	Purpose
`RobocompRapierPlugin`	Bundles `RobocompPlugin` with the Rapier pre-processor that spawns colliders and joints from `Rc*` scene markers.
`RobocompRapierControllerPlugin`	Optional keyboard motor control for revolute and prismatic joints (used by the `_ctrl_` examples).

The Rapier physics plugin must be added alongside the robocomp backend — this crate does not bundle bevy_rapier3d.

§Quick Start

[dependencies]
robocomp_rapier3d = "0.1"

use bevy::prelude::*;
use bevy_rapier3d::prelude::*;
use robocomp_rapier3d::{RobocompRapierPlugin, rc::RcSceneRoot};

app.add_plugins((
    RapierPhysicsPlugin::<NoUserData>::default(),
    RobocompRapierPlugin,
));

Controller-driven examples also require RobocompRapierControllerPlugin:

use robocomp_rapier3d::{RobocompRapierControllerPlugin, RobocompRapierPlugin};

app.add_plugins((
    RapierPhysicsPlugin::<NoUserData>::default(),
    RobocompRapierPlugin,
    RobocompRapierControllerPlugin,
));

From the workspace root (assets live at the repo root):

cargo run -p robocomp_rapier3d --example simple_rigid_bodies_rapier3d

§Examples

Example	Description	Run
`simple_rigid_bodies_rapier3d`	A simple rigid bodies example with a fixed table and cube(s) that fall onto it.	`cargo run -p robocomp_rapier3d --example simple_rigid_bodies_rapier3d`
`revolute_rapier3d`	Example demonstrating a simple robot with a revolute joint between two cubes.	`cargo run -p robocomp_rapier3d --example revolute_rapier3d`
`revolute_skein_rapier3d`	Example demonstrating a scene imported from Blender using Skein, with a revolute joint between two cubes.	`cargo run -p robocomp_rapier3d --example revolute_skein_rapier3d`
`prismatic_ctrl_rapier3d`	Example demonstrating a robot with a prismatic joint (w/ limits) between two cubes; control via W/S + ShiftLeft.	`cargo run -p robocomp_rapier3d --example prismatic_ctrl_rapier3d`
`multi_joints_ctrl_rapier3d`	Robot chain with interleaved revolute and prismatic joints (5 links); W/S + Shift to drive, Arrow Up/Down to cycle active joint.	`cargo run -p robocomp_rapier3d --example multi_joints_ctrl_rapier3d`

§Backend Specifics and Caveats

Robocomp is physics-agnostic — switching backends requires minimal code and scene changes, but motor tuning and simulation feel are not guaranteed to match out of the box. The same Rd* / Rc* components are mapped differently per backend. If porting from another physics backend, consider the differences below.

Topic	Behavior
`RdMotorModel::SpringDamper`	No native Rapier equivalent. Mapped to `MotorModel::AccelerationBased` with converted stiffness/damping: `stiffness = (2π·f)²`, `damping = 2·ζ·(2π·f)`. Behavior differs from Avian’s implicit spring-damper integrator.
`RdMotorModel::AccelerationBased`	Maps to Rapier `AccelerationBased`.
`RdMotorModel::ForceBased`	Maps to Rapier `ForceBased`.
Velocity motor damping	Rapier `set_motor_velocity(target, factor)` uses the model’s damping coefficient as the velocity factor. Not the same semantics as Avian velocity motors.
Recommended motor models	Examples use `AccelerationBased { stiffness, damping }` for position-controlled prismatic joints. The Avian prismatic example’s `SpringDamper` is roughly equivalent to `{ stiffness: 5000., damping: 650. }` on Rapier.
`RcRigidBody::Fixed`	Maps to Rapier `RigidBody::Fixed`.
`RcCcd`	Supported — inserts Rapier `Ccd::enabled()`.
`RcDisableSleep`	Supported — inserts `Sleeping::disabled()`.
Spherical joint motors	Spawned in the pre-processor, but controller motor control for spherical joints is not implemented yet.
Controller timing	Motor control runs in `FixedUpdate`, before `PhysicsSet::SyncBackend`.

§Bevy Compatibility

Bevy	bevy_rapier3d	robocomp_rapier3d
0.18	0.34	0.1

Modules§

cleanup_manager: Cleanup manager plugin and related components/systems.
plugin: Main plugin for the robot compositor.
rc: Exposes the components for the robot composition/editing.
rd: Describes the robot and its components. URDF inspired robot description format. ref: https://wiki.ros.org/urdf/XML ref: https://articulatedrobotics.xyz/tutorials/ready-for-ros/urdf/

Structs§

ActiveJointControlTracker: Tracks the currently controlled joint and other joints in controller queue.
PreProcessorPluginSystemSet: System set for [PreProcessorPlugin]’s systems.
RobocompPlugin: Robocomp Plugin
RobocompRapierControllerPlugin: Plugin for Controlling Robocomp Robots with Rapier.
RobocompRapierPlugin: Robocomp Rapier Plugin

Functions§

fixed_joint_builder_from_rd
motor_model_from_rd: Backwards-compatible alias for rapier_motor_model_from_rd.
prismatic_joint_builder_from_rd
rapier_motor_model_from_rd: Maps RdMotorModel to Rapier’s unit-variant MotorModel.
revolute_joint_builder_from_rd
rigid_body_from_rc
spherical_joint_builder_from_rd
stiffness_damping_from_rd: Returns stiffness/damping coefficients for Rapier’s motor_position.