Getting Started

This page covers the basic setup needed for Bevy development.

Also see the Setup page in the official Bevy Book and the official Bevy Readme.

Prerequisites

For the most part, Bevy is just like any other Rust library. You need to install Rust and setup your dev environment just like for any other Rust project. You can install Rust using Rustup. See Rust's official setup page. You also need various other dependencies, depending on your operating system.

If you are interested in mobile development, check out the pages on Android and iOS.

If you are interested in web development, check out the WASM chapter.

Creating a New Project

You can simply create a new Rust project, either from your IDE/editor, or the commandline:

cargo new --bin my_game

(creates a project called my_game)

The Cargo.toml file contains all the configuration of your project. Add the latest version of bevy as a dependency.

cargo add bevy --features wayland

(I recommend enabling the non-default wayland feature, so your game can better support modern Linux distros)

You can also add other optional features to bevy, if you'd like.

Your Cargo.toml should now look something like this:

[package]
name = "my_game"
version = "0.1.0"
edition = "2021"

[dependencies]
bevy = { version = "0.16", features = ["wayland"] }

If you plan to customize bevy a lot, I recommend a dedicated dependency section. It makes everything easier to read, compared to having everything on one line.

[dependencies.bevy]
version = "0.16"
features = [
  "wayland",
  # ...
]

The src/main.rs file is your main source code file. This is where you start writing your Rust code. For a minimal Bevy app, you need at least the following:

use bevy::prelude::*;

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

You can now compile and run your project. The first time, this will take a while, as it needs to build the whole Bevy engine and dependencies. Subsequent runs should be fast. You can do this from your IDE/editor, or the commandline:

cargo run

While this is enough to get you started, there are many tweaks you can do to your compiler / build toolchain configuration, for faster compile times and better performance. At the very least, consider enabling optimizations.

Documentation

You can generate your own docs (like what is on docs.rs), for offline use, including everything from your own project and all dependencies, all in one place.

cargo doc --open

This will build all the HTML docs and open them in your web browser.

It does not require an internet connection, and gives you an easy way to search the API docs for all crates in your dependency tree all at once. It is more useful than the online version of the docs.

What's Next?

Have a look at the guided tutorial page of this book and Bevy's official examples.

Check out the Bevy Assets Website to find other tutorials, learning resources from the community, and plugins to use in your project.

Join the community on Discord to chat with us!

Running into Issues?

If something is not working, be sure to check the Common Pitfalls chapter, to see if this book has something to help you. Solutions to some of the most common issues that Bevy community members have encountered are documented there.

If you need help, use GitHub Discussions, or feel welcome to come chat and ask for help in Discord.

GPU Drivers

To work at its best, Bevy needs DirectX 12 (Windows) or Vulkan (Linux, Android, Windows). macOS/iOS should just work, without any special driver setup, using Metal.

OpenGL (GLES3) can be used as a fallback, but will likely have issues (some bugs, unsupported features, worse performance).

Make sure you have compatible hardware and drivers installed on your system. Your users will also need to satisfy this requirement.

If Bevy is not working, install the latest drivers for your OS, or check with your Linux distribution whether Vulkan needs additional packages to be installed.

Web games are supported and should work in any modern browser, using WebGL2. Performance is limited and some Bevy features will not work. The new experimental high-performance WebGPU API is also supported, but browser adoption is still limited.