Struct EntityCommands

pub struct EntityCommands<'a> { /* private fields */ }

A list of commands that will be run to modify an Entity.

Note

Most Commands (and thereby EntityCommands) are deferred: when you call the command, if it requires mutable access to the World (that is, if it removes, adds, or changes something), it’s not executed immediately.

Instead, the command is added to a “command queue.” The command queue is applied later when the ApplyDeferred system runs. Commands are executed one-by-one so that each command can have exclusive access to the World.

Fallible

Due to their deferred nature, an entity you’re trying to change with an EntityCommand can be despawned by the time the command is executed.

All deferred entity commands will check whether the entity exists at the time of execution and will return an error if it doesn’t.

Error handling

An EntityCommand can return a Result, which will be passed to an error handler if the Result is an error.

The default error handler panics. It can be configured by setting the GLOBAL_ERROR_HANDLER.

Alternatively, you can customize the error handler for a specific command by calling EntityCommands::queue_handled.

The error module provides some simple error handlers for convenience.

Implementations

impl<'a> EntityCommands<'a>

pub fn with_children( &mut self, func: impl FnOnce(&mut RelatedSpawnerCommands<'_, ChildOf>), ) -> &mut Self

Spawns children of this entity (with a ChildOf relationship) by taking a function that operates on a ChildSpawner.

pub fn add_children(&mut self, children: &[Entity]) -> &mut Self

Adds the given children to this entity

pub fn insert_children( &mut self, index: usize, children: &[Entity], ) -> &mut Self

Insert children at specific index. See also insert_related.

pub fn add_child(&mut self, child: Entity) -> &mut Self

Adds the given child to this entity

pub fn remove_children(&mut self, children: &[Entity]) -> &mut Self

Removes the relationship between this entity and the given entities.

pub fn replace_children(&mut self, children: &[Entity]) -> &mut Self

Replaces the children on this entity with a new list of children.

pub fn replace_children_with_difference( &mut self, entities_to_unrelate: &[Entity], entities_to_relate: &[Entity], newly_related_entities: &[Entity], ) -> &mut Self

Replaces all the related entities with a new set of entities.

Warning

Failing to maintain the functions invariants may lead to erratic engine behavior including random crashes. Refer to EntityWorldMut::replace_related_with_difference for a list of these invariants.

Panics

Panics when debug assertions are enabled if an invariant is is broken and the command is executed.

pub fn with_child(&mut self, bundle: impl Bundle) -> &mut Self

Spawns the passed bundle and adds it to this entity as a child.

For efficient spawning of multiple children, use with_children.

pub fn remove_parent(&mut self) -> &mut Self

👎Deprecated since 0.16.0: Use entity_commands.remove::<ChildOf>()

Removes the ChildOf component, if it exists.

pub fn set_parent(&mut self, parent: Entity) -> &mut Self

👎Deprecated since 0.16.0: Use entity_commands.insert(ChildOf(entity))

Inserts the ChildOf component with the given parent entity, if it exists.

impl<'a> EntityCommands<'a>

pub fn with_related<R: Relationship>( &mut self, bundle: impl Bundle, ) -> &mut Self

Spawns a entity related to this entity (with the R relationship) by taking a bundle

pub fn with_related_entities<R: Relationship>( &mut self, func: impl FnOnce(&mut RelatedSpawnerCommands<'_, R>), ) -> &mut Self

Spawns entities related to this entity (with the R relationship) by taking a function that operates on a RelatedSpawner.

pub fn add_related<R: Relationship>(&mut self, related: &[Entity]) -> &mut Self

Relates the given entities to this entity with the relation R.

See add_one_related if you want relate only one entity.

pub fn insert_related<R: Relationship>( &mut self, index: usize, related: &[Entity], ) -> &mut Self

where <R::RelationshipTarget as RelationshipTarget>::Collection: OrderedRelationshipSourceCollection,

Relates the given entities to this entity with the relation R, starting at this particular index.

If the related has duplicates, a related entity will take the index of its last occurrence in related. If the indices go out of bounds, they will be clamped into bounds. This will not re-order existing related entities unless they are in related.

pub fn add_one_related<R: Relationship>(&mut self, entity: Entity) -> &mut Self

Relates the given entity to this with the relation R.

See add_related if you want to relate more than one entity.

pub fn remove_related<R: Relationship>( &mut self, related: &[Entity], ) -> &mut Self

Removes the relation R between this entity and the given entities.

pub fn replace_related<R: Relationship>( &mut self, related: &[Entity], ) -> &mut Self

Replaces all the related entities with the given set of new related entities.

pub fn replace_related_with_difference<R: Relationship>( &mut self, entities_to_unrelate: &[Entity], entities_to_relate: &[Entity], newly_related_entities: &[Entity], ) -> &mut Self

Replaces all the related entities with a new set of entities.

Warning

Failing to maintain the functions invariants may lead to erratic engine behavior including random crashes. Refer to EntityWorldMut::replace_related_with_difference for a list of these invariants.

Panics

Panics when debug assertions are enable, an invariant is are broken and the command is executed.

pub fn despawn_related<S: RelationshipTarget>(&mut self) -> &mut Self

Despawns entities that relate to this one via the given RelationshipTarget. This entity will not be despawned.

pub fn insert_recursive<S: RelationshipTarget>( &mut self, bundle: impl Bundle + Clone, ) -> &mut Self

Inserts a component or bundle of components into the entity and all related entities, traversing the relationship tracked in S in a breadth-first manner.

Warning

This method should only be called on relationships that form a tree-like structure. Any cycles will cause this method to loop infinitely.

pub fn remove_recursive<S: RelationshipTarget, B: Bundle>( &mut self, ) -> &mut Self

Removes a component or bundle of components of type B from the entity and all related entities, traversing the relationship tracked in S in a breadth-first manner.

Warning

This method should only be called on relationships that form a tree-like structure. Any cycles will cause this method to loop infinitely.

impl<'a> EntityCommands<'a>

pub fn id(&self) -> Entity

Returns the Entity id of the entity.

Example

fn my_system(mut commands: Commands) {
    let entity_id = commands.spawn_empty().id();
}

pub fn reborrow(&mut self) -> EntityCommands<'_>

Returns an EntityCommands with a smaller lifetime.

This is useful if you have &mut EntityCommands but you need EntityCommands.

pub fn entry<T: Component>(&mut self) -> EntityEntryCommands<'_, T>

Get an EntityEntryCommands for the Component T, allowing you to modify it or insert it if it isn’t already present.

See also insert_if_new, which lets you insert a Bundle without overwriting it.

Example

#[derive(Component)]
struct Level(u32);

fn level_up_system(mut commands: Commands, player: Res<PlayerEntity>) {
    commands
        .entity(player.entity)
        .entry::<Level>()
        // Modify the component if it exists.
        .and_modify(|mut lvl| lvl.0 += 1)
        // Otherwise, insert a default value.
        .or_insert(Level(0));
}

pub fn insert(&mut self, bundle: impl Bundle) -> &mut Self

Adds a Bundle of components to the entity.

This will overwrite any previous value(s) of the same component type. See EntityCommands::insert_if_new to keep the old value instead.

Example

#[derive(Component)]
struct Health(u32);
#[derive(Component)]
struct Strength(u32);
#[derive(Component)]
struct Defense(u32);

#[derive(Bundle)]
struct CombatBundle {
    health: Health,
    strength: Strength,
}

fn add_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
    commands
        .entity(player.entity)
        // You can insert individual components:
        .insert(Defense(10))
        // You can also insert pre-defined bundles of components:
        .insert(CombatBundle {
            health: Health(100),
            strength: Strength(40),
        })
        // You can also insert tuples of components and bundles.
        // This is equivalent to the calls above:
        .insert((
            Defense(10),
            CombatBundle {
                health: Health(100),
                strength: Strength(40),
            },
        ));
}

pub fn insert_if<F>(&mut self, bundle: impl Bundle, condition: F) -> &mut Self

where F: FnOnce() -> bool,

Adds a Bundle of components to the entity if the predicate returns true.

This is useful for chaining method calls.

Example

#[derive(Component)]
struct StillLoadingStats;
#[derive(Component)]
struct Health(u32);

fn add_health_system(mut commands: Commands, player: Res<PlayerEntity>) {
    commands
        .entity(player.entity)
        .insert_if(Health(10), || !player.is_spectator())
        .remove::<StillLoadingStats>();
}

pub fn insert_if_new(&mut self, bundle: impl Bundle) -> &mut Self

Adds a Bundle of components to the entity without overwriting.

This is the same as EntityCommands::insert, but in case of duplicate components will leave the old values instead of replacing them with new ones.

See also entry, which lets you modify a Component if it’s present, as well as initialize it with a default value.

pub fn insert_if_new_and<F>( &mut self, bundle: impl Bundle, condition: F, ) -> &mut Self

where F: FnOnce() -> bool,

Adds a Bundle of components to the entity without overwriting if the predicate returns true.

This is the same as EntityCommands::insert_if, but in case of duplicate components will leave the old values instead of replacing them with new ones.

pub unsafe fn insert_by_id<T: Send + 'static>( &mut self, component_id: ComponentId, value: T, ) -> &mut Self

Adds a dynamic Component to the entity.

This will overwrite any previous value(s) of the same component type.

You should prefer to use the typed API EntityCommands::insert where possible.

Safety

• ComponentId must be from the same world as self.
• T must have the same layout as the one passed during component_id creation.

pub unsafe fn try_insert_by_id<T: Send + 'static>( &mut self, component_id: ComponentId, value: T, ) -> &mut Self

Adds a dynamic Component to the entity.

This will overwrite any previous value(s) of the same component type.

You should prefer to use the typed API EntityCommands::try_insert where possible.

Note

If the entity does not exist when this command is executed, the resulting error will be ignored.

Safety

• ComponentId must be from the same world as self.
• T must have the same layout as the one passed during component_id creation.

pub fn try_insert(&mut self, bundle: impl Bundle) -> &mut Self

Adds a Bundle of components to the entity.

This will overwrite any previous value(s) of the same component type.

Note

If the entity does not exist when this command is executed, the resulting error will be ignored.

Example

#[derive(Component)]
struct Health(u32);
#[derive(Component)]
struct Strength(u32);
#[derive(Component)]
struct Defense(u32);

#[derive(Bundle)]
struct CombatBundle {
    health: Health,
    strength: Strength,
}

fn add_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
    commands.entity(player.entity)
        // You can insert individual components:
        .try_insert(Defense(10))
        // You can also insert tuples of components:
        .try_insert(CombatBundle {
            health: Health(100),
            strength: Strength(40),
        });

    // Suppose this occurs in a parallel adjacent system or process.
    commands.entity(player.entity).despawn();

    // This will not panic nor will it add the component.
    commands.entity(player.entity).try_insert(Defense(5));
}

pub fn try_insert_if<F>( &mut self, bundle: impl Bundle, condition: F, ) -> &mut Self

where F: FnOnce() -> bool,

Adds a Bundle of components to the entity if the predicate returns true.

This is useful for chaining method calls.

Note

If the entity does not exist when this command is executed, the resulting error will be ignored.

pub fn try_insert_if_new_and<F>( &mut self, bundle: impl Bundle, condition: F, ) -> &mut Self

where F: FnOnce() -> bool,

Adds a Bundle of components to the entity without overwriting if the predicate returns true.

This is the same as EntityCommands::try_insert_if, but in case of duplicate components will leave the old values instead of replacing them with new ones.

Note

If the entity does not exist when this command is executed, the resulting error will be ignored.

pub fn try_insert_if_new(&mut self, bundle: impl Bundle) -> &mut Self

Adds a Bundle of components to the entity without overwriting.

This is the same as EntityCommands::try_insert, but in case of duplicate components will leave the old values instead of replacing them with new ones.

Note

If the entity does not exist when this command is executed, the resulting error will be ignored.

pub fn remove<B: Bundle>(&mut self) -> &mut Self

Removes a Bundle of components from the entity.

This will remove all components that intersect with the provided bundle; the entity does not need to have all the components in the bundle.

This will emit a warning if the entity does not exist.

Example

#[derive(Component)]
struct Health(u32);
#[derive(Component)]
struct Strength(u32);
#[derive(Component)]
struct Defense(u32);

#[derive(Bundle)]
struct CombatBundle {
    health: Health,
    strength: Strength,
}

fn remove_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
    commands
        .entity(player.entity)
        // You can remove individual components:
        .remove::<Defense>()
        // You can also remove pre-defined bundles of components:
        .remove::<CombatBundle>()
        // You can also remove tuples of components and bundles.
        // This is equivalent to the calls above:
        .remove::<(Defense, CombatBundle)>();
}

pub fn try_remove<B: Bundle>(&mut self) -> &mut Self

Removes a Bundle of components from the entity.

This will remove all components that intersect with the provided bundle; the entity does not need to have all the components in the bundle.

Unlike Self::remove, this will not emit a warning if the entity does not exist.

Example

#[derive(Component)]
struct Health(u32);
#[derive(Component)]
struct Strength(u32);
#[derive(Component)]
struct Defense(u32);

#[derive(Bundle)]
struct CombatBundle {
    health: Health,
    strength: Strength,
}

fn remove_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
    commands
        .entity(player.entity)
        // You can remove individual components:
        .try_remove::<Defense>()
        // You can also remove pre-defined bundles of components:
        .try_remove::<CombatBundle>()
        // You can also remove tuples of components and bundles.
        // This is equivalent to the calls above:
        .try_remove::<(Defense, CombatBundle)>();
}

