GameObject Class

Container for components that represents an entity in the game world. More...

Declaration

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

Public Constructors Index

	GameObject ()
	Constructs a new GameObject with a unique Guid. More...
	GameObject (bool isActive)
	Constructs a new GameObject with a specified active state. More...

Public Destructor Index

	~GameObject ()=default
	Virtual destructor for proper polymorphic cleanup. More...

Public Member Functions Index

template <typename T, typename... Args>
T &	add (Args &&... args)
	Adds a new component of type T to the GameObject. More...
helios::engine::ecs::Component *	getOrAdd (std::unique_ptr< helios::engine::ecs::Component > component)
	Adds a pre-constructed component if no component of the same type exists. More...
template <typename T, typename... Args>
auto	getOrAdd (Args &&... args) -> std::remove_cvref_t< T > &
	Retrieves an existing component of type T, or creates and adds it if not present. More...
template <typename T>
auto	get () const -> std::remove_cvref_t< T > *
	Retrieves a component of type T. More...
bool	has (const std::type_index idx) const noexcept
	Checks if a component with the given type index exists. More...
template <typename T>
bool	has () const
	Checks if the GameObject has a component of type T. More...
template <typename T>
bool	hasEnabledComponent () const
	Checks if the GameObject has a component of type T and returns true if this component is enabled. More...
template <typename T>
bool	hasDisabledComponent () const
	Checks if the GameObject has a component of type T and returns true if this component is disabled. More...
void	update (helios::engine::runtime::world::UpdateContext &updateContext)
	Updates all updatable components attached to this GameObject. More...
const helios::util::Guid &	guid () const noexcept
	Returns the unique identifier for this GameObject. More...
bool	isActive () const noexcept
	Checks if this GameObject is currently active. More...
std::vector< std::unique_ptr< helios::engine::ecs::Component > > &	components () noexcept
	Returns a reference to all attached components. More...
void	setActive (bool active) noexcept
	Sets the active state of this GameObject. More...
void	onAcquire ()
	Called when this GameObject is acquired from a pool. More...
void	onRelease ()
	Called when this GameObject is released back to a pool. More...
void	finalizeAttach (helios::engine::ecs::Component *component=nullptr)
	Finalizes attachment of components by calling lifecycle callbacks. More...

Protected Member Attributes Index

helios::util::Guid	guid_
	Unique identifier for this GameObject. More...
std::vector< std::unique_ptr< Component > >	components_
	List of components attached to this GameObject. More...
std::unordered_map< std::type_index, helios::engine::ecs::Component * >	componentIndex_
	Type-indexed map for O(1) amortized component lookups. More...
std::vector< Updatable * >	updatables_
	Cached list of components that implement the Updatable interface. More...
bool	isActive_ = true
	Active state flag for this GameObject. More...

Description

Container for components that represents an entity in the game world.

A GameObject is the fundamental entity type in helios. It serves as a container for Component instances that define its behavior and data. Each GameObject has a unique Guid for identification and lookup within the GameWorld.

## Component Management

Components are added via `add<T>()` and retrieved via `get<T>()`. The GameObject uses a type-indexed map (`std::unordered_map<std::type_index, Component*>`) for **O(1) amortized** component lookup by type.

```cpp auto entity = std::make_unique<GameObject>(); entity->add<SceneNodeComponent>(sceneNode); entity->add<Move2DComponent>();

auto* move = entity->get<Move2DComponent>(); // O(1) lookup ```

## Active State

Each GameObject has an `isActive()` flag that controls participation in the game loop:

| State | Behavior | |-------|----------| | `isActive() == true` | Processed by systems, rendered, collides | | `isActive() == false` | Skipped by systems, exists but dormant |

When the active state changes, `onActivate()` or `onDeactivate()` is called on all attached components.

## Lifecycle Callbacks

Components receive lifecycle notifications:

• `onAttach()` — Called when a component is added to the GameObject
• `onActivate()` / `onDeactivate()` — Called when active state changes
• `onAcquire()` / `onRelease()` — Called when acquired from/released to a pool

