Module entity

bevy::ecs

Module entity 

Source
Expand description

This module contains all entity types and utilities for interacting with their ids.

§What is an Entity?

The ecs docs give an overview of what entities are and generally how to use them. These docs provide more detail into how they actually work. In these docs Entity and “entity id” are synonymous and refer to the Entity type, which identifies an entity. The term “entity” used on its own refers to the “thing”/“game object” that id references.

§In this Module

This module contains four main things:

§Entity Life Cycle

Entities have life cycles. They are created, used for a while, and eventually destroyed. Let’s start from the top:

Spawn: An entity is created. In bevy, this is called spawning. Most commonly, this is done through World::spawn or Commands::spawn. This creates a fresh entity in the world and returns its Entity id, which can be used to interact with the entity it identifies. These methods initialize the entity with a Bundle, a group of components that it starts with. It is also possible to use World::spawn_empty or Commands::spawn_empty, which are similar but do not add any components to the entity. In either case, the returned Entity id is used to further interact with the entity.

Update: Once an entity is created, you will need its Entity id to perform further actions on it. This can be done through World::entity_mut and Commands::entity. Even if you don’t store the id, you can still find the entity you spawned by searching for it in a Query. Queries are also the primary way of interacting with an entity’s components. You can use EntityWorldMut::remove and EntityCommands::remove to remove components, and you can use EntityWorldMut::insert and EntityCommands::insert to insert more components. Be aware that each entity can only have 0 or 1 values for each kind of component, so inserting a bundle may overwrite existing component values. This can also be further configured based on the insert method.

Despawn: Despawn an entity when it is no longer needed. This destroys it and all its components. The entity is no longer reachable through the World, Commands, or Querys. Note that this means an Entity id may refer to an entity that has since been despawned! Not all Entity ids refer to active entities. If an Entity id is used when its entity has been despawned, an EntityNotSpawnedError is emitted. Any System could despawn any entity; even if you never share its id, it could still be despawned unexpectedly. Your code should do its best to handle these errors gracefully.

In short:

  • Entities are spawned through methods like World::spawn, which return an Entity id for the new entity.
  • Once spawned, they can be accessed and modified through Querys and other apis.
  • You can get the Entity id of an entity through Querys, so losing an Entity id is not a problem.
  • Entities can have components inserted and removed via World::entity_mut and Commands::entity.
  • Entities are eventually despawned, destroying the entity and causing its Entity id to no longer refer to an entity.
  • Not all Entity ids point to actual entities, which makes many entity methods fallible.

§Entity Allocation

Entity spawning is actually done in two stages:

  1. Allocate: We generate a new valid / unique Entity.
  2. Spawn: We make the entity “exist” in the World. It will show up in queries, it can have components, etc.

The reason for this split is that we need to be able to allocate entity ids concurrently, whereas spawning requires unique (non-concurrent) access to the world.

An Entity therefore goes through the following lifecycle:

  1. Unallocated (and “valid”): Only the allocator has any knowledge of this Entity, but it could be spawned, theoretically.
  2. Allocated (and “valid”): The allocator has handed out the Entity, but it is not yet spawned.
  3. Spawned: The entity now “exists” in the World. It will show up in queries, it can have components, etc.
  4. Despawned: The entity no longer “exist” in the World.
  5. Freed (and “invalid”): The Entity is returned to the allocator. The Entity::generation is bumped, which makes all existing Entity references with the previous generation “invalid”.

Note that by default, most spawn and despawn APIs handle the Entity allocation and freeing process for developers.

Modules§

hash_map
Contains the EntityHashMap type, a HashMap pre-configured to use EntityHash hashing.
hash_set
Contains the EntityHashSet type, a HashSet pre-configured to use EntityHash hashing.
index_map
Contains the EntityIndexMap type, an IndexMap pre-configured to use EntityHash hashing.
index_set
Contains the EntityIndexSet type, a IndexSet pre-configured to use EntityHash hashing.
unique_array
A wrapper around entity arrays with a uniqueness invariant.
unique_slice
A wrapper around entity slices with a uniqueness invariant.
unique_vec
A wrapper around entity Vecs with a uniqueness invariant.