pub fn remove_with_requires<B: Bundle>(&mut self) -> &mut Self

Removes a Bundle of components from the entity, and also removes any components required by the components in the bundle.

This will remove all components that intersect with the provided bundle; the entity does not need to have all the components in the bundle.

Example

#[derive(Component)]
#[require(B)]
struct A;
#[derive(Component, Default)]
struct B;

fn remove_with_requires_system(mut commands: Commands, player: Res<PlayerEntity>) {
    commands
        .entity(player.entity)
        // Removes both A and B from the entity, because B is required by A.
        .remove_with_requires::<A>();
}

pub fn remove_by_id(&mut self, component_id: ComponentId) -> &mut Self

Removes a dynamic Component from the entity if it exists.

Panics

Panics if the provided ComponentId does not exist in the World.

pub fn clear(&mut self) -> &mut Self

Removes all components associated with the entity.

pub fn despawn(&mut self)

Despawns the entity.

This will emit a warning if the entity does not exist.

Note

This will also despawn the entities in any RelationshipTarget that is configured to despawn descendants.

For example, this will recursively despawn Children.

Example

fn remove_character_system(
    mut commands: Commands,
    character_to_remove: Res<CharacterToRemove>
) {
    commands.entity(character_to_remove.entity).despawn();
}

pub fn despawn_recursive(&mut self)

