|
guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
|
Owns entities and gives the systems the list of entities to visit. More...
#include <headers/guillaume/ecs/entity_registry.hpp>

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. | |
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.
Things to watch out for:
Definition at line 74 of file entity_registry.hpp.
|
virtualdefault |
Virtual destructor.
The entity objects are released; their components are not deleted from the ComponentRegistry. Call clearEntities() first for that.
|
protectedpure virtual |
Give read access to the list of entities this registry owns directly.
Implemented in guillaume::ecs::EntityRegistryContainer, and guillaume::ecs::ParentEntity.
|
protectedpure virtual |
Give access to the list of entities this registry owns directly. Implemented by the class that provides the storage.
Implemented in guillaume::ecs::EntityRegistryContainer, and guillaume::ecs::ParentEntity.

| 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.
| entity | The entity to own. Must not be null. |
Definition at line 51 of file entity_registry.cpp.

| 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.
|
inline |
Get the entities this registry owns directly.
Definition at line 196 of file entity_registry.hpp.

| 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.
Definition at line 133 of file entity_registry.cpp.


| 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).
Definition at line 163 of file entity_registry.cpp.

|
inline |
Find an entity owned directly by this registry, by identifier.
Nested registries are not searched.
| EntityType | The type the entity is expected to have, for instance entities::Button, or ecs::Entity to accept any. |
| identifier | The identifier of the entity to find. |
Definition at line 235 of file entity_registry.hpp.


|
inline |
Find an entity owned directly by this registry, by identifier (const overload).
Nested registries are not searched.
| EntityType | The type the entity is expected to have. |
| identifier | The identifier of the entity to find. |
Definition at line 260 of file entity_registry.hpp.

| 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.
| systemSignature | The component types an entity must declare to be listed. An empty signature matches every entity. |
Definition at line 192 of file entity_registry.cpp.


| 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.
| systemSignature | The component types an entity must declare to be listed. |
| traveler | Decides the order in which the tree is walked. |
Definition at line 199 of file entity_registry.cpp.

| 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.
| identifier | The identifier of the entity to remove. |
Definition at line 108 of file entity_registry.cpp.