Entity Class Template

Lightweight facade for entity component manipulation. More...

Declaration

template <typename TEntityManager> class helios::ecs::Entity<TEntityManager> { ... }

Public Member Typedefs Index

template <typename TEntityManager>
using	Handle_type = TEntityManager::Handle_type
template <typename TEntityManager>
using	ComponentTypeId_type = ComponentTypeId< Handle_type >
template <typename TEntityManager>
using	ComponentOpsRegistry_type = ComponentOpsRegistry< Handle_type >
template <typename TEntityManager>
using	HierarchyComponent_type = components::HierarchyComponent< Handle_type >
template <typename TEntityManager>
using	InactiveComponent_type = components::Inactive< Handle_type >
template <typename TEntityManager>
using	ActiveComponent_type = components::Active< Handle_type >

Public Constructors Index

template <typename TEntityManager>
Entity (const Handle_type entityHandle, TEntityManager *entityManager) noexcept
	Constructs a Entity wrapper. More...

Public Member Functions Index

template <typename TEntityManager>
auto	componentTypeIds () const -> std::generator< ComponentTypeId_type >
	Returns a generator over all component type IDs attached to this entity. More...
template <typename TEntityManager>
Handle_type	handle () noexcept
	Returns the underlying entity handle. More...
template <typename TEntityManager>
Handle_type	handle () const noexcept
	Returns the underlying entity handle (const). More...
template <typename T, typename ... Args>
T &	add (Args &&...args)
	Constructs and attaches a component to this entity. More...
template <typename T, typename ... Args>
T &	getOrAdd (Args &&...args)
	Returns existing component or creates a new one. More...
template <typename T>
bool	remove ()
	Removes a component from this entity. More...
template <typename TEntityManager>
void *	raw (const ComponentTypeId_type typeId)
	Returns raw pointer to component by type ID. More...
template <typename T>
T *	get ()
	Returns pointer to a component. More...
template <typename T>
const T *	get () const
	Returns const pointer to a component. More...
template <typename T>
bool	has () const noexcept
	Checks if this entity has a specific component type. More...
template <typename TEntityManager>
bool	has (ComponentTypeId_type typeId) const noexcept
	Checks if this entity has a component by type ID. More...
template <typename TEntityManager>
void	enableComponent (const ComponentTypeId_type typeId)
	Enables a specific component by type ID. More...
template <typename TEntityManager>
void	disableComponent (const ComponentTypeId_type typeId)
	Disables a specific component by type ID. More...
template <typename TEntityManager>
void	setActive (const bool active)
	Sets the activation state of this Entity. More...
template <typename TEntityManager>
bool	isActive () const
	Returns whether this Entity is active. More...
template <typename TEntityManager>
void	onRelease ()
	Notifies all components that the entity is being released to a pool. More...
template <typename TEntityManager>
void	onAcquire ()
	Notifies all components that the entity is being acquired from a pool. More...

Private Member Attributes Index

template <typename TEntityManager>
TEntityManager::Handle_type	entityHandle_ {0,0}
	The underlying entity identifier. More...
template <typename TEntityManager>
TEntityManager *	entityManager_
	Non-owning pointer to the EntityManager. More...

Description

Lightweight facade for entity component manipulation.

`Entity` provides a type-safe, convenient interface for working with entities and their components. It wraps an `EntityHandle` and a pointer to the `EntityManager`, delegating all operations.

## Size and Copy Semantics

Entity is only 16 bytes (8 bytes EntityHandle + 8 bytes pointer) and should be **passed by value**, not by reference:

```cpp // Correct - pass by value void processEntity(Entity entity) { ... }

// Unnecessary - reference adds indirection void processEntity(Entity& entity); // Avoid void processEntity(const Entity& entity); // Avoid ```

## Hierarchy Integration

When a Entity has a `HierarchyComponent`, activation changes trigger hierarchy propagation. Calling `setActive()` marks the hierarchy as dirty, and `HierarchyPropagationSystem` propagates the state to all descendants.

## Usage

```cpp auto player = gameWorld.addEntity();

// Add components player.add<TransformComponent>(position); player.add<HealthComponent>(100.0f);

// Query and access if (player.has<HealthComponent>()) { player.get<HealthComponent>()->takeDamage(10.0f); }

// Activation state (propagates to children if HierarchyComponent present) player.setActive(false); // Calls onDeactivate() on components ```

