Struct EntityWorldMut

pub struct EntityWorldMut<'w> { /* private fields */ }

A mutable reference to a particular Entity, and the entire world.

This is essentially a performance-optimized (Entity, &mut World) tuple, which caches the EntityLocation to reduce duplicate lookups.

Since this type provides mutable access to the entire world, only one EntityWorldMut can exist at a time for a given world.

See also EntityMut, which allows disjoint mutable access to multiple entities at once. Unlike EntityMut, this type allows adding and removing components, and despawning the entity.

Implementations

impl<'w> EntityWorldMut<'w>

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

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

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

Adds the given children to this entity See also add_related.

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 See also add_related.

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 all the related children with a new set 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 children with a new set of children.

Warning

Failing to maintain the functions invariants may lead to erratic engine behavior including random crashes. Refer to Self::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_mut.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_mut.insert(ChildOf(entity))

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

impl<'w> EntityWorldMut<'w>

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

Available on crate feature bevy_reflect only.

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

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

Panics

• If the entity has been despawned while this EntityWorldMut is still alive.
• If AppTypeRegistry does not have the reflection data for the given Component or Bundle.
• If the component or bundle data is invalid. See PartialReflect::apply for further details.
• If AppTypeRegistry is not present in the World.

Note

Prefer to use the typed EntityWorldMut::insert if possible. Adding a reflected component is much slower.

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

Available on crate feature bevy_reflect only.

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

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

Panics

• If the entity has been despawned while this EntityWorldMut is still alive.
• If the given Resource does not have the reflection data for the given Component or Bundle.
• If the component or bundle data is invalid. See PartialReflect::apply for further details.
• If the given Resource is not present in the World.

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

Available on crate feature bevy_reflect only.

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

If the type is a bundle, it will remove any components in that bundle regardless if the entity contains all the components.

Does nothing if the type is a component and the entity does not have a component of the same type, if the type is a bundle and the entity does not contain any of the components in the bundle, or if AppTypeRegistry does not contain the reflection data for the given component.

Panics

• If the entity has been despawned while this EntityWorldMut is still alive.
• If AppTypeRegistry is not present in the World.

Note

Prefer to use the typed EntityCommands::remove if possible. Removing a reflected component is much slower.

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

Available on crate feature bevy_reflect only.

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

If the given type is a bundle, it will remove any components in that bundle regardless if the entity contains all the components.

Does nothing if the type is a component and the entity does not have a component of the same type, if the type is a bundle and the entity does not contain any of the components in the bundle, or if AppTypeRegistry does not contain the reflection data for the given component.

Panics

• If the entity has been despawned while this EntityWorldMut is still alive.
• If AppTypeRegistry is not present in the World.

impl<'w> EntityWorldMut<'w>

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 RelatedSpawner<'_, 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.

Example

use bevy_ecs::prelude::*;

let mut world = World::new();
let e0 = world.spawn_empty().id();
let e1 = world.spawn_empty().id();
let e2 = world.spawn_empty().id();
let e3 = world.spawn_empty().id();
let e4 = world.spawn_empty().id();

let mut main_entity = world.spawn_empty();
main_entity.add_related::<ChildOf>(&[e0, e1, e2, e2]);
main_entity.insert_related::<ChildOf>(1, &[e0, e3, e4, e4]);
let main_id = main_entity.id();

let relationship_source = main_entity.get::<Children>().unwrap().collection();
assert_eq!(relationship_source, &[e1, e0, e3, e2, e4]);

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 a new set of 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.

This is a more efficient of Self::replace_related which doesn’t allocate. The passed in arguments must adhere to these invariants:

• entities_to_unrelate: A slice of entities to remove from the relationship source. Entities need not be related to this entity, but must not appear in entities_to_relate
• entities_to_relate: A slice of entities to relate to this entity. This must contain all entities that will remain related (i.e. not those in entities_to_unrelate) plus the newly related entities.
• newly_related_entities: A subset of entities_to_relate containing only entities not already related to this entity.
• Slices must not contain any duplicates

Warning

Violating these invariants may lead to panics, crashes or unpredictable engine behavior.

Panics

Panics when debug assertions are enabled and any invariants are broken.

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 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<'w> EntityWorldMut<'w>

pub fn into_readonly(self) -> EntityRef<'w>

Consumes self and returns read-only access to all of the entity’s components, with the world 'w lifetime.

pub fn as_readonly(&self) -> EntityRef<'_>

Gets read-only access to all of the entity’s components.

