Project layout
How a NEO project's Rust code is organised, what each file of the game crate does, where content lives, and where your own systems and plugins go.
On this page
A NEO project is a folder with a neo.toml, an assets/ folder and a crates/ folder of Rust crates. This page is about the Rust side: which crate is which, what each file does and where your code goes. For the project as a whole (the files the Studio writes, the templates and how to make a project), see Projects and templates.
The engine workspace#
Projects live inside the engine source's Cargo workspace, so every project builds against the same engine. The engine core itself (the neo crate and its examples) is a separate Cargo workspace inside the same source tree, which the crates below depend on by path:
NEO/
├── engine/ NEO's engine crates: gameplay kit, character, camera, input, audio, scripting, saves…
├── editor/ the Studio's crates (never shipped in a game)
├── samples/ the sample projects, including the Starter template
├── projects/ your projects (cargo xtask new, or New Project… in the Studio)
└── tools/xtask cargo xtask: new, package, serve, pluginsMake a project from the command line:
cargo xtask new arena # projects/arena from the Starter template
cargo xtask new arena --dry-run # list the files it would writeThe crates#
projects/arena/
├── neo.toml
├── assets/
└── crates/
├── arena_game/ the game: a library and the `arena` binary
│ ├── Cargo.toml
│ └── src/
│ ├── main.rs the standalone game's entry point
│ ├── lib.rs the crate root
│ ├── app.rs the game plugin and the standalone app
│ ├── plugin.rs the plugin registration and the binary's plugin set
│ ├── paths.rs where the project's files are in the source tree
│ └── level.rs the level
└── arena_editor/ the Studio with this game built in: the `arena_editor` binary| File | What it does |
|---|---|
main.rs | Builds and runs the app. In a browser it waits for the page's Play click first. |
app.rs | Your game as one Plugin (ArenaGamePlugin), plus run(), which makes the standalone app: the platform, the window, the default plugins and the content layers. |
plugin.rs | Registers the game plugin with NEO's plugin system and compiles neo.toml into the game. It also refuses to link editor-only plugins into the game. |
level.rs | The level the game plays. |
paths.rs | The project folder, its assets/ and the template content it reads. |
Cargo.toml | The crate's dependencies, plus [package.metadata.neo.game] (name, identifier, content, web preload list) and the plugin descriptor. |
The editor crate embeds the same game plugin in the Studio, so what you play in the Studio is the game you ship.
Where your code goes#
Put your gameplay in plugins and add them from the game plugin's build:
impl Plugin for ArenaGamePlugin {
fn build(&self, app: &mut App) {
// ...what the template set up...
app.add_plugins(ScorePlugin);
}
}use neo::prelude::*;
pub struct ScorePlugin;
impl Plugin for ScorePlugin {
fn build(&self, app: &mut App) {
app.init_resource::<Score>()
.add_systems(Update, count_points);
}
}
#[derive(Resource, Default)]
pub struct Score(pub u32);
fn count_points(mut score: ResMut<Score>) {
// ...
}Add mod score; (or pub mod score;) to lib.rs. Because both the standalone binary and the Studio use the game plugin, your systems run in both.
To make a piece switchable on and off from neo.toml and the Studio's Plugins panel, give it a descriptor and register it as a NEO plugin. See Plugins and neo.toml.
The app a NEO game builds#
A plain engine app uses App::new().add_plugins(DefaultPlugins). A NEO game builds its app with neo_gameplay_kit::app instead, which sets up DefaultPlugins the way games need on every platform:
| What | How |
|---|---|
| Content | The asset server reads the project's assets/ over the template's content, in development and in packaged builds. |
| Graphics | Falls back to another graphics API if the preferred one has no GPU, and finds the DirectX shader compiler next to the game on Windows. |
| Threads | Gives render pipeline compilation every core but one, so the first frame comes sooner. |
| Window | 1600×900 on the desktop, full screen on phones and tablets, the page's canvas in a browser. |
| Web | Skips the asset server's .meta file requests in a browser. |
The platform is detected first with neo_device::detect. See Gameplay kit.
Content#
The game's files are in assets/. A path you load, such as asset_server.load("models/crate.glb"), is relative to it. Your project's assets/ sits over the template's content: a file at the same path in your folder replaces the template's. See Asset sources.
Code never reads files with std::fs directly: that wouldn't work in a browser or on a console. Load content through the asset server, or through the platform layer for files a loader opens itself.
Build and run#
| To | Run |
|---|---|
| Play the game | cargo run --release --bin arena |
| Open the Studio on it | cargo run --release --bin arena_editor |
| Package it | cargo xtask package --game arena (add --target web, ios or android for other platforms) |