Template Parameters

TEntityManager

The entity manager type providing handle and component storage. Must expose `Handle_type` and component operations.

See Also

EntityHandle

See Also

EntityManager

See Also

GameWorld

See Also

HierarchyComponent

See Also

HierarchyPropagationSystem

Definition at line 83 of file Entity.ixx.

Public Member Typedefs

ActiveComponent_type

template <typename TEntityManager>

using helios::ecs::Entity< TEntityManager >::ActiveComponent_type = components::Active<Handle_type>

Definition at line 103 of file Entity.ixx.

103 using ActiveComponent_type = components::Active<Handle_type>;

ComponentOpsRegistry_type

template <typename TEntityManager>

using helios::ecs::Entity< TEntityManager >::ComponentOpsRegistry_type = ComponentOpsRegistry<Handle_type>

Definition at line 100 of file Entity.ixx.

100 using ComponentOpsRegistry_type = ComponentOpsRegistry<Handle_type>;

ComponentTypeId_type

template <typename TEntityManager>

using helios::ecs::Entity< TEntityManager >::ComponentTypeId_type = ComponentTypeId<Handle_type>

Definition at line 99 of file Entity.ixx.

99 using ComponentTypeId_type = ComponentTypeId<Handle_type>;

Handle_type

template <typename TEntityManager>

using helios::ecs::Entity< TEntityManager >::Handle_type = TEntityManager::Handle_type

Definition at line 98 of file Entity.ixx.

98 using Handle_type = TEntityManager::Handle_type;

HierarchyComponent_type

template <typename TEntityManager>

using helios::ecs::Entity< TEntityManager >::HierarchyComponent_type = components::HierarchyComponent<Handle_type>

Definition at line 101 of file Entity.ixx.

101 using HierarchyComponent_type = components::HierarchyComponent<Handle_type>;

InactiveComponent_type

template <typename TEntityManager>

using helios::ecs::Entity< TEntityManager >::InactiveComponent_type = components::Inactive<Handle_type>

Definition at line 102 of file Entity.ixx.

102 using InactiveComponent_type = components::Inactive<Handle_type>;

Public Constructors

Entity()

template <typename TEntityManager>

helios::ecs::Entity< TEntityManager >::Entity (const Handle_type entityHandle, TEntityManager * entityManager)

inline explicit noexcept

Constructs a Entity wrapper.

Parameters

entityHandle	The entity handle to wrap.
entityManager	Pointer to the EntityManager. Must not be null.

Definition at line 111 of file Entity.ixx.

111 explicit Entity(

112 const Handle_type entityHandle,

113 TEntityManager* entityManager

114

115 ) noexcept : entityHandle_(entityHandle), entityManager_(entityManager) {

116 assert(entityManager_ != nullptr && "EntityManager must not be null.");

117 };

Public Member Functions

add()

template <typename T, typename ... Args>

T & helios::ecs::Entity< TEntityManager >::add (Args &&... args)

inline

Constructs and attaches a component to this entity.

If the entity is active, calls `onActivate()` on the new component. If inactive, calls `onDeactivate()`.

Template Parameters

T	The component type to add.
Args	Constructor argument types.

Parameters

args	Arguments forwarded to the component constructor.

Returns

Reference to the newly created component.

Definition at line 161 of file Entity.ixx.

161 T& add(Args&& ...args) {

162

163 bool active = true;

164

165 if (entityManager_->template has<ActiveComponent_type>(entityHandle_)) {

166 active = true;

167 } else {

168 active = false;

169 }

170

171 auto* cmp = entityManager_->template emplace<T>(entityHandle_, std::forward<Args>(args)...);

172

173 auto typeId = ComponentTypeId_type::template id<T>();

174 const auto ops = ComponentOpsRegistry_type::ops(typeId);

175 void* raw = entityManager_->raw(entityHandle_, typeId);

176

177 if (active && ops.onActivate) {

178 ops.onActivate(raw);

179 } else if (!active && ops.onDeactivate) {

180 ops.onDeactivate(raw);

181 }

182

183 return *cmp;

184 }

