pub struct EntityMut<'w>(/* private fields */);
Expand description
Provides mutable access to a single entity and all of its components.
Contrast with EntityWorldMut
, which allows adding and removing components,
despawning the entity, and provides mutable access to the entire world.
Because of this, EntityWorldMut
cannot coexist with any other world accesses.
§Examples
Disjoint mutable access.
fn disjoint_system(
query1: Query<EntityMut, With<A>>,
query2: Query<EntityMut, Without<A>>,
) {
// ...
}
Implementations§
source§impl<'w> EntityMut<'w>
impl<'w> EntityMut<'w>
sourcepub fn reborrow(&mut self) -> EntityMut<'_>
pub fn reborrow(&mut self) -> EntityMut<'_>
Returns a new instance with a shorter lifetime.
This is useful if you have &mut EntityMut
, but you need EntityMut
.
sourcepub fn as_readonly(&self) -> EntityRef<'_>
pub fn as_readonly(&self) -> EntityRef<'_>
Gets read-only access to all of the entity’s components.
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 world
'w
lifetime for the current entity, including change detection information
as a [Ref<'w>
].
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 EntityMut::get
, this returns a raw pointer to the component,
which is only valid while the EntityMut
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
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 EntityMut::get_mut
where possible and only
use this in cases where the actual component types are not known at
compile time.
Unlike EntityMut::get_mut
, this returns a raw pointer to the component,
which is only valid while the EntityMut
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 of the given ComponentId
with world 'w
lifetime from the entity.
You should prefer to use the typed API EntityMut::into_mut
where possible and only
use this in cases where the actual component types are not known at
compile time.
Trait Implementations§
source§impl<'a> From<&'a EntityMut<'_>> for FilteredEntityRef<'a>
impl<'a> From<&'a EntityMut<'_>> for FilteredEntityRef<'a>
source§impl<'a> From<&'a mut EntityMut<'_>> for FilteredEntityMut<'a>
impl<'a> From<&'a mut EntityMut<'_>> for FilteredEntityMut<'a>
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<EntityMut<'a>> for FilteredEntityMut<'a>
impl<'a> From<EntityMut<'a>> for FilteredEntityMut<'a>
source§impl<'a> From<EntityMut<'a>> for FilteredEntityRef<'a>
impl<'a> From<EntityMut<'a>> for FilteredEntityRef<'a>
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<'a> QueryData for EntityMut<'a>
impl<'a> QueryData for EntityMut<'a>
SAFETY: access of EntityRef
is a subset of EntityMut
§type ReadOnly = EntityRef<'a>
type ReadOnly = EntityRef<'a>
QueryData
, which satisfies the ReadOnlyQueryData
trait.source§impl<'a> TryFrom<&'a mut FilteredEntityMut<'_>> for EntityMut<'a>
impl<'a> TryFrom<&'a mut FilteredEntityMut<'_>> for EntityMut<'a>
source§impl<'a> TryFrom<FilteredEntityMut<'a>> for EntityMut<'a>
impl<'a> TryFrom<FilteredEntityMut<'a>> for EntityMut<'a>
source§impl<'a> WorldQuery for EntityMut<'a>
impl<'a> WorldQuery for EntityMut<'a>
SAFETY: The accesses of Self::ReadOnly
are a subset of the accesses of Self
§type Item<'w> = EntityMut<'w>
type Item<'w> = EntityMut<'w>
WorldQuery
For QueryData
this will be the item returned by the query.
For QueryFilter
this will be either ()
, or a bool
indicating whether the entity should be included
or a tuple of such things.§type Fetch<'w> = UnsafeWorldCell<'w>
type Fetch<'w> = UnsafeWorldCell<'w>
WorldQuery
to fetch Self::Item
§type State = ()
type State = ()
Self::Fetch
. This will be cached inside QueryState
,
so it is best to move as much data / computation here as possible to reduce the cost of
constructing Self::Fetch
.source§fn shrink<'wlong: 'wshort, 'wshort>(
item: Self::Item<'wlong>
) -> Self::Item<'wshort>
fn shrink<'wlong: 'wshort, 'wshort>( item: Self::Item<'wlong> ) -> Self::Item<'wshort>
source§unsafe fn init_fetch<'w>(
world: UnsafeWorldCell<'w>,
_state: &Self::State,
_last_run: Tick,
_this_run: Tick
) -> Self::Fetch<'w>
unsafe fn init_fetch<'w>( world: UnsafeWorldCell<'w>, _state: &Self::State, _last_run: Tick, _this_run: Tick ) -> Self::Fetch<'w>
source§const IS_DENSE: bool = true
const IS_DENSE: bool = true
WorldQuery::set_table
must be used before
WorldQuery::fetch
can be called for iterators. If this returns false,
WorldQuery::set_archetype
must be used before WorldQuery::fetch
can be called for
iterators.source§unsafe fn set_archetype<'w>(
_fetch: &mut Self::Fetch<'w>,
_state: &Self::State,
_archetype: &'w Archetype,
_table: &Table
)
unsafe fn set_archetype<'w>( _fetch: &mut Self::Fetch<'w>, _state: &Self::State, _archetype: &'w Archetype, _table: &Table )
Archetype
. This will always be called on
archetypes that match this WorldQuery
. Read moresource§unsafe fn set_table<'w>(
_fetch: &mut Self::Fetch<'w>,
_state: &Self::State,
_table: &'w Table
)
unsafe fn set_table<'w>( _fetch: &mut Self::Fetch<'w>, _state: &Self::State, _table: &'w Table )
Table
. This will always be called on tables
that match this WorldQuery
. Read moresource§unsafe fn fetch<'w>(
world: &mut Self::Fetch<'w>,
entity: Entity,
_table_row: TableRow
) -> Self::Item<'w>
unsafe fn fetch<'w>( world: &mut Self::Fetch<'w>, entity: Entity, _table_row: TableRow ) -> Self::Item<'w>
Self::Item
for either the given entity
in the current Table
,
or for the given entity
in the current Archetype
. This must always be called after
WorldQuery::set_table
with a table_row
in the range of the current Table
or after
WorldQuery::set_archetype
with a entity
in the current archetype. Read moresource§fn update_component_access(
_state: &Self::State,
access: &mut FilteredAccess<ComponentId>
)
fn update_component_access( _state: &Self::State, access: &mut FilteredAccess<ComponentId> )
source§fn init_state(_world: &mut World)
fn init_state(_world: &mut World)
State
for this WorldQuery
type.source§fn matches_component_set(
_state: &Self::State,
_set_contains_id: &impl Fn(ComponentId) -> bool
) -> bool
fn matches_component_set( _state: &Self::State, _set_contains_id: &impl Fn(ComponentId) -> bool ) -> bool
source§fn set_access(_state: &mut Self::State, _access: &FilteredAccess<ComponentId>)
fn set_access(_state: &mut Self::State, _access: &FilteredAccess<ComponentId>)
FilteredEntityRef
or FilteredEntityMut
. Read moreAuto Trait Implementations§
impl<'w> Freeze for EntityMut<'w>
impl<'w> !RefUnwindSafe for EntityMut<'w>
impl<'w> Send for EntityMut<'w>
impl<'w> Sync for EntityMut<'w>
impl<'w> Unpin for EntityMut<'w>
impl<'w> !UnwindSafe for EntityMut<'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.