grilme99 / bevy_xpbd

2D and 3D physics engine based on Extended Position Based Dynamics for Bevy.

Bevy XPBD

Bevy XPBD is a 2D and 3D physics engine based on Extended Position Based Dynamics (XPBD) for the Bevy game engine.

Design

Below are some of the core design principles used in Bevy XPBD.

• Made with Bevy, for Bevy. No wrappers around existing engines.
• Provide an ergonomic and familiar API. Ergonomics is key for a good experience.
• Utilize the ECS as much as possible. The engine should feel like a part of Bevy, and it shouldn't need to maintain a separate physics world.
• Use a highly modular plugin architecture. Users should be able to replace parts of the engine with their own implementations.
• Have good documentation. A physics engine is pointless if you don't know how to use it.

Features

Below are some of the current features of Bevy XPBD.

• Dynamic, kinematic and static rigid bodies
• Colliders powered by parry
  • Collision events: Collision, CollisionStarted, CollisionEnded
  • Access to colliding entities with CollidingEntities
  • Sensor colliders
  • Collision layers
• Material properties like restitution and friction
• External forces and torque
• Gravity
• Joints
• Built-in constraints and support for custom constraints
• Automatically deactivating bodies with Sleeping
• Configurable timesteps and substepping
• f32/f64 precision (f32 by default)

Documentation

• bevy_xpbd_2d
• bevy_xpbd_3d

Usage example

For a 2D game, add the bevy_xpbd_2d crate to your Cargo.toml like this:

[dependencies]
bevy_xpbd_2d = "0.1"

Similarly for a 3D game, add bevy_xpbd_3d:

[dependencies]
bevy_xpbd_3d = "0.1"

Below is a very simple example where a box with initial angular velocity falls onto a plane. This is a modified version of Bevy's 3d_scene example.

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(PhysicsPlugins)
        .add_startup_system(setup)
        .run();
}

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    // Plane
    commands.spawn((
        PbrBundle {
            mesh: meshes.add(Mesh::from(shape::Plane::from_size(8.0))),
            material: materials.add(Color::rgb(0.3, 0.5, 0.3).into()),
            ..default()
        },
        RigidBody::Static,
        Collider::cuboid(8.0, 0.002, 8.0),
    ));
    // Cube
    commands.spawn((
        PbrBundle {
            mesh: meshes.add(Mesh::from(shape::Cube { size: 1.0 })),
            material: materials.add(Color::rgb(0.8, 0.7, 0.6).into()),
            ..default()
        },
        RigidBody::Dynamic,
        Position(Vec3::Y * 4.0),
        AngularVelocity(Vec3::new(2.5, 3.4, 1.6)),
        Collider::cuboid(1.0, 1.0, 1.0),
    ));
    // Light
    commands.spawn(PointLightBundle {
        point_light: PointLight {
            intensity: 1500.0,
            shadows_enabled: true,
            ..default()
        },
        transform: Transform::from_xyz(4.0, 8.0, 4.0),
        ..default()
    });
    // Camera
    commands.spawn(Camera3dBundle {
        transform: Transform::from_xyz(-4.0, 6.5, 8.0).looking_at(Vec3::ZERO, Vec3::Y),
        ..default()
    });
}

3d_scene.mp4

More examples

You can find lots of 2D and 3D examples in /crates/bevy_xpbd_2d/examples and /crates/bevy_xpbd_3d/examples respectively.

The examples support both f32 and f64 precisions, so the code contains some feature-dependent types like Scalar and Vector. In actual usage these are not needed, so you can just use f32 or f64 types depending on the features you have chosen.

By default the examples use f32. To run the f64 versions, you need to disable default features and manually choose the dimension and precision:

cargo run --example cubes --no-default-features --features "3d f64"

Supported Bevy versions

Bevy	Bevy XPBD
0.10	0.1

Future features

• On-demand simulation stepping
• Linear and angular velocity damping
• Locking translational and rotational axes without joints
• Joint motors
• Spatial queries
• Continuous collision detection
• Multiple colliders per body
• Debug render colliders and joints
• Performance optimization (better broad phase, parallel solver...)
• Soft bodies
  • Cloth
  • Deformable solids
• Maybe fluid simulation

Contributing

If you encounter any problems, feel free to open issues. Creating pull requests is encouraged as well, but especially for larger changes and additions it's better to open an issue first.

You can also ask for help or ask questions on the Bevy Discord server where you can find me as Jondolf.

License

Bevy XPBD is free and open source. All code in this repository is dual-licensed under either:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

at your option.