References helios::ecs::Entity< TEntityManager >::has, helios::ecs::ComponentOpsRegistry< Handle_type >::ops and helios::ecs::Entity< TEntityManager >::raw.

Referenced by helios::ecs::Entity< TEntityManager >::getOrAdd.

componentTypeIds()

template <typename TEntityManager>

std::generator< ComponentTypeId_type > helios::ecs::Entity< TEntityManager >::componentTypeIds ()

inline nodiscard

Returns a generator over all component type IDs attached to this entity.

Returns

Generator yielding ComponentTypeId for each attached component.

Definition at line 125 of file Entity.ixx.

125 componentTypeIds() const {

126 return entityManager_->componentTypeIds(entityHandle_);

127 }

Referenced by helios::ecs::Entity< TEntityManager >::onAcquire, helios::ecs::Entity< TEntityManager >::onRelease and helios::ecs::Entity< TEntityManager >::setActive.

disableComponent()

template <typename TEntityManager>

void helios::ecs::Entity< TEntityManager >::disableComponent (const ComponentTypeId_type typeId)

inline

Disables a specific component by type ID.

Parameters

typeId

The component type identifier.

Definition at line 288 of file Entity.ixx.

288 void disableComponent(const ComponentTypeId_type typeId) {

289 entityManager_->template disable(entityHandle_, typeId);

290 }

enableComponent()

template <typename TEntityManager>

void helios::ecs::Entity< TEntityManager >::enableComponent (const ComponentTypeId_type typeId)

inline

Enables a specific component by type ID.

Parameters

typeId

The component type identifier.

Definition at line 279 of file Entity.ixx.

279 void enableComponent(const ComponentTypeId_type typeId) {

280 entityManager_->template enable(entityHandle_, typeId);

281 }

get()

template <typename T>

T * helios::ecs::Entity< TEntityManager >::get ()

inline

Returns pointer to a component.

Template Parameters

T	The component type.

Returns

Pointer to the component, or nullptr if not attached.

Definition at line 235 of file Entity.ixx.

235 T* get() {

236 return entityManager_->template get<T>(entityHandle_);

237 }

Reference helios::ecs::Entity< TEntityManager >::get.

Referenced by helios::ecs::Entity< TEntityManager >::get, helios::ecs::Entity< TEntityManager >::get, helios::ecs::Entity< TEntityManager >::getOrAdd and helios::ecs::Entity< TEntityManager >::setActive.

get()

template <typename T>

const T * helios::ecs::Entity< TEntityManager >::get ()

inline

Returns const pointer to a component.

Template Parameters

T	The component type.

Returns

Const pointer to the component, or nullptr if not attached.

Definition at line 247 of file Entity.ixx.

247 const T* get() const {

248 return entityManager_->template get<T>(entityHandle_);

249 }

Reference helios::ecs::Entity< TEntityManager >::get.

getOrAdd()

template <typename T, typename ... Args>

T & helios::ecs::Entity< TEntityManager >::getOrAdd (Args &&... args)

inline

Returns existing component or creates a new one.

Template Parameters

T	The component type.
Args	Constructor argument types.

Parameters

args	Arguments forwarded to the constructor if creating.

Returns

Reference to the existing or newly created component.

Definition at line 197 of file Entity.ixx.

197 T& getOrAdd(Args&& ...args) {

198 if (entityManager_->template has<T>(entityHandle_)) {

199 return *entityManager_->template get<T>(entityHandle_);

200 }

201 return add<T>(std::forward<Args>(args)...);

202 }

References helios::ecs::Entity< TEntityManager >::add, helios::ecs::Entity< TEntityManager >::get and helios::ecs::Entity< TEntityManager >::has.

handle()

template <typename TEntityManager>

Handle_type helios::ecs::Entity< TEntityManager >::handle ()

inline nodiscard noexcept

Returns the underlying entity handle.

Returns

The EntityHandle for this Entity.

Definition at line 134 of file Entity.ixx.

134 [[nodiscard]] Handle_type handle() noexcept {

135 return entityHandle_;

136 }

handle()

template <typename TEntityManager>

Handle_type helios::ecs::Entity< TEntityManager >::handle ()

inline nodiscard noexcept

Returns the underlying entity handle (const).

Returns

The EntityHandle for this Entity.

Definition at line 143 of file Entity.ixx.

143 [[nodiscard]] Handle_type handle() const noexcept {

144 return entityHandle_;

145 }

has()

template <typename T>

bool helios::ecs::Entity< TEntityManager >::has ()

inline noexcept

Checks if this entity has a specific component type.

Template Parameters

T	The component type to check.

Returns

True if the component is attached, false otherwise.

Definition at line 259 of file Entity.ixx.

259 bool has() const noexcept{

260 return entityManager_->template has<T>(entityHandle_);

261 }

Reference helios::ecs::Entity< TEntityManager >::has.

Referenced by helios::ecs::Entity< TEntityManager >::add, helios::ecs::Entity< TEntityManager >::getOrAdd, helios::ecs::Entity< TEntityManager >::has, helios::ecs::Entity< TEntityManager >::has, helios::ecs::Entity< TEntityManager >::isActive and helios::ecs::Entity< TEntityManager >::setActive.

has()

template <typename TEntityManager>

bool helios::ecs::Entity< TEntityManager >::has (ComponentTypeId_type typeId)

inline noexcept

Checks if this entity has a component by type ID.

Parameters

typeId

The component type identifier.

Returns

True if the component is attached, false otherwise.

Definition at line 270 of file Entity.ixx.

270 bool has(ComponentTypeId_type typeId) const noexcept {

271 return entityManager_->template has(entityHandle_, typeId);

272 }

Reference helios::ecs::Entity< TEntityManager >::has.

isActive()

template <typename TEntityManager>

bool helios::ecs::Entity< TEntityManager >::isActive ()

inline nodiscard

Returns whether this Entity is active.

Returns

True if the entity has the Active tag component.

Definition at line 356 of file Entity.ixx.

356 [[nodiscard]] bool isActive() const {

357 return entityManager_->template has<ActiveComponent_type>(entityHandle_);

358 }

Reference helios::ecs::Entity< TEntityManager >::has.

Referenced by helios::ecs::Entity< TEntityManager >::setActive.

onAcquire()

template <typename TEntityManager>

void helios::ecs::Entity< TEntityManager >::onAcquire ()

inline

Notifies all components that the entity is being acquired from a pool.

Iterates through all attached components and calls `onAcquire()` on those that implement it.

Definition at line 383 of file Entity.ixx.

383 void onAcquire() {

384 for (auto typeId : componentTypeIds()) {

385 const auto ops = ComponentOpsRegistry_type::ops(typeId);

386 void* raw = entityManager_->template raw(entityHandle_, typeId);

387

388 if (ops.onAcquire) {

389 ops.onAcquire(raw);

390 }

391 }

392 }

References helios::ecs::Entity< TEntityManager >::componentTypeIds, helios::ecs::ComponentOpsRegistry< Handle_type >::ops and helios::ecs::Entity< TEntityManager >::raw.

onRelease()

template <typename TEntityManager>

void helios::ecs::Entity< TEntityManager >::onRelease ()

inline

Notifies all components that the entity is being released to a pool.

Iterates through all attached components and calls `onRelease()` on those that implement it.

Definition at line 366 of file Entity.ixx.

366 void onRelease() {

367 for (auto typeId : componentTypeIds()) {

368 const auto ops = ComponentOpsRegistry_type::ops(typeId);

369 void* raw = entityManager_->template raw(entityHandle_, typeId);

370

371 if (ops.onRelease) {

372 ops.onRelease(raw);

373 }

374 }

375 }

References helios::ecs::Entity< TEntityManager >::componentTypeIds, helios::ecs::ComponentOpsRegistry< Handle_type >::ops and helios::ecs::Entity< TEntityManager >::raw.

raw()

template <typename TEntityManager>

void * helios::ecs::Entity< TEntityManager >::raw (const ComponentTypeId_type typeId)

inline

Returns raw pointer to component by type ID.

Parameters

typeId

The component type identifier.

Returns

Raw void pointer to the component, or nullptr if not found.

Definition at line 223 of file Entity.ixx.

223 void* raw(const ComponentTypeId_type typeId) {

224 return entityManager_->template raw(entityHandle_, typeId);

225 }

