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>

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 Some(EntityLocation::INVALID).

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 unsafe fn flush_and_reserve_invalid_assuming_no_entities( &mut self, count: usize, )

Safety

This function is safe if and only if the world this Entities is on has no entities.

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 len(&self) -> u32

The count of currently allocated entities.

pub fn is_empty(&self) -> bool

Checks if any entity is currently active.

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

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

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

unsafe fn validate_param( _state: &Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'_>, ) -> bool

Validates that the param can be acquired by the get_param. Built-in executors use this to prevent systems with invalid params from running. For nested SystemParams validation will fail if any delegated validation fails.

impl<'a> ReadOnlySystemParam for &'a Entities