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.
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 EntityMut::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 `EntityMut`.
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
sourceimpl Entity
impl Entity
sourcepub const fn from_raw(index: u32) -> Entity
pub const fn from_raw(index: u32) -> Entity
Creates a new entity reference with the specified index
and a generation of 0.
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.
There are still some use cases where it might be appropriate to use this function externally.
Examples
Initializing a collection (e.g. array
or Vec
) with a known size:
// Create a new array of size 10 and initialize it with (invalid) entities.
let mut entities: [Entity; 10] = [Entity::from_raw(0); 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::from_raw(u32::MAX),
}
}
}
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.
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
sourceimpl<'de> Deserialize<'de> for Entity
impl<'de> Deserialize<'de> for Entity
sourcefn 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>,
sourceimpl FromReflect for Entity
impl FromReflect for Entity
sourcefn from_reflect(reflect: &dyn Reflect) -> Option<Self>
fn from_reflect(reflect: &dyn Reflect) -> Option<Self>
Self
from a reflected value.sourceimpl GetTypeRegistration for Entity
impl GetTypeRegistration for Entity
sourceimpl Ord for Entity
impl Ord for Entity
1.21.0 · sourcefn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
1.21.0 · sourcefn min(self, other: Self) -> Selfwhere
Self: Sized,
fn min(self, other: Self) -> Selfwhere
Self: Sized,
1.50.0 · sourcefn clamp(self, min: Self, max: Self) -> Selfwhere
Self: Sized + PartialOrd<Self>,
fn clamp(self, min: Self, max: Self) -> Selfwhere
Self: Sized + PartialOrd<Self>,
sourceimpl PartialOrd<Entity> for Entity
impl PartialOrd<Entity> for Entity
sourcefn partial_cmp(&self, other: &Entity) -> Option<Ordering>
fn partial_cmp(&self, other: &Entity) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresourceimpl Reflect for Entity
impl Reflect for Entity
sourcefn get_type_info(&self) -> &'static TypeInfo
fn get_type_info(&self) -> &'static TypeInfo
sourcefn as_any_mut(&mut self) -> &mut dyn Any
fn as_any_mut(&mut self) -> &mut dyn Any
&mut dyn Any
.sourcefn into_reflect(self: Box<Self>) -> Box<dyn Reflect>
fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>
sourcefn as_reflect(&self) -> &dyn Reflect
fn as_reflect(&self) -> &dyn Reflect
sourcefn as_reflect_mut(&mut self) -> &mut dyn Reflect
fn as_reflect_mut(&mut self) -> &mut dyn Reflect
sourcefn clone_value(&self) -> Box<dyn Reflect>
fn clone_value(&self) -> Box<dyn Reflect>
Reflect
trait object. Read moresourcefn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>
fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>
sourcefn reflect_ref(&self) -> ReflectRef<'_>
fn reflect_ref(&self) -> ReflectRef<'_>
sourcefn reflect_mut(&mut self) -> ReflectMut<'_>
fn reflect_mut(&mut self) -> ReflectMut<'_>
sourcefn reflect_owned(self: Box<Self>) -> ReflectOwned
fn reflect_owned(self: Box<Self>) -> ReflectOwned
sourcefn reflect_hash(&self) -> Option<u64>
fn reflect_hash(&self) -> Option<u64>
sourcefn reflect_partial_eq(&self, value: &dyn Reflect) -> Option<bool>
fn reflect_partial_eq(&self, value: &dyn Reflect) -> Option<bool>
sourcefn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>
fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>
sourcefn serializable(&self) -> Option<Serializable<'_>>
fn serializable(&self) -> Option<Serializable<'_>>
sourceimpl SparseSetIndex for Entity
impl SparseSetIndex for Entity
fn sparse_set_index(&self) -> usize
fn get_sparse_set_index(value: usize) -> Self
sourceimpl WorldQuery for Entity
impl WorldQuery for Entity
SAFETY: no component or archetype access
type Fetch<'w> = ()
type Fetch<'w> = ()
WorldQuery
to fetch Self::Item
type Item<'w> = Entity
type Item<'w> = Entity
WorldQuery
type ReadOnly = Entity
type ReadOnly = Entity
WorldQuery
, which satisfies the ReadOnlyWorldQuery
trait.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
. Read moresourcefn shrink<'wlong: 'wshort, 'wshort>(
item: Self::Item<'wlong>
) -> Self::Item<'wshort>
fn shrink<'wlong: 'wshort, 'wshort>(
item: Self::Item<'wlong>
) -> Self::Item<'wshort>
sourceconst 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. Read moresourceconst IS_ARCHETYPAL: bool = true
const IS_ARCHETYPAL: bool = true
sourceunsafe fn init_fetch<'w>(
_world: &'w World,
_state: &Self::State,
_last_change_tick: u32,
_change_tick: u32
) -> Self::Fetch<'w>
unsafe fn init_fetch<'w>(
_world: &'w World,
_state: &Self::State,
_last_change_tick: u32,
_change_tick: u32
) -> Self::Fetch<'w>
sourceunsafe fn clone_fetch<'w>(_fetch: &Self::Fetch<'w>) -> Self::Fetch<'w>
unsafe fn clone_fetch<'w>(_fetch: &Self::Fetch<'w>) -> Self::Fetch<'w>
Self: ReadOnlyWorldQuery
holds. Read moresourceunsafe 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 moresourceunsafe 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 moresourceunsafe fn fetch<'w>(
_fetch: &mut Self::Fetch<'w>,
entity: Entity,
_table_row: usize
) -> Self::Item<'w>
unsafe fn fetch<'w>(
_fetch: &mut Self::Fetch<'w>,
entity: Entity,
_table_row: usize
) -> 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 morefn update_component_access(
_state: &Self::State,
_access: &mut FilteredAccess<ComponentId>
)
fn update_archetype_component_access(
_state: &Self::State,
_archetype: &Archetype,
_access: &mut Access<ArchetypeComponentId>
)
fn init_state(_world: &mut World)
fn matches_component_set(
_state: &Self::State,
_set_contains_id: &impl Fn(ComponentId) -> bool
) -> bool
impl Copy for Entity
impl Eq for Entity
impl ReadOnlyWorldQuery for Entity
SAFETY: access is read only
impl StructuralEq for Entity
impl StructuralPartialEq for Entity
Auto Trait Implementations
impl RefUnwindSafe for Entity
impl Send for Entity
impl Sync for Entity
impl Unpin for Entity
impl UnwindSafe for Entity
Blanket Implementations
sourceimpl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
sourceimpl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
sourcefn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
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
. Read moresourcefn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
. Read moresourcefn 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. Read moresourcefn 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. Read moresourceimpl<T> DowncastSync for Twhere
T: Any + Send + Sync,
impl<T> DowncastSync for Twhere
T: Any + Send + Sync,
sourceimpl<T> GetPath for Twhere
T: Reflect,
impl<T> GetPath for Twhere
T: Reflect,
sourcefn path<'r, 'p>(
&'r self,
path: &'p str
) -> Result<&'r (dyn Reflect + 'static), ReflectPathError<'p>>
fn path<'r, 'p>(
&'r self,
path: &'p str
) -> Result<&'r (dyn Reflect + 'static), ReflectPathError<'p>>
path
. Read moresourcefn path_mut<'r, 'p>(
&'r mut self,
path: &'p str
) -> Result<&'r mut (dyn Reflect + 'static), ReflectPathError<'p>>
fn path_mut<'r, 'p>(
&'r mut self,
path: &'p str
) -> Result<&'r mut (dyn Reflect + 'static), ReflectPathError<'p>>
path
. Read moresourcefn get_path<T, 'r, 'p>(
&'r self,
path: &'p str
) -> Result<&'r T, ReflectPathError<'p>>where
T: Reflect,
fn get_path<T, 'r, 'p>(
&'r self,
path: &'p str
) -> Result<&'r T, ReflectPathError<'p>>where
T: Reflect,
path
.sourcefn get_path_mut<T, 'r, 'p>(
&'r mut self,
path: &'p str
) -> Result<&'r mut T, ReflectPathError<'p>>where
T: Reflect,
fn get_path_mut<T, 'r, 'p>(
&'r mut self,
path: &'p str
) -> Result<&'r mut T, ReflectPathError<'p>>where
T: Reflect,
path
. Read more