## Ownership

GameObjects are typically owned by a GameWorld via `std::unique_ptr`. The GameWorld provides lookup by Guid with amortized O(1) complexity.

See Also

Component

See Also

GameWorld

See Also

GameObjectFilter

Definition at line 73 of file GameObject.ixx.

Public Constructors

GameObject()

helios::engine::ecs::GameObject::GameObject ()

inline

Constructs a new GameObject with a unique Guid.

The Guid is automatically generated and remains constant for the lifetime of this object.

Definition at line 125 of file GameObject.ixx.

125 GameObject() : guid_(helios::util::Guid::generate()) {};

Reference guid_.

GameObject()

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

inline explicit

Constructs a new GameObject with a specified active state.

Parameters

isActive

Initial active state. If false, the object starts inactive.

Definition at line 132 of file GameObject.ixx.

132 explicit GameObject(bool isActive) : isActive_(isActive), guid_(helios::util::Guid::generate()) {};

References guid_, isActive and isActive_.

Public Destructor

~GameObject()

virtual helios::engine::ecs::GameObject::~GameObject ()

virtual default

Virtual destructor for proper polymorphic cleanup.

Definition at line 137 of file GameObject.ixx.

Public Member Functions

add()

template <typename T, typename... Args>

T & helios::engine::ecs::GameObject::add (Args &&... args)

inline

Adds a new component of type T to the GameObject.

The component is created, attached to this GameObject (onAttach is called), and if it implements Updatable, it is added to the update list. Normalizes T and uses the type-indexed componentIndex_ for O(1) lookup complexity.

Template Parameters

T	The type of component to add. Must derive from Component.
Args	Argument types for the component's constructor.

Parameters

args	Arguments forwarded to the component's constructor.

Returns

Reference to the newly created component.

Definition at line 153 of file GameObject.ixx.

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

154 using U = std::remove_cvref_t<T>;

155

156 assert(!has<U>() && "Cannot add, Component is already existing.");

157

158 auto component_ptr = std::make_unique<U>(std::forward<Args>(args)...);

159 U* raw_component_ptr = component_ptr.get();

160

161 if constexpr (std::derived_from<U, helios::engine::ecs::Updatable>) {

162 updatables_.push_back(raw_component_ptr);

163 }

164 components_.push_back(std::move(component_ptr));

165 componentIndex_[typeid(U)] = raw_component_ptr;

166

167 // make sure component is registered before onAttach is called,

168 // in case onAttach implementations query the gameObject for **this** component

169 // Use raw_component_ptr instead of component_ptr since ownership was moved above

170 finalizeAttach(raw_component_ptr);

171

172 return *raw_component_ptr;

173 }

References componentIndex_, components_, finalizeAttach, has and updatables_.

Referenced by getOrAdd.

components()

std::vector< std::unique_ptr< helios::engine::ecs::Component > > & helios::engine::ecs::GameObject::components ()

inline nodiscard noexcept

Returns a reference to all attached components.

Provides direct access to the component container. Useful for iteration over all components (e.g., during cloning).

Returns

Reference to the vector of component unique_ptrs.

warning

Modifying the vector directly bypasses lifecycle callbacks. Use add() and remove() methods for proper component management.

Definition at line 374 of file GameObject.ixx.

374 [[nodiscard]] std::vector<std::unique_ptr<helios::engine::ecs::Component>>& components() noexcept {

375 return components_;

376 }

Reference components_.

Referenced by helios::engine::runtime::world::GameWorld::clone.

finalizeAttach()

void helios::engine::ecs::GameObject::finalizeAttach (helios::engine::ecs::Component * component=nullptr)

inline

Finalizes attachment of components by calling lifecycle callbacks.

If a specific component is passed, only that component is finalized. Otherwise, all unattached components are finalized. Calls `onAttach()` followed by `onActivate()` or `onDeactivate()` based on the GameObject's active state.

Parameters

component

Optional pointer to a specific component to finalize. If nullptr, all components are processed.

