# Avian: a physics engine built inside Bevy's ECS

> Avian is an ECS-driven 2D and 3D physics engine for Bevy, published as avian2d and avian3d. Its design keeps physics state in Bevy components rather than a separate world, and its version table ties each release to a specific Bevy version.

**avianphysics/avian** — ECS-driven 2D and 3D physics engine for the Bevy game engine.

- Repository: https://github.com/avianphysics/avian
- Website: https://crates.io/crates/avian3d
- Stars: 3,203 · Forks: 285
- Language: Rust
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/avianphysics-avian

## What Avian solves for Bevy projects

Bevy ships rendering, input, asset handling and an ECS scheduler, but no collision or rigid body simulation. Avian fills that gap as a native Bevy plugin rather than a binding over an external engine. The README states the design goal directly: "Made with Bevy, for Bevy. No wrappers around existing engines." The practical consequence is that a body is a Bevy entity carrying components such as RigidBody, Collider and AngularVelocity, and the physics step is a Bevy schedule. There is no second world to synchronize transforms with, because the physics state lives on the same entities the rest of your game already queries.

The audience is narrow and specific: Rust developers writing games or simulations in Bevy who need dynamic, kinematic and static bodies, collision events, joints and spatial queries. Avian is not a general-purpose physics library you call from a non-Bevy Rust program, and the README gives no indication of a standalone mode. Collision detection itself is delegated to Parry, which the README credits as the collision backend, so the geometry and contact generation layer is not written from scratch here.

## How the ECS-first architecture actually works

The README lists a modular plugin architecture as a core principle, and the workspace layout reflects it: the top-level Cargo.toml declares two members, crates/avian2d and crates/avian3d, and excludes benches. The 2D and 3D engines are separate crates that share the same design, which is why the README points to two documentation sets on docs.rs instead of one.

At runtime you add PhysicsPlugins::default() alongside Bevy's DefaultPlugins, as the usage example shows. From there, physics behaviour is expressed as components. The example spawns a static platform with RigidBody::Static and Collider::cylinder(4.0, 0.1), and a falling cube with RigidBody::Dynamic, Collider::cuboid(1.0, 1.0, 1.0) and AngularVelocity(Vec3::new(2.5, 3.5, 1.5)). The engine reads those components, steps the simulation, and writes back transforms. The README also lists Transform interpolation and extrapolation for fixed timesteps, which is the mechanism that keeps rendered motion smooth when the physics tick rate differs from the frame rate.

The modularity claim is more than marketing copy: the README states the engine supports custom collision backends and custom joints and other constraints using XPBD, so Parry and the built-in joint types are replaceable parts rather than hardcoded internals. Colliders can also be generated for meshes and entire scenes, which matters when your level geometry already exists as meshes and you do not want to hand-author a shape per object.

## Installing avian3d and getting a cube to fall

Avian is distributed on crates.io as avian2d and avian3d, with the homepage pointing at the avian3d crate page. Add the one matching your dimension to Cargo.toml. The README gives 0.7 as the current version string.

```toml
[dependencies]
avian3d = "0.7"
```

If you want to track unreleased work, the README shows a git dependency on the main branch instead of a version number.

```toml
[dependencies]
avian3d = { git = "https://github.com/avianphysics/avian", branch = "main" }
```

With the dependency in place, the smallest working setup registers the physics plugins next to Bevy's defaults. This is the first half of the README's usage example.

```rust
use avian3d::prelude::*;
use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, PhysicsPlugins::default()))
        .add_systems(Startup, setup)
        .run();
}
```

The setup system then spawns entities. A static body needs a collider shape; a dynamic body needs a shape plus whatever initial state you want, such as an angular velocity. The README's example is a spinning cube dropped onto a cylinder, and the result it shows is a rendered scene where the cube falls and rotates. If you see the cube pass through the platform, the usual cause is a missing Collider on one of the two entities, since collision requires both sides to have a shape.

```rust
fn setup(mut commands: Commands, mut meshes: ResMut<Assets<Mesh>>, mut materials: ResMut<Assets<StandardMaterial>>) {
    commands.spawn((
        RigidBody::Static,
        Collider::cylinder(4.0, 0.1),
        Mesh3d(meshes.add(Cylinder::new(4.0, 0.1))),
        MeshMaterial3d(materials.add(Color::WHITE)),
    ));

    commands.spawn((
        RigidBody::Dynamic,
        Collider::cuboid(1.0, 1.0, 1.0),
        AngularVelocity(Vec3::new(2.5, 3.5, 1.5)),
        Mesh3d(meshes.add(Cuboid::from_length(1.0))),
        MeshMaterial3d(materials.add(Color::srgb_u8(124, 144, 255))),
        Transform::from_xyz(0.0, 4.0, 0.0),
    ));
}
```

For more than one body, the README points to the example directories at /crates/avian2d/examples and /crates/avian3d/examples. Note that those examples use feature-dependent type aliases like Real and RVector so the same code compiles under both precisions; the README says you do not need those aliases in your own code.

## The Bevy version coupling is the main constraint

Avian's version table maps each release to exactly one Bevy version: Bevy 0.19 to Avian 0.7, Bevy 0.18 to Avian 0.5 through 0.6, Bevy 0.17 to 0.4, and so on back to Bevy 0.14 and Avian 0.1. That table is the single most important thing to read before starting. You cannot pick an Avian version independently of your Bevy version, and upgrading Bevy usually forces an Avian upgrade in the same change.

