Struct Commands

pub struct Commands<'w, 's> { /* private fields */ }

A Command queue to perform structural changes to the World.

Since each command requires exclusive access to the World, all queued commands are automatically applied in sequence when the ApplyDeferred system runs (see ApplyDeferred documentation for more details).

Each command can be used to modify the World in arbitrary ways:

• spawning or despawning entities
• inserting components on new or existing entities
• inserting resources
• etc.

For a version of Commands that works in parallel contexts (such as within Query::par_iter) see ParallelCommands

Usage

Add mut commands: Commands as a function argument to your system to get a copy of this struct that will be applied the next time a copy of ApplyDeferred runs. Commands are almost always used as a SystemParam.

fn my_system(mut commands: Commands) {
   // ...
}

Implementing

Each built-in command is implemented as a separate method, e.g. Commands::spawn. In addition to the pre-defined command methods, you can add commands with any arbitrary behavior using Commands::queue, which accepts any type implementing Command.

Since closures and other functions implement this trait automatically, this allows one-shot, anonymous custom commands.

// NOTE: type inference fails here, so annotations are required on the closure.
commands.queue(|w: &mut World| {
    // Mutate the world however you want...
});

Error handling

A Command can return a Result, which will be passed to an error handler if the Result is an error.

The default error handler panics. It can be configured by setting the GLOBAL_ERROR_HANDLER.

Alternatively, you can customize the error handler for a specific command by calling Commands::queue_handled.

The error module provides some simple error handlers for convenience.

Implementations

impl<'w, 's> Commands<'w, 's>

pub fn new(queue: &'s mut CommandQueue, world: &'w World) -> Self

Returns a new Commands instance from a CommandQueue and a World.

pub fn new_from_entities( queue: &'s mut CommandQueue, entities: &'w Entities, ) -> Self

Returns a new Commands instance from a CommandQueue and an Entities reference.

pub fn reborrow(&mut self) -> Commands<'w, '_>

Returns a Commands with a smaller lifetime.

This is useful if you have &mut Commands but need Commands.

Example

fn my_system(mut commands: Commands) {
    // We do our initialization in a separate function,
    // which expects an owned `Commands`.
    do_initialization(commands.reborrow());

    // Since we only reborrowed the commands instead of moving them, we can still use them.
    commands.spawn_empty();
}

pub fn append(&mut self, other: &mut CommandQueue)

Take all commands from other and append them to self, leaving other empty.

pub fn spawn_empty(&mut self) -> EntityCommands<'_>

Spawns a new empty Entity and returns its corresponding EntityCommands.

Example

