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 via the DefaultErrorHandler resource.

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 EntityCommands<'a>

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 EntityCommands<'a>

Adds the given children to this entity

pub fn clear_children(&mut self) -> &mut EntityCommands<'a>

Removes all the children from this entity. See also clear_related

pub fn insert_children( &mut self, index: usize, children: &[Entity], ) -> &mut EntityCommands<'a>

Insert children at specific index. See also insert_related.

pub fn insert_child( &mut self, index: usize, child: Entity, ) -> &mut EntityCommands<'a>

Insert children at specific index. See also insert_related.

pub fn add_child(&mut self, child: Entity) -> &mut EntityCommands<'a>

Adds the given child to this entity

pub fn remove_children( &mut self, children: &[Entity], ) -> &mut EntityCommands<'a>

Removes the relationship between this entity and the given entities.

pub fn remove_child(&mut self, child: Entity) -> &mut EntityCommands<'a>

Removes the relationship between this entity and the given entity.

pub fn replace_children( &mut self, children: &[Entity], ) -> &mut EntityCommands<'a>

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 EntityCommands<'a>

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 broken and the command is executed.

pub fn with_child(&mut self, bundle: impl Bundle) -> &mut EntityCommands<'a>

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

For efficient spawning of multiple children, use with_children.

impl<'a> EntityCommands<'a>

pub fn with_related<R>( &mut self, bundle: impl Bundle, ) -> &mut EntityCommands<'a>

where R: Relationship,

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

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

where R: Relationship,

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

pub fn add_related<R>(&mut self, related: &[Entity]) -> &mut EntityCommands<'a>

where R: Relationship,

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

See add_one_related if you want relate only one entity.

pub fn clear_related<R>(&mut self) -> &mut EntityCommands<'a>

where R: Relationship,

Removes the relation R between this entity and all its related entities.

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

where R: Relationship, <<R as Relationship>::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>(&mut self, entity: Entity) -> &mut EntityCommands<'a>

where R: Relationship,

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>( &mut self, related: &[Entity], ) -> &mut EntityCommands<'a>

where R: Relationship,

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

pub fn replace_related<R>( &mut self, related: &[Entity], ) -> &mut EntityCommands<'a>

where R: Relationship,

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

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

where R: Relationship,

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>(&mut self) -> &mut EntityCommands<'a>

where S: RelationshipTarget,

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

pub fn despawn_children(&mut self) -> &mut EntityCommands<'a>

Despawns the children of this entity. This entity will not be despawned.

This is a specialization of despawn_related, a more general method for despawning via relationships.

pub fn insert_recursive<S>( &mut self, bundle: impl Bundle + Clone, ) -> &mut EntityCommands<'a>

where S: RelationshipTarget,

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, B>(&mut self) -> &mut EntityCommands<'a>

where S: RelationshipTarget, B: Bundle,

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

where T: Component,

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


#[derive(Component, Default)]
struct Mana {
    max: u32,
    current: u32,
}

fn level_up_system(mut commands: Commands, player: Res<PlayerEntity>) {
    // If a component already exists then modify it, otherwise insert a default value
    commands
        .entity(player.entity)
        .entry::<Level>()
        .and_modify(|mut lvl| lvl.0 += 1)
        .or_insert(Level(0));

    // Add a default value if none exists, and then modify the existing or new value
    commands
        .entity(player.entity)
        .entry::<Mana>()
        .or_default()
        .and_modify(|mut mana| {
            mana.max += 10;
            mana.current = mana.max;
    });
}

pub fn insert(&mut self, bundle: impl Bundle) -> &mut EntityCommands<'a>

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 EntityCommands<'a>

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 EntityCommands<'a>

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 EntityCommands<'a>

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>( &mut self, component_id: ComponentId, value: T, ) -> &mut EntityCommands<'a>

where T: Send + 'static,

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>( &mut self, component_id: ComponentId, value: T, ) -> &mut EntityCommands<'a>

where T: Send + 'static,

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 EntityCommands<'a>

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 EntityCommands<'a>

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 EntityCommands<'a>

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 EntityCommands<'a>

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>(&mut self) -> &mut EntityCommands<'a>

where B: Bundle,

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 remove_if<B>( &mut self, condition: impl FnOnce() -> bool, ) -> &mut EntityCommands<'a>

where B: Bundle,

Removes a Bundle of components from the entity if the predicate returns true.

This is useful for chaining method calls.

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)
        .remove_if::<(Defense, CombatBundle)>(|| !player.is_spectator());
}

pub fn try_remove_if<B>( &mut self, condition: impl FnOnce() -> bool, ) -> &mut EntityCommands<'a>

where B: Bundle,

Removes a Bundle of components from 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_remove<B>(&mut self) -> &mut EntityCommands<'a>

where B: Bundle,

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>(&mut self) -> &mut EntityCommands<'a>

where B: Bundle,

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 EntityCommands<'a>

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 EntityCommands<'a>

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 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, T, M>(&mut self, command: C) -> &mut EntityCommands<'a>