The repository acknowledges the cost of that coupling by shipping migration guides in the migration-guides directory, one per version according to the README. Those guides are the practical upgrade path, but they also imply that the API is not stable across Bevy releases. If you are maintaining a game across a Bevy upgrade, budget for reading the guide and touching every place you spawn physics components.

A second constraint is precision. The README states f32 is the default and f64 is available, but switching is not a flag flip. You must disable default features and select the dimension and precision explicitly, and the README notes that parry-f64 is what enables collision detection under f64. The documented command is:

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

That is an example invocation, but it shows the shape of the feature set: dimension, precision and collision backend are chosen together. Projects that only ever use f32, which is the default, never encounter this.

## Avian against a wrapper-style physics binding

The obvious alternative in the Bevy ecosystem is a binding that wraps an existing C or C++ physics engine and mirrors its state into Bevy. Avian's README takes an explicit position against that approach: no wrappers around existing engines, and the ECS should be used as much as possible so the engine does not maintain a separate physics world. The difference in practice is where the source of truth lives. With a wrapper, bodies typically exist in the native engine and are synchronized to Bevy entities each frame; with Avian, the components on the entity are the state, and the engine's job is to read and write them.

That choice cuts both ways. In Avian's favour, physics queries sit next to the rest of your ECS code, and the README lists a SpatialQuery system parameter plus collision hooks for filtering and modifying collisions, which are the kinds of integration points that are awkward when the real state lives elsewhere. Against it, Avian is younger than the long-established native engines, and the version table shows it tracking Bevy releases closely rather than offering long-term API stability. If your project depends on a mature solver with a fixed API, or you need physics outside Bevy entirely, Avian is the wrong tool regardless of how well it fits Bevy's data model. The README also notes that Avian's predecessor was Bevy XPBD, with its own version table going back to Bevy 0.10, which is useful context if you are migrating an older codebase.

## Licence, maintenance and upgrade cost

The repository is licensed Apache-2.0, and the README badge says MIT/Apache 2.0, with LICENSE-APACHE and LICENSE-MIT both present at the top level. For most Rust projects that dual arrangement is the same one Bevy itself uses, so there is no new licence surface to reason about. This is not legal advice; if you redistribute in a way that triggers attribution or notice requirements, read both files.

On maintenance, the last push to the repository was on 2026-09-21, and the most recent release listed is v0.7.0 from 2026-06-20, following v0.6.1 in March 2026 and v0.6.0 earlier that same month. The repository is not archived. The release cadence in 2026 has been roughly quarterly, which is consistent with a project that follows Bevy's own release rhythm rather than one that ships on its own schedule.

The upgrade cost is therefore predictable but real. Each Bevy upgrade is paired with an Avian upgrade, each Avian upgrade has a migration guide in the migration-guides directory, and the API surface you touch is every component you spawn. The README also points contributors at an AI_POLICY.md before opening pull requests, which is worth reading if you plan to send patches rather than just consume the crate.

## Conclusion

Avian fits teams already building on Bevy who want rigid bodies, colliders, joints and spatial queries as ordinary components, and who can accept that each Avian release is pinned to a Bevy release. It is the wrong choice if you need a physics engine that runs outside Bevy, or if you are on a Bevy version that the version table does not map to an Avian release. Before adopting, check the version table row for your Bevy version, read the migration guide for the jump you are making, and confirm whether you need f64 precision, since that requires disabling default features and enabling parry-f64.

## FAQ

### What is Avian in the context of Bevy?

Avian is an ECS-driven 2D and 3D physics engine for the Bevy game engine, distributed as the avian2d and avian3d crates. It is added to a Bevy app with PhysicsPlugins::default(), and bodies are Bevy entities carrying components like RigidBody and Collider.

### How do I install Avian in a Bevy project?

Add avian2d or avian3d to your dependencies in Cargo.toml, using version 0.7 for the current release, or a git dependency on the main branch for unreleased code. Then register PhysicsPlugins::default() alongside DefaultPlugins in your App.

### Which Bevy version does Avian 0.7 require?

The README's version table maps Bevy 0.19 to Avian 0.7. Earlier rows map Bevy 0.18 to Avian 0.5 through 0.6, Bevy 0.17 to 0.4, and Bevy 0.14 to 0.1.

### Does Avian support f64 precision?

Yes. f32 is the default, and f64 is available, but you must disable default features and select the dimension and precision manually, for example with the features "3d f64 parry-f64". The README states that parry-f64 enables collision detection under f64.

### What licence is Avian released under?

The repository is Apache-2.0, and the README badge indicates MIT/Apache 2.0, with LICENSE-APACHE and LICENSE-MIT present at the top level of the repository.

## Sources

- [avianphysics/avian on GitHub](https://github.com/avianphysics/avian)
- [License: Apache-2.0](https://github.com/avianphysics/avian/blob/main/LICENSE)
- [Project website](https://crates.io/crates/avian3d)
- [README](https://github.com/avianphysics/avian/blob/main/README.md)
- [Releases](https://github.com/avianphysics/avian/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/avianphysics-avian