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.
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#
| Part | What it is | Page |
|---|---|---|
| World | Holds every entity, component and resource. There is one per app (plus one for rendering). | Entities |
| Entity | A unique id. It has no data of its own; its components are its data. | Entities |
| Component | A Rust struct or enum stored on an entity. | Components |
| System | A function that runs on the world. The engine reads its parameters to give it data and to run systems in parallel. | Systems |
| Query | A system parameter that iterates the entities that have a set of components. | Queries |
| Resource | A single global value, identified by its type: time, settings, asset collections. | Resources |
| Commands | Queued changes to the world (spawn, despawn, insert, remove) applied at a safe point. | Commands |
| Messages | Buffered values that systems write and other systems read later in the frame. | Messages |
| Events and observers | Values that run their observers immediately when triggered. | Events and observers |
| Schedule | A collection of systems that runs together: Startup, Update, FixedUpdate and others. | Schedules |
| Plugin | A bundle of systems, resources and settings that you add to an app in one call. | Plugins |
Pages in this section#
| Page | What it covers |
|---|---|
| Entities | Spawning, despawning, entity ids, names and disabling entities. |
| Components | Defining components, bundles, required components, storage and immutable components. |
| Systems | System functions, parameters, adding systems to an app and parallelism. |
| Queries | Iterating, looking up and combining components. |
| Query filters | With, Without, Or, Added, Changed and friends. |
| Change detection | Reacting to added, changed and removed data. |
| Resources | Global data with Res and ResMut. |
| Commands | Deferred changes to the world. |
| Messages | MessageWriter, MessageReader and MessageMutator. |
| Events and observers | Event, EntityEvent, observers, triggers and propagation. |
| Hooks and lifecycle events | Code that runs when a component is added, replaced or removed. |
| Relationships and hierarchy | ChildOf, Children and your own relationships. |
| Schedules | Startup, Update, FixedUpdate, the frame's order and custom schedules. |
| System ordering and sets | before, after, chain and system sets. |
| Run conditions | Running systems only when a condition holds. |
| States | Menus, levels and pause screens as state machines. |
| Plugins | Plugin, PluginGroup, DefaultPlugins and MinimalPlugins. |
| System parameters | Local, ParamSet, custom parameters, exclusive and one-shot systems. |
| Error handling | Systems and commands that return Result, and error handlers. |