where C: EntityCommand<T> + CommandWithEntity<M>,

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, T, M>( &mut self, command: C, error_handler: fn(BevyError, ErrorContext), ) -> &mut EntityCommands<'a>

where C: EntityCommand<T> + CommandWithEntity<M>,

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 queue_silenced<C, T, M>(&mut self, command: C) -> &mut EntityCommands<'a>

where C: EntityCommand<T> + CommandWithEntity<M>,

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

Unlike EntityCommands::queue_handled, this will completely ignore any errors that occur.

pub fn retain<B>(&mut self) -> &mut EntityCommands<'a>

where B: Bundle,

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 EntityCommands<'a>

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 observe<E, B, M>( &mut self, observer: impl IntoObserverSystem<E, B, M>, ) -> &mut EntityCommands<'a>

where E: EntityEvent, B: Bundle,

Creates an Observer watching for an EntityEvent of type E whose EntityEvent::event_target targets this entity.

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

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

The other entity will receive all the components of the original that implement Clone or Reflect except those that are denied in the config.

Panics

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

Example

Configure through EntityClonerBuilder<OptOut> 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 ComponentA but not ComponentB onto the target.
    entity.clone_with_opt_out(target, |builder| {
        builder.deny::<ComponentB>();
    });
}

See EntityClonerBuilder for more options.

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

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

The other entity will receive only the components of the original that implement Clone or Reflect and are allowed in the config.

Panics

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

Example

Configure through EntityClonerBuilder<OptIn> 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 ComponentA but not ComponentB onto the target.
    entity.clone_with_opt_in(target, |builder| {
        builder.allow::<ComponentA>();
    });
}

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_opt_out/ opt_out.

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 entity.
    let mut entity_clone = entity.clone_and_spawn();
}

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

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

The clone will receive all the components of the original that implement Clone or Reflect except those that are denied in the config.

See the methods on EntityClonerBuilder<OptOut> 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 entity with ComponentA but without ComponentB.
    let mut entity_clone = entity.clone_and_spawn_with_opt_out(|builder| {
        builder.deny::<ComponentB>();
    });
}

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

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

The clone will receive only the components of the original that implement Clone or Reflect and are allowed in the config.

See the methods on EntityClonerBuilder<OptIn> 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 entity with ComponentA but without ComponentB.
    let mut entity_clone = entity.clone_and_spawn_with_opt_in(|builder| {
        builder.allow::<ComponentA>();
    });
}

pub fn clone_components<B>(&mut self, target: Entity) -> &mut EntityCommands<'a>

where B: Bundle,

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

where B: Bundle,

Moves the specified components of this entity into another entity.

Components with Ignore clone behavior will not be moved, while components that have a Custom clone behavior will be cloned using it and then removed from the source entity. All other components will be moved without any other special handling.

Note that this will trigger on_remove hooks/observers on this entity and on_insert/on_add hooks/observers on the target entity.

Panics

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

pub fn trigger<'t, E>( &mut self, event_fn: impl FnOnce(Entity) -> E, ) -> &mut EntityCommands<'a>

where E: EntityEvent, <E as Event>::Trigger<'t>: Default,

Passes the current entity into the given function, and triggers the EntityEvent returned by that function.

Example

A surprising number of functions meet the trait bounds for event_fn:

#[derive(EntityEvent)]
struct Explode(Entity);

impl From<Entity> for Explode {
   fn from(entity: Entity) -> Self {
      Explode(entity)
   }
}


fn trigger_via_constructor(mut commands: Commands) {
    // The fact that `Epxlode` is a single-field tuple struct
    // ensures that `Explode(entity)` is a function that generates
    // an EntityEvent, meeting the trait bounds for `event_fn`.
    commands.spawn_empty().trigger(Explode);

}


fn trigger_via_from_trait(mut commands: Commands) {
    // This variant also works for events like `struct Explode { entity: Entity }`
    commands.spawn_empty().trigger(Explode::from);
}

fn trigger_via_closure(mut commands: Commands) {
    commands.spawn_empty().trigger(|entity| Explode(entity));
}

Trait Implementations

impl BuildChildrenTransformExt for EntityCommands<'_>

fn set_parent_in_place(&mut self, parent: Entity) -> &mut EntityCommands<'_>

Change this entity’s parent while preserving this entity’s GlobalTransform by updating its Transform.

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

Make this entity parentless while preserving this entity’s GlobalTransform by updating its Transform to be equal to its current GlobalTransform.

impl ReflectCommandExt for EntityCommands<'_>

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

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

fn insert_reflect_with_registry<T>( &mut self, component: Box<dyn PartialReflect>, ) -> &mut EntityCommands<'_>

where T: Resource + AsRef<TypeRegistry>,

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

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

fn remove_reflect_with_registry<T>( &mut self, component_type_path: impl Into<Cow<'static, str>>, ) -> &mut EntityCommands<'_>

where T: Resource + AsRef<TypeRegistry>,

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