Struct Entity 

pub struct Entity { /* private fields */ }

Unique identifier for an entity in a World. Note that this is just an id, not the entity itself. Further, the entity this id refers to may no longer exist in the World. For more information about entities, their ids, and how to use them, see the module docs.

Aliasing

Once an entity is despawned, it ceases to exist. However, its Entity id is still present, and may still be contained in some data. This becomes problematic because it is possible for a later entity to be spawned at the exact same id! If this happens, which is rare but very possible, it will be logged.

Aliasing can happen without warning. Holding onto a Entity id corresponding to an entity well after that entity was despawned can cause un-intuitive behavior for both ordering, and comparing in general. To prevent these bugs, it is generally best practice to stop holding an Entity or EntityGeneration value as soon as you know it has been despawned. If you must do otherwise, do not assume the Entity id corresponds to the same entity it originally did. See EntityGeneration’s docs for more information about aliasing and why it occurs.

Stability warning

For all intents and purposes, Entity should be treated as an opaque identifier. The internal bit representation is liable to change from release to release as are the behaviors or performance characteristics of any of its trait implementations (i.e. Ord, Hash, etc.). This means that changes in Entity’s representation, though made readable through various functions on the type, are not considered breaking changes under SemVer.

In particular, directly serializing with Serialize and Deserialize make zero guarantee of long term wire format compatibility. Changes in behavior will cause serialized Entity values persisted to long term storage (i.e. disk, databases, etc.) will fail to deserialize upon being updated.

Usage

This data type is returned by iterating a Query that has Entity as part of its query fetch type parameter (learn more). It can also be obtained by calling EntityCommands::id or EntityWorldMut::id.

fn setup(mut commands: Commands) {
    // Calling `spawn` returns `EntityCommands`.
    let entity = commands.spawn(SomeComponent).id();
}

fn exclusive_system(world: &mut World) {
    // Calling `spawn` returns `EntityWorldMut`.
    let entity = world.spawn(SomeComponent).id();
}

It can be used to refer to a specific entity to apply EntityCommands, or to call Query::get (or similar methods) to access its components.

fn dispose_expired_food(mut commands: Commands, query: Query<Entity, With<Expired>>) {
    for food_entity in &query {
        commands.entity(food_entity).despawn();
    }
}

Implementations

impl Entity

pub const PLACEHOLDER: Entity

An entity ID with a placeholder value. This may or may not correspond to an actual entity, and should be overwritten by a new value before being used.

Examples

Initializing a collection (e.g. array or Vec) with a known size:

// Create a new array of size 10 filled with invalid entity ids.
let mut entities: [Entity; 10] = [Entity::PLACEHOLDER; 10];

// ... replace the entities with valid ones.

Deriving [Reflect] for a component that has an Entity field:

#[derive(Reflect, Component)]
#[reflect(Component)]
pub struct MyStruct {
    pub entity: Entity,
}

impl FromWorld for MyStruct {
    fn from_world(_world: &mut World) -> Self {
        Self {
            entity: Entity::PLACEHOLDER,
        }
    }
}

pub const fn from_index_and_generation( index: EntityIndex, generation: EntityGeneration, ) -> Entity

Creates a new instance with the given index and generation.

pub const fn from_index(index: EntityIndex) -> Entity

Creates a new entity ID with the specified index and an unspecified generation.

Note

Spawning a specific entity value is rarely the right choice. Most apps should favor Commands::spawn. This method should generally only be used for sharing entities across apps, and only when they have a scheme worked out to share an index space (which doesn’t happen by default).

In general, one should not try to synchronize the ECS by attempting to ensure that Entity lines up between instances, but instead insert a secondary identifier as a component.

pub const fn from_raw_u32(index: u32) -> Option<Entity>

This is equivalent to from_index except that it takes a u32 instead of an EntityIndex.

Returns None if the index is u32::MAX.

pub const fn to_bits(self) -> u64

Convert to a form convenient for passing outside of rust.

Only useful for identifying entities within the same instance of an application. Do not use for serialization between runs.

No particular structure is guaranteed for the returned bits.

pub const fn from_bits(bits: u64) -> Entity

Reconstruct an Entity previously destructured with Entity::to_bits.

Only useful when applied to results from to_bits in the same instance of an application.

Panics

This method will likely panic if given u64 values that did not come from Entity::to_bits.

pub const fn try_from_bits(bits: u64) -> Option<Entity>