Definition at line 447 of file GameObject.ixx.

447 void finalizeAttach(helios::engine::ecs::Component* component = nullptr) {

448

449 // call attach on all components

450 if (component != nullptr) {

451 if (component->isAttached()) {

452 return;

453 }

454 component->onAttach(this);

455

456 if (isActive_) {

457 component->onActivate();

458 } else {

459 component->onDeactivate();

460 }

461

462 return;

463 }

464

465 // call attach on all components

466 for (auto [idx, component] : componentIndex_) {

467 if (component->isAttached()) {

468 return;

469 }

470 component->onAttach(this);

471

472 if (isActive_) {

473 component->onActivate();

474 } else {

475 component->onDeactivate();

476 }

477 }

478

479 }

References componentIndex_ and isActive_.

Referenced by add and getOrAdd.

get()

template <typename T>

std::remove_cvref_t< T > * helios::engine::ecs::GameObject::get ()

inline

Retrieves a component of type T.

Normalizes T and uses the type-indexed componentIndex_ for O(1) lookup complexity.

Template Parameters

T	The type of component to retrieve.

Returns

Pointer to the component if found, nullptr otherwise.

Definition at line 250 of file GameObject.ixx.

250 std::remove_cvref_t<T>* get() const {

251 // remove ref (if provided) and return type refered to by T

252 using U = std::remove_cvref_t<T>;

253 auto it = componentIndex_.find(typeid(U));

254

255 if (it == componentIndex_.end()) {

256 return nullptr;

257 }

258

259 return static_cast<U*>(it->second);

260 }

Reference componentIndex_.

Referenced by getOrAdd, hasDisabledComponent and hasEnabledComponent.

getOrAdd()

helios::engine::ecs::Component * helios::engine::ecs::GameObject::getOrAdd (std::unique_ptr< helios::engine::ecs::Component > component)

inline

Adds a pre-constructed component if no component of the same type exists.

If a component of the same runtime type already exists, returns the existing component and does not take ownership of the passed pointer. Otherwise, takes ownership and attaches the component.

Uses the type-indexed componentIndex_ for O(1) amortized lookup complexity.

Parameters

component

Unique pointer to the component to add. Ownership is transferred only if no component of the same type exists.

Returns

Pointer to the existing or newly added component, or nullptr if the input was nullptr.

Definition at line 190 of file GameObject.ixx.

190 helios::engine::ecs::Component* getOrAdd(

191 std::unique_ptr<helios::engine::ecs::Component> component) {

192

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

194

195 if (!component) {

196 return nullptr;

197 }

198

199 auto* raw_component_ptr = component.get();

200 const std::type_index idx = typeid(*raw_component_ptr);

201

202 if (has(typeid(*raw_component_ptr))) {

203 return componentIndex_[idx];

204 }

205

206 components_.push_back(std::move(component));

207 componentIndex_[idx] = raw_component_ptr;

208

209 // make sure component is registered before onAttach is called,

210 // in case onAttach implementations query the gameObject for **this** component

211 // Use raw_component_ptr instead of component_ptr since ownership was moved above

212 finalizeAttach(raw_component_ptr);

213

214 return raw_component_ptr;

215 }

References componentIndex_, components_, finalizeAttach and has.

getOrAdd()

template <typename T, typename... Args>

std::remove_cvref_t< T > & helios::engine::ecs::GameObject::getOrAdd (Args &&... args)

inline

Retrieves an existing component of type T, or creates and adds it if not present.

Normalizes T and uses the type-indexed componentIndex_ for O(1) lookup complexity. This is a convenience method that combines get() and add(). If the component already exists, the arguments are ignored.

Template Parameters

T	The type of component to retrieve or add. Must derive from Component.
Args	Argument types for the component's constructor.

Parameters

args	Arguments forwarded to the component's constructor if it needs to be created.

Returns

Reference to the existing or newly created component.

Definition at line 230 of file GameObject.ixx.