#[derive(Component)]
struct Label(&'static str);
#[derive(Component)]
struct Strength(u32);
#[derive(Component)]
struct Agility(u32);

fn example_system(mut commands: Commands) {
    // Create a new empty entity.
    commands.spawn_empty();

    // Create another empty entity.
    commands.spawn_empty()
        // Add a new component bundle to the entity.
        .insert((Strength(1), Agility(2)))
        // Add a single component to the entity.
        .insert(Label("hello world"));
}

See also

• spawn to spawn an entity with components.
• spawn_batch to spawn many entities with the same combination of components.

pub fn spawn<T: Bundle>(&mut self, bundle: T) -> EntityCommands<'_>

Spawns a new Entity with the given components and returns the entity’s corresponding EntityCommands.

To spawn many entities with the same combination of components, spawn_batch can be used for better performance.

Example

#[derive(Component)]
struct ComponentA(u32);
#[derive(Component)]
struct ComponentB(u32);

#[derive(Bundle)]
struct ExampleBundle {
    a: ComponentA,
    b: ComponentB,
}

fn example_system(mut commands: Commands) {
    // Create a new entity with a single component.
    commands.spawn(ComponentA(1));

    // Create a new entity with two components using a "tuple bundle".
    commands.spawn((ComponentA(2), ComponentB(1)));

    // Create a new entity with a component bundle.
    commands.spawn(ExampleBundle {
        a: ComponentA(3),
        b: ComponentB(2),
    });
}

See also

• spawn_empty to spawn an entity without any components.
• spawn_batch to spawn many entities with the same combination of components.

pub fn entity(&mut self, entity: Entity) -> EntityCommands<'_>

Returns the EntityCommands for the given Entity.

This method does not guarantee that commands queued by the returned EntityCommands will be successful, since the entity could be despawned before they are executed.

Example

#[derive(Resource)]
struct PlayerEntity {
    entity: Entity
}

#[derive(Component)]
struct Label(&'static str);

fn example_system(mut commands: Commands, player: Res<PlayerEntity>) {
    // Get the entity and add a component.
    commands.entity(player.entity).insert(Label("hello world"));
}

See also

• get_entity for the fallible version.

pub fn get_entity( &mut self, entity: Entity, ) -> Result<EntityCommands<'_>, EntityDoesNotExistError>

Returns the EntityCommands for the requested Entity if it exists.

This method does not guarantee that commands queued by the returned EntityCommands will be successful, since the entity could be despawned before they are executed.

Errors

Returns EntityDoesNotExistError if the requested entity does not exist.

Example

#[derive(Resource)]
struct PlayerEntity {
    entity: Entity
}

#[derive(Component)]
struct Label(&'static str);

fn example_system(mut commands: Commands, player: Res<PlayerEntity>) -> Result {
    // Get the entity if it still exists and store the `EntityCommands`.
    // If it doesn't exist, the `?` operator will propagate the returned error
    // to the system, and the system will pass it to an error handler.
    let mut entity_commands = commands.get_entity(player.entity)?;

    // Add a component to the entity.
    entity_commands.insert(Label("hello world"));

    // Return from the system successfully.
    Ok(())
}

See also

• entity for the infallible version.

pub fn spawn_batch<I>(&mut self, batch: I)

where I: IntoIterator + Send + Sync + 'static, I::Item: Bundle<Effect: NoBundleEffect>,

Spawns multiple entities with the same combination of components, based on a batch of Bundles.

A batch can be any type that implements IntoIterator and contains bundles, such as a Vec<Bundle> or an array [Bundle; N].

This method is equivalent to iterating the batch and calling spawn for each bundle, but is faster by pre-allocating memory and having exclusive World access.

Example

use bevy_ecs::prelude::*;

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

fn example_system(mut commands: Commands) {
    commands.spawn_batch([
        (Name::new("Alice"), Score(0)),
        (Name::new("Bob"), Score(0)),
    ]);
}

See also

• spawn to spawn an entity with components.
• spawn_empty to spawn an entity without components.

pub fn queue<C: Command<T> + HandleError<T>, T>(&mut self, command: C)

Pushes a generic Command to the command queue.

If the Command returns a Result, it will be handled using the default error handler.

To use a custom error handler, see Commands::queue_handled.

The command can be:

• A custom struct that implements Command.
• A closure or function that matches one of the following signatures:
  • (&mut World)
• A built-in command from the command module.

Example

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

struct AddToCounter(String);

impl Command<Result> for AddToCounter {
    fn apply(self, world: &mut World) -> Result {
        let mut counter = world.get_resource_or_insert_with(Counter::default);
        let amount: u64 = self.0.parse()?;
        counter.0 += amount;
        Ok(())
    }
}

fn add_three_to_counter_system(mut commands: Commands) {
    commands.queue(AddToCounter("3".to_string()));
}

fn add_twenty_five_to_counter_system(mut commands: Commands) {
    commands.queue(|world: &mut World| {
        let mut counter = world.get_resource_or_insert_with(Counter::default);
        counter.0 += 25;
    });
}

pub fn queue_handled<C: Command<T> + HandleError<T>, T>( &mut self, command: C, error_handler: fn(_: BevyError, _: ErrorContext), )

Pushes a generic Command to the command queue.

If the Command returns a Result, the given error_handler will be used to handle error cases.

To implicitly use the default error handler, see Commands::queue.

The command can be:

• A custom struct that implements Command.
• A closure or function that matches one of the following signatures:
  • (&mut World)
  • (&mut World) -> Result
• A built-in command from the command module.

Example

use bevy_ecs::error::warn;

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

struct AddToCounter(String);

impl Command<Result> for AddToCounter {
    fn apply(self, world: &mut World) -> Result {
        let mut counter = world.get_resource_or_insert_with(Counter::default);
        let amount: u64 = self.0.parse()?;
        counter.0 += amount;
        Ok(())
    }
}

fn add_three_to_counter_system(mut commands: Commands) {
    commands.queue_handled(AddToCounter("3".to_string()), warn);
}

fn add_twenty_five_to_counter_system(mut commands: Commands) {
    commands.queue(|world: &mut World| {
        let mut counter = world.get_resource_or_insert_with(Counter::default);
        counter.0 += 25;
    });
}

pub fn insert_or_spawn_batch<I, B>(&mut self, bundles_iter: I)

where I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static, B: Bundle<Effect: NoBundleEffect>,

👎Deprecated since 0.16.0: This can cause extreme performance problems when used with lots of arbitrary free entities. See #18054 on GitHub.

Pushes a Command to the queue for creating entities, if needed, and for adding a bundle to each entity.

bundles_iter is a type that can be converted into an (Entity, Bundle) iterator (it can also be a collection).

When the command is applied, for each (Entity, Bundle) pair in the given bundles_iter, the Entity is spawned, if it does not exist already. Then, the Bundle is added to the entity.

This method is equivalent to iterating bundles_iter, calling spawn for each bundle, and passing it to insert, but it is faster due to memory pre-allocation.

Note

Spawning a specific entity value is rarely the right choice. Most apps should use Commands::spawn_batch. This method should generally only be used for sharing entities across apps, and only when they have a scheme worked out to share an ID space (which doesn’t happen by default).

pub fn insert_batch<I, B>(&mut self, batch: I)

where I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static, B: Bundle<Effect: NoBundleEffect>,

Adds a series of Bundles to each Entity they are paired with, based on a batch of (Entity, Bundle) pairs.

A batch can be any type that implements IntoIterator and contains (Entity, Bundle) tuples, such as a Vec<(Entity, Bundle)> or an array [(Entity, Bundle); N].

This will overwrite any pre-existing components shared by the Bundle type. Use Commands::insert_batch_if_new to keep the pre-existing components instead.

This method is equivalent to iterating the batch and calling insert for each pair, but is faster by caching data that is shared between entities.

Fallible

This command will fail if any of the given entities do not exist.

It will internally return a TryInsertBatchError, which will be handled by the default error handler.

pub fn insert_batch_if_new<I, B>(&mut self, batch: I)

where I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static, B: Bundle<Effect: NoBundleEffect>,

Adds a series of Bundles to each Entity they are paired with, based on a batch of (Entity, Bundle) pairs.

A batch can be any type that implements IntoIterator and contains (Entity, Bundle) tuples, such as a Vec<(Entity, Bundle)> or an array [(Entity, Bundle); N].

This will keep any pre-existing components shared by the Bundle type and discard the new values. Use Commands::insert_batch to overwrite the pre-existing components instead.

This method is equivalent to iterating the batch and calling insert_if_new for each pair, but is faster by caching data that is shared between entities.

Fallible

This command will fail if any of the given entities do not exist.

It will internally return a TryInsertBatchError, which will be handled by the default error handler.

pub fn try_insert_batch<I, B>(&mut self, batch: I)

where I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static, B: Bundle<Effect: NoBundleEffect>,

Adds a series of Bundles to each Entity they are paired with, based on a batch of (Entity, Bundle) pairs.

A batch can be any type that implements IntoIterator and contains (Entity, Bundle) tuples, such as a Vec<(Entity, Bundle)> or an array [(Entity, Bundle); N].

This will overwrite any pre-existing components shared by the Bundle type. Use Commands::try_insert_batch_if_new to keep the pre-existing components instead.

This method is equivalent to iterating the batch and calling insert for each pair, but is faster by caching data that is shared between entities.

Fallible

This command will fail if any of the given entities do not exist.

It will internally return a TryInsertBatchError, which will be handled by logging the error at the warn level.

pub fn try_insert_batch_if_new<I, B>(&mut self, batch: I)

where I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static, B: Bundle<Effect: NoBundleEffect>,

Adds a series of Bundles to each Entity they are paired with, based on a batch of (Entity, Bundle) pairs.

A batch can be any type that implements IntoIterator and contains (Entity, Bundle) tuples, such as a Vec<(Entity, Bundle)> or an array [(Entity, Bundle); N].

This will keep any pre-existing components shared by the Bundle type and discard the new values. Use Commands::try_insert_batch to overwrite the pre-existing components instead.

This method is equivalent to iterating the batch and calling insert_if_new for each pair, but is faster by caching data that is shared between entities.

Fallible

This command will fail if any of the given entities do not exist.

It will internally return a TryInsertBatchError, which will be handled by logging the error at the warn level.

pub fn init_resource<R: Resource + FromWorld>(&mut self)

Inserts a Resource into the World with an inferred value.

The inferred value is determined by the FromWorld trait of the resource. Note that any resource with the Default trait automatically implements FromWorld, and those default values will be used.

If the resource already exists when the command is applied, nothing happens.

Example

#[derive(Resource, Default)]
struct Scoreboard {
    current_score: u32,
    high_score: u32,
}

fn initialize_scoreboard(mut commands: Commands) {
    commands.init_resource::<Scoreboard>();
}

pub fn insert_resource<R: Resource>(&mut self, resource: R)

Inserts a Resource into the World with a specific value.

This will overwrite any previous value of the same resource type.

Example

#[derive(Resource)]
struct Scoreboard {
    current_score: u32,
    high_score: u32,
}

fn system(mut commands: Commands) {
    commands.insert_resource(Scoreboard {
        current_score: 0,
        high_score: 0,
    });
}

pub fn remove_resource<R: Resource>(&mut self)

Removes a Resource from the World.

Example

#[derive(Resource)]
struct Scoreboard {
    current_score: u32,
    high_score: u32,
}

fn system(mut commands: Commands) {
    commands.remove_resource::<Scoreboard>();
}

pub fn run_system(&mut self, id: SystemId)

Runs the system corresponding to the given SystemId. Before running a system, it must first be registered via Commands::register_system or World::register_system.

The system is run in an exclusive and single-threaded way. Running slow systems can become a bottleneck.

There is no way to get the output of a system when run as a command, because the execution of the system happens later. To get the output of a system, use World::run_system or World::run_system_with instead of running the system as a command.

Fallible

This command will fail if the given SystemId does not correspond to a System.

It will internally return a RegisteredSystemError, which will be handled by logging the error at the warn level.

pub fn run_system_with<I>(&mut self, id: SystemId<I>, input: I::Inner<'static>)

where I: SystemInput<Inner<'static>: Send> + 'static,

Runs the system corresponding to the given SystemId with input. Before running a system, it must first be registered via Commands::register_system or World::register_system.

The system is run in an exclusive and single-threaded way. Running slow systems can become a bottleneck.

There is no way to get the output of a system when run as a command, because the execution of the system happens later. To get the output of a system, use World::run_system or World::run_system_with instead of running the system as a command.

Fallible

This command will fail if the given SystemId does not correspond to a System.

It will internally return a RegisteredSystemError, which will be handled by logging the error at the warn level.

pub fn register_system<I, O, M>( &mut self, system: impl IntoSystem<I, O, M> + 'static, ) -> SystemId<I, O>

where I: SystemInput + Send + 'static, O: Send + 'static,

Registers a system and returns its SystemId so it can later be called by Commands::run_system or World::run_system.

This is different from adding systems to a Schedule, because the SystemId that is returned can be used anywhere in the World to run the associated system.

Using a Schedule is still preferred for most cases due to its better performance and ability to run non-conflicting systems simultaneously.

Note

If the same system is registered more than once, each registration will be considered a different system, and they will each be given their own SystemId.

If you want to avoid registering the same system multiple times, consider using Commands::run_system_cached or storing the SystemId in a Local.

Example

#[derive(Resource)]
struct Counter(i32);

fn register_system(
    mut commands: Commands,
    mut local_system: Local<Option<SystemId>>,
) {
    if let Some(system) = *local_system {
        commands.run_system(system);
    } else {
        *local_system = Some(commands.register_system(increment_counter));
    }
}

fn increment_counter(mut value: ResMut<Counter>) {
    value.0 += 1;
}

pub fn unregister_system<I, O>(&mut self, system_id: SystemId<I, O>)

where I: SystemInput + Send + 'static, O: Send + 'static,

Removes a system previously registered with Commands::register_system or World::register_system.

After removing a system, the SystemId becomes invalid and attempting to use it afterwards will result in an error. Re-adding the removed system will register it with a new SystemId.

Fallible

This command will fail if the given SystemId does not correspond to a System.

It will internally return a RegisteredSystemError, which will be handled by logging the error at the warn level.

pub fn unregister_system_cached<I, O, M, S>(&mut self, system: S)

where I: SystemInput + Send + 'static, O: 'static, M: 'static, S: IntoSystem<I, O, M> + Send + 'static,

Removes a system previously registered with one of the following:

• Commands::run_system_cached
• World::run_system_cached
• World::register_system_cached

Fallible

This command will fail if the given system is not currently cached in a CachedSystemId resource.

It will internally return a RegisteredSystemError, which will be handled by logging the error at the warn level.

pub fn run_system_cached<M, S>(&mut self, system: S)

where M: 'static, S: IntoSystem<(), (), M> + Send + 'static,

Runs a cached system, registering it if necessary.

Unlike Commands::run_system, this method does not require manual registration.

The first time this method is called for a particular system, it will register the system and store its SystemId in a CachedSystemId resource for later.

If you would rather manage the SystemId yourself, or register multiple copies of the same system, use Commands::register_system instead.

Limitations

This method only accepts ZST (zero-sized) systems to guarantee that any two systems of the same type must be equal. This means that closures that capture the environment, and function pointers, are not accepted.

If you want to access values from the environment within a system, consider passing them in as inputs via Commands::run_system_cached_with.

If that’s not an option, consider Commands::register_system instead.

pub fn run_system_cached_with<I, M, S>( &mut self, system: S, input: I::Inner<'static>, )

where I: SystemInput<Inner<'static>: Send> + Send + 'static, M: 'static, S: IntoSystem<I, (), M> + Send + 'static,

Runs a cached system with an input, registering it if necessary.

Unlike Commands::run_system_with, this method does not require manual registration.

The first time this method is called for a particular system, it will register the system and store its SystemId in a CachedSystemId resource for later.

If you would rather manage the SystemId yourself, or register multiple copies of the same system, use Commands::register_system instead.

Limitations

This method only accepts ZST (zero-sized) systems to guarantee that any two systems of the same type must be equal. This means that closures that capture the environment, and function pointers, are not accepted.

If you want to access values from the environment within a system, consider passing them in as inputs.

If that’s not an option, consider Commands::register_system instead.

pub fn trigger(&mut self, event: impl Event)

Sends a “global” Trigger without any targets.

This will run any Observer of the given Event that isn’t scoped to specific targets.

pub fn trigger_targets( &mut self, event: impl Event, targets: impl TriggerTargets + Send + Sync + 'static, )

Sends a Trigger for the given targets.

This will run any Observer of the given Event watching those targets.

pub fn add_observer<E: Event, B: Bundle, M>( &mut self, observer: impl IntoObserverSystem<E, B, M>, ) -> EntityCommands<'_>

Spawns an Observer and returns the EntityCommands associated with the entity that stores the observer.

Calling observe on the returned EntityCommands will observe the observer itself, which you very likely do not want.

pub fn send_event<E: Event>(&mut self, event: E) -> &mut Self

Sends an arbitrary Event.

This is a convenience method for sending events without requiring an EventWriter.

Performance

Since this is a command, exclusive world access is used, which means that it will not profit from system-level parallelism on supported platforms.

If these events are performance-critical or very frequently sent, consider using a typed EventWriter instead.

pub fn run_schedule(&mut self, label: impl ScheduleLabel)

Runs the schedule corresponding to the given ScheduleLabel.

Calls World::try_run_schedule.

Fallible

This command will fail if the given ScheduleLabel does not correspond to a Schedule.

It will internally return a TryRunScheduleError, which will be handled by logging the error at the warn level.

Example

#[derive(ScheduleLabel, Hash, Debug, PartialEq, Eq, Clone, Copy)]
struct FooSchedule;

commands.run_schedule(FooSchedule);

Trait Implementations

impl SystemParam for Commands<'_, '_>

type State = FetchState

Used to store data which persists across invocations of a system.

type Item<'w, 's> = Commands<'w, 's>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

unsafe fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta, )

For the specified Archetype, registers the components accessed by this SystemParam (if applicable).a

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during ApplyDeferred.

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next ApplyDeferred.

unsafe fn validate_param( state: &Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'_>, ) -> Result<(), SystemParamValidationError>

Validates that the param can be acquired by the get_param.

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> Self::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

impl<'w, 's> ReadOnlySystemParam for Commands<'w, 's>

where Deferred<'s, CommandQueue>: ReadOnlySystemParam, &'w Entities: ReadOnlySystemParam,

impl Send for Commands<'_, '_>

impl Sync for Commands<'_, '_>