EntityManager Class

Manages entities and their associated components. More...

Declaration

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

Public Constructors Index

	EntityManager (EntityRegistry &registry, size_t capacity=ENTITY_MANAGER_DEFAULT_CAPACITY)
	Constructs an EntityManager with the given registry. More...

Public Member Functions Index

EntityHandle	create ()
	Creates a new entity. More...
bool	isValid (const EntityHandle handle) const noexcept
	Checks if an entity handle is valid. More...
bool	isValid (const EntityId entityId) const noexcept
	Checks if an entity ID is valid. More...
bool	destroy (const EntityHandle &handle)
	Destroys an entity and invalidates its handle. More...
template <typename T>
T *	get (const EntityHandle handle) const
	Retrieves a component for the given entity. More...
template <typename T>
auto	getSparseSet () -> SparseSet< T > *
	Returns the SparseSet for a component type. More...
template <typename T>
auto	getSparseSet () const -> const SparseSet< T > *
	Returns the SparseSet for a component type (const). More...
template <typename T>
bool	has (const EntityHandle handle) const
	Checks whether an entity has a specific component. More...
bool	has (const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId) const
	Checks whether an entity has a component by type ID. More...
void	enable (const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId) const
	Enables a component by type ID. More...
void	disable (const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId) const
	Disables a component by type ID. More...
void	enable (const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId, const bool enable) const
	Enables or disables a component by type ID. More...
template <typename T, typename... Args>
T *	emplace (const EntityHandle handle, Args &&...args)
	Constructs and attaches a component to an entity. More...
template <typename T, typename... Args>
T *	emplaceOrGet (const EntityHandle handle, Args &&...args)
	Returns existing component or creates a new one. More...
template <typename T>
bool	remove (const EntityHandle &handle)
	Removes a specific component from an entity. More...
std::generator< helios::engine::ecs::types::ComponentTypeId >	componentTypeIds (const EntityHandle handle) const
	Returns a generator over all component type IDs attached to an entity. More...
void	clone (const EntityHandle source, const EntityHandle target)
	Clones all components from source entity to target entity. More...
void *	raw (const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId) const
	Returns raw void pointer to a component. More...
EntityHandle	handle (const EntityId entityId) const
	Reconstructs an EntityHandle from an EntityId. More...

Private Member Attributes Index

std::vector< std::unique_ptr< SparseSetBase > >	components_
	Component storage indexed by type ID. More...
EntityRegistry &	registry_
	Reference to the entity registry for handle management. More...
const size_t	capacity_
	initial capacity for the underlying sparsesets. More...

Description

Manages entities and their associated components.

`EntityManager` provides a unified interface for creating entities and attaching/retrieving components. It delegates handle management to an `EntityRegistry` and stores component data in type-specific `SparseSet` containers.

## Responsibilities

• **Entity Creation:** Delegates to `EntityRegistry` for handle allocation.
• **Entity Destruction:** Removes all components and invalidates the handle.
• **Component Storage:** Maintains a vector of `SparseSet` instances, one per component type, indexed by `TypeIndexer`.

## Usage

```cpp EntityRegistry registry; EntityManager manager(registry);

auto entity = manager.create(); auto* transform = manager.emplace<TransformComponent>(entity, glm::vec3{0.0f});

if (manager.has<TransformComponent>(entity)) { auto* t = manager.get<TransformComponent>(entity); }

manager.remove<TransformComponent>(entity); // Remove single component manager.destroy(entity); // Destroy entity and all components ```

See Also

EntityRegistry

See Also

SparseSet

See Also

EntityHandle

Definition at line 67 of file EntityManager.ixx.

Public Constructors

EntityManager()

helios::engine::ecs::EntityManager::EntityManager (EntityRegistry & registry, size_t capacity=ENTITY_MANAGER_DEFAULT_CAPACITY)

inline explicit

Constructs an EntityManager with the given registry.

Parameters

registry

The EntityRegistry used for handle allocation and validation.

Definition at line 92 of file EntityManager.ixx.

