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>

source

pub fn id(&self) -> Entity

Returns the ID of the current entity.

source

pub fn location(&self) -> EntityLocation

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

source

pub fn archetype(&self) -> &Archetype

Returns the archetype that the current entity belongs to.

source

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.

source

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
source

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
source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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
source

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
source

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.

source

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

Removes any components in the Bundle from the entity.

See EntityCommands::remove for more details.

source

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.

source

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.

source

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

Removes all components associated with the entity.

source

pub fn despawn(self)

Despawns the current entity.

See World::despawn for more details.

source

pub fn flush(self) -> Entity

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

source

pub fn world(&self) -> &World

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

source

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.

source

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

Returns this entity’s World, consuming itself.

source

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
});
source

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.

source

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);
source

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.

Trait Implementations§

source§

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

source§

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

Converts to this type from the input type.
source§

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

source§

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

Converts to this type from the input type.
source§

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

source§

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

Converts to this type from the input type.
source§

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

source§

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

Converts to this type from the input type.
source§

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

source§

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

Converts to this type from the input type.
source§

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

source§

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

Converts to this type from the input type.
source§

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

source§

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

Converts to this type from the input type.
source§

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

source§

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

Converts to this type from the input type.

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> 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
source§

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

source§

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

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

Convert 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)

Convert &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)

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

impl<T> DowncastSync for T
where T: Any + Send + Sync,

source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

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

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

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.

source§

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

§

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

§

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

impl<T> WithSubscriber for T

source§

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
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

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

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