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.
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().
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#
| Method | What 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:
| Schedule | When | What usually goes there |
|---|---|---|
PreStartup, Startup, PostStartup | Once, on the first update | Spawning the initial scene, loading assets. |
First | Every update, first | Time is updated here. |
PreUpdate | Every update | Engine work that has to happen before game logic, such as reading input. |
RunFixedMainLoop | Every update | Runs the fixed-step schedules (FixedUpdate and its neighbours) zero or more times. See Fixed timestep. |
Update | Every update | Most game logic. |
SpawnScene | Every update | Scenes queued for spawning are spawned. |
PostUpdate | Every update | Engine work after game logic: transform propagation, visibility, UI layout. |
Last | Every update, last | Clean-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.
| Runner | Added by | What it does |
|---|---|---|
| The default | App::new() | Updates once and returns. |
| The window event loop | WinitPlugin, in DefaultPlugins | Updates every frame while windows are open, following the window's update mode. |
ScheduleRunnerPlugin | MinimalPlugins, or DefaultPlugins without windowing | Runs once (run_once()) or in a loop (run_loop(wait)), with no window. |
| Your own | set_runner(f) | Anything: a test harness, a tool reading from stdin. |
A custom runner finishes building the plugins, then calls update() as it likes:
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:
fn quit_on_escape(keys: Res<ButtonInput<KeyCode>>, mut exit: MessageWriter<AppExit>) {
if keys.just_pressed(KeyCode::Escape) {
exit.write(AppExit::Success);
}
}| Value | Meaning |
|---|---|
AppExit::Success | A 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.
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.