👎Deprecated since 0.16.0: Use entity.despawn(), which now automatically despawns recursively.

Despawns the provided entity and its descendants.

pub fn try_despawn(&mut self)

Despawns the entity.

Unlike Self::despawn, this will not emit a warning if the entity does not exist.

Note

This will also despawn the entities in any RelationshipTarget that is configured to despawn descendants.

For example, this will recursively despawn Children.

pub fn queue<C: EntityCommand<T> + CommandWithEntity<M>, T, M>( &mut self, command: C, ) -> &mut Self

Pushes an EntityCommand to the queue, which will get executed for the current Entity.

The default error handler will be used to handle error cases. Every EntityCommand checks whether the entity exists at the time of execution and returns an error if it does not.

To use a custom error handler, see EntityCommands::queue_handled.

The command can be:

• A custom struct that implements EntityCommand.
• A closure or function that matches the following signature:
  • (EntityWorldMut)
  • (EntityWorldMut) -> Result
• A built-in command from the entity_command module.

Example

commands
    .spawn_empty()
    // Closures with this signature implement `EntityCommand`.
    .queue(|entity: EntityWorldMut| {
        println!("Executed an EntityCommand for {}", entity.id());
    });

pub fn queue_handled<C: EntityCommand<T> + CommandWithEntity<M>, T, M>( &mut self, command: C, error_handler: fn(BevyError, ErrorContext), ) -> &mut Self

