Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Start here

This handbook is for whoever works on Rusteal itself: its crates, its CLI, its Unreal Engine plugins, its templates and its release. It is meant to be enough on its own: everything a developer new to the project needs to understand it, change it and release it, and the reasons behind how it is built. Using Rusteal to make a game is the other handbook’s subject, the game developer’s handbook; read its first chapters too, since you will test every change the way a game developer uses it.

A reading order

DayReadSo that you can
1Introduction, The repository, GlossaryName the pieces and find them.
1Setting up a checkoutBuild the workspace and a test project on your machine.
2Architecture, The Rust–C++ boundaryFollow a call from Rust to the engine and back.
2Reification and the macros, Types declared in RustFollow a #[uclass] from the macro to a class in the editor.
3Code generation, The CLIFollow rusteal build step by step.
3The runtime, Errors, Hot reloadKnow what the runtime offers and how a reload works.
4Testing a change, Common tasks, Known issues and sharp edgesMake a change and prove it works.
4DecisionsKnow why things are as they are before changing them.
5Templates, Releases and versionsPort a template, ship a release.

A first change, end to end

  1. Set up the checkout and make a test project from it (cargo run -p rusteal -- new Probe --dir <dir> --runtime-path .), as Setting up a checkout and Testing a change describe.
  2. Open the project, place a HelloActor, press Play: the Output Log shows the greeting from Rust.
  3. Change HelloActor’s message in the test project’s crate, run cargo run -p rusteal -- watch <project> from the checkout, save: the editor reloads the library by itself (see Hot reload).
  4. Change something in Rusteal: a new ulog! line in rusteal-runtime’s init, say. cargo run -p rusteal -- build <project> rebuilds the game’s library against your checkout; the reload shows your line.
  5. Change the C++ plugin: cargo run -p rusteal -- setup <project>, then build --all, and restart the editor.
  6. Run cargo test --workspace and cargo clippy --workspace --all-targets -- -D warnings, commit with a Conventional Commits subject on a branch made from develop, and open a pull request to develop (see The repository).

Rules that are not negotiable

  • Game code is safe, idiomatic Rust: a feature is done only when a game developer can use it without unsafe and without raw handles, in plain Rust; game and plugin crates start with #![deny(unsafe_code)] (see Decisions, I7).
  • Commits: Conventional Commits subjects (the release computes the version from them), small commits, everything in English. See Tracking documents and conventions.
  • The boundary: a change to the API table is made on both sides at once, in the same order (see The Rust–C++ boundary).
  • Versions: never edit a version number by hand; the release writes them (see Releases and versions).
  • The CI skip marker: never write it in a commit message or a pull request, not even to talk about it.
  • Documentation: a change a game developer sees updates the game developer’s handbook; a change to how Rusteal works, or a decision, updates this one (Decisions).