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§
source§impl 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§
source§impl<'de> Deserialize<'de> for Entity
impl<'de> Deserialize<'de> for Entity
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 FromReflect for Entity
impl FromReflect for Entity
source§fn from_reflect(reflect: &dyn Reflect) -> Option<Self>
fn from_reflect(reflect: &dyn Reflect) -> Option<Self>
Self
from a reflected value.source§impl GetTypeRegistration for Entity
impl GetTypeRegistration for Entity
source§impl Ord for Entity
impl Ord for Entity
source§impl PartialOrd<Entity> for Entity
impl PartialOrd<Entity> for Entity
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl Reflect for Entity
impl Reflect for Entity
source§fn get_type_info(&self) -> &'static TypeInfo
fn get_type_info(&self) -> &'static TypeInfo
source§fn as_any_mut(&mut self) -> &mut dyn Any
fn as_any_mut(&mut self) -> &mut dyn Any
&mut dyn Any
.source§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§fn clone_value(&self) -> Box<dyn Reflect>
fn clone_value(&self) -> Box<dyn Reflect>
Reflect
trait object. Read moresource§fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>
fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>
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 reflect_hash(&self) -> Option<u64>
fn reflect_hash(&self) -> Option<u64>
source§fn reflect_partial_eq(&self, value: &dyn Reflect) -> Option<bool>
fn reflect_partial_eq(&self, value: &dyn Reflect) -> Option<bool>
source§fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>
fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>
source§fn serializable(&self) -> Option<Serializable<'_>>
fn serializable(&self) -> Option<Serializable<'_>>
source§impl SparseSetIndex for Entity
impl SparseSetIndex for Entity
fn sparse_set_index(&self) -> usize
fn get_sparse_set_index(value: usize) -> Self
source§impl 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 moresource§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§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. Read moresource§const IS_ARCHETYPAL: bool = true
const IS_ARCHETYPAL: bool = true
source§unsafe 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>
source§unsafe 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 moresource§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: 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§
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
source§fn 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 moresource§fn 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 moresource§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. Read moresource§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. Read moresource§impl<T> GetPath for Twhere
T: Reflect,
impl<T> GetPath for Twhere
T: Reflect,
source§fn 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 moresource§fn 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 moresource§fn 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
.source§fn 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