NEOLearn

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.

Updated October 20, 2026

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#

WhatWhy
Rust (stable), installed with rustupThe engine and games are Rust. The engine core needs Rust 1.96 or newer.
gitTo get and update the engine source.
A GPU with Vulkan, Metal or DirectX 12For 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:

Shell
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 features

Linux libraries#

On Ubuntu and Debian:

Shell
sudo apt-get install g++ pkg-config libx11-dev libasound2-dev libudev-dev \
  libxkbcommon-x11-0 libwayland-dev libxkbcommon-dev libfontconfig1-dev

On Fedora:

Shell
sudo dnf install gcc-c++ libX11-devel alsa-lib-devel systemd-devel \
  wayland-devel libxkbcommon-devel fontconfig-devel

On Arch:

Shell
sudo pacman -S libx11 pkgconf alsa-lib libxcursor libxrandr libxi fontconfig
LibraryWhat uses it
ALSA (libasound2-dev)Audio output.
udev (libudev-dev)Gamepads.
X11, Wayland, xkbcommonWindows 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.

Shell
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:

Shell
cargo run --example hello_world
cargo run --example 3d_scene

The 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:

ProfileSettingsUse it for
devYour code at opt-level = 1, every dependency at opt-level = 3.Everyday work. The engine runs fast while your own crates still compile quickly.
releaseThin LTO, one codegen unit.Playing and measuring performance. make run uses it.
shippingrelease 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 check for 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_linking cargo feature builds the engine as a shared library, so changing your game relinks only your crate:

    Shell
    cargo run --features neo/dynamic_linking --bin my_game

    NEO'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:

Shell
cargo run --example 3d_scene

A window opens with a cube on a round base, lit by a point light. If it doesn't:

SymptomWhat to check
Link errors for asound, udev or xkbcommonThe Linux libraries above.
"No compositor" or no window on LinuxYou need a running X11 or Wayland session.
The window opens but stays black, or the GPU is rejectedUpdate your GPU driver. On Linux, check that Vulkan works (vulkaninfo).

Next steps#