Skip to main content

EntityCommands

chunkedge::ecs::system

Struct EntityCommands 

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

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 fallback error handler panics. It can be configured via the FallbackErrorHandler 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>

👎Deprecated:

Use detach_all_children() instead

Removes all the children from this entity. See also detach_all_related

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

Removes all the parent-child relationships from this entity. To despawn the child entities, instead use EntityWorldMut::despawn_children. See also detach_all_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>

👎Deprecated:

Use detach_children() instead

Removes the relationship between this entity and the given entities.

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

Removes the parent-child relationship between this entity and the given entities. Does not despawn the children.

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

👎Deprecated:

Use detach_child() instead

Removes the relationship between this entity and the given entity.

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

Removes the parent-child relationship between this entity and the given entity. Does not despawn the child.

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>

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

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

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

See add_one_related if you want relate only one entity.

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

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.

Relates the given entity to this with the relation R.

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

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

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

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.

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 fn insert_if_neq<T>(&mut self, component: T) -> &mut EntityCommands<'a>
where T: Component + PartialEq,

Adds a Component to the entity if the component is different or missing.

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(&mut self, command: impl EntityCommand) -> &mut EntityCommands<'a>

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

The fallback 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:

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

pub fn queue_handled( &mut self, command: impl EntityCommand, error_handler: fn(BevyError, ErrorContext), ) -> &mut EntityCommands<'a>

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 fallback error handler, see EntityCommands::queue.

The command can be:

§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( &mut self, command: impl EntityCommand, ) -> &mut EntityCommands<'a>

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

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

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

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

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.

Auto Trait Implementations§

§

impl<'a> Freeze for EntityCommands<'a>

§

impl<'a> RefUnwindSafe for EntityCommands<'a>

§

impl<'a> Send for EntityCommands<'a>

§

impl<'a> Sync for EntityCommands<'a>

§

impl<'a> Unpin for EntityCommands<'a>

§

impl<'a> UnsafeUnpin for EntityCommands<'a>

§

impl<'a> !UnwindSafe for EntityCommands<'a>

Blanket Implementations§

Source§

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

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

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

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

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

Source§

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

Mutably borrows from an owned value. Read more
§

impl<T> Conv for T

§

fn conv<T>(self) -> T
where Self: Into<T>,

Converts self into T using Into<T>. Read more
§

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

§

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

Converts Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>, which can then be downcast into Box<dyn ConcreteType> where ConcreteType implements Trait.
§

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

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

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

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

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

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

impl<T> DowncastSend for T
where T: Any + Send,

§

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

Converts Box<Trait> (where Trait: DowncastSend) to Box<dyn Any + Send>, which can then be downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

impl<T> FmtForward for T

§

fn fmt_binary(self) -> FmtBinary<Self>
where Self: Binary,

Causes self to use its Binary implementation when Debug-formatted.
§

fn fmt_display(self) -> FmtDisplay<Self>
where Self: Display,

Causes self to use its Display implementation when Debug-formatted.
§

fn fmt_lower_exp(self) -> FmtLowerExp<Self>
where Self: LowerExp,

Causes self to use its LowerExp implementation when Debug-formatted.
§

fn fmt_lower_hex(self) -> FmtLowerHex<Self>
where Self: LowerHex,

Causes self to use its LowerHex implementation when Debug-formatted.
§

fn fmt_octal(self) -> FmtOctal<Self>
where Self: Octal,

Causes self to use its Octal implementation when Debug-formatted.
§

fn fmt_pointer(self) -> FmtPointer<Self>
where Self: Pointer,

Causes self to use its Pointer implementation when Debug-formatted.
§

fn fmt_upper_exp(self) -> FmtUpperExp<Self>
where Self: UpperExp,

Causes self to use its UpperExp implementation when Debug-formatted.
§

fn fmt_upper_hex(self) -> FmtUpperHex<Self>
where Self: UpperHex,

Causes self to use its UpperHex implementation when Debug-formatted.
§

fn fmt_list(self) -> FmtList<Self>
where &'a Self: for<'a> IntoIterator,

Formats each item in a sequence. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

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

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

fn in_current_span(self) -> Instrumented<Self>

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

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

Source§

fn into(self) -> U

Calls U::from(self).

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

§

impl<T> IntoResult<T> for T

§

fn into_result(self) -> Result<T, RunSystemError>

Converts this type into the system output type.
§

impl<A> Is for A
where A: Any,

§

fn is<T>() -> bool
where T: Any,

Checks if the current type “is” another type, using a TypeId equality comparison. This is most useful in the context of generic logic. Read more
§

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

§

fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> R
where Self: Sized,

Pipes by value. This is generally the method you want to use. Read more
§

fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> R
where R: 'a,

Borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R
where R: 'a,

Mutably borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
where Self: Borrow<B>, B: 'a + ?Sized, R: 'a,

Borrows self, then passes self.borrow() into the pipe function. Read more
§

fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R, ) -> R
where Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more
§

fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
where Self: AsRef<U>, U: 'a + ?Sized, R: 'a,

Borrows self, then passes self.as_ref() into the pipe function.
§

fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
where Self: AsMut<U>, U: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.as_mut() into the pipe function.
§

fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
where Self: Deref<Target = T>, T: 'a + ?Sized, R: 'a,

Borrows self, then passes self.deref() into the pipe function.
§

fn pipe_deref_mut<'a, T, R>( &'a mut self, func: impl FnOnce(&'a mut T) -> R, ) -> R
where Self: DerefMut<Target = T> + Deref, T: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.deref_mut() into the pipe function.
§

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

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<T> Tap for T

§

fn tap(self, func: impl FnOnce(&Self)) -> Self

Immutable access to a value. Read more
§

fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self

Mutable access to a value. Read more
§

fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Immutable access to the Borrow<B> of a value. Read more
§

fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Mutable access to the BorrowMut<B> of a value. Read more
§

fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Immutable access to the AsRef<R> view of a value. Read more
§

fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Mutable access to the AsMut<R> view of a value. Read more
§

fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Immutable access to the Deref::Target of a value. Read more
§

fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Mutable access to the Deref::Target of a value. Read more
§

fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self

Calls .tap() only in debug builds, and is erased in release builds.
§

fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self

Calls .tap_mut() only in debug builds, and is erased in release builds.
§

fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Calls .tap_borrow() only in debug builds, and is erased in release builds.
§

fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds.
§

fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Calls .tap_ref() only in debug builds, and is erased in release builds.
§

fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Calls .tap_ref_mut() only in debug builds, and is erased in release builds.
§

fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Calls .tap_deref() only in debug builds, and is erased in release builds.
§

fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Calls .tap_deref_mut() only in debug builds, and is erased in release builds.
§

impl<T> TryConv for T

§

fn try_conv<T>(self) -> Result<T, Self::Error>
where Self: TryInto<T>,

Attempts to convert self into T using TryInto<T>. Read more
Source§

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

Source§

type Error = Infallible

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

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

Performs the conversion.
Source§

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

Source§

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

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

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

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

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

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

fn with_current_subscriber(self) -> WithDispatch<Self>

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

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

§

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

§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,