diff --git a/rfcs/72-editor.md b/rfcs/72-editor.md new file mode 100644 index 00000000..c2085705 --- /dev/null +++ b/rfcs/72-editor.md @@ -0,0 +1,508 @@ +# Feature Name: `editor-foundation` + +## Summary + +This RFC outlines the foundation for Bevy's editor. It describes its basic +components and how they will interact with Bevy's engine. Following this RFC +will result in a minimum viable product for the Bevy Editor. + +This RFC does NOT cover the particular user interface (UI) design for the +editor. Instead, it provides the building blocks for a proper UI design, with a +minimal usable interface to place these components in context. + +## Motivation + +Unlike most major game engines, Bevy lacks an interactive editor. This has +three major downsides: + +1. it increases the barrier to entry for potential new developers; +2. this forces scene designers to learn to create scenes with code; and +3. developers must rebuild their project before seeing any changes they make. + +While teams can mitigate the last two points by creating project specific +tools, this does require them to divert resources building those tools that they +could have spent building the game. + +Bevy's plugin-heavy design poses several challenges to making a traditional +editor. Primarily, unlike other game engines, Bevy does limit developers access +to the core game loop, similar instead to many game frameworks. While an +interactive editor could be built on top of Bevy that takes away this freedom; +doing so violates the spirit of Bevy's plugin-heavy design, thus robbing it of +Bevy's expressive nature. + +**Bevy's editor must acknowledge the dual nature of Bevy as both a game engine +and a game framework.** + +A secondary, smaller challenge, is that Bevy relies on the Cargo build system +for modularity. An interactive-editor that is core to Bevy must both respect +this design, and work with the limitations and abilities of Cargo. + +## User-facing explanation + +The easiest way to get started with Bevy's editor by downloading it with Cargo: + +``` +$ cargo install bevy +``` + +*Note the use of `install`, not `add`!* This means Bevy's editor for your entire rust environment. In the future you may also be able to download it from external sources such as Steam. + +This will add `bevy` to our path: + +``` +$ bevy +Bevy's Command Line Tool + +Usage: bevy [OPTIONS] [COMMAND] + +... +``` + +This tool allows us to create new projects, manage assets, edit projects, and +even publish games. Note that `bevy` is not meant to replace `cargo`, but to +work alongside it. + +Also, just like Cargo, the Bevy library version used in a project does not need to match +the version of `bevy` you have installed. You can upgrade and downgrade them +independently. Therefore, we recommend you always use the latest version of the +`bevy` tool. + +Bevy's editor can be used graphically, or as a command line tool. This document +covers the command line usage, but running `bevy edit` in a project will open +the graphical view. + +**The `bevy` command line interface is not stable. Do not use it in build +scripts!** + +### Default Project Structure + +The first entry point for the `bevy` command is `new` and `init`, for creating +new projects, meant to mimic the commands in cargo: + +``` +bevy new [options] +``` + +As an example, let's create a new project, `flappers`: + +``` +$ bevy new flappers +``` + +This creates a new `flappers` folder in your current directory, using the +default template, similar to using `cargo new`. Unlike Cargo, however, a Bevy +project can start from any number of templates you can get from the Bevy asset +repository. + +Next, let's take a look at the project structure: + +``` +flappers/ + README.md + Cargo.toml + LICENSE-Apache2.txt + assets/ + ... + src/ + main.rs + tests/ + ... + target/ + ... + editor/ + Cargo.toml + src/ + main.rs + .git/ + ... + .github/ + workflows/ + ... +``` + +The default template provides a lot more than a standard new cargo project. Much +of this is not strictly required, but will be wanted for the average project. +Because this is mostly convention, feel free to change the layout as needed. The +first three files: `RREADME.md`, `Cargo.toml`, and `LICENSE-Apache2.txt` are +standard meta-information that are in most crates. The next folder: `assets` is +the default location to place project non-code assets. The bulk of the source +code goes in the `src` directory, likewise tests go in `tests`. Project builds +go into the `target` directory. + +The `editor` directory provides a sub-crate for the Bevy editor. Associating +Bevy's editor with the project allows you to have multiple projects using +different versions of Bevy in the same environment. The `bevy` command line tool +delegates to this editor for any project specific actions. It also has the side +benefit of allowing you to more heavily tune the editor for your specific game +while still having access to the full suite of tools Bevy provides. + +The final directories are for version control management and game publishing. + +### Bevy Assets + +The main repository for Bevy assets can be found on [the bevy webpage][asset-page] + +Assets can be added to your project through the `bevy` tool: + +``` +bevy assets add +``` + +Likewise, you can remove the asset with: + +``` +bevy assets remove +``` + +In general, assets come in three varieties: *code*, *data*, and *template*. Code +assets are little more than Cargo crates, many can even be installed with the +`cargo` command. + +Data assets are overlaid onto the existing project, and usually go into the +`assets` directory. Frequently these assets are large, should not be added to +the repository directly, or should be loaded at build time from an external +source. Therefore, in addition to copying the assets into the project, data +assets can also be references to an asset at an external location. **Note that +while referenced asses can be removed from the project, copied data assets can +not!** + +Finally, template assets are not added to a project, but are instead used by the +`bevy` tool to start new projects. The `-t` flag is used to pick a project +template: + +``` +bevy new -t