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 alloc_at(&mut self, entity: Entity) -> Option<EntityLocation>

👎Deprecated since 0.16.0: This can cause extreme performance problems when used after freeing a large number of entities and requesting an arbitrary entity. See #18054 on GitHub.

Allocate a specific entity ID, overwriting its generation.

Returns the location of the entity currently using the given ID, if any. Location should be written immediately.

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

Destroy an entity, allowing it to be reused.

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 location of an Entity. Note: for pending entities, returns None.

pub fn resolve_from_id(&self, index: u32) -> 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 EntityLocation))

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

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)

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>>>

Returns the source code location from which this entity has last been spawned or despawned. Returns None if its index has been reused by another entity or if this entity has never existed.

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, _system_meta: &mut SystemMeta) -> Self::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

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.

unsafe fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta, )

For the specified Archetype, registers the components accessed by this SystemParam (if applicable).a

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: &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