Struct bevy::ecs::world::EntityWorldMut

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

Expand description

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 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.

pub fn archetype(&self) -> &Archetype

Returns the archetype that the current entity belongs to.

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

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.

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.

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.

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

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.

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

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.

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

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.

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

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

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.

pub fn get_by_id(&self, component_id: ComponentId) -> Option<Ptr<'_>>

Gets the component of the given ComponentId from the entity.

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 a raw pointer to the component, which is only valid while the EntityWorldMut is alive.

pub fn get_mut_by_id( &mut self, component_id: ComponentId ) -> Option<MutUntyped<'_>>

Gets a MutUntyped of the component of the given ComponentId from the entity.

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 a raw pointer to the component, which is only valid while the EntityWorldMut is alive.

pub fn insert<T>(&mut self, bundle: T) -> &mut EntityWorldMut<'w>where T: Bundle,

Adds a Bundle of components to the entity.

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

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

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

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

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

pub fn take<T>(&mut self) -> Option<T>where T: Bundle,

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.

pub fn remove<T>(&mut self) -> &mut EntityWorldMut<'w>where T: Bundle,

Removes any components in the Bundle from the entity.

pub fn despawn(self)

Despawns the current entity.

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(&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
});