Introduction

Hey, so you're interested in contributing to Bevy! Feel free to pitch in on whatever interests you and we'll be happy to help you contribute.

If you're new here, you should check out our community's Code of Conduct. You can also come say hi 👋 to us on Discord. It's a nice place to chat about Bevy development, ask questions, and get to know the other contributors and users in a less formal setting.

Read on if you're looking for:

• The high-level design goals of Bevy.
• Conventions and informal practices we follow when developing Bevy.
• General advice on good open source collaboration practices.
• Concrete ways you can help us, no matter your background or skill level.

We're thrilled to have you along as we build!

What We're Trying to Build

Bevy is a completely free and open source game engine built in Rust. It currently has the following design goals:

• Capable: Offer a complete 2D and 3D feature set.
• Simple: Easy for newbies to pick up, but infinitely flexible for power users.
• Data Focused: Data-oriented architecture using the Entity Component System paradigm.
• Modular: Use only what you need. Replace what you don't like.
• Fast: App logic should run quickly, and when possible, in parallel.
• Productive: Changes should compile quickly... waiting isn't fun.

Bevy also currently has the following "development process" goals:

• Rapid experimentation over API stability: We need the freedom to experiment and iterate in order to build the best engine we can. This will change over time as APIs prove their staying power.
• Consistent vision: The engine needs to feel consistent and cohesive. This takes precedence over democratic and/or decentralized processes. See our page on The Bevy Organization for more details.
• Flexibility over bureaucracy: Developers should feel productive and unencumbered by development processes.
• Focus: The Bevy Org should focus on building a small number of features excellently over merging every new community-contributed feature quickly. Sometimes this means pull requests will sit unmerged for a long time. This is the price of focus and we are willing to pay it. Fortunately Bevy is modular to its core. 3rd party plugins are a great way to work around this policy.
• User-facing API ergonomics come first: Solid user experience should receive significant focus and investment. It should rarely be compromised in the interest of internal implementation details.
• Modularity over deep integration: Individual crates and features should be "pluggable" whenever possible. Don't tie crates, features, or types together that don't need to be.
• Don't merge everything... don't merge too early: Every feature we add increases maintenance burden and compile times. Only merge features that are "generally" useful. Don't merge major changes or new features unless we have relative consensus that the design is correct and that we have the developer capacity to support it. When possible, make a 3rd party plugin / crate first, then consider merging once the API has been tested in the wild. Bevy's modular structure means that the only difference between "official engine features" and "third party plugins" is our endorsement and the repository the code lives in. We should take advantage of that whenever possible.
• Control and consistency over 3rd party code reuse: Only add a dependency if it is absolutely necessary. Every dependency we add decreases our autonomy and consistency. Dependencies also have the potential to increase compile times and risk pulling in sub-dependencies we don't want / need.
• Don't re-invent every wheel: As a counter to the previous point, don't re-invent everything at all costs. If there is a crate in the Rust ecosystem that is the "de-facto" standard (ex: wgpu or winit), we should heavily consider using it. Bevy should be a positive force in the ecosystem. We should drive the improvements we need into these core ecosystem crates.
• Rust-first: Engine and user-facing code should optimize and encourage Rust-only workflows. Adding additional languages increases internal complexity, fractures the Bevy ecosystem, and makes it harder for users to understand the engine. Never compromise a Rust interface in the interest of compatibility with other languages.
• Thoughtful public interfaces over maximal configurability: Symbols and APIs should be private by default. Every public API should be thoughtfully, and consistently, designed. Don't expose unnecessary internal implementation details. Don't allow users to "shoot themselves in the foot", instead favor one "happy path" API over multiple APIs for different use cases.
• Test what you need to: Write useful tests. Don't write tests that aren't useful. We generally aren't strict about unit testing every line of code. We don't want you to waste your time. But at the same time:
  • Most new features should have at least one minimal example. These also serve as simple integration tests, as they are run as part of our CI process.
  • The more complex, or "core", a feature is, the more strict we are about unit tests. Use your best judgement here, and we will let you know if your pull request needs more tests.
  • We use Rust's built in testing framework.
• Welcome new contributors: Invest in new contributors. Help them fill knowledge and skill gaps. Don't ever gatekeep Bevy development according to notions of required skills or credentials. Help new developers find their niche.
• Civil discourse: We need to collectively discuss ideas, and the best ideas should win, but conversations need to remain respectful at all times. Remember that we're all in this together, and to always follow our Code of Conduct.

Getting Oriented

The Bevy Organization expands a little bit beyond just the Bevy engine, which by itself is a large project! It can be a bit overwhelming to start, so here's the bird's-eye view:

The GitHub organization has 2 primary repositories:

1. bevy: This is where the engine itself lives. The bulk of development work occurs here.
2. bevy-website: This is where the official website is hosted, along with the quick start, news, contributing book, live examples and other bits of polished content we want to show our users.

The bevy repository itself contains many smaller subcrates. Several of them can be used by themselves and almost all of them can be modularly replaced. Feel free to dig around and find one that interests you!