92 explicit EntityManager(EntityRegistry& registry, size_t capacity = ENTITY_MANAGER_DEFAULT_CAPACITY)

93 : registry_(registry), capacity_(capacity) {}

Public Member Functions

clone()

void helios::engine::ecs::EntityManager::clone (const EntityHandle source, const EntityHandle target)

inline

Clones all components from source entity to target entity.

Iterates through all components on the source and copies them to the target using the registered clone function. Skips components that already exist on the target.

Parameters

source	The entity to clone from.
target	The entity to clone to.

Definition at line 467 of file EntityManager.ixx.

467 void clone(const EntityHandle source, const EntityHandle target) {

468

469 if (!registry_.isValid(source)) {

470 return;

471 }

472

473 for (auto typeId : componentTypeIds(source)) {

474

475 if (!has(target, typeId)) {

476

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

478

479 const void* sourceCmp = raw(source, typeId);

480

481 if (sourceCmp && ops.clone) {

482 ops.clone(this, sourceCmp, &target);

483 }

484

485 }

486

487 }

488 }

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

componentTypeIds()

std::generator< helios::engine::ecs::types::ComponentTypeId > helios::engine::ecs::EntityManager::componentTypeIds (const EntityHandle handle)

inline

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

Parameters

handle

The entity to query.

Returns

Generator yielding ComponentTypeId for each attached component.

Definition at line 445 of file EntityManager.ixx.

445 componentTypeIds(const EntityHandle handle) const {

446 if (!registry_.isValid(handle)) {

447 co_return;

448 }

449

450 for (size_t i = 0; i < components_.size(); i++) {

451 if (components_[i] && components_[i]->contains(handle.entityId)) {

452 co_yield ComponentTypeId{i};

453 }

454 }

455 }

Reference handle.

Referenced by clone.

create()

EntityHandle helios::engine::ecs::EntityManager::create ()

inline nodiscard

Creates a new entity.

Delegates to the underlying `EntityRegistry` to allocate a new handle.

Returns

A valid `EntityHandle` for the newly created entity.

See Also

EntityRegistry::create

Definition at line 104 of file EntityManager.ixx.

104 [[nodiscard]] EntityHandle create() {

105 return registry_.create();

106 }

destroy()

bool helios::engine::ecs::EntityManager::destroy (const EntityHandle & handle)

inline nodiscard

Destroys an entity and invalidates its handle.

Increments the entity's version in the registry, making all existing handles to this entity stale. Does not automatically remove components from storage.

Parameters

handle

The handle of the entity to destroy.

Returns

`true` if the entity was destroyed, `false` if already invalid.

Definition at line 141 of file EntityManager.ixx.

141 [[nodiscard]] bool destroy(const EntityHandle& handle) {

142

143 if (!registry_.isValid(handle)) {

144 return false;

145 }

146

147 for (size_t i = 0; i < components_.size(); i++) {

148

149 if (!components_[i]) {

150 continue;

151 }

152 const auto typeId = ComponentTypeId{i};

153 if (void* rawCmp = raw(handle, typeId)) {

154 if (const auto& ops = helios::engine::ecs::ComponentOpsRegistry::ops(typeId); ops.onRemove) {

155 ops.onRemove(rawCmp);

156 }

157 }

158

159 components_[i]->remove(handle.entityId);

160 }

161

162 registry_.destroy(handle);

163

164 return true;

165 }

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

disable()

void helios::engine::ecs::EntityManager::disable (const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId)

inline

Disables a component by type ID.

Calls the component's `disable()` method if registered.

Parameters

handle	The entity whose component to disable.
typeId	The component type identifier.

Definition at line 296 of file EntityManager.ixx.

296 void disable(const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId) const {

297 enable(handle, typeId, false);

298 }

References enable and handle.

emplace()

template <typename T, typename... Args>

T * helios::engine::ecs::EntityManager::emplace (const EntityHandle handle, Args &&... args)

inline

Constructs and attaches a component to an entity.

