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.
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 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.
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 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 Reflect) -> Option<Self>
fn from_reflect(reflect: &dyn Reflect) -> Option<Self>
Self
from a reflected value.source§fn take_from_reflect(
reflect: Box<dyn Reflect>
) -> Result<Self, Box<dyn Reflect>>
fn take_from_reflect( reflect: Box<dyn Reflect> ) -> Result<Self, Box<dyn Reflect>>
Self
using,
constructing the value using from_reflect
if that fails. Read moresource§impl GetTypeRegistration for Entity
impl GetTypeRegistration for Entity
source§impl Ord for Entity
impl Ord for Entity
source§impl PartialEq for Entity
impl PartialEq for Entity
source§impl PartialOrd for Entity
impl PartialOrd 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_represented_type_info(&self) -> Option<&'static TypeInfo>
fn get_represented_type_info(&self) -> Option<&'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 type_name(&self) -> &str
fn type_name(&self) -> &str
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§fn is_dynamic(&self) -> bool
fn is_dynamic(&self) -> bool
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 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 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
.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§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§const IS_ARCHETYPAL: bool = true
const IS_ARCHETYPAL: bool = true
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> )
WorldQuery
to access
.source§fn update_archetype_component_access(
_state: &Self::State,
_archetype: &Archetype,
_access: &mut Access<ArchetypeComponentId>
)
fn update_archetype_component_access( _state: &Self::State, _archetype: &Archetype, _access: &mut Access<ArchetypeComponentId> )
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
true
if this query matches a set of components. Otherwise, returns false
.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> 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> 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> 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>
§impl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
impl<Q, K> Equivalent<K> for Qwhere Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
§impl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
impl<Q, K> Equivalent<K> for Qwhere Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,
§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 Twhere
T: Reflect + ?Sized,
impl<T> GetPath for Twhere T: Reflect + ?Sized,
source§fn reflect_path<'p>(
&self,
path: impl ReflectPath<'p>
) -> Result<&(dyn Reflect + 'static), ReflectPathError<'p>>
fn reflect_path<'p>( &self, path: impl ReflectPath<'p> ) -> Result<&(dyn Reflect + 'static), ReflectPathError<'p>>
path
. Read moresource§fn reflect_path_mut<'p>(
&mut self,
path: impl ReflectPath<'p>
) -> Result<&mut (dyn Reflect + 'static), ReflectPathError<'p>>
fn reflect_path_mut<'p>( &mut self, path: impl ReflectPath<'p> ) -> Result<&mut (dyn Reflect + '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