Structs§

AllocEntitiesIterator
An Iterator returning a sequence of unique Entity values from Entities. Dropping this will still retain the entities as allocated; this is effectively a leak. To prevent this, ensure the iterator is exhausted before dropping it.
ComponentCloneCtx
Context for component clone handlers.
Entities
Entities tracks all known EntityIndexs and their metadata. This is like a base table of information all entities have.
Entity
Unique identifier for an entity in a World. Note that this is just an id, not the entity itself. Further, the entity this id refers to may no longer exist in the World. For more information about entities, their ids, and how to use them, see the module docs.
EntityAllocator
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.
EntityCloner
A configuration determining how to clone entities. This can be built using EntityCloner::build_opt_out/ opt_in, which returns an EntityClonerBuilder.
EntityClonerBuilder
A builder for configuring EntityCloner. See EntityCloner for more information.
EntityGeneration
This tracks different versions or generations of an EntityIndex. Importantly, this can wrap, meaning each generation is not necessarily unique per EntityIndex.
EntityHash
A BuildHasher that results in a EntityHasher.
EntityHashMap
A HashMap pre-configured to use EntityHash hashing.
EntityHashSet
A HashSet pre-configured to use EntityHash hashing.
EntityHasher
A very fast hash that is only designed to work on generational indices like Entity. It will panic if attempting to hash a type containing non-u64 fields.
EntityIndex
This represents the index of an Entity within the Entities array. This is a lighter weight version of Entity.
EntityIndexMap
A IndexMap pre-configured to use EntityHash hashing.
EntityIndexSet
An IndexSet pre-configured to use EntityHash hashing.
EntityLocation
A location of an entity in an archetype.
EntityValidButNotSpawnedError
An error that occurs when a specified Entity is certain to be valid and is expected to be spawned but is spawned. This includes when an EntityIndex is requested but is not spawned, since each index always corresponds to exactly one valid entity.
InvalidEntityError
An error that occurs when a specified Entity does not exist in the entity id space. See module docs for more about entity validity.
OptIn
Generic for EntityClonerBuilder that makes the cloner try to clone every component that was explicitly allowed from the source entity, for example by using the allow method.
OptOut
Generic for EntityClonerBuilder that makes the cloner try to clone every component from the source entity except for components that were explicitly denied, for example by using the deny method.
SceneEntityMapper
A wrapper for EntityHashMap<Entity>, augmenting it with the ability to allocate new Entity references in a destination world. These newly allocated references are guaranteed to never point to any living entity in that world.
SourceComponent
Provides read access to the source component (the component being cloned) in a ComponentCloneFn.
UniqueEntityEquivalentArray
An array that contains only unique entities.
UniqueEntityEquivalentSlice
A slice that contains only unique entities.
UniqueEntityEquivalentVec
A Vec that contains only unique entities.
UniqueEntityIter
An iterator that yields unique entities.

Enums§

EntityNotSpawnedError
An error that occurs when a specified Entity is expected to be valid and spawned but is not. Represents an error of either InvalidEntityError (when the entity is invalid) or EntityValidButNotSpawnedError (when the EntityGeneration is correct but the EntityIndex is not spawned).
SpawnError
An error that occurs when a specified Entity can not be spawned.

Traits§

ContainsEntity
A trait for types that contain an Entity.
EntityEquivalent
A trait for types that represent an Entity.
EntityMapper
An implementor of this trait knows how to map an Entity into another Entity.
EntitySet
A set of unique entities.
EntitySetIterator
An iterator over a set of unique entities.
FromEntitySetIterator
Conversion from an EntitySetIterator.
MapEntities
Operation to map all contained Entity fields in a type to new values.

Type Aliases§

UniqueEntityArray
An array that contains only unique Entity.
UniqueEntitySlice
A slice that contains only unique Entity.
UniqueEntityVec
A Vec that contains only unique Entity.

Derive Macros§

MapEntities
Implement the MapEntities trait.