If the component type has not been registered yet, a new `SparseSet` is created. The component is constructed in-place with the provided arguments. Return nullptre if the component already exists or if the handle was invalid.

Template Parameters

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

Parameters

handle	The entity to attach the component to.
args	Arguments forwarded to the component constructor.

Returns

Pointer to the newly created component, or `nullptr` if the handle is invalid.

Definition at line 344 of file EntityManager.ixx.

344 T* emplace(const EntityHandle handle, Args&& ...args) {

345

346 if (!registry_.isValid(handle)) {

347 return nullptr;

348 }

349

350 const auto entityId = handle.entityId;

351

352 const auto typeId = ComponentTypeId::id<T>().value();

353

354 if (typeId >= components_.size()) {

355 components_.resize(typeId + 1);

356 }

357

358 if (!components_[typeId]) {

359 components_[typeId] = std::make_unique<SparseSet<T>>(capacity_);

360 }

361

362 auto* sparseSet = static_cast<SparseSet<T>*>(components_[typeId].get());

363

364 if (sparseSet->contains(entityId)) {

365 return nullptr;

366 }

367

368 return sparseSet->emplace(entityId, std::forward<Args>(args)...);

369 }

References handle, helios::engine::ecs::types::ComponentTypeId::id and helios::engine::ecs::types::ComponentTypeId::value.

Referenced by emplaceOrGet.

emplaceOrGet()

template <typename T, typename... Args>

T * helios::engine::ecs::EntityManager::emplaceOrGet (const EntityHandle handle, Args &&... args)

inline

Returns existing component or creates a new one.

Template Parameters

T	The component type.
Args	Constructor argument types.

Parameters

handle	The entity.
args	Arguments forwarded to the constructor if creating.

Returns

Pointer to the existing or newly created component, or `nullptr` if the handle is invalid.

Definition at line 384 of file EntityManager.ixx.

384 T* emplaceOrGet(const EntityHandle handle, Args&& ...args) {

385

386 if (!registry_.isValid(handle)) {

387 return nullptr;

388 }

389

390 auto* raw = emplace<T>(handle, std::forward<Args>(args)...);

391

392 if (!raw) {

393 return get<T>(handle);

394 }

395

396 return nullptr;

397 }

References emplace, get, handle and raw.

enable()

void helios::engine::ecs::EntityManager::enable (const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId)

inline

Enables a component by type ID.

Calls the component's `enable()` method if registered.

Parameters

handle	The entity whose component to enable.
typeId	The component type identifier.

Definition at line 284 of file EntityManager.ixx.

284 void enable(const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId) const {

285 enable(handle, typeId, true);

286 }

References enable and handle.

Referenced by disable, enable and enable.

enable()

void helios::engine::ecs::EntityManager::enable (const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId, const bool enable)

inline

Enables or disables a component by type ID.

Parameters

handle	The entity whose component to modify.
typeId	The component type identifier.
enable	`true` to enable, `false` to disable.

Definition at line 307 of file EntityManager.ixx.

307 void enable(const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId, const bool enable) const {

308

309 if (!has(handle, typeId)) {

310 return;

311 }

312

313 void* rawCmp = raw(handle, typeId);

314 if (!rawCmp) {

315 return;

316 }

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

318

319 if (enable && ops.enable) {

320 ops.enable(rawCmp);

321 } else if (!enable && ops.disable) {

322 ops.disable(rawCmp);

323 }

324 }

References enable, handle, has, helios::engine::ecs::ComponentOpsRegistry::ops and raw.

get()

template <typename T>

T * helios::engine::ecs::EntityManager::get (const EntityHandle handle)

inline nodiscard

Retrieves a component for the given entity.

Template Parameters

T	The component type to retrieve.

Parameters

handle

The entity whose component to retrieve.

Returns

Pointer to the component, or `nullptr` if the entity is invalid or does not have the requested component.

Definition at line 178 of file EntityManager.ixx.

