Struct Entities 

pub struct Entities { /* private fields */ }

A World’s internal metadata store on all of its entities.

Contains metadata on:

• The generation of every entity.
• The alive/dead status of a particular entity. (i.e. “has entity 3 been despawned?”)
• The location of the entity’s components in memory (via EntityLocation)

Implementations

impl Entities

pub fn reserve_entities(&self, count: u32) -> ReserveEntitiesIterator<'_>

Reserve entity IDs concurrently.

Storage for entity generation and location is lazily allocated by calling flush.

pub fn reserve_entity(&self) -> Entity

Reserve one entity ID concurrently.

Equivalent to self.reserve_entities(1).next().unwrap(), but more efficient.

pub fn alloc(&mut self) -> Entity

Allocate an entity ID directly.

pub fn free(&mut self, entity: Entity) -> Option<EntityIdLocation>

Destroy an entity, allowing it to be reused.

Returns the Option<EntityLocation> of the entity or None if the entity was not present.

Must not be called while reserved entities are awaiting flush().

pub fn reserve(&mut self, additional: u32)

Ensure at least n allocations can succeed without reallocating.

pub fn contains(&self, entity: Entity) -> bool

Returns true if the Entities contains entity.

pub fn clear(&mut self)

Clears all Entity from the World.

pub fn get(&self, entity: Entity) -> Option<EntityLocation>

Returns the EntityLocation of an Entity. Note: for pending entities and entities not participating in the ECS (entities with a EntityIdLocation of None), returns None.

pub fn get_id_location(&self, entity: Entity) -> Option<EntityIdLocation>

Returns the EntityIdLocation of an Entity. Note: for pending entities, returns None.

pub fn resolve_from_id(&self, row: EntityRow) -> Option<Entity>

Get the Entity with a given id, if it exists in this Entities collection Returns None if this Entity is outside of the range of currently reserved Entities

Note: This method may return Entities which are currently free Note that contains will correctly return false for freed entities, since it checks the generation

pub unsafe fn flush( &mut self, init: impl FnMut(Entity, &mut EntityIdLocation), by: MaybeLocation, tick: Tick, )

Allocates space for entities previously reserved with reserve_entity or reserve_entities, then initializes each one using the supplied function.

See EntityLocation for details on its meaning and how to set it.

Safety

Flush must set the entity location to the correct ArchetypeId for the given Entity each time init is called. This can be ArchetypeId::INVALID, provided the Entity has not been assigned to an Archetype.

Note: freshly-allocated entities (ones which don’t come from the pending list) are guaranteed to be initialized with the invalid archetype.

pub fn flush_as_invalid(&mut self, by: MaybeLocation, tick: Tick)

Flushes all reserved entities to an “invalid” state. Attempting to retrieve them will return None unless they are later populated with a valid archetype.

pub fn total_count(&self) -> usize

The count of all entities in the World that have ever been allocated including the entities that are currently freed.

This does not include entities that have been reserved but have never been allocated yet.

pub fn used_count(&self) -> usize

The count of all entities in the World that are used, including both those allocated and those reserved, but not those freed.

pub fn total_prospective_count(&self) -> usize

The count of all entities in the World that have ever been allocated or reserved, including those that are freed. This is the value that Self::total_count() would return if Self::flush() were called right now.

pub fn len(&self) -> u32

The count of currently allocated entities.

pub fn is_empty(&self) -> bool

Checks if any entity is currently active.

pub fn entity_get_spawned_or_despawned_by( &self, entity: Entity, ) -> MaybeLocation<Option<&'static Location<'static>>>

Try to get the source code location from which this entity has last been spawned, despawned or flushed.

Returns None if its index has been reused by another entity or if this entity has never existed.

pub fn entity_get_spawn_or_despawn_tick(&self, entity: Entity) -> Option<Tick>

Try to get the Tick at which this entity has last been spawned, despawned or flushed.

Returns None if its index has been reused by another entity or if this entity has never been spawned.

Trait Implementations

impl Debug for Entities

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

Formats the value using the given formatter.

impl<'a> SystemParam for &'a Entities

type State = ()

Used to store data which persists across invocations of a system.

type Item<'w, 's> = &'w Entities

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state(_world: &mut World) -> Self::State

Creates a new instance of this param’s State.

fn init_access( _state: &Self::State, _system_meta: &mut SystemMeta, _component_access_set: &mut FilteredAccessSet, _world: &mut World, )

Registers any World access used by this SystemParam

unsafe fn get_param<'w, 's>( _state: &'s mut Self::State, _system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, _change_tick: Tick, ) -> Self::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during ApplyDeferred.

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next ApplyDeferred.

unsafe fn validate_param( state: &mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'_>, ) -> Result<(), SystemParamValidationError>

Validates that the param can be acquired by the get_param.

impl<'a> ReadOnlySystemParam for &'a Entities