Struct bevy::ecs::prelude::Commands

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

A list of commands that modify a World, running at the end of the stage where they have been invoked.

Usage

Commands is a SystemParam, therefore it is declared as a function parameter:

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

Then, commands can be invoked by calling the methods of commands.

Implementations

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

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

Create a new Commands from a queue and a world.

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

Creates a new empty Entity and returns an EntityCommands builder for it.

To directly spawn an entity with a Bundle included, you can use spawn_bundle instead of .spawn().insert_bundle().

See World::spawn for more details.

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

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

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

Returns an EntityCommands for the given entity (if it exists) or spawns one if it doesn’t exist. This will return None if the entity exists with a different generation.

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_and_forget(&mut self, bundle: impl Bundle)

Spawns a Bundle without pre-allocating an Entity. The Entity will be allocated when this Command is applied.

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

Creates a new entity with the components contained in bundle.

This returns an EntityCommands builder, which enables inserting more components and bundles using a “builder pattern”.

Note that bundle is a Bundle, which is a collection of components. Bundle is automatically implemented for tuples of components. You can also create your own bundle types by deriving Bundle.

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 component bundle.
    commands.spawn_bundle(ExampleBundle {
        a: Component1,
        b: Component2,
    });

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

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

Returns an EntityCommands builder for the requested Entity.

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

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

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

Spawns entities to the World according to the given iterator (or a type that can be converted to it).

The end result of this command is equivalent to iterating bundles_iter and calling spawn on each bundle, but it is more performant due to memory pre-allocation.

Example

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

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

For a given batch of (Entity, Bundle) pairs, either spawns each Entity with the given bundle (if the entity does not exist), or inserts the Bundle (if the entity already exists).

This is faster than doing equivalent operations one-by-one.

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, 

Inserts a resource with standard starting values to the World.

If the resource already exists, nothing happens.

The value given by the FromWorld::from_world method will be used. Note that any resource with the Default trait automatically implements FromWorld, and those default values will be here instead.

See World::init_resource for more details. Note that commands do not take effect immediately. When possible, prefer the equivalent methods on App or World.

Example

commands.init_resource::<Scoreboard>();

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

Inserts a resource to the World, overwriting any previous value of the same type.

See World::insert_resource for more details. Note that commands do not take effect immediately. When possible, prefer the equivalent methods on App or World.

Example

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

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

Removes 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, 

Adds a command directly to the command list.

Example

use bevy_ecs::system::InsertBundle;

fn add_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
    commands.add(InsertBundle {
        entity: player.entity,
        bundle: CombatBundle {
            health: Health(100),
            strength: Strength(40),
            defense: Defense(20),
        },
    });
}

Trait Implementations

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

fn spawn_scene(&mut self, scene_handle: Handle<Scene>)

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

type Fetch = CommandQueue