pub fn into_mutable(self) -> EntityMut<'w>

Consumes self and returns non-structural mutable access to all of the entity’s components, with the world 'w lifetime.

pub fn as_mutable(&mut self) -> EntityMut<'_>

Gets non-structural mutable access to all of the entity’s components.

pub fn id(&self) -> Entity

Returns the ID of the current entity.

pub fn location(&self) -> EntityLocation

Gets metadata indicating the location where the current entity is stored.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn archetype(&self) -> &Archetype

Returns the archetype that the current entity belongs to.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn contains<T: Component>(&self) -> bool

Returns true if the current entity has a component of type T. Otherwise, this returns false.

Notes

If you do not know the concrete type of a component, consider using Self::contains_id or Self::contains_type_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn contains_id(&self, component_id: ComponentId) -> bool

Returns true if the current entity has a component identified by component_id. Otherwise, this returns false.

Notes

• If you know the concrete type of the component, you should prefer Self::contains.
• If you know the component’s TypeId but not its ComponentId, consider using Self::contains_type_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn contains_type_id(&self, type_id: TypeId) -> bool

Returns true if the current entity has a component with the type identified by type_id. Otherwise, this returns false.

Notes

• If you know the concrete type of the component, you should prefer Self::contains.
• If you have a ComponentId instead of a TypeId, consider using Self::contains_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn get<T: Component>(&self) -> Option<&T>

Gets access to the component of type T for the current entity. Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn components<Q: ReadOnlyQueryData>(&self) -> Q::Item<'_>

Returns read-only components for the current entity that match the query Q.

Panics

If the entity does not have the components required by the query Q or if the entity has been despawned while this EntityWorldMut is still alive.

pub fn get_components<Q: ReadOnlyQueryData>(&self) -> Option<Q::Item<'_>>

Returns read-only components for the current entity that match the query Q, or None if the entity does not have the components required by the query Q.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn into_borrow<T: Component>(self) -> Option<&'w T>

Consumes self and gets access to the component of type T with the world 'w lifetime for the current entity. Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn get_ref<T: Component>(&self) -> Option<Ref<'_, T>>

Gets access to the component of type T for the current entity, including change detection information as a Ref.

Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn into_ref<T: Component>(self) -> Option<Ref<'w, T>>

Consumes self and gets access to the component of type T with the world 'w lifetime for the current entity, including change detection information as a Ref.

Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn get_mut<T: Component<Mutability = Mutable>>( &mut self, ) -> Option<Mut<'_, T>>

Gets mutable access to the component of type T for the current entity. Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn modify_component<T: Component, R>( &mut self, f: impl FnOnce(&mut T) -> R, ) -> Option<R>

Temporarily removes a Component T from this Entity and runs the provided closure on it, returning the result if T was available. This will trigger the OnRemove and OnReplace component hooks without causing an archetype move.

This is most useful with immutable components, where removal and reinsertion is the only way to modify a value.

If you do not need to ensure the above hooks are triggered, and your component is mutable, prefer using get_mut.

Examples

#[derive(Component, PartialEq, Eq, Debug)]
#[component(immutable)]
struct Foo(bool);

entity.modify_component(|foo: &mut Foo| {
    foo.0 = true;
});

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn modify_component_by_id<R>( &mut self, component_id: ComponentId, f: impl for<'a> FnOnce(MutUntyped<'a>) -> R, ) -> Option<R>

Temporarily removes a Component T from this Entity and runs the provided closure on it, returning the result if T was available. This will trigger the OnRemove and OnReplace component hooks without causing an archetype move.

This is most useful with immutable components, where removal and reinsertion is the only way to modify a value.

If you do not need to ensure the above hooks are triggered, and your component is mutable, prefer using get_mut.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub unsafe fn get_mut_assume_mutable<T: Component>( &mut self, ) -> Option<Mut<'_, T>>

Gets mutable access to the component of type T for the current entity. Returns None if the entity does not have a component of type T.

Safety

• T must be a mutable component

pub fn into_mut<T: Component<Mutability = Mutable>>(self) -> Option<Mut<'w, T>>

Consumes self and gets mutable access to the component of type T with the world 'w lifetime for the current entity. Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub unsafe fn into_mut_assume_mutable<T: Component>(self) -> Option<Mut<'w, T>>

Consumes self and gets mutable access to the component of type T with the world 'w lifetime for the current entity. Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Safety

• T must be a mutable component

pub fn resource<R: Resource>(&self) -> &R

