NEOLearn

Components

Define components, add and remove them, group them in bundles, declare required components, and choose storage and mutability.

Updated October 20, 2026

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#

Rust
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:

Rust
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 EntityCommandsWhat 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:

Rust
#[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.

Rust
#[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.

FormExample
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:

Rust
#[derive(Component)]
#[component(storage = "SparseSet")]
struct Stunned;
StorageIterationAdding and removing
Table (default)FastestSlower: moves the entity's data
SparseSetSlowerFast

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.

Rust
#[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#

AttributeWhat 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.

Next steps#