230 std::remove_cvref_t<T>& getOrAdd(Args&&... args) {

231

232 using U = std::remove_cvref_t<T>;

233 if (auto* cmp = get<U>()) {

234 return *cmp;

235 }

236

237 return add<U>(std::forward<Args>(args)...);

238 }

References add and get.

guid()

const helios::util::Guid & helios::engine::ecs::GameObject::guid ()

inline nodiscard noexcept

Returns the unique identifier for this GameObject.

Returns

Const reference to the Guid, valid for the lifetime of this object.

Definition at line 348 of file GameObject.ixx.

348 [[nodiscard]] const helios::util::Guid& guid() const noexcept {

349 return guid_;

350 };

Reference guid_.

Referenced by helios::engine::runtime::factory::GameObjectFactory::fillPool and helios::engine::modules::physics::collision::systems::GridCollisionDetectionSystem::solveCell.

has()

bool helios::engine::ecs::GameObject::has (const std::type_index idx)

inline nodiscard noexcept

Checks if a component with the given type index exists.

Uses the type-indexed componentIndex_ for O(1) amortized lookup.

Parameters

idx	The type_index of the component type to check for.

Returns

True if the component exists, false otherwise.

Definition at line 271 of file GameObject.ixx.

271 [[nodiscard]] bool has(const std::type_index idx) const noexcept {

272 return componentIndex_.contains(idx);

273 }

Reference componentIndex_.

Referenced by add.

has()

template <typename T>

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

inline nodiscard

Checks if the GameObject has a component of type T.

Normalizes T and uses the type-indexed componentIndex_ for O(1) lookup complexity.

Template Parameters

T	The type of component to check for.

Returns

true if the component exists, false otherwise.

Definition at line 286 of file GameObject.ixx.

286 [[nodiscard]] bool has() const {

287 using U = std::remove_cvref_t<T>;

288 return componentIndex_.contains(typeid(U));

289 }

Reference componentIndex_.

Referenced by getOrAdd.

hasDisabledComponent()

template <typename T>

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

inline nodiscard

Checks if the GameObject has a component of type T and returns true if this component is disabled.

Template Parameters

T	The type of component to check for existence and if it's disabled.

Returns

true if the component exists and is disabled, false otherwise.

Definition at line 320 of file GameObject.ixx.

320 [[nodiscard]] bool hasDisabledComponent() const {

321 using U = std::remove_cvref_t<T>;

322 U* cmp = get<T>();

323

324 if (!cmp) {

325 return false;

326 }

327

328 return cmp->isDisabled();

329 }

Reference get.

hasEnabledComponent()

template <typename T>

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

inline nodiscard

Checks if the GameObject has a component of type T and returns true if this component is enabled.

Template Parameters

T	The type of component to check for existence and if it's enabled.

Returns

true if the component exists and is enabled, false otherwise.

Definition at line 300 of file GameObject.ixx.

300 [[nodiscard]] bool hasEnabledComponent() const {

301 using U = std::remove_cvref_t<T>;

302 U* cmp = get<T>();

303

304 if (!cmp) {

305 return false;

306 }

307

308 return cmp->isEnabled();

309 }

Reference get.

isActive()

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

inline nodiscard noexcept

Checks if this GameObject is currently active.

Returns

True if the GameObject is active, false otherwise.

info

Inactive GameObjects are typically skipped during updates and rendering.

Definition at line 359 of file GameObject.ixx.

359 [[nodiscard]] bool isActive() const noexcept {

360 return isActive_;

361 }

Reference isActive_.

Referenced by GameObject.

onAcquire()

void helios::engine::ecs::GameObject::onAcquire ()

inline

Called when this GameObject is acquired from a pool.

Notifies all attached components by calling their `onAcquire()` method. Used by the pool system to reset or initialize component state before reuse.

See Also

GameObjectPool

See Also

Component::onAcquire

Definition at line 416 of file GameObject.ixx.

416 void onAcquire() {

417 for (auto [idx, component] : componentIndex_) {

418 component->onAcquire();

419 }

420 }