178 [[nodiscard]] T* get(const EntityHandle handle) const {

179 if (!has<T>(handle)) {

180 return nullptr;

181 }

182

183 const auto entityId = handle.entityId;

184 const auto typeId = ComponentTypeId::id<T>().value();

185

186 auto* sparseSet = static_cast<SparseSet<T>*>(components_[typeId].get());

187

188 return sparseSet->get(entityId);

189 }

References handle, has, helios::engine::ecs::types::ComponentTypeId::id and helios::engine::ecs::types::ComponentTypeId::value.

Referenced by emplaceOrGet.

getSparseSet()

template <typename T>

SparseSet< T > * helios::engine::ecs::EntityManager::getSparseSet ()

inline nodiscard

Returns the SparseSet for a component type.

Template Parameters

T	The component type.

Returns

Pointer to the SparseSet, or `nullptr` if the type has no storage.

Definition at line 199 of file EntityManager.ixx.

199 [[nodiscard]] SparseSet<T>* getSparseSet() {

200

201 const auto typeId = ComponentTypeId::id<T>().value();

202

203 if (typeId >= components_.size()) {

204 return nullptr;

205 }

206

207 return static_cast<SparseSet<T>*>(components_[typeId].get());

208 }

References helios::engine::ecs::types::ComponentTypeId::id and helios::engine::ecs::types::ComponentTypeId::value.

getSparseSet()

template <typename T>

const SparseSet< T > * helios::engine::ecs::EntityManager::getSparseSet ()

inline nodiscard

Returns the SparseSet for a component type (const).

Template Parameters

T	The component type.

Returns

Const pointer to the SparseSet, or `nullptr` if the type has no storage.

Definition at line 218 of file EntityManager.ixx.

218 [[nodiscard]] const SparseSet<T>* getSparseSet() const {

219

220 const auto typeId = ComponentTypeId::id<T>().value();

221

222 if (typeId >= components_.size()) {

223 return nullptr;

224 }

225

226 return static_cast<SparseSet<T>*>(components_[typeId].get());

227 }

References helios::engine::ecs::types::ComponentTypeId::id and helios::engine::ecs::types::ComponentTypeId::value.

handle()

EntityHandle helios::engine::ecs::EntityManager::handle (const EntityId entityId)

inline nodiscard

Reconstructs an EntityHandle from an EntityId.

Parameters

entityId

The entity ID.

Returns

EntityHandle with current version from the registry.

Definition at line 513 of file EntityManager.ixx.

513 [[nodiscard]] EntityHandle handle(const EntityId entityId) const {

514 return EntityHandle{entityId, registry_.version(entityId)};

515 }

Referenced by componentTypeIds, destroy, disable, emplace, emplaceOrGet, enable, enable, get, has, has, isValid, isValid, raw and remove.

has()

template <typename T>

bool helios::engine::ecs::EntityManager::has (const EntityHandle handle)

inline nodiscard

Checks whether an entity has a specific component.

Template Parameters

T	The component type to check for.

Parameters

handle

The entity to query.

Returns

`true` if the entity has the component, `false` if the handle is invalid or the component is not attached.

Definition at line 240 of file EntityManager.ixx.

240 [[nodiscard]] bool has(const EntityHandle handle) const {

241 if (!registry_.isValid(handle)) {

242 return false;

243 }

244

245 const auto typeId = ComponentTypeId::id<T>().value();

246

247 if (typeId < components_.size() && components_[typeId]) {

248 return components_[typeId]->contains(handle.entityId);

249 }

250

251 return false;

252 }

References handle, helios::engine::ecs::types::ComponentTypeId::id and helios::engine::ecs::types::ComponentTypeId::value.

Referenced by clone, enable, get, raw and remove.

has()

bool helios::engine::ecs::EntityManager::has (const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId)

inline nodiscard

Checks whether an entity has a component by type ID.

Parameters

handle	The entity to query.
typeId	The component type identifier.

Returns

`true` if the entity has the component, `false` otherwise.

Definition at line 262 of file EntityManager.ixx.

