Struct valence::ecs::prelude::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 apply_deferred system runs (see apply_deferred 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 apply_deferred 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::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 reborrow(&mut self) -> Commands<'w, '_>

Returns a Commands with a smaller lifetime. This is useful if you have &mut Commands but need Commands.

Examples

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<'_>

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(&mut self, entity: Entity) -> EntityCommands<'_>

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>(&mut self, bundle: T) -> EntityCommands<'_>

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 entity(&mut self, entity: Entity) -> EntityCommands<'_>

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(&mut self, entity: Entity) -> Option<EntityCommands<'_>>

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: IntoIterator + Send + Sync + 'static, <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 push<C>(&mut self, command: C)

where C: Command,

Push a Command onto the queue.

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

where I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static, 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, 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 run_system(&mut self, id: SystemId)

Runs the system corresponding to the given SystemId. Systems are ran in an exclusive and single threaded way. Running slow systems can become a bottleneck.

Calls World::run_system.

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_input instead of running the system as a command.

pub fn run_system_with_input<I>(&mut self, id: SystemId<I>, input: I)

where I: 'static + Send,

Runs the system corresponding to the given SystemId. Systems are ran in an exclusive and single threaded way. Running slow systems can become a bottleneck.

Calls World::run_system_with_input.

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_input instead of running the system as a command.

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

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

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

It’s possible to register the same systems more than once, they’ll be stored separately.

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. This allows for running systems in a push-based fashion. Using a Schedule is still preferred for most cases due to its better performance and ability to run non-conflicting systems simultaneously.

If you want to prevent Commands from registering the same system multiple times, consider using Local

Example

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

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

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

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

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

Sends a “global” [Trigger] without any targets. This will run any Observer of the event that isn’t scoped to specific targets.

pub fn trigger_targets( &mut self, event: impl Event, targets: impl TriggerTargets, )

Sends a [Trigger] for the given targets. This will run any Observer of the event that watches those targets.

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

where E: Event, B: Bundle,

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

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, ) -> <Commands<'_, '_> as SystemParam>::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 <Commands<'_, '_> as SystemParam>::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 <Commands<'_, '_> as SystemParam>::State, system_meta: &SystemMeta, world: &mut World, )

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

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

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

unsafe fn get_param<'w, 's>( state: &'s mut <Commands<'_, '_> as SystemParam>::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> <Commands<'_, '_> as SystemParam>::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<'_, '_>