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

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>

Inheritance diagram for guillaume::ecs::Entity:
Collaboration diagram for guillaume::ecs::Entity:

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.

Detailed Description

One thing in the UI: an identifier, a signature and a place in the tree. It holds no state of its own.

  • The identifier is the key under which the entity's components are stored in a ComponentRegistry. It is unique in the program and never reused.
  • The signature is a bitmask with one bit per component type the entity declares. A system visits an entity when the signature contains every bit of the system's own signature.
  • The place in the tree is the parent given to setParent. It is mirrored into the entity's components::Hierarchy (parent identifier, child identifiers, layer), which is what systems read to walk the tree from identifiers alone.

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:

child->setParent(parent); // parent link: layout, depth, Hierarchy
parent->addEntity(child); // ownership: lifetime, visited by
Rules. Every class here runs each frame on the entities that have the components it declares.

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.

Note
Entities are handled through std::shared_ptr.
See also
EntityFiller
ComponentRegistry
EntityRegistry

Definition at line 77 of file entity.hpp.

Member Typedef Documentation

◆ Identifier

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.

◆ Signature

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.

Constructor & Destructor Documentation

◆ Entity()

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.

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

◆ ~Entity()

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

Destroy the entity object.

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

Here is the call graph for this function:

Member Function Documentation

◆ attachHierarchy()

void guillaume::ecs::Entity::attachHierarchy ( ComponentRegistry & componentRegistry)
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.

Parameters
componentRegistryThe 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.

Here is the call graph for this function:

◆ getIdentifier()

Entity::Identifier guillaume::ecs::Entity::getIdentifier ( void ) const
noexcept

Get the identifier of the entity.

Returns
The identifier, never InvalidIdentifier.

Definition at line 94 of file entity.cpp.

◆ getLayer()

std::int32_t guillaume::ecs::Entity::getLayer ( void ) const
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.

Returns
0 for an entity without parent, the parent's layer plus one otherwise.

Definition at line 119 of file entity.cpp.

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

◆ getParent()

std::shared_ptr< Entity > guillaume::ecs::Entity::getParent ( void ) const
noexcept

Get the parent entity.

Returns
The parent, or nullptr when the entity has none or when the parent object was destroyed.

Definition at line 207 of file entity.cpp.

◆ getSignature()

Entity::Signature guillaume::ecs::Entity::getSignature ( void ) const
noexcept

Get the set of component types the entity declares.

Returns
A copy of the signature.

Definition at line 99 of file entity.cpp.

◆ getSignatureFromTypes()

template<InheritFromComponent... ComponentTypes>
Signature guillaume::ecs::Entity::getSignatureFromTypes ( void )
static

Build the signature that has exactly the bits of the given component types.

entity->setSignature(entity->getSignature()
static Signature getSignatureFromTypes(void)
Build the signature that has exactly the bits of the given component types.
Template Parameters
ComponentTypesThe component types to include.
Returns
The signature; empty when no type is given.
Exceptions
ComponentTypeLimitExceededExceptionWhen more than MaxComponentTypes component types are in use.
Here is the caller graph for this function:

◆ releaseComponents()

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.

Returns
The identifiers of the entities that were parented to it; empty when it had no child or no Hierarchy.

Definition at line 174 of file entity.cpp.

◆ setParent()

Entity & guillaume::ecs::Entity::setParent ( std::shared_ptr< Entity > parent)

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.

Parameters
parentThe new parent, or nullptr to make the entity a root. Only a weak reference is kept.
Returns
Reference to this entity, for chaining.
Exceptions
std::invalid_argumentWhen 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.

Here is the call graph for this function:

◆ setSignature() [1/2]

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.

Parameters
signatureThe new signature. Start from getSignature() to keep the bits already set.

Definition at line 104 of file entity.cpp.

◆ setSignature() [2/2]

template<InheritFromComponent... ComponentTypes>
void guillaume::ecs::Entity::setSignature ( void )
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.

Template Parameters
ComponentTypesThe component types the entity declares.

Member Data Documentation

◆ InvalidIdentifier

Identifier guillaume::ecs::Entity::InvalidIdentifier
staticconstexpr
Initial value:
=
0

"No entity": never the identifier of a real entity

Definition at line 93 of file entity.hpp.


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