Gets a reference to the resource of the given type

Panics

Panics if the resource does not exist. Use get_resource instead if you want to handle this case.

pub fn resource_mut<R: Resource>(&mut self) -> Mut<'_, R>

Gets a mutable reference to the resource of the given type

Panics

Panics if the resource does not exist. Use get_resource_mut instead if you want to handle this case.

If you want to instead insert a value if the resource does not exist, use get_resource_or_insert_with.

pub fn get_resource<R: Resource>(&self) -> Option<&R>

Gets a reference to the resource of the given type if it exists

pub fn get_resource_mut<R: Resource>(&mut self) -> Option<Mut<'_, R>>

Gets a mutable reference to the resource of the given type if it exists

pub fn get_change_ticks<T: Component>(&self) -> Option<ComponentTicks>

Retrieves the change ticks for the given component. This can be useful for implementing change detection in custom runtimes.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn get_change_ticks_by_id( &self, component_id: ComponentId, ) -> Option<ComponentTicks>

Retrieves the change ticks for the given ComponentId. This can be useful for implementing change detection in custom runtimes.

You should prefer to use the typed API EntityWorldMut::get_change_ticks where possible and only use this in cases where the actual component types are not known at compile time.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn get_by_id<F: DynamicComponentFetch>( &self, component_ids: F, ) -> Result<F::Ref<'_>, EntityComponentError>

Returns untyped read-only reference(s) to component(s) for the current entity, based on the given ComponentIds.

You should prefer to use the typed API EntityWorldMut::get where possible and only use this in cases where the actual component types are not known at compile time.

Unlike EntityWorldMut::get, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

Returns EntityComponentError::MissingComponent if the entity does not have a component.

Examples

For examples on how to use this method, see EntityRef::get_by_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn into_borrow_by_id<F: DynamicComponentFetch>( self, component_ids: F, ) -> Result<F::Ref<'w>, EntityComponentError>

Consumes self and returns untyped read-only reference(s) to component(s) with lifetime 'w for the current entity, based on the given ComponentIds.

You should prefer to use the typed API EntityWorldMut::into_borrow where possible and only use this in cases where the actual component types are not known at compile time.

Unlike EntityWorldMut::into_borrow, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

Returns EntityComponentError::MissingComponent if the entity does not have a component.

Examples

For examples on how to use this method, see EntityRef::get_by_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn get_mut_by_id<F: DynamicComponentFetch>( &mut self, component_ids: F, ) -> Result<F::Mut<'_>, EntityComponentError>

Returns untyped mutable reference(s) to component(s) for the current entity, based on the given ComponentIds.

You should prefer to use the typed API EntityWorldMut::get_mut where possible and only use this in cases where the actual component types are not known at compile time.

Unlike EntityWorldMut::get_mut, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

• Returns EntityComponentError::MissingComponent if the entity does not have a component.
• Returns EntityComponentError::AliasedMutability if a component is requested multiple times.

Examples

For examples on how to use this method, see EntityMut::get_mut_by_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub unsafe fn get_mut_assume_mutable_by_id<F: DynamicComponentFetch>( &mut self, component_ids: F, ) -> Result<F::Mut<'_>, EntityComponentError>

Returns untyped mutable reference(s) to component(s) for the current entity, based on the given ComponentIds. Assumes the given ComponentIds refer to mutable components.

You should prefer to use the typed API EntityWorldMut::get_mut_assume_mutable where possible and only use this in cases where the actual component types are not known at compile time.

Unlike EntityWorldMut::get_mut_assume_mutable, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

• Returns EntityComponentError::MissingComponent if the entity does not have a component.
• Returns EntityComponentError::AliasedMutability if a component is requested multiple times.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Safety

It is the callers responsibility to ensure that

• the provided ComponentIds must refer to mutable components.

pub fn into_mut_by_id<F: DynamicComponentFetch>( self, component_ids: F, ) -> Result<F::Mut<'w>, EntityComponentError>

Consumes self and returns untyped mutable reference(s) to component(s) with lifetime 'w for the current entity, based on the given ComponentIds.

You should prefer to use the typed API EntityWorldMut::into_mut where possible and only use this in cases where the actual component types are not known at compile time.

Unlike EntityWorldMut::into_mut, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

• Returns EntityComponentError::MissingComponent if the entity does not have a component.
• Returns EntityComponentError::AliasedMutability if a component is requested multiple times.

Examples