Pushes an EntityCommand to the queue, which will get executed for the current Entity.

The given error_handler will be used to handle error cases. Every EntityCommand checks whether the entity exists at the time of execution and returns an error if it does not.

To implicitly use the default error handler, see EntityCommands::queue.

The command can be:

• A custom struct that implements EntityCommand.
• A closure or function that matches the following signature:
  • (EntityWorldMut)
  • (EntityWorldMut) -> Result
• A built-in command from the entity_command module.

Example

use bevy_ecs::error::warn;

commands
    .spawn_empty()
    // Closures with this signature implement `EntityCommand`.
    .queue_handled(
        |entity: EntityWorldMut| -> Result {
            let value: usize = "100".parse()?;
            println!("Successfully parsed the value {} for entity {}", value, entity.id());
            Ok(())
        },
        warn
    );

pub fn retain<B: Bundle>(&mut self) -> &mut Self

Removes all components except the given Bundle from the entity.

Example

#[derive(Component)]
struct Health(u32);
#[derive(Component)]
struct Strength(u32);
#[derive(Component)]
struct Defense(u32);

#[derive(Bundle)]
struct CombatBundle {
    health: Health,
    strength: Strength,
}

fn remove_combat_stats_system(mut commands: Commands, player: Res<PlayerEntity>) {
    commands
        .entity(player.entity)
        // You can retain a pre-defined Bundle of components,
        // with this removing only the Defense component.
        .retain::<CombatBundle>()
        // You can also retain only a single component.
        .retain::<Health>();
}

pub fn log_components(&mut self) -> &mut Self

Logs the components of the entity at the info level.

pub fn commands(&mut self) -> Commands<'_, '_>

Returns the underlying Commands.

pub fn commands_mut(&mut self) -> &mut Commands<'a, 'a>

Returns a mutable reference to the underlying Commands.

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

Sends a Trigger targeting the entity.

This will run any Observer of the given Event watching this entity.

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

