Struct bevy_ecs::system::Commands

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

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§

source§

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

source

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

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.

source

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.

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

source

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

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

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

source

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

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

source

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

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
source

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
source

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

pub fn spawn_batch<I>(&mut self, bundles_iter: I)
where I: IntoIterator + Send + Sync + 'static, I::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.
source

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

Push a Command onto the queue.

source

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

source

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

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

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

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

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

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

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.

source

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

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.

source

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

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;
}
source

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

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

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.

source

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.

source

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

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

Trait Implementations§

source§

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. Read more
source§

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.
source§

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 Read more
source§

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 apply_deferred.
source§

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

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

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. Read more
source§

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

source§

impl Send for Commands<'_, '_>

source§

impl Sync for Commands<'_, '_>

Auto Trait Implementations§

§

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

§

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

§

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

§

impl<'w, 's> !UnwindSafe for Commands<'w, 's>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> Downcast for T
where T: Any,

source§

fn into_any(self: Box<T>) -> Box<dyn Any>

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.
source§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
source§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
source§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
source§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

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

fn in_current_span(self) -> Instrumented<Self>

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

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> ConditionalSend for T
where T: Send,