For examples on how to use this method, see EntityMut::get_mut_by_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub unsafe fn into_mut_assume_mutable_by_id<F: DynamicComponentFetch>( self, component_ids: F, ) -> Result<F::Mut<'w>, EntityComponentError>

Consumes self and returns untyped mutable reference(s) to component(s) with lifetime 'w for the current entity, based on the given ComponentIds. Assumes the given ComponentIds refer to mutable components.

You should prefer to use the typed API EntityWorldMut::into_mut_assume_mutable where possible and only use this in cases where the actual component types are not known at compile time.

Unlike EntityWorldMut::into_mut_assume_mutable, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

• Returns EntityComponentError::MissingComponent if the entity does not have a component.
• Returns EntityComponentError::AliasedMutability if a component is requested multiple times.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Safety

It is the callers responsibility to ensure that

• the provided ComponentIds must refer to mutable components.

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

Adds a Bundle of components to the entity.

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

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn insert_with_relationship_hook_mode<T: Bundle>( &mut self, bundle: T, relationship_hook_mode: RelationshipHookMode, ) -> &mut Self

Adds a Bundle of components to the entity. Relationship components in the bundle will follow the configuration in relationship_hook_mode.

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

Warning

This can easily break the integrity of relationships. This is intended to be used for cloning and spawning code internals, not most user-facing scenarios.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

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

Adds a Bundle of components to the entity without overwriting.

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

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub unsafe fn insert_by_id( &mut self, component_id: ComponentId, component: OwningPtr<'_>, ) -> &mut Self

Inserts a dynamic Component into the entity.

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

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

Safety

• ComponentId must be from the same world as EntityWorldMut
• OwningPtr must be a valid reference to the type represented by ComponentId

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub unsafe fn insert_by_ids<'a, I: Iterator<Item = OwningPtr<'a>>>( &mut self, component_ids: &[ComponentId], iter_components: I, ) -> &mut Self

Inserts a dynamic Bundle into the entity.

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

You should prefer to use the typed API EntityWorldMut::insert where possible. If your Bundle only has one component, use the cached API EntityWorldMut::insert_by_id.

If possible, pass a sorted slice of ComponentId to maximize caching potential.

Safety

• Each ComponentId must be from the same world as EntityWorldMut
• Each OwningPtr must be a valid reference to the type represented by ComponentId

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn take<T: Bundle + BundleFromComponents>(&mut self) -> Option<T>

Removes all components in the Bundle from the entity and returns their previous values.

Note: If the entity does not have every component in the bundle, this method will not remove any of them.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

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

Removes any components in the Bundle from the entity.

See EntityCommands::remove for more details.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

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

Removes all components in the Bundle and remove all required components for each component in the bundle

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

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

Removes any components except those in the Bundle (and its Required Components) from the entity.

See EntityCommands::retain for more details.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

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

Removes a dynamic Component from the entity if it exists.

You should prefer to use the typed API EntityWorldMut::remove where possible.

Panics

Panics if the provided ComponentId does not exist in the World or if the entity has been despawned while this EntityWorldMut is still alive.

pub fn remove_by_ids(&mut self, component_ids: &[ComponentId]) -> &mut Self

Removes a dynamic bundle from the entity if it exists.

You should prefer to use the typed API EntityWorldMut::remove where possible.

Panics

Panics if any of the provided ComponentIds do not exist in the World or if the entity has been despawned while this EntityWorldMut is still alive.

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

Removes all components associated with the entity.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn despawn(self)

Despawns the current entity.

See World::despawn for more details.

Note

This will also despawn any Children entities, and any other RelationshipTarget that is configured to despawn descendants. This results in “recursive despawn” behavior.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn despawn_recursive(self)

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

Despawns the provided entity and its descendants.

pub fn flush(self) -> Entity

Ensures any commands triggered by the actions of Self are applied, equivalent to World::flush

pub fn world(&self) -> &World

Gets read-only access to the world that the current entity belongs to.

pub unsafe fn world_mut(&mut self) -> &mut World

Returns this entity’s world.

See EntityWorldMut::world_scope or EntityWorldMut::into_world_mut for a safe alternative.

Safety

Caller must not modify the world in a way that changes the current entity’s location If the caller does do something that could change the location, self.update_location() must be called before using any other methods on this EntityWorldMut.

pub fn into_world_mut(self) -> &'w mut World

Returns this entity’s World, consuming itself.

pub fn world_scope<U>(&mut self, f: impl FnOnce(&mut World) -> U) -> U

Gives mutable access to this entity’s World in a temporary scope. This is a safe alternative to using EntityWorldMut::world_mut.

Examples

#[derive(Resource, Default, Clone, Copy)]
struct R(u32);

// This closure gives us temporary access to the world.
let new_r = entity.world_scope(|world: &mut World| {
    // Mutate the world while we have access to it.
    let mut r = world.resource_mut::<R>();
    r.0 += 1;

    // Return a value from the world before giving it back to the `EntityWorldMut`.
    *r
});

pub fn update_location(&mut self)

Updates the internal entity location to match the current location in the internal World.

This is only required when using the unsafe function EntityWorldMut::world_mut, which enables the location to change.

pub fn is_despawned(&self) -> bool

Returns if the entity has been despawned.

Normally it shouldn’t be needed to explicitly check if the entity has been despawned between commands as this shouldn’t happen. However, for some special cases where it is known that a hook or an observer might despawn the entity while a EntityWorldMut reference is still held, this method can be used to check if the entity is still alive to avoid panicking when calling further methods.

pub fn entry<'a, T: Component>(&'a mut self) -> Entry<'w, 'a, T>