Creates an Observer listening for events of type E targeting this entity.

pub fn clone_with( &mut self, target: Entity, config: impl FnOnce(&mut EntityClonerBuilder<'_>) + Send + Sync + 'static, ) -> &mut Self

Clones parts of an entity (components, observers, etc.) onto another entity, configured through EntityClonerBuilder.

By default, the other entity will receive all the components of the original that implement Clone or Reflect.

Panics

The command will panic when applied if the target entity does not exist.

Example

Configure through EntityClonerBuilder as follows:

#[derive(Component, Clone)]
struct ComponentA(u32);
#[derive(Component, Clone)]
struct ComponentB(u32);

fn example_system(mut commands: Commands) {
    // Create an empty entity.
    let target = commands.spawn_empty().id();

    // Create a new entity and keep its EntityCommands.
    let mut entity = commands.spawn((ComponentA(10), ComponentB(20)));

    // Clone only ComponentA onto the target.
    entity.clone_with(target, |builder| {
        builder.deny::<ComponentB>();
    });
}

See EntityClonerBuilder for more options.

pub fn clone_and_spawn(&mut self) -> EntityCommands<'_>

Spawns a clone of this entity and returns the EntityCommands of the clone.

The clone will receive all the components of the original that implement Clone or Reflect.

To configure cloning behavior (such as only cloning certain components), use EntityCommands::clone_and_spawn_with.

Note

If the original entity does not exist when this command is applied, the returned entity will have no components.

Example

#[derive(Component, Clone)]
struct ComponentA(u32);
#[derive(Component, Clone)]
struct ComponentB(u32);

fn example_system(mut commands: Commands) {
    // Create a new entity and store its EntityCommands.
    let mut entity = commands.spawn((ComponentA(10), ComponentB(20)));

    // Create a clone of the first entity.
    let mut entity_clone = entity.clone_and_spawn();
}

pub fn clone_and_spawn_with( &mut self, config: impl FnOnce(&mut EntityClonerBuilder<'_>) + Send + Sync + 'static, ) -> EntityCommands<'_>

Spawns a clone of this entity and allows configuring cloning behavior using EntityClonerBuilder, returning the EntityCommands of the clone.

By default, the clone will receive all the components of the original that implement Clone or Reflect.

To exclude specific components, use EntityClonerBuilder::deny. To only include specific components, use EntityClonerBuilder::deny_all followed by EntityClonerBuilder::allow.

See the methods on EntityClonerBuilder for more options.

Note

If the original entity does not exist when this command is applied, the returned entity will have no components.

Example

#[derive(Component, Clone)]
struct ComponentA(u32);
#[derive(Component, Clone)]
struct ComponentB(u32);

fn example_system(mut commands: Commands) {
    // Create a new entity and store its EntityCommands.
    let mut entity = commands.spawn((ComponentA(10), ComponentB(20)));

    // Create a clone of the first entity, but without ComponentB.
    let mut entity_clone = entity.clone_and_spawn_with(|builder| {
        builder.deny::<ComponentB>();
    });
}

pub fn clone_components<B: Bundle>(&mut self, target: Entity) -> &mut Self

Clones the specified components of this entity and inserts them into another entity.

Components can only be cloned if they implement Clone or Reflect.

Panics

The command will panic when applied if the target entity does not exist.

pub fn move_components<B: Bundle>(&mut self, target: Entity) -> &mut Self

Clones the specified components of this entity and inserts them into another entity, then removes the components from this entity.

Components can only be cloned if they implement Clone or Reflect.

Panics

The command will panic when applied if the target entity does not exist.

Trait Implementations

impl ReflectCommandExt for EntityCommands<'_>

Available on crate feature bevy_reflect only.

fn insert_reflect(&mut self, component: Box<dyn PartialReflect>) -> &mut Self

Adds the given boxed reflect component or bundle to the entity using the reflection data in AppTypeRegistry.

fn insert_reflect_with_registry<T: Resource + AsRef<TypeRegistry>>( &mut self, component: Box<dyn PartialReflect>, ) -> &mut Self

Same as insert_reflect, but using the T resource as type registry instead of AppTypeRegistry.

fn remove_reflect( &mut self, component_type_path: impl Into<Cow<'static, str>>, ) -> &mut Self

Removes from the entity the component or bundle with the given type name registered in AppTypeRegistry.

fn remove_reflect_with_registry<T: Resource + AsRef<TypeRegistry>>( &mut self, component_type_path: impl Into<Cow<'static, str>>, ) -> &mut Self

Same as remove_reflect, but using the T resource as type registry instead of AppTypeRegistry.