Bevy CLI MVP

A Bevy CLI is a long-outstanding feature request, with even more discussion and analysis. Let's start building it!

Rather than being a single-purpose tool to accomplish a specific task, the vision is to create a single CLI entry point for tasks that best fit the CLI format.

Under the hood, the editor can then call the CLI for many of its tasks, avoiding duplication of effort and providing a mechanism for basic automation.

So what might it do?

A number of ideas for functionality that would fit well in the Bevy CLI have been floated:

  • project generation from a template
  • creating final builds for specific platforms
  • command-line driven asset preprocessing
  • automated upgrades
  • checks for known problems in environment configuration
  • single method call CI checks
  • runs Bevy-specific lints (see the design document)

How do we build it?

Requirements:

  • not required to get started with Bevy: cargo alone should work fine to get to Hello World
  • written in Rust

Hunches:

  • built using the clap crate
  • distributed using cargo as a binary extension
  • leverage cargo-generate for templates

Planning the work

Templates are the most important requirement here: useful for game jams, editor starter projects and tutorials. We should tackle this first, as it lays out a foundation while being relatively straightforward.

We should start this in the BevyFlock community organization, and then transfer the repository to the bevyengine organization once the initial architecture has been blessed.

We should follow the same structural rules as the editor here:

  • lives in a seperate repository under the Bevy org
  • maintainers have merge rights
  • depends on the latest Bevy release
  • updated to the new Bevy release during the release candidate process
  • can pull in 3rd party Bevy dependencies, but only cautiously and with consent from the crate authors

Once it's adopted, CLI-powered asset preprocesing is the next most important need: Bevy doesn't have any good alternative right now.

Prior Art

About the prototype (release 0.1.0)

The prototype as of release 0.1.0 supports the following features:

  • Bevy project generation from templates
  • Out-of-the-box support for building and running Bevy apps in the browser
  • A Bevy-specific linter

Project scaffolding

The bevy new command lets you easily scaffold a new Bevy project using a custom template or a minimal template provided by Bevy. Templates are just GitHub repositories and can be specified with the -t flag.

If the template is omitted, the default minimal template will be chosen.

bevy new my-project

To use a specific template, provide the full GitHub URL

bevy new my-project -t https://github.com/TheBevyFlock/bevy_new_2d

Additionally, any repo prefixed with bevy_new_ from the TheBevyFlock will be usable via its shortcut form i.e. -t 2d will use the template bevy_new_2d.

bevy new my-project -t 2d

Bevy web apps

The CLI makes it easy to build and run web apps made with Bevy, using bevy build web and bevy run web. It takes care of compiling the app to Wasm, creating JavaScript bindings and serving it on a local web server to test it out. Necessary tools will also be installed automatically. For more information see the Bevy Web Initiative HackMD

Linter

The CLI has 1st-party support for bevy_lint. It must be installed first using the installation guide, but then you can run the linter with the lint subcommand:

bevy lint

This command uses the same arguments as cargo check:

bevy lint --workspace --all-features

You can view a full list of supported options with:

bevy lint -- --help
Select a repo