NEOLearn

Entities

Spawn and despawn entities, keep and use their ids, name them, and disable them without deleting them.

Updated October 20, 2026

On this page

An entity is a game object: a player, a light, a UI button, a camera. On its own an entity is just a unique id, an Entity. What makes it a player or a light is the set of components it carries.

Entities live in the World, together with components and resources. In a running app you change the world from systems, usually through Commands.

Spawn an entity#

Commands::spawn creates an entity with a component or a tuple of components (a bundle) and returns its EntityCommands. Call .id() to keep the id.

Rust
use neo::prelude::*;

#[derive(Component)]
struct Player;

#[derive(Component)]
struct Health(u32);

fn setup(mut commands: Commands) {
    // one entity with three components
    let player = commands
        .spawn((Player, Health(100), Name::new("Player")))
        .id();

    // an entity with no components yet
    let marker = commands.spawn_empty().id();

    info!("spawned {player} and {marker}");
}

The id is available straight away, even though the spawn itself is applied a little later, when commands run. You can store it in a component or resource, pass it to other commands, or look the entity up in a query.

MethodWhat it does
commands.spawn(bundle)Spawns an entity with the components in bundle.
commands.spawn_empty()Spawns an entity with no components.
commands.spawn_batch(iter)Spawns one entity per bundle in an iterator. Faster than spawning in a loop.
commands.entity(id)The EntityCommands for an existing entity. Panics if the id isn't valid.
commands.get_entity(id)The same, as a Result, for ids that may be stale.
Rust
fn spawn_wave(mut commands: Commands) {
    commands.spawn_batch((0..50).map(|i| (Health(10), Name::new(format!("Enemy {i}")))));
}

Despawn an entity#

Rust
fn remove_dead(mut commands: Commands, query: Query<(Entity, &Health)>) {
    for (entity, health) in &query {
        if health.0 == 0 {
            commands.entity(entity).despawn();
        }
    }
}

Despawning removes the entity and all its components. It also despawns the entity's children, and their children: see Relationships and hierarchy. Despawning an entity that is already gone logs a warning instead of stopping the game.

Entity ids#

An Entity is a small Copy value made of an index and a generation. When an entity is despawned its index can be reused, with a new generation, so an old id never refers to a new entity by accident. Ids print as <index>v<generation>, for example 12v0.

  • Ids are only meaningful inside the world that made them. Don't save them to disk or send them over the network as stable identifiers; give entities your own id component for that.
  • An id you kept can outlive its entity. Use query.get(id) or commands.get_entity(id), which return a Result, when it might be stale.
  • Entity::PLACEHOLDER is a value that never refers to a real entity, for fields you fill in later.

Names#

Name is a built-in component holding a readable name. Logs and debugging tools use it to tell entities apart. It doesn't need to be unique.

Rust
commands.spawn((Name::new("Door"), Transform::default()));

In a query, NameOrEntity gives you the name when there is one and the id otherwise, which is handy in log messages.

Disable an entity#

Inserting the Disabled component hides an entity from every query that doesn't mention Disabled. The entity and its components stay in the world, so you can enable it again by removing the component. Use it for pooled objects, objects far from the player, or entities waiting to be revealed.

Rust
use neo::ecs::entity_disabling::Disabled;

#[derive(Component)]
struct Asleep;

fn sleep(mut commands: Commands, far_away: Query<Entity, With<Asleep>>) {
    for entity in &far_away {
        commands.entity(entity).insert(Disabled);
    }
}
QuerySees disabled entities?
Query<&Health>No
Query<&Health, With<Disabled>>Only disabled ones
Query<(&Health, Has<Disabled>)>Both, with a flag
Query<&Health, Allow<Disabled>>Both

Disabling only affects the entity you insert it on, not its children. To disable a whole tree, use insert_recursive::<Children>(Disabled) on the EntityCommands.

Working with the world directly#

Tests, tools and exclusive systems can work on a World without commands. Changes apply immediately.

Rust
let mut world = World::new();
let e = world.spawn((Player, Health(3))).id();
assert_eq!(world.entity(e).get::<Health>().unwrap().0, 3);
world.despawn(e);

Example: cargo run --example entity_disabling, from the engine core's workspace.

Next steps#