bevy_ecs/system/commands/mod.rs
1pub mod command;
2pub mod entity_command;
3
4#[cfg(feature = "std")]
5mod parallel_scope;
6
7use bevy_ptr::move_as_ptr;
8pub use command::Command;
9pub use entity_command::EntityCommand;
10
11#[cfg(feature = "std")]
12pub use parallel_scope::*;
13
14use alloc::boxed::Box;
15use core::marker::PhantomData;
16
17use crate::{
18 self as bevy_ecs,
19 bundle::{Bundle, InsertMode, NoBundleEffect},
20 change_detection::{MaybeLocation, Mut},
21 component::{Component, ComponentId, Mutable},
22 entity::{Entities, Entity, EntityClonerBuilder, EntityDoesNotExistError, OptIn, OptOut},
23 error::{warn, BevyError, CommandWithEntity, ErrorContext, HandleError},
24 event::{EntityEvent, Event},
25 message::Message,
26 observer::Observer,
27 resource::Resource,
28 schedule::ScheduleLabel,
29 system::{
30 Deferred, IntoObserverSystem, IntoSystem, RegisteredSystem, SystemId, SystemInput,
31 SystemParamValidationError,
32 },
33 world::{
34 command_queue::RawCommandQueue, unsafe_world_cell::UnsafeWorldCell, CommandQueue,
35 EntityWorldMut, FromWorld, World,
36 },
37};
38
39/// A [`Command`] queue to perform structural changes to the [`World`].
40///
41/// Since each command requires exclusive access to the `World`,
42/// all queued commands are automatically applied in sequence
43/// when the `ApplyDeferred` system runs (see [`ApplyDeferred`] documentation for more details).
44///
45/// Each command can be used to modify the [`World`] in arbitrary ways:
46/// * spawning or despawning entities
47/// * inserting components on new or existing entities
48/// * inserting resources
49/// * etc.
50///
51/// For a version of [`Commands`] that works in parallel contexts (such as
52/// within [`Query::par_iter`](crate::system::Query::par_iter)) see
53/// [`ParallelCommands`]
54///
55/// # Usage
56///
57/// Add `mut commands: Commands` as a function argument to your system to get a
58/// copy of this struct that will be applied the next time a copy of [`ApplyDeferred`] runs.
59/// Commands are almost always used as a [`SystemParam`](crate::system::SystemParam).
60///
61/// ```
62/// # use bevy_ecs::prelude::*;
63/// fn my_system(mut commands: Commands) {
64/// // ...
65/// }
66/// # bevy_ecs::system::assert_is_system(my_system);
67/// ```
68///
69/// # Implementing
70///
71/// Each built-in command is implemented as a separate method, e.g. [`Commands::spawn`].
72/// In addition to the pre-defined command methods, you can add commands with any arbitrary
73/// behavior using [`Commands::queue`], which accepts any type implementing [`Command`].
74///
75/// Since closures and other functions implement this trait automatically, this allows one-shot,
76/// anonymous custom commands.
77///
78/// ```
79/// # use bevy_ecs::prelude::*;
80/// # fn foo(mut commands: Commands) {
81/// // NOTE: type inference fails here, so annotations are required on the closure.
82/// commands.queue(|w: &mut World| {
83/// // Mutate the world however you want...
84/// });
85/// # }
86/// ```
87///
88/// # Error handling
89///
90/// A [`Command`] can return a [`Result`](crate::error::Result),
91/// which will be passed to an [error handler](crate::error) if the `Result` is an error.
92///
93/// The default error handler panics. It can be configured via
94/// the [`DefaultErrorHandler`](crate::error::DefaultErrorHandler) resource.
95///
96/// Alternatively, you can customize the error handler for a specific command
97/// by calling [`Commands::queue_handled`].
98///
99/// The [`error`](crate::error) module provides some simple error handlers for convenience.
100///
101/// [`ApplyDeferred`]: crate::schedule::ApplyDeferred
102pub struct Commands<'w, 's> {
103 queue: InternalQueue<'s>,
104 entities: &'w Entities,
105}
106
107// SAFETY: All commands [`Command`] implement [`Send`]
108unsafe impl Send for Commands<'_, '_> {}
109
110// SAFETY: `Commands` never gives access to the inner commands.
111unsafe impl Sync for Commands<'_, '_> {}
112
113const _: () = {
114 type __StructFieldsAlias<'w, 's> = (Deferred<'s, CommandQueue>, &'w Entities);
115 #[doc(hidden)]
116 pub struct FetchState {
117 state: <__StructFieldsAlias<'static, 'static> as bevy_ecs::system::SystemParam>::State,
118 }
119 // SAFETY: Only reads Entities
120 unsafe impl bevy_ecs::system::SystemParam for Commands<'_, '_> {
121 type State = FetchState;
122
123 type Item<'w, 's> = Commands<'w, 's>;
124
125 fn init_state(world: &mut World) -> Self::State {
126 FetchState {
127 state: <__StructFieldsAlias<'_, '_> as bevy_ecs::system::SystemParam>::init_state(
128 world,
129 ),
130 }
131 }
132
133 fn init_access(
134 state: &Self::State,
135 system_meta: &mut bevy_ecs::system::SystemMeta,
136 component_access_set: &mut bevy_ecs::query::FilteredAccessSet,
137 world: &mut World,
138 ) {
139 <__StructFieldsAlias<'_, '_> as bevy_ecs::system::SystemParam>::init_access(
140 &state.state,
141 system_meta,
142 component_access_set,
143 world,
144 );
145 }
146
147 fn apply(
148 state: &mut Self::State,
149 system_meta: &bevy_ecs::system::SystemMeta,
150 world: &mut World,
151 ) {
152 <__StructFieldsAlias<'_, '_> as bevy_ecs::system::SystemParam>::apply(
153 &mut state.state,
154 system_meta,
155 world,
156 );
157 }
158
159 fn queue(
160 state: &mut Self::State,
161 system_meta: &bevy_ecs::system::SystemMeta,
162 world: bevy_ecs::world::DeferredWorld,
163 ) {
164 <__StructFieldsAlias<'_, '_> as bevy_ecs::system::SystemParam>::queue(
165 &mut state.state,
166 system_meta,
167 world,
168 );
169 }
170
171 #[inline]
172 unsafe fn validate_param(
173 state: &mut Self::State,
174 system_meta: &bevy_ecs::system::SystemMeta,
175 world: UnsafeWorldCell,
176 ) -> Result<(), SystemParamValidationError> {
177 <(Deferred<CommandQueue>, &Entities) as bevy_ecs::system::SystemParam>::validate_param(
178 &mut state.state,
179 system_meta,
180 world,
181 )
182 }
183
184 #[inline]
185 unsafe fn get_param<'w, 's>(
186 state: &'s mut Self::State,
187 system_meta: &bevy_ecs::system::SystemMeta,
188 world: UnsafeWorldCell<'w>,
189 change_tick: bevy_ecs::component::Tick,
190 ) -> Self::Item<'w, 's> {
191 let(f0, f1) = <(Deferred<'s, CommandQueue>, &'w Entities) as bevy_ecs::system::SystemParam>::get_param(&mut state.state, system_meta, world, change_tick);
192 Commands {
193 queue: InternalQueue::CommandQueue(f0),
194 entities: f1,
195 }
196 }
197 }
198 // SAFETY: Only reads Entities
199 unsafe impl<'w, 's> bevy_ecs::system::ReadOnlySystemParam for Commands<'w, 's>
200 where
201 Deferred<'s, CommandQueue>: bevy_ecs::system::ReadOnlySystemParam,
202 &'w Entities: bevy_ecs::system::ReadOnlySystemParam,
203 {
204 }
205};
206
207enum InternalQueue<'s> {
208 CommandQueue(Deferred<'s, CommandQueue>),
209 RawCommandQueue(RawCommandQueue),
210}
211
212impl<'w, 's> Commands<'w, 's> {
213 /// Returns a new `Commands` instance from a [`CommandQueue`] and a [`World`].
214 pub fn new(queue: &'s mut CommandQueue, world: &'w World) -> Self {
215 Self::new_from_entities(queue, &world.entities)
216 }
217
218 /// Returns a new `Commands` instance from a [`CommandQueue`] and an [`Entities`] reference.
219 pub fn new_from_entities(queue: &'s mut CommandQueue, entities: &'w Entities) -> Self {
220 Self {
221 queue: InternalQueue::CommandQueue(Deferred(queue)),
222 entities,
223 }
224 }
225
226 /// Returns a new `Commands` instance from a [`RawCommandQueue`] and an [`Entities`] reference.
227 ///
228 /// This is used when constructing [`Commands`] from a [`DeferredWorld`](crate::world::DeferredWorld).
229 ///
230 /// # Safety
231 ///
232 /// * Caller ensures that `queue` must outlive `'w`
233 pub(crate) unsafe fn new_raw_from_entities(
234 queue: RawCommandQueue,
235 entities: &'w Entities,
236 ) -> Self {
237 Self {
238 queue: InternalQueue::RawCommandQueue(queue),
239 entities,
240 }
241 }
242
243 /// Returns a [`Commands`] with a smaller lifetime.
244 ///
245 /// This is useful if you have `&mut Commands` but need `Commands`.
246 ///
247 /// # Example
248 ///
249 /// ```
250 /// # use bevy_ecs::prelude::*;
251 /// fn my_system(mut commands: Commands) {
252 /// // We do our initialization in a separate function,
253 /// // which expects an owned `Commands`.
254 /// do_initialization(commands.reborrow());
255 ///
256 /// // Since we only reborrowed the commands instead of moving them, we can still use them.
257 /// commands.spawn_empty();
258 /// }
259 /// #
260 /// # fn do_initialization(_: Commands) {}
261 /// ```
262 pub fn reborrow(&mut self) -> Commands<'w, '_> {
263 Commands {
264 queue: match &mut self.queue {
265 InternalQueue::CommandQueue(queue) => InternalQueue::CommandQueue(queue.reborrow()),
266 InternalQueue::RawCommandQueue(queue) => {
267 InternalQueue::RawCommandQueue(queue.clone())
268 }
269 },
270 entities: self.entities,
271 }
272 }
273
274 /// Take all commands from `other` and append them to `self`, leaving `other` empty.
275 pub fn append(&mut self, other: &mut CommandQueue) {
276 match &mut self.queue {
277 InternalQueue::CommandQueue(queue) => queue.bytes.append(&mut other.bytes),
278 InternalQueue::RawCommandQueue(queue) => {
279 // SAFETY: Pointers in `RawCommandQueue` are never null
280 unsafe { queue.bytes.as_mut() }.append(&mut other.bytes);
281 }
282 }
283 }
284
285 /// Spawns a new empty [`Entity`] and returns its corresponding [`EntityCommands`].
286 ///
287 /// # Example
288 ///
289 /// ```
290 /// # use bevy_ecs::prelude::*;
291 /// #[derive(Component)]
292 /// struct Label(&'static str);
293 /// #[derive(Component)]
294 /// struct Strength(u32);
295 /// #[derive(Component)]
296 /// struct Agility(u32);
297 ///
298 /// fn example_system(mut commands: Commands) {
299 /// // Create a new empty entity.
300 /// commands.spawn_empty();
301 ///
302 /// // Create another empty entity.
303 /// commands.spawn_empty()
304 /// // Add a new component bundle to the entity.
305 /// .insert((Strength(1), Agility(2)))
306 /// // Add a single component to the entity.
307 /// .insert(Label("hello world"));
308 /// }
309 /// # bevy_ecs::system::assert_is_system(example_system);
310 /// ```
311 ///
312 /// # See also
313 ///
314 /// - [`spawn`](Self::spawn) to spawn an entity with components.
315 /// - [`spawn_batch`](Self::spawn_batch) to spawn many entities
316 /// with the same combination of components.
317 #[track_caller]
318 pub fn spawn_empty(&mut self) -> EntityCommands<'_> {
319 let entity = self.entities.reserve_entity();
320 let mut entity_commands = EntityCommands {
321 entity,
322 commands: self.reborrow(),
323 };
324 let caller = MaybeLocation::caller();
325 entity_commands.queue(move |entity: EntityWorldMut| {
326 let index = entity.id().index();
327 let world = entity.into_world_mut();
328 let tick = world.change_tick();
329 // SAFETY: Entity has been flushed
330 unsafe {
331 world.entities_mut().mark_spawn_despawn(index, caller, tick);
332 }
333 });
334 entity_commands
335 }
336
337 /// Spawns a new [`Entity`] with the given components
338 /// and returns the entity's corresponding [`EntityCommands`].
339 ///
340 /// To spawn many entities with the same combination of components,
341 /// [`spawn_batch`](Self::spawn_batch) can be used for better performance.
342 ///
343 /// # Example
344 ///
345 /// ```
346 /// # use bevy_ecs::prelude::*;
347 /// #[derive(Component)]
348 /// struct ComponentA(u32);
349 /// #[derive(Component)]
350 /// struct ComponentB(u32);
351 ///
352 /// #[derive(Bundle)]
353 /// struct ExampleBundle {
354 /// a: ComponentA,
355 /// b: ComponentB,
356 /// }
357 ///
358 /// fn example_system(mut commands: Commands) {
359 /// // Create a new entity with a single component.
360 /// commands.spawn(ComponentA(1));
361 ///
362 /// // Create a new entity with two components using a "tuple bundle".
363 /// commands.spawn((ComponentA(2), ComponentB(1)));
364 ///
365 /// // Create a new entity with a component bundle.
366 /// commands.spawn(ExampleBundle {
367 /// a: ComponentA(3),
368 /// b: ComponentB(2),
369 /// });
370 /// }
371 /// # bevy_ecs::system::assert_is_system(example_system);
372 /// ```
373 ///
374 /// # See also
375 ///
376 /// - [`spawn_empty`](Self::spawn_empty) to spawn an entity without any components.
377 /// - [`spawn_batch`](Self::spawn_batch) to spawn many entities
378 /// with the same combination of components.
379 #[track_caller]
380 pub fn spawn<T: Bundle>(&mut self, bundle: T) -> EntityCommands<'_> {
381 let entity = self.entities.reserve_entity();
382 let mut entity_commands = EntityCommands {
383 entity,
384 commands: self.reborrow(),
385 };
386 let caller = MaybeLocation::caller();
387
388 entity_commands.queue(move |mut entity: EntityWorldMut| {
389 // Store metadata about the spawn operation.
390 // This is the same as in `spawn_empty`, but merged into
391 // the same command for better performance.
392 let index = entity.id().index();
393 entity.world_scope(|world| {
394 let tick = world.change_tick();
395 // SAFETY: Entity has been flushed
396 unsafe {
397 world.entities_mut().mark_spawn_despawn(index, caller, tick);
398 }
399 });
400
401 move_as_ptr!(bundle);
402 entity.insert_with_caller(
403 bundle,
404 InsertMode::Replace,
405 caller,
406 crate::relationship::RelationshipHookMode::Run,
407 );
408 });
409 // entity_command::insert(bundle, InsertMode::Replace)
410 entity_commands
411 }
412
413 /// Returns the [`EntityCommands`] for the given [`Entity`].
414 ///
415 /// This method does not guarantee that commands queued by the returned `EntityCommands`
416 /// will be successful, since the entity could be despawned before they are executed.
417 ///
418 /// # Example
419 ///
420 /// ```
421 /// # use bevy_ecs::prelude::*;
422 /// #[derive(Resource)]
423 /// struct PlayerEntity {
424 /// entity: Entity
425 /// }
426 ///
427 /// #[derive(Component)]
428 /// struct Label(&'static str);
429 ///
430 /// fn example_system(mut commands: Commands, player: Res<PlayerEntity>) {
431 /// // Get the entity and add a component.
432 /// commands.entity(player.entity).insert(Label("hello world"));
433 /// }
434 /// # bevy_ecs::system::assert_is_system(example_system);
435 /// ```
436 ///
437 /// # See also
438 ///
439 /// - [`get_entity`](Self::get_entity) for the fallible version.
440 #[inline]
441 #[track_caller]
442 pub fn entity(&mut self, entity: Entity) -> EntityCommands<'_> {
443 EntityCommands {
444 entity,
445 commands: self.reborrow(),
446 }
447 }
448
449 /// Returns the [`EntityCommands`] for the requested [`Entity`] if it exists.
450 ///
451 /// This method does not guarantee that commands queued by the returned `EntityCommands`
452 /// will be successful, since the entity could be despawned before they are executed.
453 ///
454 /// # Errors
455 ///
456 /// Returns [`EntityDoesNotExistError`] if the requested entity does not exist.
457 ///
458 /// # Example
459 ///
460 /// ```
461 /// # use bevy_ecs::prelude::*;
462 /// #[derive(Resource)]
463 /// struct PlayerEntity {
464 /// entity: Entity
465 /// }
466 ///
467 /// #[derive(Component)]
468 /// struct Label(&'static str);
469 ///
470 /// fn example_system(mut commands: Commands, player: Res<PlayerEntity>) -> Result {
471 /// // Get the entity if it still exists and store the `EntityCommands`.
472 /// // If it doesn't exist, the `?` operator will propagate the returned error
473 /// // to the system, and the system will pass it to an error handler.
474 /// let mut entity_commands = commands.get_entity(player.entity)?;
475 ///
476 /// // Add a component to the entity.
477 /// entity_commands.insert(Label("hello world"));
478 ///
479 /// // Return from the system successfully.
480 /// Ok(())
481 /// }
482 /// # bevy_ecs::system::assert_is_system::<(), (), _>(example_system);
483 /// ```
484 ///
485 /// # See also
486 ///
487 /// - [`entity`](Self::entity) for the infallible version.
488 #[inline]
489 #[track_caller]
490 pub fn get_entity(
491 &mut self,
492 entity: Entity,
493 ) -> Result<EntityCommands<'_>, EntityDoesNotExistError> {
494 if self.entities.contains(entity) {
495 Ok(EntityCommands {
496 entity,
497 commands: self.reborrow(),
498 })
499 } else {
500 Err(EntityDoesNotExistError::new(entity, self.entities))
501 }
502 }
503
504 /// Spawns multiple entities with the same combination of components,
505 /// based on a batch of [`Bundles`](Bundle).
506 ///
507 /// A batch can be any type that implements [`IntoIterator`] and contains bundles,
508 /// such as a [`Vec<Bundle>`](alloc::vec::Vec) or an array `[Bundle; N]`.
509 ///
510 /// This method is equivalent to iterating the batch
511 /// and calling [`spawn`](Self::spawn) for each bundle,
512 /// but is faster by pre-allocating memory and having exclusive [`World`] access.
513 ///
514 /// # Example
515 ///
516 /// ```
517 /// use bevy_ecs::prelude::*;
518 ///
519 /// #[derive(Component)]
520 /// struct Score(u32);
521 ///
522 /// fn example_system(mut commands: Commands) {
523 /// commands.spawn_batch([
524 /// (Name::new("Alice"), Score(0)),
525 /// (Name::new("Bob"), Score(0)),
526 /// ]);
527 /// }
528 /// # bevy_ecs::system::assert_is_system(example_system);
529 /// ```
530 ///
531 /// # See also
532 ///
533 /// - [`spawn`](Self::spawn) to spawn an entity with components.
534 /// - [`spawn_empty`](Self::spawn_empty) to spawn an entity without components.
535 #[track_caller]
536 pub fn spawn_batch<I>(&mut self, batch: I)
537 where
538 I: IntoIterator + Send + Sync + 'static,
539 I::Item: Bundle<Effect: NoBundleEffect>,
540 {
541 self.queue(command::spawn_batch(batch));
542 }
543
544 /// Pushes a generic [`Command`] to the command queue.
545 ///
546 /// If the [`Command`] returns a [`Result`],
547 /// it will be handled using the [default error handler](crate::error::DefaultErrorHandler).
548 ///
549 /// To use a custom error handler, see [`Commands::queue_handled`].
550 ///
551 /// The command can be:
552 /// - A custom struct that implements [`Command`].
553 /// - A closure or function that matches one of the following signatures:
554 /// - [`(&mut World)`](World)
555 /// - A built-in command from the [`command`] module.
556 ///
557 /// # Example
558 ///
559 /// ```
560 /// # use bevy_ecs::prelude::*;
561 /// #[derive(Resource, Default)]
562 /// struct Counter(u64);
563 ///
564 /// struct AddToCounter(String);
565 ///
566 /// impl Command<Result> for AddToCounter {
567 /// fn apply(self, world: &mut World) -> Result {
568 /// let mut counter = world.get_resource_or_insert_with(Counter::default);
569 /// let amount: u64 = self.0.parse()?;
570 /// counter.0 += amount;
571 /// Ok(())
572 /// }
573 /// }
574 ///
575 /// fn add_three_to_counter_system(mut commands: Commands) {
576 /// commands.queue(AddToCounter("3".to_string()));
577 /// }
578 ///
579 /// fn add_twenty_five_to_counter_system(mut commands: Commands) {
580 /// commands.queue(|world: &mut World| {
581 /// let mut counter = world.get_resource_or_insert_with(Counter::default);
582 /// counter.0 += 25;
583 /// });
584 /// }
585 /// # bevy_ecs::system::assert_is_system(add_three_to_counter_system);
586 /// # bevy_ecs::system::assert_is_system(add_twenty_five_to_counter_system);
587 /// ```
588 pub fn queue<C: Command<T> + HandleError<T>, T>(&mut self, command: C) {
589 self.queue_internal(command.handle_error());
590 }
591
592 /// Pushes a generic [`Command`] to the command queue.
593 ///
594 /// If the [`Command`] returns a [`Result`],
595 /// the given `error_handler` will be used to handle error cases.
596 ///
597 /// To implicitly use the default error handler, see [`Commands::queue`].
598 ///
599 /// The command can be:
600 /// - A custom struct that implements [`Command`].
601 /// - A closure or function that matches one of the following signatures:
602 /// - [`(&mut World)`](World)
603 /// - [`(&mut World)`](World) `->` [`Result`]
604 /// - A built-in command from the [`command`] module.
605 ///
606 /// # Example
607 ///
608 /// ```
609 /// # use bevy_ecs::prelude::*;
610 /// use bevy_ecs::error::warn;
611 ///
612 /// #[derive(Resource, Default)]
613 /// struct Counter(u64);
614 ///
615 /// struct AddToCounter(String);
616 ///
617 /// impl Command<Result> for AddToCounter {
618 /// fn apply(self, world: &mut World) -> Result {
619 /// let mut counter = world.get_resource_or_insert_with(Counter::default);
620 /// let amount: u64 = self.0.parse()?;
621 /// counter.0 += amount;
622 /// Ok(())
623 /// }
624 /// }
625 ///
626 /// fn add_three_to_counter_system(mut commands: Commands) {
627 /// commands.queue_handled(AddToCounter("3".to_string()), warn);
628 /// }
629 ///
630 /// fn add_twenty_five_to_counter_system(mut commands: Commands) {
631 /// commands.queue(|world: &mut World| {
632 /// let mut counter = world.get_resource_or_insert_with(Counter::default);
633 /// counter.0 += 25;
634 /// });
635 /// }
636 /// # bevy_ecs::system::assert_is_system(add_three_to_counter_system);
637 /// # bevy_ecs::system::assert_is_system(add_twenty_five_to_counter_system);
638 /// ```
639 pub fn queue_handled<C: Command<T> + HandleError<T>, T>(
640 &mut self,
641 command: C,
642 error_handler: fn(BevyError, ErrorContext),
643 ) {
644 self.queue_internal(command.handle_error_with(error_handler));
645 }
646
647 /// Pushes a generic [`Command`] to the queue like [`Commands::queue_handled`], but instead silently ignores any errors.
648 pub fn queue_silenced<C: Command<T> + HandleError<T>, T>(&mut self, command: C) {
649 self.queue_internal(command.ignore_error());
650 }
651
652 fn queue_internal(&mut self, command: impl Command) {
653 match &mut self.queue {
654 InternalQueue::CommandQueue(queue) => {
655 queue.push(command);
656 }
657 InternalQueue::RawCommandQueue(queue) => {
658 // SAFETY: `RawCommandQueue` is only every constructed in `Commands::new_raw_from_entities`
659 // where the caller of that has ensured that `queue` outlives `self`
660 unsafe {
661 queue.push(command);
662 }
663 }
664 }
665 }
666
667 /// Adds a series of [`Bundles`](Bundle) to each [`Entity`] they are paired with,
668 /// based on a batch of `(Entity, Bundle)` pairs.
669 ///
670 /// A batch can be any type that implements [`IntoIterator`]
671 /// and contains `(Entity, Bundle)` tuples,
672 /// such as a [`Vec<(Entity, Bundle)>`](alloc::vec::Vec)
673 /// or an array `[(Entity, Bundle); N]`.
674 ///
675 /// This will overwrite any pre-existing components shared by the [`Bundle`] type.
676 /// Use [`Commands::insert_batch_if_new`] to keep the pre-existing components instead.
677 ///
678 /// This method is equivalent to iterating the batch
679 /// and calling [`insert`](EntityCommands::insert) for each pair,
680 /// but is faster by caching data that is shared between entities.
681 ///
682 /// # Fallible
683 ///
684 /// This command will fail if any of the given entities do not exist.
685 ///
686 /// It will internally return a [`TryInsertBatchError`](crate::world::error::TryInsertBatchError),
687 /// which will be handled by the [default error handler](crate::error::DefaultErrorHandler).
688 #[track_caller]
689 pub fn insert_batch<I, B>(&mut self, batch: I)
690 where
691 I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static,
692 B: Bundle<Effect: NoBundleEffect>,
693 {
694 self.queue(command::insert_batch(batch, InsertMode::Replace));
695 }
696
697 /// Adds a series of [`Bundles`](Bundle) to each [`Entity`] they are paired with,
698 /// based on a batch of `(Entity, Bundle)` pairs.
699 ///
700 /// A batch can be any type that implements [`IntoIterator`]
701 /// and contains `(Entity, Bundle)` tuples,
702 /// such as a [`Vec<(Entity, Bundle)>`](alloc::vec::Vec)
703 /// or an array `[(Entity, Bundle); N]`.
704 ///
705 /// This will keep any pre-existing components shared by the [`Bundle`] type
706 /// and discard the new values.
707 /// Use [`Commands::insert_batch`] to overwrite the pre-existing components instead.
708 ///
709 /// This method is equivalent to iterating the batch
710 /// and calling [`insert_if_new`](EntityCommands::insert_if_new) for each pair,
711 /// but is faster by caching data that is shared between entities.
712 ///
713 /// # Fallible
714 ///
715 /// This command will fail if any of the given entities do not exist.
716 ///
717 /// It will internally return a [`TryInsertBatchError`](crate::world::error::TryInsertBatchError),
718 /// which will be handled by the [default error handler](crate::error::DefaultErrorHandler).
719 #[track_caller]
720 pub fn insert_batch_if_new<I, B>(&mut self, batch: I)
721 where
722 I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static,
723 B: Bundle<Effect: NoBundleEffect>,
724 {
725 self.queue(command::insert_batch(batch, InsertMode::Keep));
726 }
727
728 /// Adds a series of [`Bundles`](Bundle) to each [`Entity`] they are paired with,
729 /// based on a batch of `(Entity, Bundle)` pairs.
730 ///
731 /// A batch can be any type that implements [`IntoIterator`]
732 /// and contains `(Entity, Bundle)` tuples,
733 /// such as a [`Vec<(Entity, Bundle)>`](alloc::vec::Vec)
734 /// or an array `[(Entity, Bundle); N]`.
735 ///
736 /// This will overwrite any pre-existing components shared by the [`Bundle`] type.
737 /// Use [`Commands::try_insert_batch_if_new`] to keep the pre-existing components instead.
738 ///
739 /// This method is equivalent to iterating the batch
740 /// and calling [`insert`](EntityCommands::insert) for each pair,
741 /// but is faster by caching data that is shared between entities.
742 ///
743 /// # Fallible
744 ///
745 /// This command will fail if any of the given entities do not exist.
746 ///
747 /// It will internally return a [`TryInsertBatchError`](crate::world::error::TryInsertBatchError),
748 /// which will be handled by [logging the error at the `warn` level](warn).
749 #[track_caller]
750 pub fn try_insert_batch<I, B>(&mut self, batch: I)
751 where
752 I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static,
753 B: Bundle<Effect: NoBundleEffect>,
754 {
755 self.queue(command::insert_batch(batch, InsertMode::Replace).handle_error_with(warn));
756 }
757
758 /// Adds a series of [`Bundles`](Bundle) to each [`Entity`] they are paired with,
759 /// based on a batch of `(Entity, Bundle)` pairs.
760 ///
761 /// A batch can be any type that implements [`IntoIterator`]
762 /// and contains `(Entity, Bundle)` tuples,
763 /// such as a [`Vec<(Entity, Bundle)>`](alloc::vec::Vec)
764 /// or an array `[(Entity, Bundle); N]`.
765 ///
766 /// This will keep any pre-existing components shared by the [`Bundle`] type
767 /// and discard the new values.
768 /// Use [`Commands::try_insert_batch`] to overwrite the pre-existing components instead.
769 ///
770 /// This method is equivalent to iterating the batch
771 /// and calling [`insert_if_new`](EntityCommands::insert_if_new) for each pair,
772 /// but is faster by caching data that is shared between entities.
773 ///
774 /// # Fallible
775 ///
776 /// This command will fail if any of the given entities do not exist.
777 ///
778 /// It will internally return a [`TryInsertBatchError`](crate::world::error::TryInsertBatchError),
779 /// which will be handled by [logging the error at the `warn` level](warn).
780 #[track_caller]
781 pub fn try_insert_batch_if_new<I, B>(&mut self, batch: I)
782 where
783 I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static,
784 B: Bundle<Effect: NoBundleEffect>,
785 {
786 self.queue(command::insert_batch(batch, InsertMode::Keep).handle_error_with(warn));
787 }
788
789 /// Inserts a [`Resource`] into the [`World`] with an inferred value.
790 ///
791 /// The inferred value is determined by the [`FromWorld`] trait of the resource.
792 /// Note that any resource with the [`Default`] trait automatically implements [`FromWorld`],
793 /// and those default values will be used.
794 ///
795 /// If the resource already exists when the command is applied, nothing happens.
796 ///
797 /// # Example
798 ///
799 /// ```
800 /// # use bevy_ecs::prelude::*;
801 /// #[derive(Resource, Default)]
802 /// struct Scoreboard {
803 /// current_score: u32,
804 /// high_score: u32,
805 /// }
806 ///
807 /// fn initialize_scoreboard(mut commands: Commands) {
808 /// commands.init_resource::<Scoreboard>();
809 /// }
810 /// # bevy_ecs::system::assert_is_system(initialize_scoreboard);
811 /// ```
812 #[track_caller]
813 pub fn init_resource<R: Resource + FromWorld>(&mut self) {
814 self.queue(command::init_resource::<R>());
815 }
816
817 /// Inserts a [`Resource`] into the [`World`] with a specific value.
818 ///
819 /// This will overwrite any previous value of the same resource type.
820 ///
821 /// # Example
822 ///
823 /// ```
824 /// # use bevy_ecs::prelude::*;
825 /// #[derive(Resource)]
826 /// struct Scoreboard {
827 /// current_score: u32,
828 /// high_score: u32,
829 /// }
830 ///
831 /// fn system(mut commands: Commands) {
832 /// commands.insert_resource(Scoreboard {
833 /// current_score: 0,
834 /// high_score: 0,
835 /// });
836 /// }
837 /// # bevy_ecs::system::assert_is_system(system);
838 /// ```
839 #[track_caller]
840 pub fn insert_resource<R: Resource>(&mut self, resource: R) {
841 self.queue(command::insert_resource(resource));
842 }
843
844 /// Removes a [`Resource`] from the [`World`].
845 ///
846 /// # Example
847 ///
848 /// ```
849 /// # use bevy_ecs::prelude::*;
850 /// #[derive(Resource)]
851 /// struct Scoreboard {
852 /// current_score: u32,
853 /// high_score: u32,
854 /// }
855 ///
856 /// fn system(mut commands: Commands) {
857 /// commands.remove_resource::<Scoreboard>();
858 /// }
859 /// # bevy_ecs::system::assert_is_system(system);
860 /// ```
861 pub fn remove_resource<R: Resource>(&mut self) {
862 self.queue(command::remove_resource::<R>());
863 }
864
865 /// Runs the system corresponding to the given [`SystemId`].
866 /// Before running a system, it must first be registered via
867 /// [`Commands::register_system`] or [`World::register_system`].
868 ///
869 /// The system is run in an exclusive and single-threaded way.
870 /// Running slow systems can become a bottleneck.
871 ///
872 /// There is no way to get the output of a system when run as a command, because the
873 /// execution of the system happens later. To get the output of a system, use
874 /// [`World::run_system`] or [`World::run_system_with`] instead of running the system as a command.
875 ///
876 /// # Fallible
877 ///
878 /// This command will fail if the given [`SystemId`]
879 /// does not correspond to a [`System`](crate::system::System).
880 ///
881 /// It will internally return a [`RegisteredSystemError`](crate::system::system_registry::RegisteredSystemError),
882 /// which will be handled by [logging the error at the `warn` level](warn).
883 pub fn run_system(&mut self, id: SystemId) {
884 self.queue(command::run_system(id).handle_error_with(warn));
885 }
886
887 /// Runs the system corresponding to the given [`SystemId`] with input.
888 /// Before running a system, it must first be registered via
889 /// [`Commands::register_system`] or [`World::register_system`].
890 ///
891 /// The system is run in an exclusive and single-threaded way.
892 /// Running slow systems can become a bottleneck.
893 ///
894 /// There is no way to get the output of a system when run as a command, because the
895 /// execution of the system happens later. To get the output of a system, use
896 /// [`World::run_system`] or [`World::run_system_with`] instead of running the system as a command.
897 ///
898 /// # Fallible
899 ///
900 /// This command will fail if the given [`SystemId`]
901 /// does not correspond to a [`System`](crate::system::System).
902 ///
903 /// It will internally return a [`RegisteredSystemError`](crate::system::system_registry::RegisteredSystemError),
904 /// which will be handled by [logging the error at the `warn` level](warn).
905 pub fn run_system_with<I>(&mut self, id: SystemId<I>, input: I::Inner<'static>)
906 where
907 I: SystemInput<Inner<'static>: Send> + 'static,
908 {
909 self.queue(command::run_system_with(id, input).handle_error_with(warn));
910 }
911
912 /// Registers a system and returns its [`SystemId`] so it can later be called by
913 /// [`Commands::run_system`] or [`World::run_system`].
914 ///
915 /// This is different from adding systems to a [`Schedule`](crate::schedule::Schedule),
916 /// because the [`SystemId`] that is returned can be used anywhere in the [`World`] to run the associated system.
917 ///
918 /// Using a [`Schedule`](crate::schedule::Schedule) is still preferred for most cases
919 /// due to its better performance and ability to run non-conflicting systems simultaneously.
920 ///
921 /// # Note
922 ///
923 /// If the same system is registered more than once,
924 /// each registration will be considered a different system,
925 /// and they will each be given their own [`SystemId`].
926 ///
927 /// If you want to avoid registering the same system multiple times,
928 /// consider using [`Commands::run_system_cached`] or storing the [`SystemId`]
929 /// in a [`Local`](crate::system::Local).
930 ///
931 /// # Example
932 ///
933 /// ```
934 /// # use bevy_ecs::{prelude::*, world::CommandQueue, system::SystemId};
935 /// #[derive(Resource)]
936 /// struct Counter(i32);
937 ///
938 /// fn register_system(
939 /// mut commands: Commands,
940 /// mut local_system: Local<Option<SystemId>>,
941 /// ) {
942 /// if let Some(system) = *local_system {
943 /// commands.run_system(system);
944 /// } else {
945 /// *local_system = Some(commands.register_system(increment_counter));
946 /// }
947 /// }
948 ///
949 /// fn increment_counter(mut value: ResMut<Counter>) {
950 /// value.0 += 1;
951 /// }
952 ///
953 /// # let mut world = World::default();
954 /// # world.insert_resource(Counter(0));
955 /// # let mut queue_1 = CommandQueue::default();
956 /// # let systemid = {
957 /// # let mut commands = Commands::new(&mut queue_1, &world);
958 /// # commands.register_system(increment_counter)
959 /// # };
960 /// # let mut queue_2 = CommandQueue::default();
961 /// # {
962 /// # let mut commands = Commands::new(&mut queue_2, &world);
963 /// # commands.run_system(systemid);
964 /// # }
965 /// # queue_1.append(&mut queue_2);
966 /// # queue_1.apply(&mut world);
967 /// # assert_eq!(1, world.resource::<Counter>().0);
968 /// # bevy_ecs::system::assert_is_system(register_system);
969 /// ```
970 pub fn register_system<I, O, M>(
971 &mut self,
972 system: impl IntoSystem<I, O, M> + 'static,
973 ) -> SystemId<I, O>
974 where
975 I: SystemInput + Send + 'static,
976 O: Send + 'static,
977 {
978 let entity = self.spawn_empty().id();
979 let system = RegisteredSystem::<I, O>::new(Box::new(IntoSystem::into_system(system)));
980 self.entity(entity).insert(system);
981 SystemId::from_entity(entity)
982 }
983
984 /// Removes a system previously registered with [`Commands::register_system`]
985 /// or [`World::register_system`].
986 ///
987 /// After removing a system, the [`SystemId`] becomes invalid
988 /// and attempting to use it afterwards will result in an error.
989 /// Re-adding the removed system will register it with a new `SystemId`.
990 ///
991 /// # Fallible
992 ///
993 /// This command will fail if the given [`SystemId`]
994 /// does not correspond to a [`System`](crate::system::System).
995 ///
996 /// It will internally return a [`RegisteredSystemError`](crate::system::system_registry::RegisteredSystemError),
997 /// which will be handled by [logging the error at the `warn` level](warn).
998 pub fn unregister_system<I, O>(&mut self, system_id: SystemId<I, O>)
999 where
1000 I: SystemInput + Send + 'static,
1001 O: Send + 'static,
1002 {
1003 self.queue(command::unregister_system(system_id).handle_error_with(warn));
1004 }
1005
1006 /// Removes a system previously registered with one of the following:
1007 /// - [`Commands::run_system_cached`]
1008 /// - [`World::run_system_cached`]
1009 /// - [`World::register_system_cached`]
1010 ///
1011 /// # Fallible
1012 ///
1013 /// This command will fail if the given system
1014 /// is not currently cached in a [`CachedSystemId`](crate::system::CachedSystemId) resource.
1015 ///
1016 /// It will internally return a [`RegisteredSystemError`](crate::system::system_registry::RegisteredSystemError),
1017 /// which will be handled by [logging the error at the `warn` level](warn).
1018 pub fn unregister_system_cached<I, O, M, S>(&mut self, system: S)
1019 where
1020 I: SystemInput + Send + 'static,
1021 O: 'static,
1022 M: 'static,
1023 S: IntoSystem<I, O, M> + Send + 'static,
1024 {
1025 self.queue(command::unregister_system_cached(system).handle_error_with(warn));
1026 }
1027
1028 /// Runs a cached system, registering it if necessary.
1029 ///
1030 /// Unlike [`Commands::run_system`], this method does not require manual registration.
1031 ///
1032 /// The first time this method is called for a particular system,
1033 /// it will register the system and store its [`SystemId`] in a
1034 /// [`CachedSystemId`](crate::system::CachedSystemId) resource for later.
1035 ///
1036 /// If you would rather manage the [`SystemId`] yourself,
1037 /// or register multiple copies of the same system,
1038 /// use [`Commands::register_system`] instead.
1039 ///
1040 /// # Limitations
1041 ///
1042 /// This method only accepts ZST (zero-sized) systems to guarantee that any two systems of
1043 /// the same type must be equal. This means that closures that capture the environment, and
1044 /// function pointers, are not accepted.
1045 ///
1046 /// If you want to access values from the environment within a system,
1047 /// consider passing them in as inputs via [`Commands::run_system_cached_with`].
1048 ///
1049 /// If that's not an option, consider [`Commands::register_system`] instead.
1050 pub fn run_system_cached<M, S>(&mut self, system: S)
1051 where
1052 M: 'static,
1053 S: IntoSystem<(), (), M> + Send + 'static,
1054 {
1055 self.queue(command::run_system_cached(system).handle_error_with(warn));
1056 }
1057
1058 /// Runs a cached system with an input, registering it if necessary.
1059 ///
1060 /// Unlike [`Commands::run_system_with`], this method does not require manual registration.
1061 ///
1062 /// The first time this method is called for a particular system,
1063 /// it will register the system and store its [`SystemId`] in a
1064 /// [`CachedSystemId`](crate::system::CachedSystemId) resource for later.
1065 ///
1066 /// If you would rather manage the [`SystemId`] yourself,
1067 /// or register multiple copies of the same system,
1068 /// use [`Commands::register_system`] instead.
1069 ///
1070 /// # Limitations
1071 ///
1072 /// This method only accepts ZST (zero-sized) systems to guarantee that any two systems of
1073 /// the same type must be equal. This means that closures that capture the environment, and
1074 /// function pointers, are not accepted.
1075 ///
1076 /// If you want to access values from the environment within a system,
1077 /// consider passing them in as inputs.
1078 ///
1079 /// If that's not an option, consider [`Commands::register_system`] instead.
1080 pub fn run_system_cached_with<I, M, S>(&mut self, system: S, input: I::Inner<'static>)
1081 where
1082 I: SystemInput<Inner<'static>: Send> + Send + 'static,
1083 M: 'static,
1084 S: IntoSystem<I, (), M> + Send + 'static,
1085 {
1086 self.queue(command::run_system_cached_with(system, input).handle_error_with(warn));
1087 }
1088
1089 /// Triggers the given [`Event`], which will run any [`Observer`]s watching for it.
1090 ///
1091 /// [`Observer`]: crate::observer::Observer
1092 #[track_caller]
1093 pub fn trigger<'a>(&mut self, event: impl Event<Trigger<'a>: Default>) {
1094 self.queue(command::trigger(event));
1095 }
1096
1097 /// A deprecated alias for [`trigger`](Self::trigger) to ease migration.
1098 ///
1099 /// Instead of specifying the trigger target separately,
1100 /// information about the target of the event is embedded in the data held by
1101 /// the event type itself.
1102 #[deprecated(since = "0.17.0", note = "Use `Commands::trigger` instead.")]
1103 pub fn trigger_targets<'a>(&mut self, event: impl Event<Trigger<'a>: Default>) {
1104 self.trigger(event);
1105 }
1106
1107 /// Triggers the given [`Event`] using the given [`Trigger`], which will run any [`Observer`]s watching for it.
1108 ///
1109 /// [`Trigger`]: crate::event::Trigger
1110 /// [`Observer`]: crate::observer::Observer
1111 #[track_caller]
1112 pub fn trigger_with<E: Event<Trigger<'static>: Send + Sync>>(
1113 &mut self,
1114 event: E,
1115 trigger: E::Trigger<'static>,
1116 ) {
1117 self.queue(command::trigger_with(event, trigger));
1118 }
1119
1120 /// Spawns an [`Observer`] and returns the [`EntityCommands`] associated
1121 /// with the entity that stores the observer.
1122 ///
1123 /// `observer` can be any system whose first parameter is [`On`].
1124 ///
1125 /// **Calling [`observe`](EntityCommands::observe) on the returned
1126 /// [`EntityCommands`] will observe the observer itself, which you very
1127 /// likely do not want.**
1128 ///
1129 /// # Panics
1130 ///
1131 /// Panics if the given system is an exclusive system.
1132 ///
1133 /// [`On`]: crate::observer::On
1134 pub fn add_observer<E: Event, B: Bundle, M>(
1135 &mut self,
1136 observer: impl IntoObserverSystem<E, B, M>,
1137 ) -> EntityCommands<'_> {
1138 self.spawn(Observer::new(observer))
1139 }
1140
1141 /// Writes an arbitrary [`Message`].
1142 ///
1143 /// This is a convenience method for writing messages
1144 /// without requiring a [`MessageWriter`](crate::message::MessageWriter).
1145 ///
1146 /// # Performance
1147 ///
1148 /// Since this is a command, exclusive world access is used, which means that it will not profit from
1149 /// system-level parallelism on supported platforms.
1150 ///
1151 /// If these messages are performance-critical or very frequently sent,
1152 /// consider using a [`MessageWriter`](crate::message::MessageWriter) instead.
1153 #[track_caller]
1154 pub fn write_message<M: Message>(&mut self, message: M) -> &mut Self {
1155 self.queue(command::write_message(message));
1156 self
1157 }
1158
1159 /// Writes an arbitrary [`Message`].
1160 ///
1161 /// This is a convenience method for writing events
1162 /// without requiring a [`MessageWriter`](crate::message::MessageWriter).
1163 ///
1164 /// # Performance
1165 ///
1166 /// Since this is a command, exclusive world access is used, which means that it will not profit from
1167 /// system-level parallelism on supported platforms.
1168 ///
1169 /// If these events are performance-critical or very frequently sent,
1170 /// consider using a typed [`MessageWriter`](crate::message::MessageWriter) instead.
1171 #[track_caller]
1172 #[deprecated(since = "0.17.0", note = "Use `Commands::write_message` instead.")]
1173 pub fn send_event<E: Message>(&mut self, event: E) -> &mut Self {
1174 self.write_message(event)
1175 }
1176
1177 /// Runs the schedule corresponding to the given [`ScheduleLabel`].
1178 ///
1179 /// Calls [`World::try_run_schedule`](World::try_run_schedule).
1180 ///
1181 /// # Fallible
1182 ///
1183 /// This command will fail if the given [`ScheduleLabel`]
1184 /// does not correspond to a [`Schedule`](crate::schedule::Schedule).
1185 ///
1186 /// It will internally return a [`TryRunScheduleError`](crate::world::error::TryRunScheduleError),
1187 /// which will be handled by [logging the error at the `warn` level](warn).
1188 ///
1189 /// # Example
1190 ///
1191 /// ```
1192 /// # use bevy_ecs::prelude::*;
1193 /// # use bevy_ecs::schedule::ScheduleLabel;
1194 /// # #[derive(Default, Resource)]
1195 /// # struct Counter(u32);
1196 /// #[derive(ScheduleLabel, Hash, Debug, PartialEq, Eq, Clone, Copy)]
1197 /// struct FooSchedule;
1198 ///
1199 /// # fn foo_system(mut counter: ResMut<Counter>) {
1200 /// # counter.0 += 1;
1201 /// # }
1202 /// #
1203 /// # let mut schedule = Schedule::new(FooSchedule);
1204 /// # schedule.add_systems(foo_system);
1205 /// #
1206 /// # let mut world = World::default();
1207 /// #
1208 /// # world.init_resource::<Counter>();
1209 /// # world.add_schedule(schedule);
1210 /// #
1211 /// # assert_eq!(world.resource::<Counter>().0, 0);
1212 /// #
1213 /// # let mut commands = world.commands();
1214 /// commands.run_schedule(FooSchedule);
1215 /// #
1216 /// # world.flush();
1217 /// #
1218 /// # assert_eq!(world.resource::<Counter>().0, 1);
1219 /// ```
1220 pub fn run_schedule(&mut self, label: impl ScheduleLabel) {
1221 self.queue(command::run_schedule(label).handle_error_with(warn));
1222 }
1223}
1224
1225/// A list of commands that will be run to modify an [`Entity`].
1226///
1227/// # Note
1228///
1229/// Most [`Commands`] (and thereby [`EntityCommands`]) are deferred:
1230/// when you call the command, if it requires mutable access to the [`World`]
1231/// (that is, if it removes, adds, or changes something), it's not executed immediately.
1232///
1233/// Instead, the command is added to a "command queue."
1234/// The command queue is applied later
1235/// when the [`ApplyDeferred`](crate::schedule::ApplyDeferred) system runs.
1236/// Commands are executed one-by-one so that
1237/// each command can have exclusive access to the `World`.
1238///
1239/// # Fallible
1240///
1241/// Due to their deferred nature, an entity you're trying to change with an [`EntityCommand`]
1242/// can be despawned by the time the command is executed.
1243///
1244/// All deferred entity commands will check whether the entity exists at the time of execution
1245/// and will return an error if it doesn't.
1246///
1247/// # Error handling
1248///
1249/// An [`EntityCommand`] can return a [`Result`](crate::error::Result),
1250/// which will be passed to an [error handler](crate::error) if the `Result` is an error.
1251///
1252/// The default error handler panics. It can be configured via
1253/// the [`DefaultErrorHandler`](crate::error::DefaultErrorHandler) resource.
1254///
1255/// Alternatively, you can customize the error handler for a specific command
1256/// by calling [`EntityCommands::queue_handled`].
1257///
1258/// The [`error`](crate::error) module provides some simple error handlers for convenience.
1259pub struct EntityCommands<'a> {
1260 pub(crate) entity: Entity,
1261 pub(crate) commands: Commands<'a, 'a>,
1262}
1263
1264impl<'a> EntityCommands<'a> {
1265 /// Returns the [`Entity`] id of the entity.
1266 ///
1267 /// # Example
1268 ///
1269 /// ```
1270 /// # use bevy_ecs::prelude::*;
1271 /// #
1272 /// fn my_system(mut commands: Commands) {
1273 /// let entity_id = commands.spawn_empty().id();
1274 /// }
1275 /// # bevy_ecs::system::assert_is_system(my_system);
1276 /// ```
1277 #[inline]
1278 #[must_use = "Omit the .id() call if you do not need to store the `Entity` identifier."]
1279 pub fn id(&self) -> Entity {
1280 self.entity
1281 }
1282
1283 /// Returns an [`EntityCommands`] with a smaller lifetime.
1284 ///
1285 /// This is useful if you have `&mut EntityCommands` but you need `EntityCommands`.
1286 pub fn reborrow(&mut self) -> EntityCommands<'_> {
1287 EntityCommands {
1288 entity: self.entity,
1289 commands: self.commands.reborrow(),
1290 }
1291 }
1292
1293 /// Get an [`EntityEntryCommands`] for the [`Component`] `T`,
1294 /// allowing you to modify it or insert it if it isn't already present.
1295 ///
1296 /// See also [`insert_if_new`](Self::insert_if_new),
1297 /// which lets you insert a [`Bundle`] without overwriting it.
1298 ///
1299 /// # Example
1300 ///
1301 /// ```
1302 /// # use bevy_ecs::prelude::*;
1303 /// # #[derive(Resource)]
1304 /// # struct PlayerEntity { entity: Entity }
1305 /// #[derive(Component)]
1306 /// struct Level(u32);
1307 ///
1308 ///
1309 /// #[derive(Component, Default)]
1310 /// struct Mana {
1311 /// max: u32,
1312 /// current: u32,
1313 /// }
1314 ///
1315 /// fn level_up_system(mut commands: Commands, player: Res<PlayerEntity>) {
1316 /// // If a component already exists then modify it, otherwise insert a default value
1317 /// commands
1318 /// .entity(player.entity)
1319 /// .entry::<Level>()
1320 /// .and_modify(|mut lvl| lvl.0 += 1)
1321 /// .or_insert(Level(0));
1322 ///
1323 /// // Add a default value if none exists, and then modify the existing or new value
1324 /// commands
1325 /// .entity(player.entity)
1326 /// .entry::<Mana>()
1327 /// .or_default()
1328 /// .and_modify(|mut mana| {
1329 /// mana.max += 10;
1330 /// mana.current = mana.max;
1331 /// });
1332 /// }
1333 ///
1334 /// # bevy_ecs::system::assert_is_system(level_up_system);
1335 /// ```
1336 pub fn entry<T: Component>(&mut self) -> EntityEntryCommands<'_, T> {
1337 EntityEntryCommands {
1338 entity_commands: self.reborrow(),
1339 marker: PhantomData,
1340 }
1341 }
1342
1343 /// Adds a [`Bundle`] of components to the entity.
1344 ///
1345 /// This will overwrite any previous value(s) of the same component type.
1346 /// See [`EntityCommands::insert_if_new`] to keep the old value instead.
1347 ///
1348 /// # Example
1349 ///
1350 /// ```
1351 /// # use bevy_ecs::prelude::*;
1352 /// # #[derive(Resource)]
1353 /// # struct PlayerEntity { entity: Entity }
1354 /// #[derive(Component)]
1355 /// struct Health(u32);
1356 /// #[derive(Component)]
1357 /// struct Strength(u32);
1358 /// #[derive(Component)]
1359 /// struct Defense(u32);
1360 ///
1361 /// #[derive(Bundle)]
1362 /// struct CombatBundle {
1363 /// health: Health,
1364 /// strength: Strength,
1365 /// }
1366 ///
1367 /// fn add_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
1368 /// commands
1369 /// .entity(player.entity)
1370 /// // You can insert individual components:
1371 /// .insert(Defense(10))
1372 /// // You can also insert pre-defined bundles of components:
1373 /// .insert(CombatBundle {
1374 /// health: Health(100),
1375 /// strength: Strength(40),
1376 /// })
1377 /// // You can also insert tuples of components and bundles.
1378 /// // This is equivalent to the calls above:
1379 /// .insert((
1380 /// Defense(10),
1381 /// CombatBundle {
1382 /// health: Health(100),
1383 /// strength: Strength(40),
1384 /// },
1385 /// ));
1386 /// }
1387 /// # bevy_ecs::system::assert_is_system(add_combat_stats_system);
1388 /// ```
1389 #[track_caller]
1390 pub fn insert(&mut self, bundle: impl Bundle) -> &mut Self {
1391 self.queue(entity_command::insert(bundle, InsertMode::Replace))
1392 }
1393
1394 /// Adds a [`Bundle`] of components to the entity if the predicate returns true.
1395 ///
1396 /// This is useful for chaining method calls.
1397 ///
1398 /// # Example
1399 ///
1400 /// ```
1401 /// # use bevy_ecs::prelude::*;
1402 /// # #[derive(Resource)]
1403 /// # struct PlayerEntity { entity: Entity }
1404 /// # impl PlayerEntity { fn is_spectator(&self) -> bool { true } }
1405 /// #[derive(Component)]
1406 /// struct StillLoadingStats;
1407 /// #[derive(Component)]
1408 /// struct Health(u32);
1409 ///
1410 /// fn add_health_system(mut commands: Commands, player: Res<PlayerEntity>) {
1411 /// commands
1412 /// .entity(player.entity)
1413 /// .insert_if(Health(10), || !player.is_spectator())
1414 /// .remove::<StillLoadingStats>();
1415 /// }
1416 /// # bevy_ecs::system::assert_is_system(add_health_system);
1417 /// ```
1418 #[track_caller]
1419 pub fn insert_if<F>(&mut self, bundle: impl Bundle, condition: F) -> &mut Self
1420 where
1421 F: FnOnce() -> bool,
1422 {
1423 if condition() {
1424 self.insert(bundle)
1425 } else {
1426 self
1427 }
1428 }
1429
1430 /// Adds a [`Bundle`] of components to the entity without overwriting.
1431 ///
1432 /// This is the same as [`EntityCommands::insert`], but in case of duplicate
1433 /// components will leave the old values instead of replacing them with new ones.
1434 ///
1435 /// See also [`entry`](Self::entry), which lets you modify a [`Component`] if it's present,
1436 /// as well as initialize it with a default value.
1437 #[track_caller]
1438 pub fn insert_if_new(&mut self, bundle: impl Bundle) -> &mut Self {
1439 self.queue(entity_command::insert(bundle, InsertMode::Keep))
1440 }
1441
1442 /// Adds a [`Bundle`] of components to the entity without overwriting if the
1443 /// predicate returns true.
1444 ///
1445 /// This is the same as [`EntityCommands::insert_if`], but in case of duplicate
1446 /// components will leave the old values instead of replacing them with new ones.
1447 #[track_caller]
1448 pub fn insert_if_new_and<F>(&mut self, bundle: impl Bundle, condition: F) -> &mut Self
1449 where
1450 F: FnOnce() -> bool,
1451 {
1452 if condition() {
1453 self.insert_if_new(bundle)
1454 } else {
1455 self
1456 }
1457 }
1458
1459 /// Adds a dynamic [`Component`] to the entity.
1460 ///
1461 /// This will overwrite any previous value(s) of the same component type.
1462 ///
1463 /// You should prefer to use the typed API [`EntityCommands::insert`] where possible.
1464 ///
1465 /// # Safety
1466 ///
1467 /// - [`ComponentId`] must be from the same world as `self`.
1468 /// - `T` must have the same layout as the one passed during `component_id` creation.
1469 #[track_caller]
1470 pub unsafe fn insert_by_id<T: Send + 'static>(
1471 &mut self,
1472 component_id: ComponentId,
1473 value: T,
1474 ) -> &mut Self {
1475 self.queue(
1476 // SAFETY:
1477 // - `ComponentId` safety is ensured by the caller.
1478 // - `T` safety is ensured by the caller.
1479 unsafe { entity_command::insert_by_id(component_id, value, InsertMode::Replace) },
1480 )
1481 }
1482
1483 /// Adds a dynamic [`Component`] to the entity.
1484 ///
1485 /// This will overwrite any previous value(s) of the same component type.
1486 ///
1487 /// You should prefer to use the typed API [`EntityCommands::try_insert`] where possible.
1488 ///
1489 /// # Note
1490 ///
1491 /// If the entity does not exist when this command is executed,
1492 /// the resulting error will be ignored.
1493 ///
1494 /// # Safety
1495 ///
1496 /// - [`ComponentId`] must be from the same world as `self`.
1497 /// - `T` must have the same layout as the one passed during `component_id` creation.
1498 #[track_caller]
1499 pub unsafe fn try_insert_by_id<T: Send + 'static>(
1500 &mut self,
1501 component_id: ComponentId,
1502 value: T,
1503 ) -> &mut Self {
1504 self.queue_silenced(
1505 // SAFETY:
1506 // - `ComponentId` safety is ensured by the caller.
1507 // - `T` safety is ensured by the caller.
1508 unsafe { entity_command::insert_by_id(component_id, value, InsertMode::Replace) },
1509 )
1510 }
1511
1512 /// Adds a [`Bundle`] of components to the entity.
1513 ///
1514 /// This will overwrite any previous value(s) of the same component type.
1515 ///
1516 /// # Note
1517 ///
1518 /// If the entity does not exist when this command is executed,
1519 /// the resulting error will be ignored.
1520 ///
1521 /// # Example
1522 ///
1523 /// ```
1524 /// # use bevy_ecs::prelude::*;
1525 /// # #[derive(Resource)]
1526 /// # struct PlayerEntity { entity: Entity }
1527 /// #[derive(Component)]
1528 /// struct Health(u32);
1529 /// #[derive(Component)]
1530 /// struct Strength(u32);
1531 /// #[derive(Component)]
1532 /// struct Defense(u32);
1533 ///
1534 /// #[derive(Bundle)]
1535 /// struct CombatBundle {
1536 /// health: Health,
1537 /// strength: Strength,
1538 /// }
1539 ///
1540 /// fn add_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
1541 /// commands.entity(player.entity)
1542 /// // You can insert individual components:
1543 /// .try_insert(Defense(10))
1544 /// // You can also insert tuples of components:
1545 /// .try_insert(CombatBundle {
1546 /// health: Health(100),
1547 /// strength: Strength(40),
1548 /// });
1549 ///
1550 /// // Suppose this occurs in a parallel adjacent system or process.
1551 /// commands.entity(player.entity).despawn();
1552 ///
1553 /// // This will not panic nor will it add the component.
1554 /// commands.entity(player.entity).try_insert(Defense(5));
1555 /// }
1556 /// # bevy_ecs::system::assert_is_system(add_combat_stats_system);
1557 /// ```
1558 #[track_caller]
1559 pub fn try_insert(&mut self, bundle: impl Bundle) -> &mut Self {
1560 self.queue_silenced(entity_command::insert(bundle, InsertMode::Replace))
1561 }
1562
1563 /// Adds a [`Bundle`] of components to the entity if the predicate returns true.
1564 ///
1565 /// This is useful for chaining method calls.
1566 ///
1567 /// # Note
1568 ///
1569 /// If the entity does not exist when this command is executed,
1570 /// the resulting error will be ignored.
1571 #[track_caller]
1572 pub fn try_insert_if<F>(&mut self, bundle: impl Bundle, condition: F) -> &mut Self
1573 where
1574 F: FnOnce() -> bool,
1575 {
1576 if condition() {
1577 self.try_insert(bundle)
1578 } else {
1579 self
1580 }
1581 }
1582
1583 /// Adds a [`Bundle`] of components to the entity without overwriting if the
1584 /// predicate returns true.
1585 ///
1586 /// This is the same as [`EntityCommands::try_insert_if`], but in case of duplicate
1587 /// components will leave the old values instead of replacing them with new ones.
1588 ///
1589 /// # Note
1590 ///
1591 /// If the entity does not exist when this command is executed,
1592 /// the resulting error will be ignored.
1593 #[track_caller]
1594 pub fn try_insert_if_new_and<F>(&mut self, bundle: impl Bundle, condition: F) -> &mut Self
1595 where
1596 F: FnOnce() -> bool,
1597 {
1598 if condition() {
1599 self.try_insert_if_new(bundle)
1600 } else {
1601 self
1602 }
1603 }
1604
1605 /// Adds a [`Bundle`] of components to the entity without overwriting.
1606 ///
1607 /// This is the same as [`EntityCommands::try_insert`], but in case of duplicate
1608 /// components will leave the old values instead of replacing them with new ones.
1609 ///
1610 /// # Note
1611 ///
1612 /// If the entity does not exist when this command is executed,
1613 /// the resulting error will be ignored.
1614 #[track_caller]
1615 pub fn try_insert_if_new(&mut self, bundle: impl Bundle) -> &mut Self {
1616 self.queue_silenced(entity_command::insert(bundle, InsertMode::Keep))
1617 }
1618
1619 /// Removes a [`Bundle`] of components from the entity.
1620 ///
1621 /// This will remove all components that intersect with the provided bundle;
1622 /// the entity does not need to have all the components in the bundle.
1623 ///
1624 /// This will emit a warning if the entity does not exist.
1625 ///
1626 /// # Example
1627 ///
1628 /// ```
1629 /// # use bevy_ecs::prelude::*;
1630 /// # #[derive(Resource)]
1631 /// # struct PlayerEntity { entity: Entity }
1632 /// #[derive(Component)]
1633 /// struct Health(u32);
1634 /// #[derive(Component)]
1635 /// struct Strength(u32);
1636 /// #[derive(Component)]
1637 /// struct Defense(u32);
1638 ///
1639 /// #[derive(Bundle)]
1640 /// struct CombatBundle {
1641 /// health: Health,
1642 /// strength: Strength,
1643 /// }
1644 ///
1645 /// fn remove_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
1646 /// commands
1647 /// .entity(player.entity)
1648 /// // You can remove individual components:
1649 /// .remove::<Defense>()
1650 /// // You can also remove pre-defined bundles of components:
1651 /// .remove::<CombatBundle>()
1652 /// // You can also remove tuples of components and bundles.
1653 /// // This is equivalent to the calls above:
1654 /// .remove::<(Defense, CombatBundle)>();
1655 /// }
1656 /// # bevy_ecs::system::assert_is_system(remove_combat_stats_system);
1657 /// ```
1658 #[track_caller]
1659 pub fn remove<B: Bundle>(&mut self) -> &mut Self {
1660 self.queue_handled(entity_command::remove::<B>(), warn)
1661 }
1662
1663 /// Removes a [`Bundle`] of components from the entity if the predicate returns true.
1664 ///
1665 /// This is useful for chaining method calls.
1666 ///
1667 /// # Example
1668 ///
1669 /// ```
1670 /// # use bevy_ecs::prelude::*;
1671 /// # #[derive(Resource)]
1672 /// # struct PlayerEntity { entity: Entity }
1673 /// # impl PlayerEntity { fn is_spectator(&self) -> bool { true } }
1674 /// #[derive(Component)]
1675 /// struct Health(u32);
1676 /// #[derive(Component)]
1677 /// struct Strength(u32);
1678 /// #[derive(Component)]
1679 /// struct Defense(u32);
1680 ///
1681 /// #[derive(Bundle)]
1682 /// struct CombatBundle {
1683 /// health: Health,
1684 /// strength: Strength,
1685 /// }
1686 ///
1687 /// fn remove_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
1688 /// commands
1689 /// .entity(player.entity)
1690 /// .remove_if::<(Defense, CombatBundle)>(|| !player.is_spectator());
1691 /// }
1692 /// # bevy_ecs::system::assert_is_system(remove_combat_stats_system);
1693 /// ```
1694 #[track_caller]
1695 pub fn remove_if<B: Bundle>(&mut self, condition: impl FnOnce() -> bool) -> &mut Self {
1696 if condition() {
1697 self.remove::<B>()
1698 } else {
1699 self
1700 }
1701 }
1702
1703 /// Removes a [`Bundle`] of components from the entity if the predicate returns true.
1704 ///
1705 /// This is useful for chaining method calls.
1706 ///
1707 /// # Note
1708 ///
1709 /// If the entity does not exist when this command is executed,
1710 /// the resulting error will be ignored.
1711 #[track_caller]
1712 pub fn try_remove_if<B: Bundle>(&mut self, condition: impl FnOnce() -> bool) -> &mut Self {
1713 if condition() {
1714 self.try_remove::<B>()
1715 } else {
1716 self
1717 }
1718 }
1719
1720 /// Removes a [`Bundle`] of components from the entity.
1721 ///
1722 /// This will remove all components that intersect with the provided bundle;
1723 /// the entity does not need to have all the components in the bundle.
1724 ///
1725 /// Unlike [`Self::remove`],
1726 /// this will not emit a warning if the entity does not exist.
1727 ///
1728 /// # Example
1729 ///
1730 /// ```
1731 /// # use bevy_ecs::prelude::*;
1732 /// # #[derive(Resource)]
1733 /// # struct PlayerEntity { entity: Entity }
1734 /// #[derive(Component)]
1735 /// struct Health(u32);
1736 /// #[derive(Component)]
1737 /// struct Strength(u32);
1738 /// #[derive(Component)]
1739 /// struct Defense(u32);
1740 ///
1741 /// #[derive(Bundle)]
1742 /// struct CombatBundle {
1743 /// health: Health,
1744 /// strength: Strength,
1745 /// }
1746 ///
1747 /// fn remove_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
1748 /// commands
1749 /// .entity(player.entity)
1750 /// // You can remove individual components:
1751 /// .try_remove::<Defense>()
1752 /// // You can also remove pre-defined bundles of components:
1753 /// .try_remove::<CombatBundle>()
1754 /// // You can also remove tuples of components and bundles.
1755 /// // This is equivalent to the calls above:
1756 /// .try_remove::<(Defense, CombatBundle)>();
1757 /// }
1758 /// # bevy_ecs::system::assert_is_system(remove_combat_stats_system);
1759 /// ```
1760 pub fn try_remove<B: Bundle>(&mut self) -> &mut Self {
1761 self.queue_silenced(entity_command::remove::<B>())
1762 }
1763
1764 /// Removes a [`Bundle`] of components from the entity,
1765 /// and also removes any components required by the components in the bundle.
1766 ///
1767 /// This will remove all components that intersect with the provided bundle;
1768 /// the entity does not need to have all the components in the bundle.
1769 ///
1770 /// # Example
1771 ///
1772 /// ```
1773 /// # use bevy_ecs::prelude::*;
1774 /// # #[derive(Resource)]
1775 /// # struct PlayerEntity { entity: Entity }
1776 /// #
1777 /// #[derive(Component)]
1778 /// #[require(B)]
1779 /// struct A;
1780 /// #[derive(Component, Default)]
1781 /// struct B;
1782 ///
1783 /// fn remove_with_requires_system(mut commands: Commands, player: Res<PlayerEntity>) {
1784 /// commands
1785 /// .entity(player.entity)
1786 /// // Removes both A and B from the entity, because B is required by A.
1787 /// .remove_with_requires::<A>();
1788 /// }
1789 /// # bevy_ecs::system::assert_is_system(remove_with_requires_system);
1790 /// ```
1791 #[track_caller]
1792 pub fn remove_with_requires<B: Bundle>(&mut self) -> &mut Self {
1793 self.queue(entity_command::remove_with_requires::<B>())
1794 }
1795
1796 /// Removes a dynamic [`Component`] from the entity if it exists.
1797 ///
1798 /// # Panics
1799 ///
1800 /// Panics if the provided [`ComponentId`] does not exist in the [`World`].
1801 #[track_caller]
1802 pub fn remove_by_id(&mut self, component_id: ComponentId) -> &mut Self {
1803 self.queue(entity_command::remove_by_id(component_id))
1804 }
1805
1806 /// Removes all components associated with the entity.
1807 #[track_caller]
1808 pub fn clear(&mut self) -> &mut Self {
1809 self.queue(entity_command::clear())
1810 }
1811
1812 /// Despawns the entity.
1813 ///
1814 /// This will emit a warning if the entity does not exist.
1815 ///
1816 /// # Note
1817 ///
1818 /// This will also despawn the entities in any [`RelationshipTarget`](crate::relationship::RelationshipTarget)
1819 /// that is configured to despawn descendants.
1820 ///
1821 /// For example, this will recursively despawn [`Children`](crate::hierarchy::Children).
1822 ///
1823 /// # Example
1824 ///
1825 /// ```
1826 /// # use bevy_ecs::prelude::*;
1827 /// # #[derive(Resource)]
1828 /// # struct CharacterToRemove { entity: Entity }
1829 /// #
1830 /// fn remove_character_system(
1831 /// mut commands: Commands,
1832 /// character_to_remove: Res<CharacterToRemove>
1833 /// ) {
1834 /// commands.entity(character_to_remove.entity).despawn();
1835 /// }
1836 /// # bevy_ecs::system::assert_is_system(remove_character_system);
1837 /// ```
1838 #[track_caller]
1839 pub fn despawn(&mut self) {
1840 self.queue_handled(entity_command::despawn(), warn);
1841 }
1842
1843 /// Despawns the entity.
1844 ///
1845 /// Unlike [`Self::despawn`],
1846 /// this will not emit a warning if the entity does not exist.
1847 ///
1848 /// # Note
1849 ///
1850 /// This will also despawn the entities in any [`RelationshipTarget`](crate::relationship::RelationshipTarget)
1851 /// that is configured to despawn descendants.
1852 ///
1853 /// For example, this will recursively despawn [`Children`](crate::hierarchy::Children).
1854 pub fn try_despawn(&mut self) {
1855 self.queue_silenced(entity_command::despawn());
1856 }
1857
1858 /// Pushes an [`EntityCommand`] to the queue,
1859 /// which will get executed for the current [`Entity`].
1860 ///
1861 /// The [default error handler](crate::error::DefaultErrorHandler)
1862 /// will be used to handle error cases.
1863 /// Every [`EntityCommand`] checks whether the entity exists at the time of execution
1864 /// and returns an error if it does not.
1865 ///
1866 /// To use a custom error handler, see [`EntityCommands::queue_handled`].
1867 ///
1868 /// The command can be:
1869 /// - A custom struct that implements [`EntityCommand`].
1870 /// - A closure or function that matches the following signature:
1871 /// - [`(EntityWorldMut)`](EntityWorldMut)
1872 /// - [`(EntityWorldMut)`](EntityWorldMut) `->` [`Result`]
1873 /// - A built-in command from the [`entity_command`] module.
1874 ///
1875 /// # Example
1876 ///
1877 /// ```
1878 /// # use bevy_ecs::prelude::*;
1879 /// # fn my_system(mut commands: Commands) {
1880 /// commands
1881 /// .spawn_empty()
1882 /// // Closures with this signature implement `EntityCommand`.
1883 /// .queue(|entity: EntityWorldMut| {
1884 /// println!("Executed an EntityCommand for {}", entity.id());
1885 /// });
1886 /// # }
1887 /// # bevy_ecs::system::assert_is_system(my_system);
1888 /// ```
1889 pub fn queue<C: EntityCommand<T> + CommandWithEntity<M>, T, M>(
1890 &mut self,
1891 command: C,
1892 ) -> &mut Self {
1893 self.commands.queue(command.with_entity(self.entity));
1894 self
1895 }
1896
1897 /// Pushes an [`EntityCommand`] to the queue,
1898 /// which will get executed for the current [`Entity`].
1899 ///
1900 /// The given `error_handler` will be used to handle error cases.
1901 /// Every [`EntityCommand`] checks whether the entity exists at the time of execution
1902 /// and returns an error if it does not.
1903 ///
1904 /// To implicitly use the default error handler, see [`EntityCommands::queue`].
1905 ///
1906 /// The command can be:
1907 /// - A custom struct that implements [`EntityCommand`].
1908 /// - A closure or function that matches the following signature:
1909 /// - [`(EntityWorldMut)`](EntityWorldMut)
1910 /// - [`(EntityWorldMut)`](EntityWorldMut) `->` [`Result`]
1911 /// - A built-in command from the [`entity_command`] module.
1912 ///
1913 /// # Example
1914 ///
1915 /// ```
1916 /// # use bevy_ecs::prelude::*;
1917 /// # fn my_system(mut commands: Commands) {
1918 /// use bevy_ecs::error::warn;
1919 ///
1920 /// commands
1921 /// .spawn_empty()
1922 /// // Closures with this signature implement `EntityCommand`.
1923 /// .queue_handled(
1924 /// |entity: EntityWorldMut| -> Result {
1925 /// let value: usize = "100".parse()?;
1926 /// println!("Successfully parsed the value {} for entity {}", value, entity.id());
1927 /// Ok(())
1928 /// },
1929 /// warn
1930 /// );
1931 /// # }
1932 /// # bevy_ecs::system::assert_is_system(my_system);
1933 /// ```
1934 pub fn queue_handled<C: EntityCommand<T> + CommandWithEntity<M>, T, M>(
1935 &mut self,
1936 command: C,
1937 error_handler: fn(BevyError, ErrorContext),
1938 ) -> &mut Self {
1939 self.commands
1940 .queue_handled(command.with_entity(self.entity), error_handler);
1941 self
1942 }
1943
1944 /// Pushes an [`EntityCommand`] to the queue, which will get executed for the current [`Entity`].
1945 ///
1946 /// Unlike [`EntityCommands::queue_handled`], this will completely ignore any errors that occur.
1947 pub fn queue_silenced<C: EntityCommand<T> + CommandWithEntity<M>, T, M>(
1948 &mut self,
1949 command: C,
1950 ) -> &mut Self {
1951 self.commands
1952 .queue_silenced(command.with_entity(self.entity));
1953 self
1954 }
1955
1956 /// Removes all components except the given [`Bundle`] from the entity.
1957 ///
1958 /// # Example
1959 ///
1960 /// ```
1961 /// # use bevy_ecs::prelude::*;
1962 /// # #[derive(Resource)]
1963 /// # struct PlayerEntity { entity: Entity }
1964 /// #[derive(Component)]
1965 /// struct Health(u32);
1966 /// #[derive(Component)]
1967 /// struct Strength(u32);
1968 /// #[derive(Component)]
1969 /// struct Defense(u32);
1970 ///
1971 /// #[derive(Bundle)]
1972 /// struct CombatBundle {
1973 /// health: Health,
1974 /// strength: Strength,
1975 /// }
1976 ///
1977 /// fn remove_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
1978 /// commands
1979 /// .entity(player.entity)
1980 /// // You can retain a pre-defined Bundle of components,
1981 /// // with this removing only the Defense component.
1982 /// .retain::<CombatBundle>()
1983 /// // You can also retain only a single component.
1984 /// .retain::<Health>();
1985 /// }
1986 /// # bevy_ecs::system::assert_is_system(remove_combat_stats_system);
1987 /// ```
1988 #[track_caller]
1989 pub fn retain<B: Bundle>(&mut self) -> &mut Self {
1990 self.queue(entity_command::retain::<B>())
1991 }
1992
1993 /// Logs the components of the entity at the [`info`](log::info) level.
1994 pub fn log_components(&mut self) -> &mut Self {
1995 self.queue(entity_command::log_components())
1996 }
1997
1998 /// Returns the underlying [`Commands`].
1999 pub fn commands(&mut self) -> Commands<'_, '_> {
2000 self.commands.reborrow()
2001 }
2002
2003 /// Returns a mutable reference to the underlying [`Commands`].
2004 pub fn commands_mut(&mut self) -> &mut Commands<'a, 'a> {
2005 &mut self.commands
2006 }
2007
2008 /// Creates an [`Observer`] watching for an [`EntityEvent`] of type `E` whose [`EntityEvent::event_target`]
2009 /// targets this entity.
2010 pub fn observe<E: EntityEvent, B: Bundle, M>(
2011 &mut self,
2012 observer: impl IntoObserverSystem<E, B, M>,
2013 ) -> &mut Self {
2014 self.queue(entity_command::observe(observer))
2015 }
2016
2017 /// Clones parts of an entity (components, observers, etc.) onto another entity,
2018 /// configured through [`EntityClonerBuilder`].
2019 ///
2020 /// The other entity will receive all the components of the original that implement
2021 /// [`Clone`] or [`Reflect`](bevy_reflect::Reflect) except those that are
2022 /// [denied](EntityClonerBuilder::deny) in the `config`.
2023 ///
2024 /// # Panics
2025 ///
2026 /// The command will panic when applied if the target entity does not exist.
2027 ///
2028 /// # Example
2029 ///
2030 /// Configure through [`EntityClonerBuilder<OptOut>`] as follows:
2031 /// ```
2032 /// # use bevy_ecs::prelude::*;
2033 /// #[derive(Component, Clone)]
2034 /// struct ComponentA(u32);
2035 /// #[derive(Component, Clone)]
2036 /// struct ComponentB(u32);
2037 ///
2038 /// fn example_system(mut commands: Commands) {
2039 /// // Create an empty entity.
2040 /// let target = commands.spawn_empty().id();
2041 ///
2042 /// // Create a new entity and keep its EntityCommands.
2043 /// let mut entity = commands.spawn((ComponentA(10), ComponentB(20)));
2044 ///
2045 /// // Clone ComponentA but not ComponentB onto the target.
2046 /// entity.clone_with_opt_out(target, |builder| {
2047 /// builder.deny::<ComponentB>();
2048 /// });
2049 /// }
2050 /// # bevy_ecs::system::assert_is_system(example_system);
2051 /// ```
2052 ///
2053 /// See [`EntityClonerBuilder`] for more options.
2054 pub fn clone_with_opt_out(
2055 &mut self,
2056 target: Entity,
2057 config: impl FnOnce(&mut EntityClonerBuilder<OptOut>) + Send + Sync + 'static,
2058 ) -> &mut Self {
2059 self.queue(entity_command::clone_with_opt_out(target, config))
2060 }
2061
2062 /// Clones parts of an entity (components, observers, etc.) onto another entity,
2063 /// configured through [`EntityClonerBuilder`].
2064 ///
2065 /// The other entity will receive only the components of the original that implement
2066 /// [`Clone`] or [`Reflect`](bevy_reflect::Reflect) and are
2067 /// [allowed](EntityClonerBuilder::allow) in the `config`.
2068 ///
2069 /// # Panics
2070 ///
2071 /// The command will panic when applied if the target entity does not exist.
2072 ///
2073 /// # Example
2074 ///
2075 /// Configure through [`EntityClonerBuilder<OptIn>`] as follows:
2076 /// ```
2077 /// # use bevy_ecs::prelude::*;
2078 /// #[derive(Component, Clone)]
2079 /// struct ComponentA(u32);
2080 /// #[derive(Component, Clone)]
2081 /// struct ComponentB(u32);
2082 ///
2083 /// fn example_system(mut commands: Commands) {
2084 /// // Create an empty entity.
2085 /// let target = commands.spawn_empty().id();
2086 ///
2087 /// // Create a new entity and keep its EntityCommands.
2088 /// let mut entity = commands.spawn((ComponentA(10), ComponentB(20)));
2089 ///
2090 /// // Clone ComponentA but not ComponentB onto the target.
2091 /// entity.clone_with_opt_in(target, |builder| {
2092 /// builder.allow::<ComponentA>();
2093 /// });
2094 /// }
2095 /// # bevy_ecs::system::assert_is_system(example_system);
2096 /// ```
2097 ///
2098 /// See [`EntityClonerBuilder`] for more options.
2099 pub fn clone_with_opt_in(
2100 &mut self,
2101 target: Entity,
2102 config: impl FnOnce(&mut EntityClonerBuilder<OptIn>) + Send + Sync + 'static,
2103 ) -> &mut Self {
2104 self.queue(entity_command::clone_with_opt_in(target, config))
2105 }
2106
2107 /// Spawns a clone of this entity and returns the [`EntityCommands`] of the clone.
2108 ///
2109 /// The clone will receive all the components of the original that implement
2110 /// [`Clone`] or [`Reflect`](bevy_reflect::Reflect).
2111 ///
2112 /// To configure cloning behavior (such as only cloning certain components),
2113 /// use [`EntityCommands::clone_and_spawn_with_opt_out`]/
2114 /// [`opt_out`](EntityCommands::clone_and_spawn_with_opt_out).
2115 ///
2116 /// # Note
2117 ///
2118 /// If the original entity does not exist when this command is applied,
2119 /// the returned entity will have no components.
2120 ///
2121 /// # Example
2122 ///
2123 /// ```
2124 /// # use bevy_ecs::prelude::*;
2125 /// #[derive(Component, Clone)]
2126 /// struct ComponentA(u32);
2127 /// #[derive(Component, Clone)]
2128 /// struct ComponentB(u32);
2129 ///
2130 /// fn example_system(mut commands: Commands) {
2131 /// // Create a new entity and store its EntityCommands.
2132 /// let mut entity = commands.spawn((ComponentA(10), ComponentB(20)));
2133 ///
2134 /// // Create a clone of the entity.
2135 /// let mut entity_clone = entity.clone_and_spawn();
2136 /// }
2137 /// # bevy_ecs::system::assert_is_system(example_system);
2138 pub fn clone_and_spawn(&mut self) -> EntityCommands<'_> {
2139 self.clone_and_spawn_with_opt_out(|_| {})
2140 }
2141
2142 /// Spawns a clone of this entity and allows configuring cloning behavior
2143 /// using [`EntityClonerBuilder`], returning the [`EntityCommands`] of the clone.
2144 ///
2145 /// The clone will receive all the components of the original that implement
2146 /// [`Clone`] or [`Reflect`](bevy_reflect::Reflect) except those that are
2147 /// [denied](EntityClonerBuilder::deny) in the `config`.
2148 ///
2149 /// See the methods on [`EntityClonerBuilder<OptOut>`] for more options.
2150 ///
2151 /// # Note
2152 ///
2153 /// If the original entity does not exist when this command is applied,
2154 /// the returned entity will have no components.
2155 ///
2156 /// # Example
2157 ///
2158 /// ```
2159 /// # use bevy_ecs::prelude::*;
2160 /// #[derive(Component, Clone)]
2161 /// struct ComponentA(u32);
2162 /// #[derive(Component, Clone)]
2163 /// struct ComponentB(u32);
2164 ///
2165 /// fn example_system(mut commands: Commands) {
2166 /// // Create a new entity and store its EntityCommands.
2167 /// let mut entity = commands.spawn((ComponentA(10), ComponentB(20)));
2168 ///
2169 /// // Create a clone of the entity with ComponentA but without ComponentB.
2170 /// let mut entity_clone = entity.clone_and_spawn_with_opt_out(|builder| {
2171 /// builder.deny::<ComponentB>();
2172 /// });
2173 /// }
2174 /// # bevy_ecs::system::assert_is_system(example_system);
2175 pub fn clone_and_spawn_with_opt_out(
2176 &mut self,
2177 config: impl FnOnce(&mut EntityClonerBuilder<OptOut>) + Send + Sync + 'static,
2178 ) -> EntityCommands<'_> {
2179 let entity_clone = self.commands().spawn_empty().id();
2180 self.clone_with_opt_out(entity_clone, config);
2181 EntityCommands {
2182 commands: self.commands_mut().reborrow(),
2183 entity: entity_clone,
2184 }
2185 }
2186
2187 /// Spawns a clone of this entity and allows configuring cloning behavior
2188 /// using [`EntityClonerBuilder`], returning the [`EntityCommands`] of the clone.
2189 ///
2190 /// The clone will receive only the components of the original that implement
2191 /// [`Clone`] or [`Reflect`](bevy_reflect::Reflect) and are
2192 /// [allowed](EntityClonerBuilder::allow) in the `config`.
2193 ///
2194 /// See the methods on [`EntityClonerBuilder<OptIn>`] for more options.
2195 ///
2196 /// # Note
2197 ///
2198 /// If the original entity does not exist when this command is applied,
2199 /// the returned entity will have no components.
2200 ///
2201 /// # Example
2202 ///
2203 /// ```
2204 /// # use bevy_ecs::prelude::*;
2205 /// #[derive(Component, Clone)]
2206 /// struct ComponentA(u32);
2207 /// #[derive(Component, Clone)]
2208 /// struct ComponentB(u32);
2209 ///
2210 /// fn example_system(mut commands: Commands) {
2211 /// // Create a new entity and store its EntityCommands.
2212 /// let mut entity = commands.spawn((ComponentA(10), ComponentB(20)));
2213 ///
2214 /// // Create a clone of the entity with ComponentA but without ComponentB.
2215 /// let mut entity_clone = entity.clone_and_spawn_with_opt_in(|builder| {
2216 /// builder.allow::<ComponentA>();
2217 /// });
2218 /// }
2219 /// # bevy_ecs::system::assert_is_system(example_system);
2220 pub fn clone_and_spawn_with_opt_in(
2221 &mut self,
2222 config: impl FnOnce(&mut EntityClonerBuilder<OptIn>) + Send + Sync + 'static,
2223 ) -> EntityCommands<'_> {
2224 let entity_clone = self.commands().spawn_empty().id();
2225 self.clone_with_opt_in(entity_clone, config);
2226 EntityCommands {
2227 commands: self.commands_mut().reborrow(),
2228 entity: entity_clone,
2229 }
2230 }
2231
2232 /// Clones the specified components of this entity and inserts them into another entity.
2233 ///
2234 /// Components can only be cloned if they implement
2235 /// [`Clone`] or [`Reflect`](bevy_reflect::Reflect).
2236 ///
2237 /// # Panics
2238 ///
2239 /// The command will panic when applied if the target entity does not exist.
2240 pub fn clone_components<B: Bundle>(&mut self, target: Entity) -> &mut Self {
2241 self.queue(entity_command::clone_components::<B>(target))
2242 }
2243
2244 /// Moves the specified components of this entity into another entity.
2245 ///
2246 /// Components with [`Ignore`] clone behavior will not be moved, while components that
2247 /// have a [`Custom`] clone behavior will be cloned using it and then removed from the source entity.
2248 /// All other components will be moved without any other special handling.
2249 ///
2250 /// Note that this will trigger `on_remove` hooks/observers on this entity and `on_insert`/`on_add` hooks/observers on the target entity.
2251 ///
2252 /// # Panics
2253 ///
2254 /// The command will panic when applied if the target entity does not exist.
2255 ///
2256 /// [`Ignore`]: crate::component::ComponentCloneBehavior::Ignore
2257 /// [`Custom`]: crate::component::ComponentCloneBehavior::Custom
2258 pub fn move_components<B: Bundle>(&mut self, target: Entity) -> &mut Self {
2259 self.queue(entity_command::move_components::<B>(target))
2260 }
2261
2262 /// Passes the current entity into the given function, and triggers the [`EntityEvent`] returned by that function.
2263 ///
2264 /// # Example
2265 ///
2266 /// A surprising number of functions meet the trait bounds for `event_fn`:
2267 ///
2268 /// ```rust
2269 /// # use bevy_ecs::prelude::*;
2270 ///
2271 /// #[derive(EntityEvent)]
2272 /// struct Explode(Entity);
2273 ///
2274 /// impl From<Entity> for Explode {
2275 /// fn from(entity: Entity) -> Self {
2276 /// Explode(entity)
2277 /// }
2278 /// }
2279 ///
2280 ///
2281 /// fn trigger_via_constructor(mut commands: Commands) {
2282 /// // The fact that `Epxlode` is a single-field tuple struct
2283 /// // ensures that `Explode(entity)` is a function that generates
2284 /// // an EntityEvent, meeting the trait bounds for `event_fn`.
2285 /// commands.spawn_empty().trigger(Explode);
2286 ///
2287 /// }
2288 ///
2289 ///
2290 /// fn trigger_via_from_trait(mut commands: Commands) {
2291 /// // This variant also works for events like `struct Explode { entity: Entity }`
2292 /// commands.spawn_empty().trigger(Explode::from);
2293 /// }
2294 ///
2295 /// fn trigger_via_closure(mut commands: Commands) {
2296 /// commands.spawn_empty().trigger(|entity| Explode(entity));
2297 /// }
2298 /// ```
2299 #[track_caller]
2300 pub fn trigger<'t, E: EntityEvent<Trigger<'t>: Default>>(
2301 &mut self,
2302 event_fn: impl FnOnce(Entity) -> E,
2303 ) -> &mut Self {
2304 let event = (event_fn)(self.entity);
2305 self.commands.trigger(event);
2306 self
2307 }
2308}
2309
2310/// A wrapper around [`EntityCommands`] with convenience methods for working with a specified component type.
2311pub struct EntityEntryCommands<'a, T> {
2312 entity_commands: EntityCommands<'a>,
2313 marker: PhantomData<T>,
2314}
2315
2316impl<'a, T: Component<Mutability = Mutable>> EntityEntryCommands<'a, T> {
2317 /// Modify the component `T` if it exists, using the function `modify`.
2318 pub fn and_modify(&mut self, modify: impl FnOnce(Mut<T>) + Send + Sync + 'static) -> &mut Self {
2319 self.entity_commands
2320 .queue(move |mut entity: EntityWorldMut| {
2321 if let Some(value) = entity.get_mut() {
2322 modify(value);
2323 }
2324 });
2325 self
2326 }
2327}
2328
2329impl<'a, T: Component> EntityEntryCommands<'a, T> {
2330 /// [Insert](EntityCommands::insert) `default` into this entity,
2331 /// if `T` is not already present.
2332 #[track_caller]
2333 pub fn or_insert(&mut self, default: T) -> &mut Self {
2334 self.entity_commands.insert_if_new(default);
2335 self
2336 }
2337
2338 /// [Insert](EntityCommands::insert) `default` into this entity,
2339 /// if `T` is not already present.
2340 ///
2341 /// # Note
2342 ///
2343 /// If the entity does not exist when this command is executed,
2344 /// the resulting error will be ignored.
2345 #[track_caller]
2346 pub fn or_try_insert(&mut self, default: T) -> &mut Self {
2347 self.entity_commands.try_insert_if_new(default);
2348 self
2349 }
2350
2351 /// [Insert](EntityCommands::insert) the value returned from `default` into this entity,
2352 /// if `T` is not already present.
2353 ///
2354 /// `default` will only be invoked if the component will actually be inserted.
2355 #[track_caller]
2356 pub fn or_insert_with<F>(&mut self, default: F) -> &mut Self
2357 where
2358 F: FnOnce() -> T + Send + 'static,
2359 {
2360 self.entity_commands
2361 .queue(entity_command::insert_with(default, InsertMode::Keep));
2362 self
2363 }
2364
2365 /// [Insert](EntityCommands::insert) the value returned from `default` into this entity,
2366 /// if `T` is not already present.
2367 ///
2368 /// `default` will only be invoked if the component will actually be inserted.
2369 ///
2370 /// # Note
2371 ///
2372 /// If the entity does not exist when this command is executed,
2373 /// the resulting error will be ignored.
2374 #[track_caller]
2375 pub fn or_try_insert_with<F>(&mut self, default: F) -> &mut Self
2376 where
2377 F: FnOnce() -> T + Send + 'static,
2378 {
2379 self.entity_commands
2380 .queue_silenced(entity_command::insert_with(default, InsertMode::Keep));
2381 self
2382 }
2383
2384 /// [Insert](EntityCommands::insert) `T::default` into this entity,
2385 /// if `T` is not already present.
2386 ///
2387 /// `T::default` will only be invoked if the component will actually be inserted.
2388 #[track_caller]
2389 pub fn or_default(&mut self) -> &mut Self
2390 where
2391 T: Default,
2392 {
2393 self.or_insert_with(T::default)
2394 }
2395
2396 /// [Insert](EntityCommands::insert) `T::from_world` into this entity,
2397 /// if `T` is not already present.
2398 ///
2399 /// `T::from_world` will only be invoked if the component will actually be inserted.
2400 #[track_caller]
2401 pub fn or_from_world(&mut self) -> &mut Self
2402 where
2403 T: FromWorld,
2404 {
2405 self.entity_commands
2406 .queue(entity_command::insert_from_world::<T>(InsertMode::Keep));
2407 self
2408 }
2409
2410 /// Get the [`EntityCommands`] from which the [`EntityEntryCommands`] was initiated.
2411 ///
2412 /// This allows you to continue chaining method calls after calling [`EntityCommands::entry`].
2413 ///
2414 /// # Example
2415 ///
2416 /// ```
2417 /// # use bevy_ecs::prelude::*;
2418 /// # #[derive(Resource)]
2419 /// # struct PlayerEntity { entity: Entity }
2420 /// #[derive(Component)]
2421 /// struct Level(u32);
2422 ///
2423 /// fn level_up_system(mut commands: Commands, player: Res<PlayerEntity>) {
2424 /// commands
2425 /// .entity(player.entity)
2426 /// .entry::<Level>()
2427 /// // Modify the component if it exists.
2428 /// .and_modify(|mut lvl| lvl.0 += 1)
2429 /// // Otherwise, insert a default value.
2430 /// .or_insert(Level(0))
2431 /// // Return the EntityCommands for the entity.
2432 /// .entity()
2433 /// // Continue chaining method calls.
2434 /// .insert(Name::new("Player"));
2435 /// }
2436 /// # bevy_ecs::system::assert_is_system(level_up_system);
2437 /// ```
2438 pub fn entity(&mut self) -> EntityCommands<'_> {
2439 self.entity_commands.reborrow()
2440 }
2441}
2442
2443#[cfg(test)]
2444mod tests {
2445 use crate::{
2446 component::Component,
2447 resource::Resource,
2448 system::Commands,
2449 world::{CommandQueue, FromWorld, World},
2450 };
2451 use alloc::{string::String, sync::Arc, vec, vec::Vec};
2452 use core::{
2453 any::TypeId,
2454 sync::atomic::{AtomicUsize, Ordering},
2455 };
2456
2457 #[expect(
2458 dead_code,
2459 reason = "This struct is used to test how `Drop` behavior works in regards to SparseSet storage, and as such is solely a wrapper around `DropCk` to make it use the SparseSet storage. Because of this, the inner field is intentionally never read."
2460 )]
2461 #[derive(Component)]
2462 #[component(storage = "SparseSet")]
2463 struct SparseDropCk(DropCk);
2464
2465 #[derive(Component)]
2466 struct DropCk(Arc<AtomicUsize>);
2467 impl DropCk {
2468 fn new_pair() -> (Self, Arc<AtomicUsize>) {
2469 let atomic = Arc::new(AtomicUsize::new(0));
2470 (DropCk(atomic.clone()), atomic)
2471 }
2472 }
2473
2474 impl Drop for DropCk {
2475 fn drop(&mut self) {
2476 self.0.as_ref().fetch_add(1, Ordering::Relaxed);
2477 }
2478 }
2479
2480 #[derive(Component, Resource)]
2481 struct W<T>(T);
2482
2483 fn simple_command(world: &mut World) {
2484 world.spawn((W(0u32), W(42u64)));
2485 }
2486
2487 impl FromWorld for W<String> {
2488 fn from_world(world: &mut World) -> Self {
2489 let v = world.resource::<W<usize>>();
2490 Self("*".repeat(v.0))
2491 }
2492 }
2493
2494 impl Default for W<u8> {
2495 fn default() -> Self {
2496 unreachable!()
2497 }
2498 }
2499
2500 #[test]
2501 fn entity_commands_entry() {
2502 let mut world = World::default();
2503 let mut queue = CommandQueue::default();
2504 let mut commands = Commands::new(&mut queue, &world);
2505 let entity = commands.spawn_empty().id();
2506 commands
2507 .entity(entity)
2508 .entry::<W<u32>>()
2509 .and_modify(|_| unreachable!());
2510 queue.apply(&mut world);
2511 assert!(!world.entity(entity).contains::<W<u32>>());
2512 let mut commands = Commands::new(&mut queue, &world);
2513 commands
2514 .entity(entity)
2515 .entry::<W<u32>>()
2516 .or_insert(W(0))
2517 .and_modify(|mut val| {
2518 val.0 = 21;
2519 });
2520 queue.apply(&mut world);
2521 assert_eq!(21, world.get::<W<u32>>(entity).unwrap().0);
2522 let mut commands = Commands::new(&mut queue, &world);
2523 commands
2524 .entity(entity)
2525 .entry::<W<u64>>()
2526 .and_modify(|_| unreachable!())
2527 .or_insert(W(42));
2528 queue.apply(&mut world);
2529 assert_eq!(42, world.get::<W<u64>>(entity).unwrap().0);
2530 world.insert_resource(W(5_usize));
2531 let mut commands = Commands::new(&mut queue, &world);
2532 commands.entity(entity).entry::<W<String>>().or_from_world();
2533 queue.apply(&mut world);
2534 assert_eq!("*****", &world.get::<W<String>>(entity).unwrap().0);
2535 let mut commands = Commands::new(&mut queue, &world);
2536 let id = commands.entity(entity).entry::<W<u64>>().entity().id();
2537 queue.apply(&mut world);
2538 assert_eq!(id, entity);
2539 let mut commands = Commands::new(&mut queue, &world);
2540 commands
2541 .entity(entity)
2542 .entry::<W<u8>>()
2543 .or_insert_with(|| W(5))
2544 .or_insert_with(|| unreachable!())
2545 .or_try_insert_with(|| unreachable!())
2546 .or_default()
2547 .or_from_world();
2548 queue.apply(&mut world);
2549 assert_eq!(5, world.get::<W<u8>>(entity).unwrap().0);
2550 }
2551
2552 #[test]
2553 fn commands() {
2554 let mut world = World::default();
2555 let mut command_queue = CommandQueue::default();
2556 let entity = Commands::new(&mut command_queue, &world)
2557 .spawn((W(1u32), W(2u64)))
2558 .id();
2559 command_queue.apply(&mut world);
2560 assert_eq!(world.query::<&W<u32>>().query(&world).count(), 1);
2561 let results = world
2562 .query::<(&W<u32>, &W<u64>)>()
2563 .iter(&world)
2564 .map(|(a, b)| (a.0, b.0))
2565 .collect::<Vec<_>>();
2566 assert_eq!(results, vec![(1u32, 2u64)]);
2567 // test entity despawn
2568 {
2569 let mut commands = Commands::new(&mut command_queue, &world);
2570 commands.entity(entity).despawn();
2571 commands.entity(entity).despawn(); // double despawn shouldn't panic
2572 }
2573 command_queue.apply(&mut world);
2574 let results2 = world
2575 .query::<(&W<u32>, &W<u64>)>()
2576 .iter(&world)
2577 .map(|(a, b)| (a.0, b.0))
2578 .collect::<Vec<_>>();
2579 assert_eq!(results2, vec![]);
2580
2581 // test adding simple (FnOnce) commands
2582 {
2583 let mut commands = Commands::new(&mut command_queue, &world);
2584
2585 // set up a simple command using a closure that adds one additional entity
2586 commands.queue(|world: &mut World| {
2587 world.spawn((W(42u32), W(0u64)));
2588 });
2589
2590 // set up a simple command using a function that adds one additional entity
2591 commands.queue(simple_command);
2592 }
2593 command_queue.apply(&mut world);
2594 let results3 = world
2595 .query::<(&W<u32>, &W<u64>)>()
2596 .iter(&world)
2597 .map(|(a, b)| (a.0, b.0))
2598 .collect::<Vec<_>>();
2599
2600 assert_eq!(results3, vec![(42u32, 0u64), (0u32, 42u64)]);
2601 }
2602
2603 #[test]
2604 fn insert_components() {
2605 let mut world = World::default();
2606 let mut command_queue1 = CommandQueue::default();
2607
2608 // insert components
2609 let entity = Commands::new(&mut command_queue1, &world)
2610 .spawn(())
2611 .insert_if(W(1u8), || true)
2612 .insert_if(W(2u8), || false)
2613 .insert_if_new(W(1u16))
2614 .insert_if_new(W(2u16))
2615 .insert_if_new_and(W(1u32), || false)
2616 .insert_if_new_and(W(2u32), || true)
2617 .insert_if_new_and(W(3u32), || true)
2618 .id();
2619 command_queue1.apply(&mut world);
2620
2621 let results = world
2622 .query::<(&W<u8>, &W<u16>, &W<u32>)>()
2623 .iter(&world)
2624 .map(|(a, b, c)| (a.0, b.0, c.0))
2625 .collect::<Vec<_>>();
2626 assert_eq!(results, vec![(1u8, 1u16, 2u32)]);
2627
2628 // try to insert components after despawning entity
2629 // in another command queue
2630 Commands::new(&mut command_queue1, &world)
2631 .entity(entity)
2632 .try_insert_if_new_and(W(1u64), || true);
2633
2634 let mut command_queue2 = CommandQueue::default();
2635 Commands::new(&mut command_queue2, &world)
2636 .entity(entity)
2637 .despawn();
2638 command_queue2.apply(&mut world);
2639 command_queue1.apply(&mut world);
2640 }
2641
2642 #[test]
2643 fn remove_components() {
2644 let mut world = World::default();
2645
2646 let mut command_queue = CommandQueue::default();
2647 let (dense_dropck, dense_is_dropped) = DropCk::new_pair();
2648 let (sparse_dropck, sparse_is_dropped) = DropCk::new_pair();
2649 let sparse_dropck = SparseDropCk(sparse_dropck);
2650
2651 let entity = Commands::new(&mut command_queue, &world)
2652 .spawn((W(1u32), W(2u64), dense_dropck, sparse_dropck))
2653 .id();
2654 command_queue.apply(&mut world);
2655 let results_before = world
2656 .query::<(&W<u32>, &W<u64>)>()
2657 .iter(&world)
2658 .map(|(a, b)| (a.0, b.0))
2659 .collect::<Vec<_>>();
2660 assert_eq!(results_before, vec![(1u32, 2u64)]);
2661
2662 // test component removal
2663 Commands::new(&mut command_queue, &world)
2664 .entity(entity)
2665 .remove::<W<u32>>()
2666 .remove::<(W<u32>, W<u64>, SparseDropCk, DropCk)>();
2667
2668 assert_eq!(dense_is_dropped.load(Ordering::Relaxed), 0);
2669 assert_eq!(sparse_is_dropped.load(Ordering::Relaxed), 0);
2670 command_queue.apply(&mut world);
2671 assert_eq!(dense_is_dropped.load(Ordering::Relaxed), 1);
2672 assert_eq!(sparse_is_dropped.load(Ordering::Relaxed), 1);
2673
2674 let results_after = world
2675 .query::<(&W<u32>, &W<u64>)>()
2676 .iter(&world)
2677 .map(|(a, b)| (a.0, b.0))
2678 .collect::<Vec<_>>();
2679 assert_eq!(results_after, vec![]);
2680 let results_after_u64 = world
2681 .query::<&W<u64>>()
2682 .iter(&world)
2683 .map(|v| v.0)
2684 .collect::<Vec<_>>();
2685 assert_eq!(results_after_u64, vec![]);
2686 }
2687
2688 #[test]
2689 fn remove_components_by_id() {
2690 let mut world = World::default();
2691
2692 let mut command_queue = CommandQueue::default();
2693 let (dense_dropck, dense_is_dropped) = DropCk::new_pair();
2694 let (sparse_dropck, sparse_is_dropped) = DropCk::new_pair();
2695 let sparse_dropck = SparseDropCk(sparse_dropck);
2696
2697 let entity = Commands::new(&mut command_queue, &world)
2698 .spawn((W(1u32), W(2u64), dense_dropck, sparse_dropck))
2699 .id();
2700 command_queue.apply(&mut world);
2701 let results_before = world
2702 .query::<(&W<u32>, &W<u64>)>()
2703 .iter(&world)
2704 .map(|(a, b)| (a.0, b.0))
2705 .collect::<Vec<_>>();
2706 assert_eq!(results_before, vec![(1u32, 2u64)]);
2707
2708 // test component removal
2709 Commands::new(&mut command_queue, &world)
2710 .entity(entity)
2711 .remove_by_id(world.components().get_id(TypeId::of::<W<u32>>()).unwrap())
2712 .remove_by_id(world.components().get_id(TypeId::of::<W<u64>>()).unwrap())
2713 .remove_by_id(world.components().get_id(TypeId::of::<DropCk>()).unwrap())
2714 .remove_by_id(
2715 world
2716 .components()
2717 .get_id(TypeId::of::<SparseDropCk>())
2718 .unwrap(),
2719 );
2720
2721 assert_eq!(dense_is_dropped.load(Ordering::Relaxed), 0);
2722 assert_eq!(sparse_is_dropped.load(Ordering::Relaxed), 0);
2723 command_queue.apply(&mut world);
2724 assert_eq!(dense_is_dropped.load(Ordering::Relaxed), 1);
2725 assert_eq!(sparse_is_dropped.load(Ordering::Relaxed), 1);
2726
2727 let results_after = world
2728 .query::<(&W<u32>, &W<u64>)>()
2729 .iter(&world)
2730 .map(|(a, b)| (a.0, b.0))
2731 .collect::<Vec<_>>();
2732 assert_eq!(results_after, vec![]);
2733 let results_after_u64 = world
2734 .query::<&W<u64>>()
2735 .iter(&world)
2736 .map(|v| v.0)
2737 .collect::<Vec<_>>();
2738 assert_eq!(results_after_u64, vec![]);
2739 }
2740
2741 #[test]
2742 fn remove_resources() {
2743 let mut world = World::default();
2744 let mut queue = CommandQueue::default();
2745 {
2746 let mut commands = Commands::new(&mut queue, &world);
2747 commands.insert_resource(W(123i32));
2748 commands.insert_resource(W(456.0f64));
2749 }
2750
2751 queue.apply(&mut world);
2752 assert!(world.contains_resource::<W<i32>>());
2753 assert!(world.contains_resource::<W<f64>>());
2754
2755 {
2756 let mut commands = Commands::new(&mut queue, &world);
2757 // test resource removal
2758 commands.remove_resource::<W<i32>>();
2759 }
2760 queue.apply(&mut world);
2761 assert!(!world.contains_resource::<W<i32>>());
2762 assert!(world.contains_resource::<W<f64>>());
2763 }
2764
2765 #[test]
2766 fn remove_component_with_required_components() {
2767 #[derive(Component)]
2768 #[require(Y)]
2769 struct X;
2770
2771 #[derive(Component, Default)]
2772 struct Y;
2773
2774 #[derive(Component)]
2775 struct Z;
2776
2777 let mut world = World::default();
2778 let mut queue = CommandQueue::default();
2779 let e = {
2780 let mut commands = Commands::new(&mut queue, &world);
2781 commands.spawn((X, Z)).id()
2782 };
2783 queue.apply(&mut world);
2784
2785 assert!(world.get::<Y>(e).is_some());
2786 assert!(world.get::<X>(e).is_some());
2787 assert!(world.get::<Z>(e).is_some());
2788
2789 {
2790 let mut commands = Commands::new(&mut queue, &world);
2791 commands.entity(e).remove_with_requires::<X>();
2792 }
2793 queue.apply(&mut world);
2794
2795 assert!(world.get::<Y>(e).is_none());
2796 assert!(world.get::<X>(e).is_none());
2797
2798 assert!(world.get::<Z>(e).is_some());
2799 }
2800
2801 #[test]
2802 fn unregister_system_cached_commands() {
2803 let mut world = World::default();
2804 let mut queue = CommandQueue::default();
2805
2806 fn nothing() {}
2807
2808 let resources = world.iter_resources().count();
2809 let id = world.register_system_cached(nothing);
2810 assert_eq!(world.iter_resources().count(), resources + 1);
2811 assert!(world.get_entity(id.entity).is_ok());
2812
2813 let mut commands = Commands::new(&mut queue, &world);
2814 commands.unregister_system_cached(nothing);
2815 queue.apply(&mut world);
2816 assert_eq!(world.iter_resources().count(), resources);
2817 assert!(world.get_entity(id.entity).is_err());
2818 }
2819
2820 fn is_send<T: Send>() {}
2821 fn is_sync<T: Sync>() {}
2822
2823 #[test]
2824 fn test_commands_are_send_and_sync() {
2825 is_send::<Commands>();
2826 is_sync::<Commands>();
2827 }
2828
2829 #[test]
2830 fn append() {
2831 let mut world = World::default();
2832 let mut queue_1 = CommandQueue::default();
2833 {
2834 let mut commands = Commands::new(&mut queue_1, &world);
2835 commands.insert_resource(W(123i32));
2836 }
2837 let mut queue_2 = CommandQueue::default();
2838 {
2839 let mut commands = Commands::new(&mut queue_2, &world);
2840 commands.insert_resource(W(456.0f64));
2841 }
2842 queue_1.append(&mut queue_2);
2843 queue_1.apply(&mut world);
2844 assert!(world.contains_resource::<W<i32>>());
2845 assert!(world.contains_resource::<W<f64>>());
2846 }
2847
2848 #[test]
2849 fn track_spawn_ticks() {
2850 let mut world = World::default();
2851 world.increment_change_tick();
2852 let expected = world.change_tick();
2853 let id = world.commands().spawn_empty().id();
2854 world.flush();
2855 assert_eq!(
2856 Some(expected),
2857 world.entities().entity_get_spawn_or_despawn_tick(id)
2858 );
2859 }
2860}