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>
impl<'w, 's> Commands<'w, 's>
sourcepub fn new(queue: &'s mut CommandQueue, world: &'w World) -> Self
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.
sourcepub fn new_from_entities(
queue: &'s mut CommandQueue,
entities: &'w Entities
) -> Self
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.
sourcepub fn reborrow(&mut self) -> Commands<'w, '_>
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();
}
sourcepub fn append(&mut self, other: &mut CommandQueue)
pub fn append(&mut self, other: &mut CommandQueue)
Take all commands from other
and append them to self
, leaving other
empty
sourcepub fn spawn_empty(&mut self) -> EntityCommands<'_>
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.
sourcepub fn get_or_spawn(&mut self, entity: Entity) -> EntityCommands<'_>
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).
sourcepub fn spawn<T: Bundle>(&mut self, bundle: T) -> EntityCommands<'_>
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
spawn_empty
to spawn an entity without any components.spawn_batch
to spawn entities with a bundle each.
sourcepub fn entity(&mut self, entity: Entity) -> EntityCommands<'_>
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.
sourcepub fn get_entity(&mut self, entity: Entity) -> Option<EntityCommands<'_>>
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.
sourcepub fn spawn_batch<I>(&mut self, bundles_iter: I)
pub fn spawn_batch<I>(&mut self, bundles_iter: I)
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.
sourcepub fn insert_or_spawn_batch<I, B>(&mut self, bundles_iter: I)
pub fn insert_or_spawn_batch<I, B>(&mut self, bundles_iter: I)
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).
sourcepub fn init_resource<R: Resource + FromWorld>(&mut self)
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>();
sourcepub fn insert_resource<R: Resource>(&mut self, resource: R)
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,
});
sourcepub fn remove_resource<R: Resource>(&mut self)
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>();
sourcepub fn run_system(&mut self, id: SystemId)
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.
sourcepub fn run_system_with_input<I: 'static + Send>(
&mut self,
id: SystemId<I>,
input: I
)
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.
sourcepub 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>
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;
}
sourcepub fn add<C: Command>(&mut self, command: C)
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;
});
}
sourcepub fn trigger(&mut self, event: impl Event)
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.
sourcepub fn trigger_targets(
&mut self,
event: impl Event,
targets: impl TriggerTargets
)
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.
sourcepub fn observe<E: Event, B: Bundle, M>(
&mut self,
observer: impl IntoObserverSystem<E, B, M>
) -> EntityCommands<'_>
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<'_, '_>
impl SystemParam for Commands<'_, '_>
§type Item<'w, 's> = Commands<'w, 's>
type Item<'w, 's> = Commands<'w, 's>
Self
, instantiated with new lifetimes. Read moresource§fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State
fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State
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
)
unsafe fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta )
Archetype
, registers the components accessed by this SystemParam
(if applicable).a Read moresource§fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)
fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)
SystemParam
’s state.
This is used to apply Commands
during apply_deferred
.source§fn queue(
state: &mut Self::State,
system_meta: &SystemMeta,
world: DeferredWorld<'_>
)
fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_> )
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>
unsafe fn get_param<'w, 's>( state: &'s mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick ) -> Self::Item<'w, 's>
SystemParamFunction
. Read moreimpl<'w, 's> ReadOnlySystemParam for Commands<'w, 's>
impl Send for Commands<'_, '_>
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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
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>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
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)
fn as_any(&self) -> &(dyn Any + 'static)
&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)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.