Struct EntityAllocator 

pub struct EntityAllocator { /* private fields */ }

Allocates Entity ids uniquely. This is used in World::spawn_at and World::despawn_no_free to track entity ids no longer in use. Allocating is fully concurrent and can be done from multiple threads.

Conceptually, this is a collection of Entity ids who’s EntityIndex is despawned and who’s EntityGeneration is the most recent. See the module docs for how these ids and this allocator participate in the life cycle of an entity.

Implementations

impl EntityAllocator

pub fn build_remote_allocator(&self) -> RemoteAllocator

Builds a new remote allocator that hooks into this EntityAllocator. This is useful when you need to allocate entities without holding a reference to the world (like in async).

pub fn has_remote_allocator(&self, allocator: &RemoteAllocator) -> bool

Returns true when the allocator is connected to this EntityAllocator and its allocated Entity values can still be used in this world.

pub fn free(&mut self, freed: Entity)

This allows freed to be retrieved from alloc, etc. Freeing an Entity such that one EntityIndex is in the allocator in multiple places can cause panics when spawning the allocated entity. Additionally, to differentiate versions of an Entity, updating the EntityGeneration before freeing is a good idea (but not strictly necessary if you don’t mind Entity id aliasing.)

pub fn free_many(&mut self, freed: &[Entity])

This allows freed to be retrieved from alloc, etc.

The same caveats of free apply here. (Eg. the slice should not contain duplicates.)

pub fn alloc(&self) -> Entity

Allocates some Entity. The result could have come from a free or be a brand new EntityIndex.

The returned entity is valid and unique, but it is not yet spawned. Using the id as if it were spawned may produce errors. It can not be queried, and it has no EntityLocation. See module docs for more information about entity validity vs spawning.

This is different from empty entities, which are spawned and just happen to have no components.

These ids must be used; otherwise, they will be forgotten. For example, the result must be eventually used to either spawn an entity or be freed.

Panics

If there are no more entities available, this panics.

Example

This is particularly useful when spawning entities in special ways. For example, Commands uses this to allocate an entity and spawn_at it later. But remember, since this entity is not queryable and is not discoverable, losing the returned Entity effectively leaks it, never to be used again!

let mut world = World::new();
let entity = world.entity_allocator().alloc();
// wait as long as you like
let entity_access = world.spawn_empty_at(entity).unwrap(); // or spawn_at(entity, my_bundle)
// treat it as a normal entity
entity_access.despawn();

More generally, manually spawning and despawn_no_freeing entities allows you to skip Bevy’s default entity allocator. This is useful if you want to enforce properties about the EntityIndexs of a group of entities, make a custom allocator, etc.

pub fn alloc_many(&self, count: u32) -> AllocEntitiesIterator<'_>

A more efficient way of calling alloc repeatedly count times. See alloc for details.

Like alloc, these entities must be used, otherwise they will be forgotten. If the iterator is not exhausted, its remaining entities are forgotten. See AllocEntitiesIterator docs for more.

Trait Implementations

impl Debug for EntityAllocator

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

Formats the value using the given formatter.

impl Default for EntityAllocator

fn default() -> EntityAllocator

Returns the “default value” for a type.

impl<'a> SystemParam for &'a EntityAllocator

type State = ()

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

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

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) -> <&'a EntityAllocator as SystemParam>::State

Creates a new instance of this param’s State.

fn init_access( _state: &<&'a EntityAllocator as SystemParam>::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 <&'a EntityAllocator as SystemParam>::State, _system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, _change_tick: Tick, ) -> Result<<&'a EntityAllocator as SystemParam>::Item<'w, 's>, SystemParamValidationError>

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.

impl<'a> ReadOnlySystemParam for &'a EntityAllocator