Crate robocomp_avian3d

Expand description

§robocomp_avian3d

Avian 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_avian3d only and get the full robocomp API alongside the Avian backend.

§Plugins

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

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

§Quick Start

[dependencies]
robocomp_avian3d = "0.1"

use bevy::prelude::*;
use avian3d::prelude::*;
use robocomp_avian3d::{RobocompAvianPlugin, rc::RcSceneRoot};

app.add_plugins((
    PhysicsPlugins::default(),
    RobocompAvianPlugin,
));

Controller-driven examples also require RobocompAvianControllerPlugin:

use robocomp_avian3d::{RobocompAvianControllerPlugin, RobocompAvianPlugin};

app.add_plugins((
    PhysicsPlugins::default(),
    RobocompAvianPlugin,
    RobocompAvianControllerPlugin,
));

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

cargo run -p robocomp_avian3d --example simple_rigid_bodies_avian3d

§Examples

Example	Description	Run
`simple_rigid_bodies_avian3d`	A simple rigid bodies example with a fixed table and cube(s) that fall onto it.	`cargo run -p robocomp_avian3d --example simple_rigid_bodies_avian3d`
`revolute_avian3d`	Example demonstrating a simple robot with a revolute joint between two cubes.	`cargo run -p robocomp_avian3d --example revolute_avian3d`
`revolute_skein_avian3d`	Example demonstrating a scene imported from Blender using Skein, with a revolute joint between two cubes.	`cargo run -p robocomp_avian3d --example revolute_skein_avian3d`
`prismatic_ctrl_avian3d`	Example demonstrating a robot with a prismatic joint (w/ limits) between two cubes; control via W/S + ShiftLeft.	`cargo run -p robocomp_avian3d --example prismatic_ctrl_avian3d`
`multi_joints_ctrl_avian3d`	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_avian3d --example multi_joints_ctrl_avian3d`

§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
Motor models	All three `RdMotorModel` variants map natively (`SpringDamper`, `ForceBased`, `AccelerationBased`).
Prismatic position control	`SpringDamper` is the recommended/stable choice (see the prismatic example).
Revolute continuous spin	Avian wraps position error to `[-π, π]`; use velocity motors for continuous rotation, not `SpringDamper` position control (see the multi-joint example).
`RcRigidBody::Fixed`	Maps to Avian `RigidBody::Static` (not `Fixed`).
`RcCcd`	Not wired yet — `RcCcd` is ignored in the Avian pre-processor.
`RcDisableSleep`	Supported — inserts `SleepingDisabled`.
Spherical joint motors	Not wired yet — pre-processor passes `motor_x/y/z: None` regardless of `RcSphericalJointMotor`.
Spherical joint limits	Best-effort mapping: per-axis Rapier-style limits → Avian swing/twist limits.
Controller timing	Motor control runs in `FixedPostUpdate`, before `PhysicsSystems::Prepare`.

§Bevy Compatibility

Bevy	avian3d	robocomp_avian3d
0.18	0.6.1	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 the controller queue.
ControllerPluginSystemSet: Update-scheduled controller systems.
PreProcessorPluginSystemSet: System set for [PreProcessorPlugin]’s systems.
RobocompAvianControllerPlugin: Plugin for controlling Robocomp robots with Avian.
RobocompAvianPlugin: Robocomp Avian Plugin
RobocompPlugin: Robocomp Plugin

Functions§

angular_motor_from_rd
fixed_joint_from_rd
linear_motor_from_rd
motor_model_from_rd
prismatic_joint_from_rd
revolute_joint_from_rd
rigid_body_from_rc
spherical_joint_from_rd