NEOLearn

The App

How a NEO App holds the world and runs the main loop, the order of the main schedules, runners, exiting with AppExit, headless apps and sub-apps.

Updated October 20, 2026

On this page

An App is a NEO program. It owns the ECS World, the schedules of systems that run on it, and a runner that decides when to update. You build it up with plugins, systems and resources, then call run().

src/main.rs
use neo::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .insert_resource(ClearColor(Color::BLACK))
        .add_systems(Startup, setup)
        .add_systems(Update, (move_player, update_score))
        .run();
}

Building an app#

MethodWhat it does
add_plugins(p)Adds a plugin, a plugin group or a tuple of them. See Plugins.
add_systems(schedule, systems)Adds systems to a schedule such as Startup, Update or FixedUpdate.
insert_resource(r), init_resource::<R>()Adds a resource, either a value or one made with Default or FromWorld.
add_message::<M>()Registers a buffered message type. See Messages.
add_observer(o)Adds a global observer. See Observers.
configure_sets(schedule, sets)Orders and configures system sets. See System ordering.
init_state::<S>()Adds a state machine. See States.
register_type::<T>()Registers a type for reflection. Most types register themselves.
world(), world_mut()Direct access to the world, for setup that needs it.
set_runner(f)Replaces the runner (below).

The main schedule#

Each update, the app runs the Main schedule, which runs the other schedules in this order:

ScheduleWhenWhat usually goes there
PreStartup, Startup, PostStartupOnce, on the first updateSpawning the initial scene, loading assets.
FirstEvery update, firstTime is updated here.
PreUpdateEvery updateEngine work that has to happen before game logic, such as reading input.
RunFixedMainLoopEvery updateRuns the fixed-step schedules (FixedUpdate and its neighbours) zero or more times. See Fixed timestep.
UpdateEvery updateMost game logic.
SpawnSceneEvery updateScenes queued for spawning are spawned.
PostUpdateEvery updateEngine work after game logic: transform propagation, visibility, UI layout.
LastEvery update, lastClean-up, exiting when windows close.

Rendering doesn't happen in these schedules. After the main world updates, the renderer copies what it needs and draws, on desktop builds in parallel with the next update. You can add your own schedules to this order; see Schedules.

Runners#

The runner owns the loop. run() hands the app to it.

RunnerAdded byWhat it does
The defaultApp::new()Updates once and returns.
The window event loopWinitPlugin, in DefaultPluginsUpdates every frame while windows are open, following the window's update mode.
ScheduleRunnerPluginMinimalPlugins, or DefaultPlugins without windowingRuns once (run_once()) or in a loop (run_loop(wait)), with no window.
Your ownset_runner(f)Anything: a test harness, a tool reading from stdin.

A custom runner finishes building the plugins, then calls update() as it likes:

Rust
use neo::{app::AppExit, prelude::*};

fn my_runner(mut app: App) -> AppExit {
    app.finish();
    app.cleanup();
    for _ in 0..100 {
        app.update();
        if let Some(exit) = app.should_exit() {
            return exit;
        }
    }
    AppExit::Success
}

fn main() -> AppExit {
    App::new().set_runner(my_runner).add_systems(Update, tick).run()
}

Example: cargo run --example custom_loop.

Exiting#

A system ends the app by writing the AppExit message:

Rust
fn quit_on_escape(keys: Res<ButtonInput<KeyCode>>, mut exit: MessageWriter<AppExit>) {
    if keys.just_pressed(KeyCode::Escape) {
        exit.write(AppExit::Success);
    }
}
ValueMeaning
AppExit::SuccessA normal exit.
AppExit::Error(code)An error, with a non-zero exit code. AppExit::error() uses code 1.

run() returns the AppExit, and main can return it as the process's exit status. Closing the last window also exits, unless you change WindowPlugin::exit_condition.

Headless apps#

An app with no window, such as a server or a command-line tool, uses MinimalPlugins: task pools, frame counting, time and a schedule runner.

src/main.rs
use core::time::Duration;
use neo::{app::ScheduleRunnerPlugin, prelude::*};

fn main() {
    App::new()
        .add_plugins(MinimalPlugins.set(ScheduleRunnerPlugin::run_loop(
            Duration::from_secs_f64(1.0 / 60.0),
        )))
        .add_systems(Update, counter)
        .run();
}

fn counter(mut count: Local<u32>) {
    *count += 1;
}

To leave the renderer and windowing out of the build entirely, depend on neo with default-features = false and only the features you need; see Cargo features. With windowing compiled out, DefaultPlugins uses ScheduleRunnerPlugin instead of a window.

Examples: cargo run --example headless --no-default-features --features neo_log, cargo run --example no_renderer, cargo run --example headless_renderer (renders to image files with no window).

Sub-apps#

A sub-app is a second world with its own schedules, updated after the main world. The renderer is one: RenderApp holds the GPU-side copy of the scene, filled each frame by an extract step. You rarely touch sub-apps unless you write rendering code; see Custom materials.

Next steps#