Components
Define components, add and remove them, group them in bundles, declare required components, and choose storage and mutability.
On this page
A component is a piece of data attached to an entity: a position, a health value, a "this is the player" marker. Components are ordinary Rust types with #[derive(Component)]. Keep each one small and focused on one thing; an entity's behaviour comes from the combination of components it has.
Define a component#
use neo::prelude::*;
// data
#[derive(Component)]
struct Health {
current: u32,
max: u32,
}
// a tuple struct
#[derive(Component)]
struct Speed(f32);
// a marker with no data, used to find entities in queries
#[derive(Component)]
struct Enemy;
// an enum
#[derive(Component)]
enum Team {
Red,
Blue,
}Components must be Send + Sync + 'static: no borrowed references, and nothing that can't move between threads.
Add and remove components#
You add components when you spawn an entity, or later with commands:
fn setup(mut commands: Commands) {
let enemy = commands.spawn((Enemy, Health { current: 30, max: 30 })).id();
commands.entity(enemy).insert((Speed(2.0), Team::Red));
commands.entity(enemy).remove::<Speed>();
}Method on EntityCommands | What it does |
|---|---|
insert(bundle) | Adds the components, replacing any the entity already has. |
insert_if_new(bundle) | Adds only the components the entity doesn't have yet. |
try_insert(bundle) | Like insert, but does nothing if the entity no longer exists. |
remove::<T>() | Removes T (or a tuple of types). |
remove_with_requires::<T>() | Removes T and the components it required. |
retain::<T>() | Removes every component except those in T. |
An entity has at most one component of each type. Inserting a second Speed replaces the first.
Bundles#
A tuple of components is a bundle, and you can use one anywhere a component is accepted. To give a common group a name, derive Bundle:
#[derive(Bundle)]
struct EnemyBundle {
enemy: Enemy,
health: Health,
speed: Speed,
}
commands.spawn(EnemyBundle {
enemy: Enemy,
health: Health { current: 30, max: 30 },
speed: Speed(2.0),
});Bundles are only a way to insert several components at once. Once inserted, each component is stored and queried on its own.
Required components#
Often a better tool than a bundle: a component can declare the other components it needs with #[require(...)]. When it is inserted, any required component the entity doesn't already have is added too, using its Default or the value you give.
#[derive(Component, Default)]
struct Speed(f32);
#[derive(Component)]
#[require(Health { current: 30, max: 30 }, Speed(2.0), Transform)]
struct Enemy;
#[derive(Component)]
struct Health { current: u32, max: u32 }
// gets Health, Speed and Transform (and everything Transform requires) automatically
commands.spawn(Enemy);
// values you pass yourself win over the required defaults
commands.spawn((Enemy, Speed(5.0)));Requirements are recursive: if B requires C, then requiring B also brings C. The engine's own components work this way. A Camera3d brings a Camera and a Projection, and Camera in turn brings a Transform, Visibility and the rest of what a camera needs. A Mesh3d brings a Transform.
| Form | Example |
|---|---|
The type's Default | #[require(Transform)] |
| A value | #[require(Speed(2.0))], #[require(Team::Red)] |
| A struct with defaults | #[require(Health { current: 30, ..Default::default() })] |
| An expression | #[require(Speed = base_speed())] |
You can also register requirements at runtime with app.register_required_components::<A, B>() or register_required_components_with::<A, B>(|| B(..)), before A is first inserted.
Storage#
Components are stored in tables by default: dense arrays grouped by the set of components an entity has. Tables iterate fast but cost more when a component is added or removed. For components that come and go often (a "stunned" marker, a short-lived effect), use sparse set storage:
#[derive(Component)]
#[component(storage = "SparseSet")]
struct Stunned;| Storage | Iteration | Adding and removing |
|---|---|---|
Table (default) | Fastest | Slower: moves the entity's data |
SparseSet | Slower | Fast |
Immutable components#
#[component(immutable)] makes a component read-only once inserted. You can't get &mut to it from a query; to change it you insert a new value. Because every change goes through an insert, hooks and observers see all of them, which makes immutable components a good fit for values you index elsewhere.
#[derive(Component, PartialEq, Eq, Hash, Clone, Copy)]
#[component(immutable)]
struct GridCell(i32, i32);Example: cargo run --example immutable_components, from the engine core's workspace.
Component attributes#
| Attribute | What it does |
|---|---|
#[require(...)] | Required components, above. |
#[component(storage = "SparseSet")] | Sparse set storage. |
#[component(immutable)] | No mutable access after insertion. |
#[component(on_add = f, on_insert = f, on_discard = f, on_remove = f, on_despawn = f)] | Lifecycle hooks; see Hooks and lifecycle events. |
#[component(clone_behavior = Ignore)] | How the component behaves when an entity is cloned. |
#[relationship(...)], #[relationship_target(...)] | Relationship components; see Relationships and hierarchy. |
To make a component visible to the Studio, scenes and saving, also derive Reflect; see Scenes and reflection. To make it visible to scripts, see Exposure and permissions.