Getting started

Setting up Rust

We recommend using rustup to easily install the latest stable version of rust. Instructions should be on the screen once rustup is downloaded.

Updating Rust: If you already have Rust installed, make sure you're using the the latest version by running rustup update.

We recommend using the stable version of Rust, as Rust nightlies tend to break rather often.

Using the stable toolchain: Rustup can be configured to default to the stable toolchain by running rustup default stable.

Required dependencies

Please check the dependencies section of the for details on what dependencies are required for compiling Amethyst.

Please note that you need to have a functional graphics driver installed. If you get a panic about the renderer unable to create the rendering context when trying to run an example, a faulty driver installation could be the issue.

Setting up an Amethyst Project

You can either use our Starter Projects or do it the manual way.

Creating a Project the manual way.

  • Add amethyst as a dependency in your Cargo.toml.
  • Create a config folder and put a display.ron in it.
  • (Optional) Copy the code from one of the amethyst's examples.

Starter Project

If you want to get running as quickly as possible and start playing around with Amethyst, you can also use a starter project. These are specifically made for certain types of games and will set you up with the groundwork needed to start right away.
The file on these will include everything you need to know to run the starter project.

Note: Right now, the only starter available is for 2D games. This will expand over time, and offer more options for different types of games.

Important note on versioning

Amethyst is divided into two major versions:

  • The released version, which is the latest version available on
  • The git (master) version, which is the current unreleased development snapshot of Amethyst available on Github

Note: You can see which version you're currently looking at by checking the URL in your browser. The book/documentation for master contains "master" in the address, the version is called "stable".

Depending on the book version that you choose to read, make sure that the amethyst version in your Cargo.toml matches that.

For the released version, you should have something like this:


The latest version can be found here.

If you want to use the latest unreleased changes, your Cargo.toml file should look like this:

amethyst = { git = "", rev = "COMMIT_HASH" }

The commit hash part is optional. It indicates which specific commit your project uses, to prevent unexpected breakage when we make changes to the git version.