#[repr(C, align(8))]pub struct Entity { /* private fields */ }
Expand description
Lightweight identifier of an entity.
The identifier is implemented using a generational index: a combination of an index and a generation. This allows fast insertion after data removal in an array while minimizing loss of spatial locality.
These identifiers are only valid on the World
it’s sourced from. Attempting to use an Entity
to
fetch entity components or metadata from a different world will either fail or return unexpected results.
§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§
Source§impl Entity
impl Entity
Sourcepub const PLACEHOLDER: Self = _
pub const PLACEHOLDER: Self = _
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,
}
}
}
Sourcepub const fn from_raw(index: u32) -> Entity
pub const fn from_raw(index: u32) -> Entity
Creates a new entity ID with the specified index
and a generation of 1.
§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.
Sourcepub const fn to_bits(self) -> u64
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.
Sourcepub const fn from_bits(bits: u64) -> Self
pub const fn from_bits(bits: u64) -> Self
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
.
Sourcepub const fn try_from_bits(bits: u64) -> Result<Self, IdentifierError>
pub const fn try_from_bits(bits: u64) -> Result<Self, IdentifierError>
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
.
Sourcepub const fn index(self) -> u32
pub const fn index(self) -> u32
Return a transiently unique identifier.
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.
Sourcepub const fn generation(self) -> u32
pub const fn generation(self) -> u32
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§
Source§impl Debug for Entity
impl Debug for Entity
Outputs the full entity identifier, including the index, generation, and the raw bits.
This takes the format: {index}v{generation}#{bits}
.
For Entity::PLACEHOLDER
, this outputs PLACEHOLDER
.
§Usage
Prefer to use this format for debugging and logging purposes. Because the output contains the raw bits, it is easy to check it against serialized scene data.
Example serialized scene data:
(
...
entities: {
4294967297: ( <--- Raw Bits
components: {
...
),
...
)
Source§impl<'de> Deserialize<'de> for Entity
Available on crate feature serialize
only.
impl<'de> Deserialize<'de> for Entity
serialize
only.Source§fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where
D: Deserializer<'de>,
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where
D: Deserializer<'de>,
Source§impl Display for Entity
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
.
Source§impl From<Entity> for Identifier
impl From<Entity> for Identifier
Source§impl From<RemovedComponentEntity> for Entity
impl From<RemovedComponentEntity> for Entity
Source§fn from(value: RemovedComponentEntity) -> Self
fn from(value: RemovedComponentEntity) -> Self
Source§impl FromReflect for Entity
impl FromReflect for Entity
Source§fn from_reflect(reflect: &dyn PartialReflect) -> Option<Self>
fn from_reflect(reflect: &dyn PartialReflect) -> Option<Self>
Self
from a reflected value.Source§fn take_from_reflect(
reflect: Box<dyn PartialReflect>,
) -> Result<Self, Box<dyn PartialReflect>>
fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>
Self
using,
constructing the value using from_reflect
if that fails. Read moreSource§impl GetOwnership for &Entity
impl GetOwnership for &Entity
Source§impl GetOwnership for &mut Entity
impl GetOwnership for &mut Entity
Source§impl GetOwnership for Entity
impl GetOwnership for Entity
Source§impl GetTypeRegistration for Entity
impl GetTypeRegistration for Entity
Source§fn get_type_registration() -> TypeRegistration
fn get_type_registration() -> TypeRegistration
TypeRegistration
for this type.Source§fn register_type_dependencies(registry: &mut TypeRegistry)
fn register_type_dependencies(registry: &mut TypeRegistry)
Source§impl IntoReturn for &Entity
impl IntoReturn for &Entity
Source§impl IntoReturn for &mut Entity
impl IntoReturn for &mut Entity
Source§impl IntoReturn for Entity
impl IntoReturn for Entity
Source§impl Ord for Entity
impl Ord for Entity
Source§impl PartialOrd for Entity
impl PartialOrd for Entity
Source§impl PartialReflect for Entity
impl PartialReflect for Entity
Source§fn get_represented_type_info(&self) -> Option<&'static TypeInfo>
fn get_represented_type_info(&self) -> Option<&'static TypeInfo>
Source§fn clone_value(&self) -> Box<dyn PartialReflect>
fn clone_value(&self) -> Box<dyn PartialReflect>
Reflect
trait object. Read moreSource§fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError>
fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError>
Source§fn reflect_kind(&self) -> ReflectKind
fn reflect_kind(&self) -> ReflectKind
Source§fn reflect_ref(&self) -> ReflectRef<'_>
fn reflect_ref(&self) -> ReflectRef<'_>
Source§fn reflect_mut(&mut self) -> ReflectMut<'_>
fn reflect_mut(&mut self) -> ReflectMut<'_>
Source§fn reflect_owned(self: Box<Self>) -> ReflectOwned
fn reflect_owned(self: Box<Self>) -> ReflectOwned
Source§fn try_into_reflect(
self: Box<Self>,
) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>
fn try_into_reflect( self: Box<Self>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>
Source§fn try_as_reflect(&self) -> Option<&dyn Reflect>
fn try_as_reflect(&self) -> Option<&dyn Reflect>
Source§fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect>
fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect>
Source§fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect>
fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect>
Source§fn as_partial_reflect(&self) -> &dyn PartialReflect
fn as_partial_reflect(&self) -> &dyn PartialReflect
Source§fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect
fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect
Source§fn reflect_hash(&self) -> Option<u64>
fn reflect_hash(&self) -> Option<u64>
Source§fn reflect_partial_eq(&self, value: &dyn PartialReflect) -> Option<bool>
fn reflect_partial_eq(&self, value: &dyn PartialReflect) -> Option<bool>
Source§fn apply(&mut self, value: &(dyn PartialReflect + 'static))
fn apply(&mut self, value: &(dyn PartialReflect + 'static))
Source§fn serializable(&self) -> Option<Serializable<'_>>
fn serializable(&self) -> Option<Serializable<'_>>
Source§fn is_dynamic(&self) -> bool
fn is_dynamic(&self) -> bool
Source§impl Reflect for Entity
impl Reflect for Entity
Source§fn as_any_mut(&mut self) -> &mut dyn Any
fn as_any_mut(&mut self) -> &mut dyn Any
&mut dyn Any
. Read moreSource§fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>
fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>
Source§fn as_reflect(&self) -> &dyn Reflect
fn as_reflect(&self) -> &dyn Reflect
Source§fn as_reflect_mut(&mut self) -> &mut dyn Reflect
fn as_reflect_mut(&mut self) -> &mut dyn Reflect
Source§impl SparseSetIndex for Entity
impl SparseSetIndex for Entity
Source§fn sparse_set_index(&self) -> usize
fn sparse_set_index(&self) -> usize
Source§fn get_sparse_set_index(value: usize) -> Self
fn get_sparse_set_index(value: usize) -> Self
Source§impl TriggerTargets for Entity
impl TriggerTargets for Entity
Source§fn components(&self) -> &[ComponentId]
fn components(&self) -> &[ComponentId]
Source§impl TryFrom<Identifier> for Entity
impl TryFrom<Identifier> for Entity
Source§type Error = IdentifierError
type Error = IdentifierError
Source§impl TypePath for Entity
impl TypePath for Entity
Source§fn type_path() -> &'static str
fn type_path() -> &'static str
Source§fn short_type_path() -> &'static str
fn short_type_path() -> &'static str
Source§fn type_ident() -> Option<&'static str>
fn type_ident() -> Option<&'static str>
Source§fn crate_name() -> Option<&'static str>
fn crate_name() -> Option<&'static str>
Source§impl VisitEntities for Entity
impl VisitEntities for Entity
Source§fn visit_entities<F: FnMut(Entity)>(&self, f: F)
fn visit_entities<F: FnMut(Entity)>(&self, f: F)
Source§impl VisitEntitiesMut for Entity
impl VisitEntitiesMut for Entity
Source§fn visit_entities_mut<F: FnMut(&mut Entity)>(&mut self, f: F)
fn visit_entities_mut<F: FnMut(&mut Entity)>(&mut self, f: F)
Source§impl WorldEntityFetch for Entity
impl WorldEntityFetch for Entity
Source§type Ref<'w> = EntityRef<'w>
type Ref<'w> = EntityRef<'w>
WorldEntityFetch::fetch_ref
.Source§type Mut<'w> = EntityWorldMut<'w>
type Mut<'w> = EntityWorldMut<'w>
WorldEntityFetch::fetch_mut
.Source§type DeferredMut<'w> = EntityMut<'w>
type DeferredMut<'w> = EntityMut<'w>
WorldEntityFetch::fetch_deferred_mut
,
but without structural mutability.Source§unsafe fn fetch_mut(
self,
cell: UnsafeWorldCell<'_>,
) -> Result<Self::Mut<'_>, EntityFetchError>
unsafe fn fetch_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::Mut<'_>, EntityFetchError>
Source§unsafe fn fetch_deferred_mut(
self,
cell: UnsafeWorldCell<'_>,
) -> Result<Self::DeferredMut<'_>, EntityFetchError>
unsafe fn fetch_deferred_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::DeferredMut<'_>, EntityFetchError>
Source§impl WorldQuery for Entity
impl WorldQuery for Entity
SAFETY:
update_component_access
and update_archetype_component_access
do nothing.
This is sound because fetch
does not access components.
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§type Item<'w> = Entity
type Item<'w> = Entity
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.Source§type Fetch<'w> = ()
type Fetch<'w> = ()
WorldQuery
to fetch Self::Item
Source§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§fn shrink_fetch<'wlong: 'wshort, 'wshort>(
_: Self::Fetch<'wlong>,
) -> Self::Fetch<'wshort>
fn shrink_fetch<'wlong: 'wshort, 'wshort>( _: Self::Fetch<'wlong>, ) -> Self::Fetch<'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§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>(
_fetch: &mut Self::Fetch<'w>,
entity: Entity,
_table_row: TableRow,
) -> Self::Item<'w>
unsafe fn fetch<'w>( _fetch: &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 moreimpl Copy for Entity
impl Eq for Entity
impl ReadOnlyQueryData for Entity
SAFETY: access is read only
Auto Trait Implementations§
impl Freeze for Entity
impl RefUnwindSafe for Entity
impl Send for Entity
impl Sync for Entity
impl Unpin for Entity
impl UnwindSafe for Entity
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> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<Q, K> Comparable<K> for Q
impl<Q, K> Comparable<K> for Q
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.Source§impl<T> DowncastSync for T
impl<T> DowncastSync for T
Source§impl<T> DynamicTypePath for Twhere
T: TypePath,
impl<T> DynamicTypePath for Twhere
T: TypePath,
Source§fn reflect_type_path(&self) -> &str
fn reflect_type_path(&self) -> &str
TypePath::type_path
.Source§fn reflect_short_type_path(&self) -> &str
fn reflect_short_type_path(&self) -> &str
Source§fn reflect_type_ident(&self) -> Option<&str>
fn reflect_type_ident(&self) -> Option<&str>
TypePath::type_ident
.Source§fn reflect_crate_name(&self) -> Option<&str>
fn reflect_crate_name(&self) -> Option<&str>
TypePath::crate_name
.Source§fn reflect_module_path(&self) -> Option<&str>
fn reflect_module_path(&self) -> Option<&str>
Source§impl<T> DynamicTyped for Twhere
T: Typed,
impl<T> DynamicTyped for Twhere
T: Typed,
Source§fn reflect_type_info(&self) -> &'static TypeInfo
fn reflect_type_info(&self) -> &'static TypeInfo
Typed::type_info
.Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.Source§impl<T> GetPath for T
impl<T> GetPath for T
Source§fn reflect_path<'p>(
&self,
path: impl ReflectPath<'p>,
) -> Result<&(dyn PartialReflect + 'static), ReflectPathError<'p>>
fn reflect_path<'p>( &self, path: impl ReflectPath<'p>, ) -> Result<&(dyn PartialReflect + 'static), ReflectPathError<'p>>
path
. Read moreSource§fn reflect_path_mut<'p>(
&mut self,
path: impl ReflectPath<'p>,
) -> Result<&mut (dyn PartialReflect + 'static), ReflectPathError<'p>>
fn reflect_path_mut<'p>( &mut self, path: impl ReflectPath<'p>, ) -> Result<&mut (dyn PartialReflect + 'static), ReflectPathError<'p>>
path
. Read moreSource§fn path<'p, T>(
&self,
path: impl ReflectPath<'p>,
) -> Result<&T, ReflectPathError<'p>>where
T: Reflect,
fn path<'p, T>(
&self,
path: impl ReflectPath<'p>,
) -> Result<&T, ReflectPathError<'p>>where
T: Reflect,
path
. Read moreSource§fn path_mut<'p, T>(
&mut self,
path: impl ReflectPath<'p>,
) -> Result<&mut T, ReflectPathError<'p>>where
T: Reflect,
fn path_mut<'p, T>(
&mut self,
path: impl ReflectPath<'p>,
) -> Result<&mut T, ReflectPathError<'p>>where
T: Reflect,
path
. Read more