guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::ecs::EntityRegistry Class Referenceabstract

Owns entities and gives the systems the list of entities to visit. More...

#include <headers/guillaume/ecs/entity_registry.hpp>

Inheritance diagram for guillaume::ecs::EntityRegistry:

Public Member Functions

 EntityRegistry (void)=default
 Create a registry.
virtual ~EntityRegistry (void)=default
 Virtual destructor.
void addEntity (std::shared_ptr< Entity > entity)
 Make this registry own an entity, so that it stays alive and systems visit it.
bool removeEntity (Entity::Identifier identifier)
 Remove an entity, with its children and all their components.
void clearEntities (void)
 Remove every entity owned by this registry, with everything they own and all their components.
const std::vector< std::shared_ptr< Entity > > & getEntities (void) const
 Get the entities this registry owns directly.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void)
 List every entity of this registry and of the registries nested in it, level by level.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void) const
 List every entity of this registry and of the registries nested in it, level by level (const overload).
template<InheritFromEntity EntityType>
std::shared_ptr< EntityType > getEntity (Entity::Identifier identifier)
 Find an entity owned directly by this registry, by identifier.
template<InheritFromEntity EntityType>
std::shared_ptr< const EntityType > getEntity (Entity::Identifier identifier) const
 Find an entity owned directly by this registry, by identifier (const overload).
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature) const
 List the entities that have every component type of a signature, from the root down.
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature, const EntityTreeTraveler &traveler) const
 List the entities that have every component type of a signature, in the order chosen by a traveler.

Protected Member Functions

virtual std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void)=0
 Give access to the list of entities this registry owns directly. Implemented by the class that provides the storage.
virtual const std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) const =0
 Give read access to the list of entities this registry owns directly.

Detailed Description

Owns entities and gives the systems the list of entities to visit.

Two kinds of object are an EntityRegistry: a Scene, which owns its root entities (through EntityRegistryContainer), and a ParentEntity, which owns its children. Because an owned entity can itself be a registry, registries nest and form the ownership tree of a scene. Each frame, System::routine asks a traveler for every entity of that tree, starting at the scene.

// Add a child under a parent widget (a ParentEntity).
child->setParent(parent); // parent link and components::Hierarchy
parent->addEntity(child); // ownership
// Remove it later, from any registry above it, with its own children
// and all their components.
scene.getEntityRegistry().removeEntity(child->getIdentifier());

Things to watch out for:

  • Ownership (addEntity) and the parent link (Entity::setParent) are set separately and can differ. A widget that builds its own children owns them; an entity created through a widget Builder is owned by the scene, whatever parent it was given. This is why removeEntity also follows the parent links.
  • getEntities and getEntity look at the entities this registry owns directly; getEntitiesBreadthFirst, getEntityWithSignature, removeEntity and clearEntities go through the nested registries too.
  • Removing entities while iterating over getEntities() invalidates the iteration.
See also
Entity::setParent
ParentEntity
EntityTreeTraveler

Definition at line 74 of file entity_registry.hpp.

Constructor & Destructor Documentation

◆ ~EntityRegistry()

virtual guillaume::ecs::EntityRegistry::~EntityRegistry ( void )
virtualdefault

Virtual destructor.

The entity objects are released; their components are not deleted from the ComponentRegistry. Call clearEntities() first for that.

Member Function Documentation

◆ accessDirectEntities() [1/2]

virtual const std::vector< std::shared_ptr< Entity > > & guillaume::ecs::EntityRegistry::accessDirectEntities ( void ) const
protectedpure virtual

Give read access to the list of entities this registry owns directly.

Returns
Const reference to the list, in insertion order.

Implemented in guillaume::ecs::EntityRegistryContainer, and guillaume::ecs::ParentEntity.

◆ accessDirectEntities() [2/2]

virtual std::vector< std::shared_ptr< Entity > > & guillaume::ecs::EntityRegistry::accessDirectEntities ( void )
protectedpure virtual

Give access to the list of entities this registry owns directly. Implemented by the class that provides the storage.

Returns
Mutable reference to the list, in insertion order.

Implemented in guillaume::ecs::EntityRegistryContainer, and guillaume::ecs::ParentEntity.

Here is the caller graph for this function:

◆ addEntity()

void guillaume::ecs::EntityRegistry::addEntity ( std::shared_ptr< Entity > entity)

Make this registry own an entity, so that it stays alive and systems visit it.

The entity is appended after the ones already owned. Its parent link is not touched: call Entity::setParent as well when the entity is a child. Adding the same entity twice makes systems visit it twice.

Parameters
entityThe entity to own. Must not be null.

Definition at line 51 of file entity_registry.cpp.

Here is the call graph for this function:

◆ clearEntities()

void guillaume::ecs::EntityRegistry::clearEntities ( void )

Remove every entity owned by this registry, with everything they own and all their components.

