Bevy Physics: Avian

Avian is the successor to bevy_xpbd. It's the de-facto ECS native physics solution for Bevy right now.

This guide is a work in progress and is still being updated.

The other big alternative is bevy_rapier. The key differences between the two libraries come down to how they connect to Bevy:

Avian is using components and doing the calculations on them directly within Bevy's ECS.

Rapier keeps a separate representation of the game's physics that are projected back on to Bevy's ECS.

Rapier is more mature and can be used outside of Bevy while Avian is specifically focused on integrating deeply with Bevy.

Instead of repeating what is already in Jondolf's post about the why. I'll specifically be writing about the pragmatic how.

Making things move

To show up on a window, we have to be rendered. Bevy provides a rendering system which will draw you somewhere on the screen if your entity has the required components.

Your position, in the eyes of Bevy's renderer, is dictated by an entity's Transform component.

A simple movement system could change that transform's translation property, adding to its x field each frame.

fn move_things(query: Query<&mut Transform>) {
  for transform in &mut query {
    transform.x += 1.
  }
}

There is obviously nothing physical about this. It would break our intuition about objects to see something actually fly through the air like this forever.

That's where libraries like Avian or Rapier come in. They are just like Bevy's renderer. They add systems to our app that will wait for entities with the right combination of components and change them for us.

Simulating physics

Rigid bodies are components we attach to entities. These components are what Avian's systems will query for and update. Finally one of Avian's systems will translate these changes to the Transform component which will cause Bevy to change its position on the screen when it renders.

Rigid bodies come in 3 flavors, each specialized for something:

1. Dynamic bodies are similar to real life objects and are affected by forces and contacts.
2. Kinematic bodies can only be moved programmatically, which is useful for things like player character controllers and moving platforms.
3. Static bodies can not move, so they can be good for objects in the environment like the ground and walls.

To create one we simply spawn an entity with the component:

fn spawn_ball(mut commands: Commands) {
  commands.spawn(RigidBody::Dynamic)
}

To move the same way as the initial example, but with Avian managing the physics, we would use a LinearVelocity component:

fn spawn_ball(mut commands: Commands) {
  commands.spawn((
    RigidBody::Dynamic,
    LinearVelocity(Vec2::new(0.0, 0.0)),
  ));
}

Okay but how big is this thing? How heavy? These kinds of questions are answered via an entities mass properties:

• Mass: Represents resistance to linear acceleration. A higher mass requires more force for the same acceleration.
• Angular Inertia: Represents resistance to angular acceleration. A higher angular inertia requires more torque for the same angular acceleration.
• Center of Mass: The average position of mass in the body. Applying forces at this point produces no torque.

By default, Avian is going to determine these for us via our our collider. But we can also override them by providing our own components for each:

fn spawn_ball(mut commands: Commands) {
  commands.spawn((
    RigidBody::Dynamic,
    LinearVelocity(Vec2::new(0.0, 0.0)),
    Collider::circle(0.5),
    Mass(5.0),
    CenterOfMass::new(0.0, -0.5),
  ));
}

The type of body you are will also change your mass properties. Static and kinematic rigid bodies have infinite mass and angular inertia. They also do not respond to forces or torques.

Colliding

Now, just because something is a physical body does not mean it has to interact with anything else.

Avian will calculate collisions, but only if your body has a component that explains exactly how it should collide.

fn spawn_ball(mut commands: Commands) {
  commands.spawn((
    RigidBody::Dynamic,
    Collider::circle(0.5),
  ));
}

Avian is going to use the size of this collider to determine how much mass your body has.