GameObject Class

Lightweight facade for entity component manipulation. More...

Declaration

class helios::engine::ecs::GameObject { ... }

Public Constructors Index

	GameObject (const helios::engine::ecs::EntityHandle entityHandle, helios::engine::ecs::EntityManager *entityManager) noexcept
	Constructs a GameObject wrapper. More...

Public Member Functions Index

std::generator< helios::engine::core::data::ComponentTypeId >	componentTypeIds () const
	Returns a generator over all component type IDs attached to this entity. More...
helios::engine::ecs::EntityHandle	entityHandle () noexcept
	Returns the underlying entity handle. More...
helios::engine::ecs::EntityHandle	entityHandle () 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...
void *	raw (const helios::engine::core::data::ComponentTypeId 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 ()
	Checks if this entity has a specific component type. More...
bool	has (helios::engine::core::data::ComponentTypeId typeId)
	Checks if this entity has a component by type ID. More...
void	enableComponent (const helios::engine::core::data::ComponentTypeId typeId)
	Enables a specific component by type ID. More...
void	disableComponent (const helios::engine::core::data::ComponentTypeId typeId)
	Disables a specific component by type ID. More...
void	setActive (const bool active)
	Sets the activation state of this GameObject. More...
bool	isActive () const
	Returns whether this GameObject is active. More...
void	onRelease ()
	Notifies all components that the entity is being released to a pool. More...
void	onAcquire ()
	Notifies all components that the entity is being acquired from a pool. More...

Private Member Attributes Index

helios::engine::ecs::EntityHandle	entityHandle_ {0,0}
	The underlying entity identifier. More...
helios::engine::ecs::EntityManager *	entityManager_
	Non-owning pointer to the EntityManager. More...

Description

Lightweight facade for entity component manipulation.

`GameObject` 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

GameObject 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(GameObject entity) { ... }

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

## Hierarchy Integration

When a GameObject 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.addGameObject();

// 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 ```

See Also

EntityHandle

See Also

EntityManager

See Also

GameWorld

See Also

HierarchyComponent

See Also

HierarchyPropagationSystem

Definition at line 85 of file GameObject.ixx.

Public Constructors

GameObject()

helios::engine::ecs::GameObject::GameObject (const helios::engine::ecs::EntityHandle entityHandle, helios::engine::ecs::EntityManager * entityManager)

inline explicit noexcept

Constructs a GameObject wrapper.

Parameters

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

Definition at line 106 of file GameObject.ixx.

106 explicit GameObject(

107 const helios::engine::ecs::EntityHandle entityHandle,

108 helios::engine::ecs::EntityManager* entityManager

109

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

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

112 };

Reference entityHandle.

Public Member Functions

add()

template <typename T, typename ... Args>

T & helios::engine::ecs::GameObject::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 156 of file GameObject.ixx.

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

157

158 bool active = true;

159

160 if (entityManager_->has<helios::engine::mechanics::lifecycle::components::Active>(entityHandle_)) {

161 active = true;

162 } else {

163 active = false;

164 }

165

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

167

168 auto typeId = helios::engine::core::data::ComponentTypeId::id<T>();

169 const auto ops = helios::engine::ecs::ComponentOpsRegistry::ops(typeId);

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

171

172 if (active && ops.onActivate) {

173 ops.onActivate(raw);

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

175 ops.onDeactivate(raw);

176 }

177

178 return *cmp;

179 }

References helios::engine::core::data::ComponentTypeId::id, helios::engine::ecs::ComponentOpsRegistry::ops and raw.

Referenced by getOrAdd.

componentTypeIds()

std::generator< helios::engine::core::data::ComponentTypeId > helios::engine::ecs::GameObject::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 120 of file GameObject.ixx.

120 componentTypeIds() const {

121 return entityManager_->componentTypeIds(entityHandle_);

122 }

Referenced by helios::engine::runtime::spawn::behavior::initializers::DelayedComponentEnablerInitializer< ComponentTypes >::initialize, onAcquire, onRelease and setActive.

