Struct bevy::ecs::system::Commands

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

A Command queue to perform impactful changes to the World.

Since each command requires exclusive access to the World, all queued commands are automatically applied in sequence only after each system in a stage has completed.

The command queue of a system can also be manually applied by calling System::apply_buffers.

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.

Usage

Add mut commands: Commands as a function argument to your system to get a copy of this struct that will be applied at the end of the current stage. 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. spawn. In addition to the pre-defined command methods, you can add commands with any arbitrary behavior using Commands::add, 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.add(|w: &mut World| {
    // Mutate the world however you want...
});

Implementations

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

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

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

It is not required to call this constructor when using Commands as a system parameter.

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

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

It is not required to call this constructor when using Commands as a system parameter.

pub fn spawn_empty<'a>(&'a mut self) -> EntityCommands<'w, 's, 'a>

Pushes a Command to the queue for creating a new empty Entity, and returns its corresponding EntityCommands.

See World::spawn_empty for more details.

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 and retrieve its id.
    let empty_entity = commands.spawn_empty().id();

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

See also

• spawn to spawn an entity with a bundle.
• spawn_batch to spawn entities with a bundle each.

pub fn get_or_spawn<'a>(
    &'a mut self,
    entity: Entity
) -> EntityCommands<'w, 's, 'a>

Pushes a Command to the queue for creating a new Entity if the given one does not exists, and returns its corresponding EntityCommands.

This method silently fails by returning EntityCommands even if the given Entity cannot be spawned.

See World::get_or_spawn for more details.

Note

Spawning a specific entity value is rarely the right choice. Most apps should favor Commands::spawn. 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 spawn<T, 'a>(&'a mut self, bundle: T) -> EntityCommands<'w, 's, 'a>where
    T: Bundle,

Pushes a Command to the queue for creating a new entity with the given Bundle’s components, and returns its corresponding EntityCommands.

Example

use bevy_ecs::prelude::*;

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

#[derive(Bundle)]
struct ExampleBundle {
    a: Component1,
    b: Component2,
}

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

    // Create a new entity with a component bundle.
    commands.spawn(ExampleBundle {
        a: Component1,
        b: Component2,
    });

    commands
        // Create a new entity with two components using a "tuple bundle".
        .spawn((Component1, Component2))
        // `spawn returns a builder, so you can insert more bundles like this:
        .insert((Strength(1), Agility(2)))
        // or insert single components like this:
        .insert(Label("hello world"));
}

See also

• spawn_empty to spawn an entity without any components.
• spawn_batch to spawn entities with a bundle each.

pub fn spawn_bundle<T, 'a>(&'a mut self, bundle: T) -> EntityCommands<'w, 's, 'a>where
    T: Bundle,

👎Deprecated since 0.9.0: Use spawn instead, which now accepts bundles, components, and tuples of bundles and components.

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

Returns the EntityCommands for the requested Entity.

Panics

This method panics if the requested entity does not exist.

Example

use bevy_ecs::prelude::*;

#[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
    let entity = commands.spawn_empty().id();

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

See also

• get_entity for the fallible version.

pub fn get_entity<'a>(
    &'a mut self,
    entity: Entity
) -> Option<EntityCommands<'w, 's, 'a>>

Returns the EntityCommands for the requested Entity, if it exists.

Returns None if the entity does not exist.

This method does not guarantee that EntityCommands will be successfully applied, since another command in the queue may delete the entity before them.

Example

use bevy_ecs::prelude::*;

#[derive(Component)]
struct Label(&'static str);
fn example_system(mut commands: Commands) {
    // Create a new, empty entity
    let entity = commands.spawn_empty().id();

    // Get the entity if it still exists, which it will in this case
    if let Some(mut entity_commands) = commands.get_entity(entity) {
        // adds a single component to the entity
        entity_commands.insert(Label("hello world"));
    }
}

See also

• entity for the panicking version.

pub fn spawn_batch<I>(&mut self, bundles_iter: I)where
    I: 'static + IntoIterator + Send + Sync,
    <I as IntoIterator>::Item: Bundle,

Pushes a Command to the queue for creating entities with a particular Bundle type.

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

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

Example

commands.spawn_batch(vec![
    (
        Name("Alice".to_string()),
        Score(0),
    ),
    (
        Name("Bob".to_string()),
        Score(0),
    ),
]);

See also

• spawn to spawn an entity with a bundle.
• spawn_empty to spawn an entity without any components.

pub fn insert_or_spawn_batch<I, B>(&mut self, bundles_iter: I)where
    I: 'static + IntoIterator + Send + Sync,
    <I as IntoIterator>::IntoIter: Iterator<Item = (Entity, B)>,
    B: Bundle,

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 get_or_spawn for each bundle, and passing it to insert_bundle, 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 init_resource<R>(&mut self)where
    R: Resource + FromWorld,

Pushes a Command to the queue for inserting a Resource in the World with an inferred value.

The inferred value is determined by the FromWorld trait of the resource. When the command is applied, if the resource already exists, nothing happens.

See World::init_resource for more details.

Example

commands.init_resource::<Scoreboard>();

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

Pushes a Command to the queue for inserting a Resource in the World with a specific value.

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

See World::insert_resource for more details.

Example

commands.insert_resource(Scoreboard {
    current_score: 0,
    high_score: 0,
});

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

Pushes a Command to the queue for removing a Resource from the World.

See World::remove_resource for more details.

Example

commands.remove_resource::<Scoreboard>();

pub fn add<C>(&mut self, command: C)where
    C: Command,

Pushes a generic Command to the command queue.

command can be a built-in command, custom struct that implements Command or a closure that takes &mut World as an argument.

Example

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

struct AddToCounter(u64);

impl Command for AddToCounter {
    fn write(self, world: &mut World) {
        let mut counter = world.get_resource_or_insert_with(Counter::default);
        counter.0 += self.0;
    }
}

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

Trait Implementations

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

type Fetch = CommandQueue