NEOLearn

Commands

Queue changes to the world from systems with Commands and EntityCommands, know when they apply, delay them, and write your own commands.

Updated October 20, 2026

On this page

Most systems run in parallel, so they can't change the shape of the world while they run: spawning, despawning, or adding and removing components would disturb every other system. Instead, a system takes Commands and queues the change. The engine applies queued commands at a safe point, in the order they were queued.

Rust
use neo::prelude::*;

#[derive(Component)]
struct Bullet;

fn fire(mut commands: Commands, keys: Res<ButtonInput<KeyCode>>) {
    if keys.just_pressed(KeyCode::Space) {
        commands.spawn((Bullet, Transform::default()));
    }
}

When commands apply#

Commands from a system are applied:

  • at the end of the schedule the system ran in (for example the end of Update), and
  • at sync points the engine inserts between a system that has commands and any system ordered after it with .after, .before or .chain().

So a system ordered after fire sees the new bullet in the same frame. A system with no ordering against fire sees it next frame at the latest.

Rust
app.add_systems(Update, (fire, move_bullets).chain()); // move_bullets sees this frame's bullets

If you don't want the sync point on an edge, use .after_ignore_deferred, .before_ignore_deferred or .chain_ignore_deferred(). You can also place one yourself with the ApplyDeferred system. See System ordering and sets.

World commands#

CommandWhat it does
spawn(bundle), spawn_empty(), spawn_batch(iter)Spawn entities.
entity(id), get_entity(id)The EntityCommands for an entity.
insert_resource(value), init_resource::<T>(), remove_resource::<T>()Change resources.
write_message(message)Write a message.
trigger(event)Trigger an event for its observers.
add_observer(system)Add a global observer.
run_system(id), run_system_cached(system)Run a one-shot system.
register_system(system)Register a one-shot system and get its SystemId.
run_schedule(label)Run a whole schedule.
queue(command)Queue any Command, including a closure that takes &mut World.
set_state(state)Queue a state change.

Entity commands#

commands.entity(id) and commands.spawn(..) return EntityCommands, which change one entity. The calls chain:

Rust
fn equip(mut commands: Commands, player: Single<Entity, With<Player>>) {
    commands
        .entity(*player)
        .insert(Armor(5))
        .remove::<Unarmed>()
        .with_child((Name::new("Shield"), Transform::from_xyz(0.3, 1.0, 0.0)));
}

#[derive(Component)]
struct Player;
#[derive(Component)]
struct Armor(u32);
#[derive(Component)]
struct Unarmed;
MethodWhat it does
id()The entity's id.
insert(bundle), insert_if_new(bundle), try_insert(bundle)Add components.
remove::<T>(), try_remove::<T>(), retain::<T>()Remove components.
despawn(), try_despawn()Despawn the entity and its children.
with_child(bundle), with_children(..), add_child(id)Build a hierarchy; see Relationships and hierarchy.
observe(system)Add an observer that watches this entity.
trigger(f)Trigger an entity event on this entity; f builds the event from the entity id.
entry::<T>()Edit a component in place, with .or_insert(value) or .and_modify(..).
queue(command)Queue an EntityCommand or a closure taking EntityWorldMut.
clone_and_spawn()Spawn a copy of this entity.

The try_ versions do nothing if the entity is gone by the time the command applies. The plain versions report an error to the error handler, which panics by default for most commands; despawn only logs a warning.

Delayed commands#

commands.delayed() queues commands that apply after some game time has passed:

Rust
fn flash(mut commands: Commands, target: Single<Entity, With<Player>>) {
    let mut delayed = commands.delayed();
    delayed.secs(0.5).entity(*target).insert(Visibility::Hidden);
    delayed.secs(0.6).entity(*target).insert(Visibility::Visible);
}

secs(seconds) and duration(Duration) each return a Commands for that delay. Ids for entities spawned with a delay are allocated straight away, so you can refer to them in later delayed commands.

Your own commands#

Any closure that takes &mut World is a command:

Rust
commands.queue(|world: &mut World| {
    let count = world.query::<&Bullet>().iter(world).count();
    info!("{count} bullets");
});

For something you reuse, implement Command:

Rust
#[derive(Resource, Default)]
struct Counter(u64);

struct AddToCounter(u64);

impl Command for AddToCounter {
    type Out = ();

    fn apply(self, world: &mut World) {
        world.get_resource_or_insert_with(Counter::default).0 += self.0;
    }
}

fn count(mut commands: Commands) {
    commands.queue(AddToCounter(1));
}

A command can also return Result; errors go to the error handler, or to your own handler with commands.queue_handled(command, handler).

Commands in parallel iteration#

Commands can't be used inside par_iter. Use the ParallelCommands parameter instead:

Rust
fn cull(par: ParallelCommands, query: Query<(Entity, &Transform)>) {
    query.par_iter().for_each(|(entity, transform)| {
        if transform.translation.y < -100.0 {
            par.command_scope(|mut commands| {
                commands.entity(entity).despawn();
            });
        }
    });
}

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

Next steps#