disableComponent()

void helios::engine::ecs::GameObject::disableComponent (const helios::engine::core::data::ComponentTypeId typeId)

inline

Disables a specific component by type ID.

Parameters

typeId

The component type identifier.

Definition at line 283 of file GameObject.ixx.

283 void disableComponent(const helios::engine::core::data::ComponentTypeId typeId) {

284 entityManager_->disable(entityHandle_, typeId);

285 }

Referenced by helios::engine::mechanics::lifecycle::components::DelayedComponentEnabler::defer.

enableComponent()

void helios::engine::ecs::GameObject::enableComponent (const helios::engine::core::data::ComponentTypeId typeId)

inline

Enables a specific component by type ID.

Parameters

typeId

The component type identifier.

Definition at line 274 of file GameObject.ixx.

274 void enableComponent(const helios::engine::core::data::ComponentTypeId typeId) {

275 entityManager_->enable(entityHandle_, typeId);

276 }

entityHandle()

helios::engine::ecs::EntityHandle helios::engine::ecs::GameObject::entityHandle ()

inline nodiscard noexcept

Returns the underlying entity handle.

Returns

The EntityHandle for this GameObject.

Definition at line 129 of file GameObject.ixx.

129 [[nodiscard]] helios::engine::ecs::EntityHandle entityHandle() noexcept {

130 return entityHandle_;

131 }

Referenced by helios::engine::modules::ui::widgets::components::MenuComponent::addMenuItem, helios::engine::runtime::world::GameWorld::clone, GameObject, helios::engine::modules::ui::widgets::components::MenuComponent::insert and helios::engine::modules::physics::collision::systems::GridCollisionDetectionSystem::solveCell.

entityHandle()

helios::engine::ecs::EntityHandle helios::engine::ecs::GameObject::entityHandle ()

inline nodiscard noexcept

Returns the underlying entity handle (const).

Returns

The EntityHandle for this GameObject.

Definition at line 138 of file GameObject.ixx.

138 [[nodiscard]] helios::engine::ecs::EntityHandle entityHandle() const noexcept {

139 return entityHandle_;

140 }

get()

template <typename T>

T * helios::engine::ecs::GameObject::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 230 of file GameObject.ixx.

230 T* get() {

231 return entityManager_->get<T>(entityHandle_);

232 }

Referenced by helios::engine::runtime::spawn::behavior::initializers::DelayedComponentEnablerInitializer< ComponentTypes >::initialize, helios::engine::runtime::spawn::behavior::initializers::EmitterInitializer::initialize and helios::engine::runtime::spawn::behavior::initializers::RandomDirectionInitializer::initialize.

get()

template <typename T>

const T * helios::engine::ecs::GameObject::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 242 of file GameObject.ixx.

242 const T* get() const {

243 return entityManager_->get<T>(entityHandle_);

244 }

getOrAdd()

template <typename T, typename ... Args>

T & helios::engine::ecs::GameObject::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 192 of file GameObject.ixx.

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

193 if (entityManager_->has<T>(entityHandle_)) {

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

195 }

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

197 }

Reference add.

has()

template <typename T>

bool helios::engine::ecs::GameObject::has ()

inline

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 254 of file GameObject.ixx.

254 bool has() {

255 return entityManager_->has<T>(entityHandle_);

256 }

Referenced by helios::engine::mechanics::lifecycle::components::DelayedComponentEnabler::defer.

has()

bool helios::engine::ecs::GameObject::has (helios::engine::core::data::ComponentTypeId typeId)

inline

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 265 of file GameObject.ixx.

265 bool has(helios::engine::core::data::ComponentTypeId typeId) {

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

267 }

isActive()

bool helios::engine::ecs::GameObject::isActive ()

inline nodiscard

Returns whether this GameObject is active.

Returns

True if the entity has the Active tag component.

Definition at line 351 of file GameObject.ixx.

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

352 return entityManager_->has<helios::engine::mechanics::lifecycle::components::Active>(entityHandle_);

