bevy_urdf

A Bevy plugin for importing robots from URDF files and running physics simulations. Ground vehicles use Rapier physics, while drones are simulated using integrated dynamics models.

Features

Import URDF robot descriptions into Bevy
Support for STL and OBJ mesh formats
Rapier physics integration for ground vehicles
Custom dynamics simulation for drone vehicles
Event-driven sensor reading and motor control
Multiple robot type support (ground vehicles, quadrupeds, drones)

Installation

Add to your Cargo.toml:

[dependencies]
bevy_urdf = "0.3.0"  # Replace with actual version

Quick Start

1. Add Plugins

Add the necessary plugins to your Bevy app:

use bevy::prelude::*;
use bevy_urdf::{UrdfPlugin, StlPlugin, ObjPlugin};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins((
            UrdfPlugin,
            StlPlugin,
            ObjPlugin,
        ))
        .run();
}

2. Load Robot

Load a robot in your startup systems:

use bevy_urdf::{LoadRobot, RobotLoaded};

fn setup(mut load_robot_events: EventWriter<LoadRobot>) {
    load_robot_events.send(LoadRobot {
        urdf_path: "robots/flamingo_edu/urdf/Edu_v4.urdf".to_string(),
        mesh_dir: "assets/robots/flamingo_edu/urdf".to_string(),
    });
}

3. Spawn Robot

Subscribe to the loaded event and spawn the robot:

use bevy_urdf::{RobotLoaded, SpawnRobot, RobotType};

fn start_simulation(
    mut robot_loaded_events: EventReader<RobotLoaded>,
    mut spawn_robot_events: EventWriter<SpawnRobot>,
    mut next_state: ResMut<NextState<AppState>>,
) {
    for event in robot_loaded_events.read() {
        spawn_robot_events.send(SpawnRobot {
            handle: event.handle.clone(),
            mesh_dir: event.mesh_dir.clone(),
            robot_type: RobotType::NotDrone,
        });
        next_state.set(AppState::Simulation);
    }
}

API Reference

Events

The plugin uses an event-driven architecture for robot control and sensor feedback:

Sensor Reading

#[derive(Event)]
pub struct SensorsRead {
    pub handle: Handle<UrdfAsset>,
    pub transforms: Vec<Transform>,
    pub joint_angles: Vec<f32>,
}

Motor Control (Ground Robots)

For ground-based robots and vehicles:

#[derive(Event)]
pub struct ControlMotors {
    pub handle: Handle<UrdfAsset>,
    pub velocities: Vec<f32>,
}

Thrust Control (Drones)

For aerial vehicles and drones:

#[derive(Event)]
pub struct ControlThrusts {
    pub handle: Handle<UrdfAsset>,
    pub thrusts: Vec<f32>,
}

Robot Types

RobotType::NotDrone - Ground vehicles, quadrupeds, manipulators
RobotType::Drone - Aerial vehicles with thrust-based control

Examples

Run the included examples to see the plugin in action:

# Drone simulation
cargo run --example quadrotor --release

# Quadruped robot simulation  
cargo run --example quadruped --release

URDF Requirements

Before using URDF files with this plugin:

Mesh Paths: Ensure all mesh file references use relative paths
Unsupported Elements: Remove or replace package:// URIs
Gazebo Elements: Gazebo-specific nodes are not supported and should be removed

Example of supported mesh reference:

<!-- Good: relative path -->
<mesh filename="meshes/base_link.stl"/>

<!-- Not supported: package URI -->
<mesh filename="package://robot_description/meshes/base_link.stl"/>

Known Limitations

Package URIs (package://) are not supported
Gazebo-specific URDF elements are ignored
Drone rotor animations are not yet implemented
Limited to STL and OBJ mesh formats

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

bevy_urdf 0.3.3