EntityRegistry Class

Central registry for creating and managing entity handles. More...

Declaration

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

Public Constructors Index

	EntityRegistry ()=default
	Default constructor. Creates an empty registry. More...
	EntityRegistry (const size_t capacity)
	Constructs an EntityRegistry with pre-allocated capacity. More...

Public Member Functions Index

EntityHandle	create ()
	Creates a new entity and returns its handle. More...
helios::engine::common::types::VersionId	version (const helios::engine::ecs::types::EntityId entityId) const
	looks up the version for an EntityId. More...
bool	isValid (const EntityHandle handle) const noexcept
	Checks whether the given handle refers to a currently alive entity. More...
bool	destroy (const EntityHandle handle)
	Destroys the entity referenced by the given handle. More...
std::span< helios::engine::common::types::VersionId >	version () noexcept
	Returns a view of the version vector. More...

Private Member Attributes Index

std::vector< helios::engine::ecs::types::EntityId >	freeList_
	Free list of recycled entity indices available for reuse. More...
std::vector< helios::engine::common::types::VersionId >	versions_
	Version numbers for each entity slot. More...

Description

Central registry for creating and managing entity handles.

The `EntityRegistry` serves as the authoritative source for entity lifecycle management in the ECS architecture. It is responsible for:

• **Handle Creation:** Generates unique `EntityHandle` instances with versioned IDs.
• **Validation:** Determines whether a given handle refers to a currently alive entity.
• **Destruction:** Marks entities as destroyed by incrementing their version and recycling the index for future use.

## Versioning

Each entity slot maintains a version number. When an entity is destroyed, its version is incremented. This allows the registry to detect **stale handles** - handles that reference an entity that has been destroyed and potentially replaced by a new entity at the same index.

## Index Recycling

Destroyed entity indices are added to a free list and reused when creating new entities. This keeps the dense version array compact and minimizes memory growth.

## Usage Example

```cpp helios::engine::ecs::EntityRegistry registry;

// Create a new entity auto handle = registry.create();

// Check if the handle is valid if (registry.isValid(handle)) { // Entity is alive, safe to use }

// Destroy the entity registry.destroy(handle);

// The handle is now stale assert(!registry.isValid(handle)); ```

See Also

EntityHandle

See Also

helios::engine::ecs::types::EntityId

See Also

helios::engine::common::types::VersionId

Definition at line 77 of file EntityRegistry.ixx.

Public Constructors

EntityRegistry()

helios::engine::ecs::EntityRegistry::EntityRegistry ()

default

Default constructor. Creates an empty registry.

Definition at line 97 of file EntityRegistry.ixx.

EntityRegistry()

helios::engine::ecs::EntityRegistry::EntityRegistry (const size_t capacity)

inline explicit

Constructs an EntityRegistry with pre-allocated capacity.

Reserving capacity upfront can improve performance when the approximate number of entities is known in advance.

Parameters

capacity

The initial capacity to reserve for the version vector.

Definition at line 107 of file EntityRegistry.ixx.

107 explicit EntityRegistry(const size_t capacity) {

108 versions_.reserve(capacity);

109 }

Public Member Functions

create()

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

inline

Creates a new entity and returns its handle.

If recycled indices are available in the free list, one is reused. Otherwise, a new index is allocated at the end of the version vector.

Returns

A valid `EntityHandle` for the newly created entity.

Definition at line 119 of file EntityRegistry.ixx.

119 EntityHandle create() {

120

121 helios::engine::ecs::types::EntityId idx;

122 helios::engine::common::types::VersionId version;

123

124 if (freeList_.empty()) {

125 idx = versions_.size();

126 version = InitialVersion;

127

128 versions_.push_back(version);

129

130 } else {

131 idx = freeList_.back();

132 freeList_.pop_back();

133

134 // version was already incremented in destroy

135 version = versions_[idx];

136 }

137

138

139 return {idx, version};

140

141 }

References helios::engine::ecs::InitialVersion and version.

destroy()

bool helios::engine::ecs::EntityRegistry::destroy (const EntityHandle handle)

inline

Destroys the entity referenced by the given handle.

If the handle is valid, the entity's version is incremented (invalidating all existing handles to it) and its index is added to the free list for recycling.

Parameters

handle

The handle of the entity to destroy.

Returns

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

Definition at line 194 of file EntityRegistry.ixx.

194 bool destroy(const EntityHandle handle) {

195

196 if (!isValid(handle)) {

197 return false;

198 }

199

200 const auto index = handle.entityId;

201

202 versions_[index] += 1;

203

204 freeList_.push_back(index);

205

206 return true;

207 }

References helios::engine::ecs::EntityHandle::entityId and isValid.

isValid()

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

inline nodiscard noexcept

Checks whether the given handle refers to a currently alive entity.

A handle is valid if its index is within bounds and its version matches the current version stored in the registry.

Parameters

handle

The handle to validate.

Returns

`true` if the handle is valid and the entity is alive, `false` otherwise.

Definition at line 171 of file EntityRegistry.ixx.

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

172

173 const auto index = handle.entityId;

174

175 if (index >= versions_.size()) {

176 return false;

177 }

178

179 return handle.versionId == versions_[index];

180 }

Referenced by destroy.

version()

helios::engine::common::types::VersionId helios::engine::ecs::EntityRegistry::version (const helios::engine::ecs::types::EntityId entityId)

inline nodiscard

looks up the version for an EntityId.

This method takes an EntityId as the argument and looks up the corresponding version. If the EntityId is not part of the registry, 0 will be returned.

Parameters

entityId

The entity to retrieve the version for.

Returns

The version for the EntityId, or 0 if not found.

Definition at line 153 of file EntityRegistry.ixx.

153 [[nodiscard]] helios::engine::common::types::VersionId version(const helios::engine::ecs::types::EntityId entityId) const {

154 if (entityId >= versions_.size()) {

155 return 0;

156 }

157 return versions_[entityId];

158 }

Referenced by create.

version()

std::span< helios::engine::common::types::VersionId > helios::engine::ecs::EntityRegistry::version ()

inline noexcept

Returns a view of the version vector.

Provides read-write access to the internal version data. Useful for debugging or advanced use cases where direct version inspection is needed.

Returns

A span over the version vector.

Definition at line 217 of file EntityRegistry.ixx.

217 std::span<helios::engine::common::types::VersionId> version() noexcept {

218 return versions_;

219 }

Private Member Attributes

freeList_

std::vector<helios::engine::ecs::types::EntityId> helios::engine::ecs::EntityRegistry::freeList_

Free list of recycled entity indices available for reuse.

Definition at line 82 of file EntityRegistry.ixx.

82 std::vector<helios::engine::ecs::types::EntityId> freeList_;

versions_

std::vector<helios::engine::common::types::VersionId> helios::engine::ecs::EntityRegistry::versions_

Version numbers for each entity slot.

The version is incremented when an entity at that index is destroyed, allowing detection of stale handles.

Definition at line 90 of file EntityRegistry.ixx.

90 std::vector<helios::engine::common::types::VersionId> versions_;

---

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

• EntityRegistry.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.