NEOLearn

ECS

The entity component system at the heart of the NEO engine. Entities, components, systems, resources, schedules, events and states, and how they fit together.

Updated October 20, 2026

On this page

Everything a NEO game does runs on the engine's entity component system (ECS). Game objects are entities, their data is components, and the logic that reads and changes that data is systems. The engine itself is built the same way: transforms, rendering, input, audio and UI are all components and systems.

This section explains each part of the ECS and how they fit together. If you're new to it, read the pages in order.

The model in one example#

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

// A component: plain Rust data attached to an entity.
#[derive(Component)]
struct Velocity(Vec3);

// A system: a plain Rust function. Its parameters say what data it needs.
fn movement(time: Res<Time>, mut query: Query<(&mut Transform, &Velocity)>) {
    for (mut transform, velocity) in &mut query {
        transform.translation += velocity.0 * time.delta_secs();
    }
}

fn setup(mut commands: Commands) {
    // An entity: an id with a set of components.
    commands.spawn((Transform::default(), Velocity(Vec3::X)));
}

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, setup)
        .add_systems(Update, movement)
        .run();
}

The parts#

PartWhat it isPage
WorldHolds every entity, component and resource. There is one per app (plus one for rendering).Entities
EntityA unique id. It has no data of its own; its components are its data.Entities
ComponentA Rust struct or enum stored on an entity.Components
SystemA function that runs on the world. The engine reads its parameters to give it data and to run systems in parallel.Systems
QueryA system parameter that iterates the entities that have a set of components.Queries
ResourceA single global value, identified by its type: time, settings, asset collections.Resources
CommandsQueued changes to the world (spawn, despawn, insert, remove) applied at a safe point.Commands
MessagesBuffered values that systems write and other systems read later in the frame.Messages
Events and observersValues that run their observers immediately when triggered.Events and observers
ScheduleA collection of systems that runs together: Startup, Update, FixedUpdate and others.Schedules
PluginA bundle of systems, resources and settings that you add to an app in one call.Plugins

Pages in this section#

PageWhat it covers
EntitiesSpawning, despawning, entity ids, names and disabling entities.
ComponentsDefining components, bundles, required components, storage and immutable components.
SystemsSystem functions, parameters, adding systems to an app and parallelism.
QueriesIterating, looking up and combining components.
Query filtersWith, Without, Or, Added, Changed and friends.
Change detectionReacting to added, changed and removed data.
ResourcesGlobal data with Res and ResMut.
CommandsDeferred changes to the world.
MessagesMessageWriter, MessageReader and MessageMutator.
Events and observersEvent, EntityEvent, observers, triggers and propagation.
Hooks and lifecycle eventsCode that runs when a component is added, replaced or removed.
Relationships and hierarchyChildOf, Children and your own relationships.
SchedulesStartup, Update, FixedUpdate, the frame's order and custom schedules.
System ordering and setsbefore, after, chain and system sets.
Run conditionsRunning systems only when a condition holds.
StatesMenus, levels and pause screens as state machines.
PluginsPlugin, PluginGroup, DefaultPlugins and MinimalPlugins.
System parametersLocal, ParamSet, custom parameters, exclusive and one-shot systems.
Error handlingSystems and commands that return Result, and error handlers.

Next steps#