Entities
Spawn and despawn entities, keep and use their ids, name them, and disable them without deleting them.
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.
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.
| Method | What 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. |
fn spawn_wave(mut commands: Commands) {
commands.spawn_batch((0..50).map(|i| (Health(10), Name::new(format!("Enemy {i}")))));
}Despawn an entity#
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)orcommands.get_entity(id), which return aResult, when it might be stale. Entity::PLACEHOLDERis 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.
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.
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);
}
}| Query | Sees 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.
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.