Reference componentIndex_.

onRelease()

void helios::engine::ecs::GameObject::onRelease ()

inline

Called when this GameObject is released back to a pool.

Notifies all attached components by calling their `onRelease()` method. Used by the pool system to clean up component state before pooling.

See Also

GameObjectPool

See Also

Component::onRelease

Definition at line 431 of file GameObject.ixx.

431 void onRelease() {

432 for (auto [idx, component] : componentIndex_) {

433 component->onRelease();

434 }

435 }

Reference componentIndex_.

setActive()

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

inline noexcept

Sets the active state of this GameObject.

When the active state changes, this method notifies all attached components by calling onActivate() or onDeactivate() accordingly. If the new state equals the current state, no action is taken. (

See Also

add())

Parameters

active

The new active state.

Definition at line 387 of file GameObject.ixx.

387 void setActive(bool active) noexcept {

388 if (isActive_ == active) {

389 return;

390 }

391

392 isActive_ = active;

393

394 if (isActive_) {

395 for (auto& it: components_) {

396 it->onActivate();

397 }

398 } else {

399 for (auto& it: components_) {

400 it->onDeactivate();

401 }

402 }

403

404

405 }

References components_ and isActive_.

Referenced by helios::engine::runtime::factory::GameObjectFactory::fillPool and helios::engine::runtime::pooling::GameObjectPoolFacade::release.

update()

void helios::engine::ecs::GameObject::update (helios::engine::runtime::world::UpdateContext & updateContext)

inline

Updates all updatable components attached to this GameObject.

Parameters

updateContext

Context containing frame delta time and other update data.

Definition at line 337 of file GameObject.ixx.

337 void update(helios::engine::runtime::world::UpdateContext& updateContext) {

338 for (auto* updatable: updatables_) {

339 updatable->update(updateContext);

340 }

341 }

Reference updatables_.

Protected Member Attributes

componentIndex_

std::unordered_map<std::type_index, helios::engine::ecs::Component*> helios::engine::ecs::GameObject::componentIndex_

protected

Type-indexed map for O(1) amortized component lookups.

Maps `std::type_index` to raw component pointers for efficient retrieval by type. The map is updated when components are added. Worst-case is O(n) due to hash collisions, but typical lookups are O(1).

Definition at line 99 of file GameObject.ixx.

99 std::unordered_map<std::type_index, helios::engine::ecs::Component*> componentIndex_;

Referenced by add, finalizeAttach, get, getOrAdd, has, has, onAcquire and onRelease.

components_

std::vector<std::unique_ptr<Component> > helios::engine::ecs::GameObject::components_

protected

List of components attached to this GameObject.

Components are owned by the GameObject via std::unique_ptr.

Definition at line 90 of file GameObject.ixx.

90 std::vector<std::unique_ptr<Component>> components_;

Referenced by add, components, getOrAdd and setActive.

guid_

helios::util::Guid helios::engine::ecs::GameObject::guid_

protected

Unique identifier for this GameObject.

Generated during construction and remains constant for the lifetime of the object. Used for lookups in GameWorld and command targeting.

Definition at line 83 of file GameObject.ixx.

83 helios::util::Guid guid_;

Referenced by GameObject, GameObject and guid.

isActive_

bool helios::engine::ecs::GameObject::isActive_ = true

protected

Active state flag for this GameObject.

Inactive GameObjects are skipped during iteration and updates. When the state changes, onActivate() or onDeactivate() is called on all components.

Definition at line 115 of file GameObject.ixx.

115 bool isActive_ = true;

Referenced by finalizeAttach, GameObject, isActive and setActive.

updatables_

std::vector<Updatable*> helios::engine::ecs::GameObject::updatables_

protected

Cached list of components that implement the Updatable interface.

This list is maintained for efficient iteration during the update phase. The pointers are non-owning references to elements within components_.

Definition at line 107 of file GameObject.ixx.

107 std::vector<Updatable*> updatables_;

Referenced by add and update.

---

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

• GameObject.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.