Set up the engine
Install Rust and the system libraries the NEO engine needs, get the engine source building, and make compiles faster while you work.
On this page
NEO games are Rust programs built on the neo crate. To write Rust game code you need a Rust toolchain, a few system libraries on Linux, and the engine source. The desktop Studio builds projects with the same toolchain, so once this works, the Studio's Build mode works too.
You don't need any of this to make a game with scripts in the browser Studio. See Rust code and scripts for which kind of code does what.
What you need#
| What | Why |
|---|---|
Rust (stable), installed with rustup | The engine and games are Rust. The engine core needs Rust 1.96 or newer. |
git | To get and update the engine source. |
| A GPU with Vulkan, Metal or DirectX 12 | For rendering. If the preferred graphics API has no usable GPU, NEO's games try the other APIs built in before giving up. |
| The system libraries below (Linux only) | Audio, input devices, windowing and fonts. |
Install Rust:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update stable
rustup component add rust-analyzer # optional: for the Studio's Rust language featuresLinux libraries#
On Ubuntu and Debian:
sudo apt-get install g++ pkg-config libx11-dev libasound2-dev libudev-dev \
libxkbcommon-x11-0 libwayland-dev libxkbcommon-dev libfontconfig1-devOn Fedora:
sudo dnf install gcc-c++ libX11-devel alsa-lib-devel systemd-devel \
wayland-devel libxkbcommon-devel fontconfig-develOn Arch:
sudo pacman -S libx11 pkgconf alsa-lib libxcursor libxrandr libxi fontconfig| Library | What uses it |
|---|---|
ALSA (libasound2-dev) | Audio output. |
udev (libudev-dev) | Gamepads. |
| X11, Wayland, xkbcommon | Windows and the keyboard. NEO builds support both X11 and Wayland. |
fontconfig (libfontconfig1-dev) | Finding the system's fonts. NEO's games turn on system font discovery. |
macOS needs only the Xcode command-line tools (xcode-select --install). Windows needs the Visual Studio C++ build tools that rustup asks for.
Build the engine source#
The engine source is one Cargo workspace: the NEO engine core, NEO's engine crates, the editor, the samples and the tools. It has a Makefile with the common commands.
make help # every command
make run # the Starter sample as a standalone game
make editor # the desktop Studio on the Starter sample
make web # the Starter sample in the browser (prints the link)The first build compiles every dependency and takes a while. Later builds only compile what changed.
The engine core (the neo crate) is a Cargo workspace of its own inside the engine source, and that is where its examples live. From its folder, the one that holds the neo crate's Cargo.toml:
cargo run --example hello_world
cargo run --example 3d_sceneThe Examples section lists every example and what it shows.
Build profiles#
The workspace's Cargo.toml sets these profiles, and your project's crates inherit them:
| Profile | Settings | Use it for |
|---|---|---|
dev | Your code at opt-level = 1, every dependency at opt-level = 3. | Everyday work. The engine runs fast while your own crates still compile quickly. |
release | Thin LTO, one codegen unit. | Playing and measuring performance. make run uses it. |
shipping | release without symbols or debug info. | Packaged builds: cargo xtask package --profile shipping. |
Faster compiles#
Most of a rebuild's time goes to linking. These help, from the simplest:
Keep
cargo checkfor quick feedback. It skips code generation. rust-analyzer in the Studio runs it for you.Use a faster linker. LLD (Windows, and the default on Linux) and mold (Linux) are faster than the system default. On macOS the default linker is already the fastest.
Dynamic linking. The
dynamic_linkingcargo feature builds the engine as a shared library, so changing your game relinks only your crate:Shellcargo run --features neo/dynamic_linking --bin my_gameNEO's builds don't turn it on, and it isn't for packaged, web or mobile builds: use it only for local runs.
Check that it works#
From the engine core's folder:
cargo run --example 3d_sceneA window opens with a cube on a round base, lit by a point light. If it doesn't:
| Symptom | What to check |
|---|---|
Link errors for asound, udev or xkbcommon | The Linux libraries above. |
| "No compositor" or no window on Linux | You need a running X11 or Wayland session. |
| The window opens but stays black, or the GPU is rejected | Update your GPU driver. On Linux, check that Vulkan works (vulkaninfo). |