Struct bevy_ecs::world::EntityWorldMut
source · 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§
source§impl<'w> EntityWorldMut<'w>
impl<'w> EntityWorldMut<'w>
sourcepub fn location(&self) -> EntityLocation
pub fn location(&self) -> EntityLocation
Gets metadata indicating the location where the current entity is stored.
sourcepub fn archetype(&self) -> &Archetype
pub fn archetype(&self) -> &Archetype
Returns the archetype that the current entity belongs to.
sourcepub fn contains<T: Component>(&self) -> bool
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
.
sourcepub fn contains_id(&self, component_id: ComponentId) -> bool
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 itsComponentId
, consider usingSelf::contains_type_id
.
sourcepub fn contains_type_id(&self, type_id: TypeId) -> bool
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 aTypeId
, consider usingSelf::contains_id
.
sourcepub fn get<T: Component>(&self) -> Option<&T>
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
.
sourcepub fn into_borrow<T: Component>(self) -> Option<&'w T>
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
.
sourcepub fn get_ref<T: Component>(&self) -> Option<Ref<'_, T>>
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
.
sourcepub fn into_ref<T: Component>(self) -> Option<Ref<'w, T>>
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
.
sourcepub fn get_mut<T: Component>(&mut self) -> Option<Mut<'_, T>>
pub fn get_mut<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
.
sourcepub fn into_mut<T: Component>(self) -> Option<Mut<'w, T>>
pub fn into_mut<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
.
sourcepub fn get_change_ticks<T: Component>(&self) -> Option<ComponentTicks>
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.
sourcepub fn get_change_ticks_by_id(
&self,
component_id: ComponentId
) -> Option<ComponentTicks>
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.
sourcepub fn get_by_id(&self, component_id: ComponentId) -> Option<Ptr<'_>>
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.
sourcepub fn into_borrow_by_id(self, component_id: ComponentId) -> Option<Ptr<'w>>
pub fn into_borrow_by_id(self, component_id: ComponentId) -> Option<Ptr<'w>>
Consumes self
and gets the component of the given ComponentId
with
with world 'w
lifetime from the entity.
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.
sourcepub fn get_mut_by_id(
&mut self,
component_id: ComponentId
) -> Option<MutUntyped<'_>>
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.
sourcepub fn into_mut_by_id(self, component_id: ComponentId) -> Option<MutUntyped<'w>>
pub fn into_mut_by_id(self, component_id: ComponentId) -> Option<MutUntyped<'w>>
Consumes self
and gets a [MutUntyped<'w>
] of the component with the world 'w
lifetime
of the given ComponentId
from the entity.
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.
sourcepub fn insert<T: Bundle>(&mut self, bundle: T) -> &mut Self
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.
sourcepub unsafe fn insert_by_id(
&mut self,
component_id: ComponentId,
component: OwningPtr<'_>
) -> &mut Self
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 asEntityWorldMut
OwningPtr
must be a valid reference to the type represented byComponentId
sourcepub unsafe fn insert_by_ids<'a, I: Iterator<Item = OwningPtr<'a>>>(
&mut self,
component_ids: &[ComponentId],
iter_components: I
) -> &mut Self
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 asEntityWorldMut
- Each
OwningPtr
must be a valid reference to the type represented byComponentId
sourcepub fn take<T: Bundle>(&mut self) -> Option<T>
pub fn take<T: Bundle>(&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.
sourcepub fn remove<T: Bundle>(&mut self) -> &mut Self
pub fn remove<T: Bundle>(&mut self) -> &mut Self
Removes any components in the Bundle
from the entity.
See EntityCommands::remove
for more details.
sourcepub fn retain<T: Bundle>(&mut self) -> &mut Self
pub fn retain<T: Bundle>(&mut self) -> &mut Self
Removes any components except those in the Bundle
from the entity.
See EntityCommands::retain
for more details.
sourcepub fn remove_by_id(&mut self, component_id: ComponentId) -> &mut Self
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
.
sourcepub fn despawn(self)
pub fn despawn(self)
Despawns the current entity.
See World::despawn
for more details.
sourcepub fn flush(self) -> Entity
pub fn flush(self) -> Entity
Ensures any commands triggered by the actions of Self are applied, equivalent to World::flush
sourcepub fn world(&self) -> &World
pub fn world(&self) -> &World
Gets read-only access to the world that the current entity belongs to.
sourcepub unsafe fn world_mut(&mut self) -> &mut World
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
.
sourcepub fn into_world_mut(self) -> &'w mut World
pub fn into_world_mut(self) -> &'w mut World
Returns this entity’s World
, consuming itself.
sourcepub fn world_scope<U>(&mut self, f: impl FnOnce(&mut World) -> U) -> U
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
});
sourcepub fn update_location(&mut self)
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.
sourcepub fn entry<'a, T: Component>(&'a mut self) -> Entry<'w, 'a, T>
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).0, 4);
entity.entry::<Comp>().and_modify(|mut c| c.0 += 1);
assert_eq!(world.query::<&Comp>().single(&world).0, 5);
Trait Implementations§
source§impl<'a> From<&'a EntityWorldMut<'_>> for EntityRef<'a>
impl<'a> From<&'a EntityWorldMut<'_>> for EntityRef<'a>
source§fn from(value: &'a EntityWorldMut<'_>) -> Self
fn from(value: &'a EntityWorldMut<'_>) -> Self
source§impl<'a> From<&'a EntityWorldMut<'_>> for FilteredEntityRef<'a>
impl<'a> From<&'a EntityWorldMut<'_>> for FilteredEntityRef<'a>
source§fn from(entity: &'a EntityWorldMut<'_>) -> Self
fn from(entity: &'a EntityWorldMut<'_>) -> Self
source§impl<'a> From<&'a mut EntityWorldMut<'_>> for EntityMut<'a>
impl<'a> From<&'a mut EntityWorldMut<'_>> for EntityMut<'a>
source§fn from(value: &'a mut EntityWorldMut<'_>) -> Self
fn from(value: &'a mut EntityWorldMut<'_>) -> Self
source§impl<'a> From<&'a mut EntityWorldMut<'_>> for FilteredEntityMut<'a>
impl<'a> From<&'a mut EntityWorldMut<'_>> for FilteredEntityMut<'a>
source§fn from(entity: &'a mut EntityWorldMut<'_>) -> Self
fn from(entity: &'a mut EntityWorldMut<'_>) -> Self
source§impl<'a> From<EntityWorldMut<'a>> for FilteredEntityMut<'a>
impl<'a> From<EntityWorldMut<'a>> for FilteredEntityMut<'a>
source§fn from(entity: EntityWorldMut<'a>) -> Self
fn from(entity: EntityWorldMut<'a>) -> Self
source§impl<'a> From<EntityWorldMut<'a>> for FilteredEntityRef<'a>
impl<'a> From<EntityWorldMut<'a>> for FilteredEntityRef<'a>
source§fn from(entity: EntityWorldMut<'a>) -> Self
fn from(entity: EntityWorldMut<'a>) -> Self
source§impl<'w> From<EntityWorldMut<'w>> for EntityMut<'w>
impl<'w> From<EntityWorldMut<'w>> for EntityMut<'w>
source§fn from(value: EntityWorldMut<'w>) -> Self
fn from(value: EntityWorldMut<'w>) -> Self
source§impl<'w> From<EntityWorldMut<'w>> for EntityRef<'w>
impl<'w> From<EntityWorldMut<'w>> for EntityRef<'w>
source§fn from(entity_mut: EntityWorldMut<'w>) -> EntityRef<'w>
fn from(entity_mut: EntityWorldMut<'w>) -> EntityRef<'w>
Auto Trait Implementations§
impl<'w> Freeze for EntityWorldMut<'w>
impl<'w> !RefUnwindSafe for EntityWorldMut<'w>
impl<'w> Send for EntityWorldMut<'w>
impl<'w> Sync for EntityWorldMut<'w>
impl<'w> Unpin for EntityWorldMut<'w>
impl<'w> !UnwindSafe for EntityWorldMut<'w>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
.source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.