Struct bevy::ecs::prelude::Commands

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

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§

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.

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.

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.

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).

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
👎Deprecated since 0.9.0: Use spawn instead, which now accepts bundles, components, and tuples of bundles and components.

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

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.

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.

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).

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>();

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,
});

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>();

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§

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Return the T ShaderType for self. When used in AsBindGroup derives, it is safe to assume that all images in self exist. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait. Read more
Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait. Read more
Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s. Read more
Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s. Read more
Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait. Read more

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.
Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more