Installing

The easiest way to install Ambient is to download the latest binary release from the GitHub releases. Currently, there are builds for Windows x64, Linux x64, and Mac ARM64. For other platforms, use the installing from Git method.

You will also need Rust installed with the wasm32-wasi toolchain so that you can compile Ambient modules. Note that Ambient compiles Rust code with stable Rust, so you must make sure that wasm32-wasi is installed for stable:

rustup target add --toolchain stable wasm32-wasi

Installing from Git

Ambient can be installed through cargo install, which will download and build the repository. Our current minimum supported Rust version is 1.67.0, as we use recently-stabilised standard library features.

To install the latest released version from Git, run the following:

cargo install --git https://github.com/AmbientRun/Ambient.git --tag v0.3.0-dev ambient

To install the latest version on the main branch, run the following:

cargo install --git https://github.com/AmbientRun/Ambient.git ambient

Note that if you are running a project outside of the guest/rust workspace, it is likely that the published version of the API will be incompatible with main, and you will need to specify the dependency manually.

Optional features

You can supply these feature flags to get optional features that are disabled by default, e.g. cargo install --git https://github.com/AmbientRun/Ambient.git ambient --features assimp

assimp: This adds support for assimp, which loads ~40 additional model file formats, such as .obj, text based fbx and much more

Build dependencies: Linux/Ubuntu

For the above to work on Linux, you also need to install the following build dependencies:

apt-get install -y \
    build-essential cmake pkg-config \
    libfontconfig1-dev clang libasound2-dev ninja-build

Installing via asdf (Linux, Macos)

Thanks to @jtakakura, Ambient can also be installed using asdf by running asdf plugin add ambient. For more details, visit https://github.com/jtakakura/asdf-ambient.

Running on headless Linux/Ubuntu

To run on a headless Linux machine, install the following dependencies in addition to the dependencies specified above:

add-apt-repository ppa:oibaf/graphics-drivers -y
apt-get update
apt install -y libxcb-xfixes0-dev mesa-vulkan-drivers

Ambient currently assumes that you have access to GPU drivers (but not necessarily a GPU) in headless mode. This requirement may be relaxed in future.

Dockerfile

A Dockerfile is also provided that provides a headless Debian environment with all of the dependencies required to run Ambient as a server. This Dockerfile is intended for development, not production, so it has more dependencies than are strictly required to run Ambient.

To build the Dockerfile:

docker build -t ambient .

To run the Dockerfile with bash in the current directory:

docker run --rm -it -e bash -v "$(pwd)":/app ambient

Ambient Documentation