|
guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
|
One thing in the UI: an identifier, a signature and a place in the tree. It holds no state of its own. More...
#include <headers/guillaume/ecs/entity.hpp>


Public Types | |
| using | Identifier = std::size_t |
| The key under which an entity's components are stored. Systems and components refer to entities by this value. | |
| using | Signature = std::bitset<128> |
| A set of component types, one bit per type (bit position given by ComponentTypeId, MaxComponentTypes bits). | |
Public Member Functions | |
| Entity (void) | |
| Create an entity with a fresh identifier, an empty signature, no parent and no component. | |
| virtual | ~Entity (void)=default |
| Destroy the entity object. | |
| Entity::Identifier | getIdentifier (void) const noexcept |
| Get the identifier of the entity. | |
| Entity::Signature | getSignature (void) const noexcept |
| Get the set of component types the entity declares. | |
| void | setSignature (const Signature &signature) |
| Replace the signature of the entity. | |
| std::int32_t | getLayer (void) const noexcept |
| Get the depth of the entity in the tree. | |
| Entity & | setParent (std::shared_ptr< Entity > parent) |
| Attach the entity under another one, or detach it. | |
| std::vector< Identifier > | releaseComponents (void) |
| Drop the entity's place in the tree and all its components. | |
| std::shared_ptr< Entity > | getParent (void) const noexcept |
| Get the parent entity. | |
Static Public Member Functions | |
| template<InheritFromComponent... ComponentTypes> | |
| static Signature | getSignatureFromTypes (void) |
| Build the signature that has exactly the bits of the given component types. | |
Static Public Attributes | |
| static constexpr Identifier | InvalidIdentifier |
| "No entity": never the identifier of a real entity | |
Protected Member Functions | |
| void | attachHierarchy (ComponentRegistry &componentRegistry) |
| Give the entity a components::Hierarchy in a registry and add that component to its signature. | |
| template<InheritFromComponent... ComponentTypes> | |
| void | setSignature (void) |
| Replace the signature by the one made of the given component types. | |
One thing in the UI: an identifier, a signature and a place in the tree. It holds no state of its own.
Widgets (entities::Button, ...) derive from EntityFiller or ParentEntityFiller, which create the components, set the signature and attach the Hierarchy. A bare Entity has none of that.
Two different links make up the tree, and a child needs both:
setParent alone does not keep the child alive (the entity only holds a weak reference to its parent, and the parent none to the child), and systems only visit entities owned, directly or not, by the scene's EntityRegistry. The owner is not always the parent: the widget Builders register what they create in the scene itself.
Definition at line 77 of file entity.hpp.
| using guillaume::ecs::Entity::Identifier = std::size_t |
The key under which an entity's components are stored. Systems and components refer to entities by this value.
Definition at line 86 of file entity.hpp.
| using guillaume::ecs::Entity::Signature = std::bitset<128> |
A set of component types, one bit per type (bit position given by ComponentTypeId, MaxComponentTypes bits).
Definition at line 91 of file entity.hpp.
| guillaume::ecs::Entity::Entity | ( | void | ) |
Create an entity with a fresh identifier, an empty signature, no parent and no component.
Definition at line 88 of file entity.cpp.


|
virtualdefault |
Destroy the entity object.
Its components stay in the registry. Remove an entity with EntityRegistry::removeEntity to delete them too.

|
protected |
Give the entity a components::Hierarchy in a registry and add that component to its signature.
From then on setParent mirrors the parent, the children and the layer into that component, and getLayer reads it. An existing Hierarchy of the entity is kept. Called by EntityFiller and ParentEntityFiller.
| componentRegistry | The registry that stores the component. The entity keeps a pointer to it, so it must stay alive as long as the entity is used. |
Definition at line 109 of file entity.cpp.

|
noexcept |
Get the identifier of the entity.
Definition at line 94 of file entity.cpp.
|
noexcept |
Get the depth of the entity in the tree.
Read from the entity's components::Hierarchy when it has one. systems::Layout uses the layer to offset an entity along the forward axis of its parent, so a child sits in front of it.
Definition at line 119 of file entity.cpp.


|
noexcept |
Get the parent entity.
Definition at line 207 of file entity.cpp.
|
noexcept |
Get the set of component types the entity declares.
Definition at line 99 of file entity.cpp.
|
static |
Build the signature that has exactly the bits of the given component types.
| ComponentTypes | The component types to include. |
| ComponentTypeLimitExceededException | When more than MaxComponentTypes component types are in use. |

| std::vector< Entity::Identifier > guillaume::ecs::Entity::releaseComponents | ( | void | ) |
Drop the entity's place in the tree and all its components.
Removes the entity from its parent's components::Hierarchy, resets the parent identifier of the entities parented to it to InvalidIdentifier, and deletes every component stored for it in the registry given to attachHierarchy. Called by EntityRegistry::removeEntity; the entity must not be used afterwards. An entity without Hierarchy only forgets its parent.
Definition at line 174 of file entity.cpp.
Attach the entity under another one, or detach it.
The layer becomes the parent's layer plus one (0 when detached). When the entity has a components::Hierarchy, the tree is mirrored into the components: the entity leaves the child list of its previous parent, joins the one of the new parent, stores the parent's identifier, and the layer of every descendant is recomputed. Those writes mark the Hierarchy components changed when a value differs.
The parent does not take ownership: also register the entity with EntityRegistry::addEntity (usually on the parent) so that it stays alive and systems visit it.
| parent | The new parent, or nullptr to make the entity a root. Only a weak reference is kept. |
| std::invalid_argument | When the parent is the entity itself or, for an entity with a Hierarchy, one of its descendants. The tree is left as it was. |
Definition at line 131 of file entity.cpp.

| void guillaume::ecs::Entity::setSignature | ( | const Signature & | signature | ) |
Replace the signature of the entity.
The signature is not derived from the registry: after adding a component with ComponentRegistry::addComponent, add its bit here, otherwise the systems that need that component skip the entity.
| signature | The new signature. Start from getSignature() to keep the bits already set. |
Definition at line 104 of file entity.cpp.
|
protected |
Replace the signature by the one made of the given component types.
Bits set before the call are lost, including the one of components::Hierarchy.
| ComponentTypes | The component types the entity declares. |
|
staticconstexpr |
"No entity": never the identifier of a real entity
Definition at line 93 of file entity.hpp.