353 }

Referenced by setActive.

onAcquire()

void helios::engine::ecs::GameObject::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 378 of file GameObject.ixx.

378 void onAcquire() {

379 for (auto typeId : componentTypeIds()) {

380 const auto ops = helios::engine::ecs::ComponentOpsRegistry::ops(typeId);

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

382

383 if (ops.onAcquire) {

384 ops.onAcquire(raw);

385 }

386 }

387 }

References componentTypeIds, helios::engine::ecs::ComponentOpsRegistry::ops and raw.

onRelease()

void helios::engine::ecs::GameObject::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 361 of file GameObject.ixx.

361 void onRelease() {

362 for (auto typeId : componentTypeIds()) {

363 const auto ops = helios::engine::ecs::ComponentOpsRegistry::ops(typeId);

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

365

366 if (ops.onRelease) {

367 ops.onRelease(raw);

368 }

369 }

370 }

References componentTypeIds, helios::engine::ecs::ComponentOpsRegistry::ops and raw.

raw()

void * helios::engine::ecs::GameObject::raw (const helios::engine::core::data::ComponentTypeId 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 218 of file GameObject.ixx.

218 void* raw(const helios::engine::core::data::ComponentTypeId typeId) {

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

220 }

Referenced by add, onAcquire, onRelease and setActive.

remove()

template <typename T>

bool helios::engine::ecs::GameObject::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 207 of file GameObject.ixx.

207 bool remove() {

208 return entityManager_->remove<T>(entityHandle_);

209 }

setActive()

void helios::engine::ecs::GameObject::setActive (const bool active)

inline

Sets the activation state of this GameObject.

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

See Also

HierarchyPropagationSystem

Definition at line 309 of file GameObject.ixx.

309 void setActive(const bool active) {

310

311 bool isActive = entityManager_->has<helios::engine::mechanics::lifecycle::components::Active>(entityHandle_);

312 bool isInActive = entityManager_->has<helios::engine::mechanics::lifecycle::components::Inactive>(entityHandle_);

313

314 if (!isActive && active) {

315 auto* hc = entityManager_->get<helios::engine::ecs::components::HierarchyComponent>(entityHandle_);

316 if (hc) {

317 hc->markDirty();

318 }

319

320 entityManager_->remove<helios::engine::mechanics::lifecycle::components::Inactive>(entityHandle_);

321 entityManager_->emplaceOrGet<helios::engine::mechanics::lifecycle::components::Active>(entityHandle_);

322 }

323

324 if (!isInActive && !active) {

325 auto* hc = entityManager_->get<helios::engine::ecs::components::HierarchyComponent>(entityHandle_);

326 if (hc) {

327 hc->markDirty();

328 }

329

330 entityManager_->emplaceOrGet<helios::engine::mechanics::lifecycle::components::Inactive>(entityHandle_);

331 entityManager_->remove<helios::engine::mechanics::lifecycle::components::Active>(entityHandle_);

332 }

333

334 for (auto typeId : componentTypeIds()) {

335 const auto ops = helios::engine::ecs::ComponentOpsRegistry::ops(typeId);

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

337

338 if (active && ops.onActivate) {

339 ops.onActivate(raw);

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

341 ops.onDeactivate(raw);

342 }

343 }

344 }

References componentTypeIds, isActive, helios::engine::ecs::ComponentOpsRegistry::ops and raw.

Private Member Attributes

entityHandle_

helios::engine::ecs::EntityHandle helios::engine::ecs::GameObject::entityHandle_ {0,0}

The underlying entity identifier.

Definition at line 90 of file GameObject.ixx.

90 helios::engine::ecs::EntityHandle entityHandle_{0,0};

entityManager_

helios::engine::ecs::EntityManager* helios::engine::ecs::GameObject::entityManager_

Non-owning pointer to the EntityManager.

Definition at line 95 of file GameObject.ixx.

95 helios::engine::ecs::EntityManager* entityManager_;

---

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

• GameObject.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.