Reconstruct an Entity previously destructured with Entity::to_bits.

Only useful when applied to results from to_bits in the same instance of an application.

This method is the fallible counterpart to Entity::from_bits.

pub const fn index(self) -> EntityIndex

Return a transiently unique identifier. See also EntityIndex.

No two simultaneously-live entities share the same index, but dead entities’ indices may collide with both live and dead entities. Useful for compactly representing entities within a specific snapshot of the world, such as when serializing.

pub const fn index_u32(self) -> u32

Equivalent to self.index().index(). See Self::index for details.

pub const fn generation(self) -> EntityGeneration

Returns the generation of this Entity’s index. The generation is incremented each time an entity with a given index is despawned. This serves as a “count” of the number of times a given index has been reused (index, generation) pairs uniquely identify a given Entity.

Trait Implementations

impl Clone for Entity

fn clone(&self) -> Entity

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ContainsEntity for Entity

fn entity(&self) -> Entity

Returns the contained entity.

impl ContiguousQueryData for Entity

type Contiguous<'w, 's> = &'w [Entity]

Item returned by ContiguousQueryData::fetch_contiguous. Represents a contiguous chunk of memory.

unsafe fn fetch_contiguous<'w, 's>( _state: &'s <Entity as WorldQuery>::State, _fetch: &mut <Entity as WorldQuery>::Fetch<'w>, entities: &'w [Entity], ) -> <Entity as ContiguousQueryData>::Contiguous<'w, 's>

Fetch ContiguousQueryData::Contiguous which represents a contiguous chunk of memory (e.g., an array) in the current Table. This must always be called after WorldQuery::set_table.

impl Debug for Entity

Outputs the short entity identifier, including the index and generation.

This takes the format: {index}v{generation}.

For Entity::PLACEHOLDER, this outputs PLACEHOLDER.

For a unique u64 representation, use Entity::to_bits.

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for Entity

Outputs the short entity identifier, including the index and generation.

This takes the format: {index}v{generation}.

For Entity::PLACEHOLDER, this outputs PLACEHOLDER.

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a> Extend<&'a Entity> for EntityHashSet

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = &'a Entity>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a> Extend<&'a Entity> for EntityIndexSet

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = &'a Entity>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl Extend<Entity> for EntityHashSet

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = Entity>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl Extend<Entity> for EntityIndexSet

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = Entity>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<Entity> for EntityTemplate

fn from(entity: Entity) -> EntityTemplate

Converts to this type from the input type.

impl From<RemovedComponentEntity> for Entity

fn from(value: RemovedComponentEntity) -> Entity

Converts to this type from the input type.

impl FromEntitySetIterator<Entity> for EntityHashSet

fn from_entity_set_iter<I>(set_iter: I) -> EntityHashSet

where I: EntitySet<Item = Entity>,

Creates a value from an EntitySetIterator.

impl FromIterator<Entity> for EntityHashSet

fn from_iter<I>(iterable: I) -> EntityHashSet

where I: IntoIterator<Item = Entity>,

Creates a value from an iterator.

impl FromIterator<Entity> for EntityIndexSet

fn from_iter<I>(iterable: I) -> EntityIndexSet

where I: IntoIterator<Item = Entity>,

Creates a value from an iterator.

impl FromReflect for Entity

fn from_reflect(reflect: &(dyn PartialReflect + 'static)) -> Option<Entity>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl FromTemplate for Entity

type Template = EntityTemplate

The Template for this type.

impl GetTypeRegistration for Entity

fn get_type_registration() -> TypeRegistration

Returns the default [TypeRegistration] for this type.

fn register_type_dependencies(_registry: &mut TypeRegistry)

Registers other types needed by this type.

impl Hash for Entity

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl MapEntities for Entity

fn map_entities<E>(&mut self, entity_mapper: &mut E)

where E: EntityMapper,

Updates all Entity references stored inside using entity_mapper.

impl Ord for Entity

fn cmp(&self, other: &Entity) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Entity

fn eq(&self, other: &Entity) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Entity

fn partial_cmp(&self, other: &Entity) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialReflect for Entity

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the [TypeInfo] of the type represented by this value.

fn to_dynamic(&self) -> Box<dyn PartialReflect>

Converts this reflected value into its dynamic representation based on its kind.

fn try_apply( &mut self, value: &(dyn PartialReflect + 'static), ) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Entity>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Entity>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&(dyn Reflect + 'static)>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut (dyn Reflect + 'static)>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Entity>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &(dyn PartialReflect + 'static)

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut (dyn PartialReflect + 'static)

Casts this type to a mutable, reflected value.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn reflect_partial_eq( &self, value: &(dyn PartialReflect + 'static), ) -> Option<bool>

Returns a “partial equality” comparison result.

fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Debug formatter for the value.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn reflect_clone_and_take<T>(&self) -> Result<T, ReflectCloneError>

where T: 'static, Self: Sized + TypePath,

For a type implementing [PartialReflect], combines reflect_clone and take in a useful fashion, automatically constructing an appropriate [ReflectCloneError] if the downcast fails.

fn reflect_partial_cmp( &self, _value: &(dyn PartialReflect + 'static), ) -> Option<Ordering>

Returns a “partial comparison” result.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl QueryData for Entity

const IS_READ_ONLY: bool = true

True if this query is read-only and may not perform mutable access.

const IS_ARCHETYPAL: bool = true

Returns true if (and only if) this query data relies strictly on archetypes to limit which entities are accessed by the Query.

type ReadOnly = Entity

The read-only variant of this QueryData, which satisfies the ReadOnlyQueryData trait.

type Item<'w, 's> = Entity

The item returned by this WorldQuery This will be the data retrieved by the query, and is visible to the end user when calling e.g. Query<Self>::get.

fn shrink<'wlong, 'wshort, 's>( item: <Entity as QueryData>::Item<'wlong, 's>, ) -> <Entity as QueryData>::Item<'wshort, 's>

where 'wlong: 'wshort,

This function manually implements subtyping for the query items.

unsafe fn fetch<'w, 's>( _state: &'s <Entity as WorldQuery>::State, _fetch: &mut <Entity as WorldQuery>::Fetch<'w>, entity: Entity, _table_row: TableRow, ) -> Option<<Entity as QueryData>::Item<'w, 's>>

Fetch 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 an entity in the current archetype. Accesses components registered in WorldQuery::update_component_access.

fn iter_access( _state: &<Entity as WorldQuery>::State, ) -> impl Iterator<Item = EcsAccessType<'_>>

Returns an iterator over the access needed by QueryData::fetch. Access conflicts are usually checked in WorldQuery::update_component_access, but in certain cases this method can be useful to implement a way of checking for access conflicts in a non-allocating way.

fn provide_extra_access( _state: &mut Self::State, _access: &mut Access, _available_access: &Access, )

Offers additional access above what we requested in update_component_access. Implementations may add additional access that is a subset of available_access and does not conflict with anything in access, and must update access to include that access.

impl Reflect for Entity

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

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &(dyn Any + 'static)

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Entity>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &(dyn Reflect + 'static)

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)

Casts this type to a mutable, fully-reflected value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

impl RelationshipSourceCollection for Entity

type SourceIter<'a> = IntoIter<Entity>

The type of iterator returned by the iter method.

fn new() -> Entity

Creates a new empty instance.

fn reserve(&mut self, _: usize)

Reserves capacity for at least additional more entities to be inserted.

fn with_capacity(_capacity: usize) -> Entity

Returns an instance with the given pre-allocated entity capacity.

fn add(&mut self, entity: Entity) -> bool

Adds the given entity to the collection.

fn remove(&mut self, entity: Entity) -> bool

Removes the given entity from the collection.

fn iter(&self) -> <Entity as RelationshipSourceCollection>::SourceIter<'_>

Iterates all entities in the collection.

fn len(&self) -> usize

Returns the current length of the collection.

fn clear(&mut self)

Clears the collection.

fn shrink_to_fit(&mut self)

Attempts to save memory by shrinking the capacity to fit the current length.

fn extend_from_iter(&mut self, entities: impl IntoIterator<Item = Entity>)

Add multiple entities to collection at once.

fn source_to_remove_before_add(&self) -> Option<Entity>

For one-to-one relationships, returns the entity that should be removed before adding a new one. Returns None for one-to-many relationships or when no entity needs to be removed.

fn is_empty(&self) -> bool

Returns true if the collection contains no entities.

impl ReleaseStateQueryData for Entity

fn release_state<'w>( item: <Entity as QueryData>::Item<'w, '_>, ) -> <Entity as QueryData>::Item<'w, 'static>

Releases the borrow from the query state by converting an item to have a 'static state lifetime.

impl SparseSetIndex for Entity

fn sparse_set_index(&self) -> usize

Gets the sparse set index corresponding to this instance.

fn get_sparse_set_index(value: usize) -> Entity

Creates a new instance of this type with the specified index.

impl TypePath for Entity

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl Typed for Entity

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl WorldEntityFetch for Entity

type Ref<'w> = EntityRef<'w>

The read-only reference type returned by WorldEntityFetch::fetch_ref.

type Mut<'w> = EntityWorldMut<'w>

The mutable reference type returned by WorldEntityFetch::fetch_mut.

type DeferredMut<'w> = EntityMut<'w>

The mutable reference type returned by WorldEntityFetch::fetch_deferred_mut, but without structural mutability.

unsafe fn fetch_ref( self, cell: UnsafeWorldCell<'_>, ) -> Result<<Entity as WorldEntityFetch>::Ref<'_>, EntityNotSpawnedError>

Returns read-only reference(s) to the entities with the given Entity IDs, as determined by self.

unsafe fn fetch_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<<Entity as WorldEntityFetch>::Mut<'_>, EntityMutableFetchError>

Returns mutable reference(s) to the entities with the given Entity IDs, as determined by self.

unsafe fn fetch_deferred_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<<Entity as WorldEntityFetch>::DeferredMut<'_>, EntityMutableFetchError>

Returns mutable reference(s) to the entities with the given Entity IDs, as determined by self, but without structural mutability.

impl WorldQuery for Entity

const IS_DENSE: bool = true

Returns true if (and only if) every table of every archetype matched by this fetch contains all of the matched components.

type Fetch<'w> = ()

Per archetype/table state retrieved by this WorldQuery to compute Self::Item for each entity.

type State = ()

State used to construct a 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.

fn shrink_fetch<'wlong, 'wshort>( _: <Entity as WorldQuery>::Fetch<'wlong>, ) -> <Entity as WorldQuery>::Fetch<'wshort>

where 'wlong: 'wshort,

This function manually implements subtyping for the query fetches.

unsafe fn init_fetch<'w, 's>( _world: UnsafeWorldCell<'w>, _state: &'s <Entity as WorldQuery>::State, _last_run: Tick, _this_run: Tick, ) -> <Entity as WorldQuery>::Fetch<'w>

Creates a new instance of Self::Fetch, by combining data from the World with the cached Self::State. Readonly accesses resources registered in WorldQuery::update_component_access.

unsafe fn set_archetype<'w, 's>( _fetch: &mut <Entity as WorldQuery>::Fetch<'w>, _state: &'s <Entity as WorldQuery>::State, _archetype: &'w Archetype, _table: &Table, )

Adjusts internal state to account for the next Archetype. This will always be called on archetypes that match this WorldQuery.

unsafe fn set_table<'w, 's>( _fetch: &mut <Entity as WorldQuery>::Fetch<'w>, _state: &'s <Entity as WorldQuery>::State, _table: &'w Table, )

Adjusts internal state to account for the next Table. This will always be called on tables that match this WorldQuery.

fn update_component_access( _state: &<Entity as WorldQuery>::State, _access: &mut FilteredAccess, )

Adds any component accesses to the current entity used by this WorldQuery to access.

fn init_state(_world: &mut World)

Creates and initializes a State for this WorldQuery type.

fn get_state(_components: &Components) -> Option<()>

Attempts to initialize a State for this WorldQuery type using read-only access to Components.

fn matches_component_set( _state: &<Entity as WorldQuery>::State, _set_contains_id: &impl Fn(ComponentId) -> bool, ) -> bool

Returns true if this query matches a set of components. Otherwise, returns false.

fn init_nested_access( _state: &Self::State, _system_name: Option<&str>, _component_access_set: &mut FilteredAccessSet, _world: UnsafeWorldCell<'_>, )

Adds any component accesses to other entities used by this WorldQuery.

fn update_archetypes(_state: &mut Self::State, _world: UnsafeWorldCell<'_>)

Called when the query state is updating its archetype cache. This can be used by nested queries to update their internal archetype caches.

impl ArchetypeQueryData for Entity

impl Copy for Entity

impl EntityEquivalent for Entity

impl Eq for Entity

impl IterQueryData for Entity

impl ReadOnlyQueryData for Entity

impl SingleEntityQueryData for Entity