Gets an Entry into the world for this entity and component for in-place manipulation.

The type parameter specifies which component to get.

Examples

#[derive(Component, Default, Clone, Copy, Debug, PartialEq)]
struct Comp(u32);

let mut entity = world.spawn_empty();
entity.entry().or_insert_with(|| Comp(4));
assert_eq!(world.query::<&Comp>().single(&world).unwrap().0, 4);

entity.entry::<Comp>().and_modify(|mut c| c.0 += 1);
assert_eq!(world.query::<&Comp>().single(&world).unwrap().0, 5);

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

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

Triggers the given event for this entity, which will run any observers watching for it.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

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. In order to trigger the callback the entity must also match the query when the event is fired.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

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.

Configure through EntityClonerBuilder as follows:

world.entity_mut(entity).clone_with(target, |builder| {
    builder.deny::<ComponentB>();
});

See EntityClonerBuilder for more options.

Panics

• If this entity has been despawned while this EntityWorldMut is still alive.
• If the target entity does not exist.

pub fn clone_and_spawn(&mut self) -> Entity

Spawns a clone of this entity and returns the Entity 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 EntityWorldMut::clone_and_spawn_with.

Panics

If this entity has been despawned while this EntityWorldMut is still alive.

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

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

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

Configure through EntityClonerBuilder as follows:

let entity_clone = world.entity_mut(entity).clone_and_spawn_with(|builder| {
    builder.deny::<ComponentB>();
});

See EntityClonerBuilder for more options.

Panics

If this entity has been despawned while this EntityWorldMut is still alive.

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

• If this entity has been despawned while this EntityWorldMut is still alive.
• 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

• If this entity has been despawned while this EntityWorldMut is still alive.
• If the target entity does not exist.

pub fn spawned_by(&self) -> MaybeLocation

Returns the source code location from which this entity has last been spawned.

Trait Implementations

impl<'a> From<&'a EntityWorldMut<'_>> for EntityRef<'a>

fn from(entity: &'a EntityWorldMut<'_>) -> Self

Converts to this type from the input type.

impl<'a> From<&'a EntityWorldMut<'_>> for FilteredEntityRef<'a>

fn from(entity: &'a EntityWorldMut<'_>) -> Self

Converts to this type from the input type.

impl<'a> From<&'a mut EntityWorldMut<'_>> for EntityMut<'a>

fn from(entity: &'a mut EntityWorldMut<'_>) -> Self

Converts to this type from the input type.

impl<'a> From<&'a mut EntityWorldMut<'_>> for FilteredEntityMut<'a>

fn from(entity: &'a mut EntityWorldMut<'_>) -> Self

Converts to this type from the input type.

impl<'a> From<EntityWorldMut<'a>> for FilteredEntityMut<'a>

fn from(entity: EntityWorldMut<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<EntityWorldMut<'a>> for FilteredEntityRef<'a>

fn from(entity: EntityWorldMut<'a>) -> Self

Converts to this type from the input type.

impl<'w> From<EntityWorldMut<'w>> for EntityMut<'w>

fn from(entity: EntityWorldMut<'w>) -> Self

Converts to this type from the input type.

impl<'w> From<EntityWorldMut<'w>> for EntityRef<'w>

fn from(entity: EntityWorldMut<'w>) -> EntityRef<'w>

Converts to this type from the input type.