A widget that rebuilds its children calls it before creating the new ones. Entities parented to a removed entity but owned elsewhere are unlinked, not removed.

Definition at line 125 of file entity_registry.cpp.

◆ getEntities()

const std::vector< std::shared_ptr< Entity > > & guillaume::ecs::EntityRegistry::getEntities ( void ) const
inline

Get the entities this registry owns directly.

Returns
Const reference to the list, in insertion order; the entities owned by nested registries are not included.

Definition at line 196 of file entity_registry.hpp.

Here is the call graph for this function:

◆ getEntitiesBreadthFirst() [1/2]

std::vector< std::shared_ptr< Entity > > guillaume::ecs::EntityRegistry::getEntitiesBreadthFirst ( void )

List every entity of this registry and of the registries nested in it, level by level.

The entities owned directly come first, in insertion order, then the entities owned by those, and so on: an owner always comes before what it owns. The result is cached until an entity is added or removed anywhere.

Returns
A copy of the list; empty when the registry owns nothing.

Definition at line 133 of file entity_registry.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getEntitiesBreadthFirst() [2/2]

std::vector< std::shared_ptr< Entity > > guillaume::ecs::EntityRegistry::getEntitiesBreadthFirst ( void ) const

List every entity of this registry and of the registries nested in it, level by level (const overload).

Returns
A copy of the list, in the same order as the non-const overload; empty when the registry owns nothing.

Definition at line 163 of file entity_registry.cpp.

Here is the call graph for this function:

◆ getEntity() [1/2]

template<InheritFromEntity EntityType>
std::shared_ptr< EntityType > guillaume::ecs::EntityRegistry::getEntity ( Entity::Identifier identifier)
inline

Find an entity owned directly by this registry, by identifier.

Nested registries are not searched.

Template Parameters
EntityTypeThe type the entity is expected to have, for instance entities::Button, or ecs::Entity to accept any.
Parameters
identifierThe identifier of the entity to find.
Returns
The entity, or nullptr when this registry does not own an entity with that identifier or when the entity is not an EntityType.

Definition at line 235 of file entity_registry.hpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getEntity() [2/2]

template<InheritFromEntity EntityType>
std::shared_ptr< const EntityType > guillaume::ecs::EntityRegistry::getEntity ( Entity::Identifier identifier) const
inline

Find an entity owned directly by this registry, by identifier (const overload).

Nested registries are not searched.

Template Parameters
EntityTypeThe type the entity is expected to have.
Parameters
identifierThe identifier of the entity to find.
Returns
The entity, or nullptr when this registry does not own an entity with that identifier or when the entity is not an EntityType.

Definition at line 260 of file entity_registry.hpp.

Here is the call graph for this function:

◆ getEntityWithSignature() [1/2]

std::vector< Entity::Identifier > guillaume::ecs::EntityRegistry::getEntityWithSignature ( Entity::Signature systemSignature) const

List the entities that have every component type of a signature, from the root down.

Same as the other overload with a LevelOrderTraveler.

Parameters
systemSignatureThe component types an entity must declare to be listed. An empty signature matches every entity.
Returns
The identifiers of the matching entities of this registry and the nested ones, owners before what they own; empty when none matches.

Definition at line 192 of file entity_registry.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getEntityWithSignature() [2/2]

std::vector< Entity::Identifier > guillaume::ecs::EntityRegistry::getEntityWithSignature ( Entity::Signature systemSignature,
const EntityTreeTraveler & traveler ) const

List the entities that have every component type of a signature, in the order chosen by a traveler.

An entity matches when its own signature (Entity::getSignature) contains every bit of systemSignature; extra bits do not matter. This is the test System::routine applies.

Parameters
systemSignatureThe component types an entity must declare to be listed.
travelerDecides the order in which the tree is walked.
Returns
The identifiers of the matching entities, in traveler order; empty when none matches.

Definition at line 199 of file entity_registry.cpp.

Here is the call graph for this function:

◆ removeEntity()

bool guillaume::ecs::EntityRegistry::removeEntity ( Entity::Identifier identifier)

Remove an entity, with its children and all their components.

The entity is searched in this registry and in the registries nested in it. Everything the removed entity owns is removed with it, and so is every entity parented to it (recursively) that can be found from this registry; one registered out of reach is only unlinked (its parent identifier becomes Entity::InvalidIdentifier). Components are deleted and the entity leaves the child list of its parent's components::Hierarchy. Render systems drop its graphics on the next frame.

std::shared_ptrs to a removed entity held elsewhere stay valid as objects, but the entity has no component left and must not be used.

Parameters
identifierThe identifier of the entity to remove.
Returns
True when the entity was found and removed; false when it is not below this registry or the identifier is Entity::InvalidIdentifier.

Definition at line 108 of file entity_registry.cpp.


The documentation for this class was generated from the following files: