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 >
	Concrete ComponentTypeId bound to this entity's handle type. More...
template <typename TEntityManager>
using	ComponentOpsRegistry_type = ComponentOpsRegistry< Handle_type >
	Concrete ComponentOpsRegistry bound to this entity's handle type. More...
template <typename TEntityManager>
using	HierarchyComponent_type = HierarchyComponent< Handle_type >
	HierarchyComponent specialisation for this entity's handle type. More...
template <typename TEntityManager>
using	ActiveComponent_type = Active< Handle_type >
	Active tag component specialisation for this entity's handle type. More...
template <typename TEntityManager>
using	InactiveComponent_type = Inactive< Handle_type >
	Inactive tag component specialisation for this entity's handle type. More...

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 TFunc>
void	forEachComponentTypeId (TFunc &&func) const
	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 TComponent, typename TBuffer, typename ... Args>
void	deferAdd (TBuffer &buffer, Args &&...args)
	Enqueues a deferred add-component command into buffer. More...
template <typename TComponent, typename TBuffer>
void	deferRemove (TBuffer &buffer)
	Enqueues a deferred remove-component command into buffer. More...
template <typename TBuffer>
void	deferSetActive (TBuffer &buffer)
	Enqueues a deferred activate-entity command into buffer. More...
template <typename TBuffer>
void	deferSetInactive (TBuffer &buffer)
	Enqueues a deferred deactivate-entity command into buffer. More...
template <typename T, typename ... Args>
T &	getOrAdd (Args &&...args)
	Returns existing component or creates a new one. More...
template <typename T, typename ... Args>
T &	trackDirty (Args &&...args)
	Tracks the specified component which will be added if not already existing. More...
template <typename TComponent, typename TValue>
void	setTrackedValue (TComponent *component, TValue value)
	Updates the component's value and marks the component type dirty. More...
template <typename TComponent, typename TValue>
void	setTrackedValue (TComponent *component, const TValue &value)
	Updates the component's value and marks the component type dirty. 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 Functions Index

template <typename T>
void	markDirty ()
	Marks the specified component as dirty and registers the dirty set with the EntityManager. 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.

Definition at line 86 of file Entity.ixx.

Public Member Typedefs

ActiveComponent_type

template <typename TEntityManager>

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

Active tag component specialisation for this entity's handle type.

Definition at line 123 of file Entity.ixx.

123 using ActiveComponent_type = Active<Handle_type>;

ComponentOpsRegistry_type

template <typename TEntityManager>

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

Concrete ComponentOpsRegistry bound to this entity's handle type.

Definition at line 119 of file Entity.ixx.

119 using ComponentOpsRegistry_type = ComponentOpsRegistry<Handle_type>;

ComponentTypeId_type

template <typename TEntityManager>

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

Concrete ComponentTypeId bound to this entity's handle type.

Definition at line 117 of file Entity.ixx.

117 using ComponentTypeId_type = ComponentTypeId<Handle_type>;

Handle_type

template <typename TEntityManager>

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

Definition at line 115 of file Entity.ixx.

115 using Handle_type = TEntityManager::Handle_type;

HierarchyComponent_type

template <typename TEntityManager>

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

HierarchyComponent specialisation for this entity's handle type.

Definition at line 121 of file Entity.ixx.

121 using HierarchyComponent_type = HierarchyComponent<Handle_type>;

InactiveComponent_type

template <typename TEntityManager>

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

Inactive tag component specialisation for this entity's handle type.

Definition at line 125 of file Entity.ixx.

125 using InactiveComponent_type = 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 133 of file Entity.ixx.

133 explicit Entity(

134 const Handle_type entityHandle,

135 TEntityManager* entityManager

136

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

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

139 };

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 183 of file Entity.ixx.

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

184

185 bool active = true;

186

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

188 active = true;

189 } else {

190 active = false;

191 }

192

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

194

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

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

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

198

199 if (active && ops.onActivate) {

200 ops.onActivate(raw);

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

202 ops.onDeactivate(raw);

203 }

204

205 return *cmp;

206 }

References helios::ecs::ComponentOpsRegistry< THandle >::ops and helios::ecs::Entity< TEntityManager >::raw.

deferAdd()

template <typename TComponent, typename TBuffer, typename ... Args>

void helios::ecs::Entity< TEntityManager >::deferAdd (TBuffer & buffer, Args &&... args)

inline

Enqueues a deferred add-component command into buffer.

The component is not attached immediately; the command is applied when the buffer is flushed by the EntityMutationManager.

Template Parameters

TComponent	Component type to add.
TBuffer	Command buffer type. Its Handle_type must match this entity's.
Args	Constructor argument types for TComponent.

Parameters

buffer	Target command buffer to enqueue into.
args	Arguments forwarded to the TComponent constructor.

Definition at line 222 of file Entity.ixx.

222 void deferAdd(TBuffer& buffer, Args&& ...args) {

223 buffer.template add<AddComponentCommand<TComponent>>(entityHandle_, std::forward<Args>(args)...);

224 }

deferRemove()

template <typename TComponent, typename TBuffer>

void helios::ecs::Entity< TEntityManager >::deferRemove (TBuffer & buffer)

inline

Enqueues a deferred remove-component command into buffer.

The component is not detached immediately; the command is applied when the buffer is flushed by the EntityMutationManager.

Template Parameters

TComponent	Component type to remove.
TBuffer	Command buffer type. Its Handle_type must match this entity's.

Parameters

buffer

Target command buffer to enqueue into.

Definition at line 238 of file Entity.ixx.

238 void deferRemove(TBuffer& buffer) {

239 buffer.template add<RemoveComponentCommand<TComponent>>(entityHandle_);

240 }

deferSetActive()

template <typename TBuffer>

void helios::ecs::Entity< TEntityManager >::deferSetActive (TBuffer & buffer)

inline

Enqueues a deferred activate-entity command into buffer.

Activation is not applied immediately; the command is processed when the buffer is flushed by the EntityMutationManager.

Template Parameters

TBuffer

Command buffer type. Its Handle_type must match this entity's.

Parameters

buffer

Target command buffer to enqueue into.

Definition at line 253 of file Entity.ixx.

253 void deferSetActive(TBuffer& buffer) {

254 buffer.template add<ActivateEntityCommand<typename TEntityManager::Handle_type>>(entityHandle_);

255 }

deferSetInactive()

template <typename TBuffer>

void helios::ecs::Entity< TEntityManager >::deferSetInactive (TBuffer & buffer)

inline

Enqueues a deferred deactivate-entity command into buffer.

Deactivation is not applied immediately; the command is processed when the buffer is flushed by the EntityMutationManager.

Template Parameters

TBuffer

Command buffer type. Its Handle_type must match this entity's.

Parameters

buffer

Target command buffer to enqueue into.

Definition at line 268 of file Entity.ixx.

268 void deferSetInactive(TBuffer& buffer) {

269 buffer.template add<DeactivateEntityCommand<typename TEntityManager::Handle_type>>(entityHandle_);

270 }

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 428 of file Entity.ixx.

428 void disableComponent(const ComponentTypeId_type typeId) {

429 entityManager_->disable(entityHandle_, typeId);

430 }

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 419 of file Entity.ixx.

419 void enableComponent(const ComponentTypeId_type typeId) {

420 entityManager_->enable(entityHandle_, typeId);

421 }

forEachComponentTypeId()

template <typename TFunc>

void helios::ecs::Entity< TEntityManager >::forEachComponentTypeId (TFunc && func)

inline

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

Returns

Generator yielding ComponentTypeId for each attached component.

Definition at line 147 of file Entity.ixx.

147 void forEachComponentTypeId(TFunc&& func) const {

148 entityManager_->forEachComponentTypeId(entityHandle_, std::forward<TFunc>(func));

149 }

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

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 375 of file Entity.ixx.

375 T* get() {

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

377 }

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 387 of file Entity.ixx.

387 const T* get() const {

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

389 }

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 283 of file Entity.ixx.

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

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

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

286 }

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

288 }

handle()

template <typename TEntityManager>

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

inline noexcept

Returns the underlying entity handle.

Returns

The EntityHandle for this Entity.

Definition at line 156 of file Entity.ixx.

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

157 return entityHandle_;

158 }

handle()

template <typename TEntityManager>

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

inline noexcept

Returns the underlying entity handle (const).

Returns

The EntityHandle for this Entity.

Definition at line 165 of file Entity.ixx.

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

166 return entityHandle_;

167 }

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 399 of file Entity.ixx.

399 bool has() const noexcept{

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

401 }

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 410 of file Entity.ixx.

410 bool has(ComponentTypeId_type typeId) const noexcept {

411 return entityManager_->has(entityHandle_, typeId);

412 }

isActive()

template <typename TEntityManager>

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

inline

Returns whether this Entity is active.

Returns

True if the entity has the Active tag component.

Definition at line 495 of file Entity.ixx.

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

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

497 }

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 527 of file Entity.ixx.

527 void onAcquire() {

528 forEachComponentTypeId(

529 [&](const ComponentTypeId_type typeId) {

530 const auto& ops = ComponentOpsRegistry_type::ops(typeId);

531

532 if (ops.onAcquire) {

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

534 ops.onAcquire(raw);

535 }

536 }

537 );

538 }

References helios::ecs::Entity< TEntityManager >::forEachComponentTypeId, helios::ecs::ComponentOpsRegistry< THandle >::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 505 of file Entity.ixx.

505 void onRelease() {

506

507 forEachComponentTypeId(

508 [&](const ComponentTypeId_type typeId) {

509 const auto& ops = ComponentOpsRegistry_type::ops(typeId);

510

511 if (ops.onRelease) {

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

513 ops.onRelease(raw);

514 }

515 }

516 );

517

518

519 }

References helios::ecs::Entity< TEntityManager >::forEachComponentTypeId, helios::ecs::ComponentOpsRegistry< THandle >::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 363 of file Entity.ixx.

363 void* raw(const ComponentTypeId_type typeId) {

364 return entityManager_->raw(entityHandle_, typeId);

365 }

Referenced by helios::ecs::Entity< TEntityManager >::add, helios::ecs::Entity< TEntityManager >::onAcquire, helios::ecs::Entity< TEntityManager >::onRelease 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 352 of file Entity.ixx.

352 bool remove() {

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

354 }

setActive()

template <typename TEntityManager>

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

inline

Sets the activation state of this Entity.

When deactivated:

• 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
• Inactive will be marked as dirty component to indicate state change.

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
• Active will be marked as dirty component to indicate state change.

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 455 of file Entity.ixx.

455 void setActive(const bool active) {

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

457 const bool isInActive = !isActive;

458

459 if (!isActive && active) {

460 if (auto* hc = entityManager_->template get<HierarchyComponent_type>(entityHandle_)) {

461 hc->markDirty();

462 }

463 remove<InactiveComponent_type>();

464 trackDirty<ActiveComponent_type>();

465 }

466

467 if (!isInActive && !active) {

468 if (auto* hc = entityManager_->template get<HierarchyComponent_type>(entityHandle_)) {

469 hc->markDirty();

470 }

471 remove<ActiveComponent_type>();

472 trackDirty<InactiveComponent_type>();

473 }

474

475 forEachComponentTypeId(

476 [&](const ComponentTypeId_type typeId) {

477 const auto& ops = ComponentOpsRegistry_type::ops(typeId);

478

479 if (active && ops.onActivate) {

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

481 ops.onActivate(raw);

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

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

484 ops.onDeactivate(raw);

485 }

486 }

487 );

488 }

References helios::ecs::Entity< TEntityManager >::forEachComponentTypeId, helios::ecs::Entity< TEntityManager >::isActive, helios::ecs::ComponentOpsRegistry< THandle >::ops and helios::ecs::Entity< TEntityManager >::raw.

setTrackedValue()

template <typename TComponent, typename TValue>

void helios::ecs::Entity< TEntityManager >::setTrackedValue (TComponent * component, TValue value)

inline

Updates the component's value and marks the component type dirty.

Template Parameters

TComponent	The component type to update. Must be existing for this entity.
TValue	The value type to set. Must be compatible with TComponent::Value_type.

Parameters

component	Pointer to the TComponent
value	The value to update the component with.

Definition at line 319 of file Entity.ixx.

319 void setTrackedValue(TComponent* component, TValue value) {

320 assert(component != nullptr && "Unexpected nullptr for component.");

321 component->setValue(value);

322 markDirty<TComponent>();

323 }

setTrackedValue()

template <typename TComponent, typename TValue>

void helios::ecs::Entity< TEntityManager >::setTrackedValue (TComponent * component, const TValue & value)

inline

Updates the component's value and marks the component type dirty.

Template Parameters

TComponent	The component type to update. Must be existing for this entity.
TValue	The value type to set. Must be compatible with TComponent::Value_type.

Parameters

component	Pointer to the TComponent
value	The value to update the component with.

Definition at line 337 of file Entity.ixx.

337 void setTrackedValue(TComponent* component, const TValue& value) {

338 assert(component != nullptr && "Unexpected nullptr for component.");

339 component->setValue(value);

340 markDirty<TComponent>();

341 }

trackDirty()

template <typename T, typename ... Args>

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

inline

Tracks the specified component which will be added if not already existing.

Template Parameters

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

Parameters

args	Arguments forwarded to the component constructor.

Returns

Reference to the tracked component.

See Also

markDirty

Definition at line 301 of file Entity.ixx.

301 T& trackDirty(Args&& ...args) {

302 entityManager_->template trackDirty<T>();

303 markDirty<T>();

304 return getOrAdd<T>(std::forward<Args>(args)...);

305 }

Private Member Functions

markDirty()

template <typename T>

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

inline

Marks the specified component as dirty and registers the dirty set with the EntityManager.

Template Parameters

T	The component type to mark as dirty.

Definition at line 104 of file Entity.ixx.

104 void markDirty() {

105 if (!entityManager_->template managesDirty<T>()) {

106 bool mg = entityManager_->template managesDirty<T>();

107 assert((entityManager_->template managesDirty<T>()) && "Cannot mark component as dirty, not tracked by EntityManager." );

108

109 }

110 getOrAdd<DirtyComponentSpec<T>>();

111 }

Private Member Attributes

entityHandle_

template <typename TEntityManager>

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

The underlying entity identifier.

Definition at line 91 of file Entity.ixx.

91 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 96 of file Entity.ixx.

96 TEntityManager* entityManager_;

---

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

• Entity.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.