262 [[nodiscard]] bool has(const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId) const {

263 if (!registry_.isValid(handle)) {

264 return false;

265 }

266

267 const auto tvalue = typeId.value();

268

269 if (tvalue < components_.size() && components_[tvalue]) {

270 return components_[tvalue]->contains(handle.entityId);

271 }

272

273 return false;

274 }

References handle and helios::engine::ecs::types::ComponentTypeId::value.

isValid()

bool helios::engine::ecs::EntityManager::isValid (const EntityHandle handle)

inline nodiscard noexcept

Checks if an entity handle is valid.

Parameters

handle

The handle to validate.

Returns

`true` if the handle refers to a living entity.

Definition at line 115 of file EntityManager.ixx.

115 [[nodiscard]] bool isValid(const EntityHandle handle) const noexcept {

116 return registry_.isValid(handle);

117 }

Reference handle.

isValid()

bool helios::engine::ecs::EntityManager::isValid (const EntityId entityId)

inline nodiscard noexcept

Checks if an entity ID is valid.

Parameters

entityId

The entity ID to validate.

Returns

`true` if the entity ID refers to a living entity.

Definition at line 126 of file EntityManager.ixx.

126 [[nodiscard]] bool isValid(const EntityId entityId) const noexcept {

127 return registry_.isValid(handle(entityId));

128 }

Reference handle.

raw()

void * helios::engine::ecs::EntityManager::raw (const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId)

inline nodiscard

Returns raw void pointer to a component.

Parameters

handle	The entity.
typeId	The component type identifier.

Returns

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

Definition at line 498 of file EntityManager.ixx.

498 [[nodiscard]] void* raw(const EntityHandle handle, const helios::engine::ecs::types::ComponentTypeId typeId ) const {

499 if (!has(handle, typeId)) {

500 return nullptr;

501 }

502

503 return components_[typeId.value()]->raw(handle.entityId);

504 }

References handle, has and helios::engine::ecs::types::ComponentTypeId::value.

Referenced by clone, destroy, emplaceOrGet, enable and remove.

remove()

template <typename T>

bool helios::engine::ecs::EntityManager::remove (const EntityHandle & handle)

inline

Removes a specific component from an entity.

Unlike `destroy()`, this only removes a single component type while keeping the entity and other components intact.

Template Parameters

T	The component type to remove.

Parameters

handle

The entity whose component to remove.

Returns

`true` if the component was removed, `false` if the handle was invalid, the component was not attached, or removal was blocked by `onRemove`.

See Also

destroy

See Also

SparseSet::remove

Definition at line 417 of file EntityManager.ixx.

417 bool remove(const EntityHandle& handle) {

418

419 if (!has<T>(handle)) {

420 return false;

421 }

422

423 const auto typeId = ComponentTypeId::id<T>();

424 void* rawCmp = raw(handle, typeId);

425 if (!rawCmp) {

426 return false;

427 }

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

429

430 if (ops.onRemove && !ops.onRemove(rawCmp)) {

431 return false;

432 }

433

434 return components_[typeId.value()]->remove(handle.entityId);

435 }

References handle, has, helios::engine::ecs::types::ComponentTypeId::id, helios::engine::ecs::ComponentOpsRegistry::ops and raw.

Private Member Attributes

capacity_

const size_t helios::engine::ecs::EntityManager::capacity_

initial capacity for the underlying sparsesets.

Definition at line 83 of file EntityManager.ixx.

83 const size_t capacity_;

components_

std::vector<std::unique_ptr<SparseSetBase> > helios::engine::ecs::EntityManager::components_

Component storage indexed by type ID.

@odo sort after size()

Definition at line 73 of file EntityManager.ixx.

73 std::vector<std::unique_ptr<SparseSetBase>> components_;

registry_

EntityRegistry& helios::engine::ecs::EntityManager::registry_

Reference to the entity registry for handle management.

Definition at line 78 of file EntityManager.ixx.

78 EntityRegistry& registry_;

---

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

• EntityManager.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.