NEOLearn

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.

Updated October 20, 2026

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:

Text
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, plugins

Make a project from the command line:

Shell
cargo xtask new arena                  # projects/arena from the Starter template
cargo xtask new arena --dry-run        # list the files it would write

The crates#

Text
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
FileWhat it does
main.rsBuilds and runs the app. In a browser it waits for the page's Play click first.
app.rsYour game as one Plugin (ArenaGamePlugin), plus run(), which makes the standalone app: the platform, the window, the default plugins and the content layers.
plugin.rsRegisters 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.rsThe level the game plays.
paths.rsThe project folder, its assets/ and the template content it reads.
Cargo.tomlThe 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:

crates/arena_game/src/app.rs
impl Plugin for ArenaGamePlugin {
    fn build(&self, app: &mut App) {
        // ...what the template set up...
        app.add_plugins(ScorePlugin);
    }
}
crates/arena_game/src/score.rs
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:

WhatHow
ContentThe asset server reads the project's assets/ over the template's content, in development and in packaged builds.
GraphicsFalls back to another graphics API if the preferred one has no GPU, and finds the DirectX shader compiler next to the game on Windows.
ThreadsGives render pipeline compilation every core but one, so the first frame comes sooner.
Window1600×900 on the desktop, full screen on phones and tablets, the page's canvas in a browser.
WebSkips 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#

ToRun
Play the gamecargo run --release --bin arena
Open the Studio on itcargo run --release --bin arena_editor
Package itcargo xtask package --game arena (add --target web, ios or android for other platforms)

Next steps#