Reference helios::ecs::Entity< TEntityManager >::raw.

Referenced by helios::ecs::Entity< TEntityManager >::add, helios::ecs::Entity< TEntityManager >::onAcquire, helios::ecs::Entity< TEntityManager >::onRelease, helios::ecs::Entity< TEntityManager >::raw and helios::ecs::Entity< TEntityManager >::setActive.

remove()

template <typename T>

bool helios::ecs::Entity< TEntityManager >::remove ()

inline

Removes a component from this entity.

Template Parameters

T	The component type to remove.

Returns

True if the component was removed, false if not present.

Definition at line 212 of file Entity.ixx.

212 bool remove() {

213 return entityManager_->template remove<T>(entityHandle_);

214 }

Reference helios::ecs::Entity< TEntityManager >::remove.

Referenced by helios::ecs::Entity< TEntityManager >::remove and helios::ecs::Entity< TEntityManager >::setActive.

setActive()

template <typename TEntityManager>

void helios::ecs::Entity< TEntityManager >::setActive (const bool active)

inline

Sets the activation state of this Entity.

When deactivated:

• An `Inactive` tag component is added
• The `Active` tag component is removed
• `onDeactivate()` is called on components that support it
• If a `HierarchyComponent` is present, it is marked dirty for propagation

When activated:

• The `Inactive` tag component is removed
• An `Active` tag component is added
• `onActivate()` is called on components that support it
• If a `HierarchyComponent` is present, it is marked dirty for propagation

info

Does **not** call `enable()`/`disable()` on components.

Parameters

active

True to activate, false to deactivate.

See Also

HierarchyComponent_type

See Also

HierarchyPropagationSystem

Definition at line 314 of file Entity.ixx.

314 void setActive(const bool active) {

315

316 bool isActive = entityManager_->template has<ActiveComponent_type>(entityHandle_);

317 bool isInActive = entityManager_->template has<InactiveComponent_type>(entityHandle_);

318

319 if (!isActive && active) {

320 auto* hc = entityManager_->template get<HierarchyComponent_type>(entityHandle_);

321 if (hc) {

322 hc->markDirty();

323 }

324

325 entityManager_->template remove<InactiveComponent_type>(entityHandle_);

326 entityManager_->template emplaceOrGet<ActiveComponent_type>(entityHandle_);

327 }

328

329 if (!isInActive && !active) {

330 auto* hc = entityManager_->template get<HierarchyComponent_type>(entityHandle_);

331 if (hc) {

332 hc->markDirty();

333 }

334

335 entityManager_->template emplaceOrGet<InactiveComponent_type>(entityHandle_);

336 entityManager_->template remove<ActiveComponent_type>(entityHandle_);

337 }

338

339 for (auto typeId : componentTypeIds()) {

340 const auto ops = ComponentOpsRegistry_type::ops(typeId);

341 void* raw = entityManager_->raw(entityHandle_, typeId);

342

343 if (active && ops.onActivate) {

344 ops.onActivate(raw);

345 } else if (!active && ops.onDeactivate) {

346 ops.onDeactivate(raw);

347 }

348 }

349 }

References helios::ecs::Entity< TEntityManager >::componentTypeIds, helios::ecs::Entity< TEntityManager >::get, helios::ecs::Entity< TEntityManager >::has, helios::ecs::Entity< TEntityManager >::isActive, helios::ecs::ComponentOpsRegistry< Handle_type >::ops, helios::ecs::Entity< TEntityManager >::raw and helios::ecs::Entity< TEntityManager >::remove.

Private Member Attributes

entityHandle_

template <typename TEntityManager>

TEntityManager::Handle_type helios::ecs::Entity< TEntityManager >::entityHandle_ {0,0}

The underlying entity identifier.

Definition at line 88 of file Entity.ixx.

88 TEntityManager::Handle_type entityHandle_{0,0};

entityManager_

template <typename TEntityManager>

TEntityManager* helios::ecs::Entity< TEntityManager >::entityManager_

Non-owning pointer to the EntityManager.

Definition at line 93 of file Entity.ixx.

93 TEntityManager* entityManager_;

---

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

• Entity.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.