EntityRegistry Class Template

Generic registry for creating and managing strongly-typed entity handles. More...

Declaration

template <typename TStrongId, typename TLookupStrategy = HashedLookupStrategy, bool TAllowRemoval = true> class helios::core::ecs::EntityRegistry<TStrongId, TLookupStrategy, TAllowRemoval> { ... }

Public Constructors Index

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

Public Member Functions Index

template < ... >
auto	create (TStrongId strongId=TStrongId{}) -> EntityHandle< TStrongId >
	Creates a new entity and returns its handle. More...
template < ... >
VersionId	version (const EntityId entityId) const
	Looks up the version for an EntityId. More...
template < ... >
bool	isValid (const EntityHandle< TStrongId > handle) const noexcept
	Checks whether the given handle refers to a currently alive entity. More...
template < ... >
bool	destroy (const EntityHandle< TStrongId > handle)
	Destroys the entity referenced by the given handle. More...

Private Member Attributes Index

template < ... >
std::vector< EntityId >	freeList_
	Free list of recycled entity indices available for reuse. More...
template < ... >
std::vector< VersionId >	versions_
	Version numbers for each entity slot. More...
template < ... >
std::vector< StrongId_t >	strongIds_
	Strong ID values for each entity slot. More...
template < ... >
TLookupStrategy	lookupStrategy_
	Lookup strategy instance for strong ID collision detection. More...

Description

Generic registry for creating and managing strongly-typed entity handles.

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

• **Handle Creation:** Generates unique `EntityHandle` instances with versioned IDs and domain-specific strong 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 (when `TAllowRemoval` is true).

## 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.

## Strong ID Collision Detection

The registry delegates collision checks to a configurable `TLookupStrategy`, which tracks which strong IDs are currently in use. The default strategy (`HashedLookupStrategy`) provides O(1) amortized lookups.

Template Parameters

TStrongId	A strong ID type carrying domain semantics.
TLookupStrategy	The strategy used for strong ID collision detection.
TAllowRemoval	If false, `destroy()` triggers an assertion instead of removing.

See Also

EntityHandle

See Also

HashedLookupStrategy

See Also

LinearLookupStrategy

Definition at line 75 of file EntityRegistry.ixx.

Public Constructors

EntityRegistry()

template <typename TStrongId, typename TLookupStrategy = HashedLookupStrategy, bool TAllowRemoval = true>

helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::EntityRegistry ()

default

Default constructor. Creates an empty registry.

Definition at line 108 of file EntityRegistry.ixx.

EntityRegistry()

template <typename TStrongId, typename TLookupStrategy = HashedLookupStrategy, bool TAllowRemoval = true>

helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::EntityRegistry (const size_t capacity)

inline explicit

Constructs a registry 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.

Definition at line 118 of file EntityRegistry.ixx.

118 explicit EntityRegistry(const size_t capacity) : lookupStrategy_(capacity) {

119 versions_.reserve(capacity);

120 strongIds_.reserve(capacity);

121 freeList_.reserve(capacity);

122 }

Public Member Functions

create()

template <typename TStrongId, typename TLookupStrategy = HashedLookupStrategy, bool TAllowRemoval = true>

EntityHandle< TStrongId > helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::create (TStrongId strongId=TStrongId{})

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. If the provided `strongId` is invalid, one is auto-assigned from the entity index.

Parameters

strongId

Optional domain-specific strong ID. Defaults to auto-assignment.

Returns

A valid `EntityHandle` for the newly created entity.

Definition at line 137 of file EntityRegistry.ixx.

137 EntityHandle<TStrongId> create(TStrongId strongId = TStrongId{}) {

138

139 EntityId idx;

140 VersionId version;

141

142 if (freeList_.empty()) {

143 idx = static_cast<EntityId>(versions_.size());

144 version = InitialVersion;

145 versions_.push_back(version);

146 strongIds_.push_back(StrongId_t{});

147 } else {

148 idx = freeList_.back();

149 freeList_.pop_back();

150

151 // version was already incremented in destroy

152 version = versions_[idx];

153 }

154

155 if (!strongId.isValid()) {

156 strongId = TStrongId{idx};

157 }

158

159 assert(!lookupStrategy_.has(strongId.value()) && "EntityRegistry: strongId collision");

160

161 strongIds_[idx] = strongId.value();

162

163 lookupStrategy_.add(strongId.value());

164

165 return {idx, version, strongId};

166

167 }

destroy()

template <typename TStrongId, typename TLookupStrategy = HashedLookupStrategy, bool TAllowRemoval = true>

bool helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::destroy (const EntityHandle< TStrongId > 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), the strong ID is unregistered, and the index is added to the free list for recycling.

If `TAllowRemoval` is false, triggers an assertion failure.

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 222 of file EntityRegistry.ixx.

222 bool destroy(const EntityHandle<TStrongId> handle) {

223

224 if constexpr (!TAllowRemoval) {

225 assert(false && "EntityRegistry: Entity removal is not allowed");

226 return false;

227 }

228

229 if (!isValid(handle)) {

230 return false;

231 }

232

233 const auto index = handle.entityId;

234

235 versions_[index] += 1;

236 strongIds_[index] = 0;

237 lookupStrategy_.remove(handle.strongId.value());

238

239 freeList_.push_back(index);

240

241 return true;

242 }

References helios::core::ecs::EntityHandle< TStrongId >::entityId, helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::isValid and helios::core::ecs::EntityHandle< TStrongId >::strongId.

isValid()

template <typename TStrongId, typename TLookupStrategy = HashedLookupStrategy, bool TAllowRemoval = true>

bool helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::isValid (const EntityHandle< TStrongId > 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, its version matches the current version stored in the registry, and its strong ID matches the registered value.

Parameters

handle

The handle to validate.

Returns

True if the handle is valid and the entity is alive.

Definition at line 195 of file EntityRegistry.ixx.

195 [[nodiscard]] bool isValid(const EntityHandle<TStrongId> handle) const noexcept {

196 const auto index = handle.entityId;

197

198 if (index >= static_cast<EntityId>(versions_.size())) {

199 return false;

200 }

201

202 return handle.strongId.value() == strongIds_[index] &&

203 handle.versionId == versions_[index] &&

204 handle.strongId.isValid();

205 }

Referenced by helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::destroy.

version()

template <typename TStrongId, typename TLookupStrategy = HashedLookupStrategy, bool TAllowRemoval = true>

VersionId helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::version (const EntityId entityId)

inline nodiscard

Looks up the version for an EntityId.

Parameters

entityId

The entity to retrieve the version for.

Returns

The version for the EntityId, or `InvalidVersion` if not found.

Definition at line 176 of file EntityRegistry.ixx.

176 [[nodiscard]] VersionId version(const EntityId entityId) const {

177 if (entityId >= static_cast<EntityId>(versions_.size())) {

178 return InvalidVersion;

179 }

180 return versions_[entityId];

181 }

Reference helios::core::ecs::InvalidVersion.

Private Member Attributes

freeList_

template <typename TStrongId, typename TLookupStrategy = HashedLookupStrategy, bool TAllowRemoval = true>

std::vector<EntityId> helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::freeList_

Free list of recycled entity indices available for reuse.

Definition at line 81 of file EntityRegistry.ixx.

81 std::vector<EntityId> freeList_;

lookupStrategy_

template <typename TStrongId, typename TLookupStrategy = HashedLookupStrategy, bool TAllowRemoval = true>

TLookupStrategy helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::lookupStrategy_

Lookup strategy instance for strong ID collision detection.

Definition at line 101 of file EntityRegistry.ixx.

101 TLookupStrategy lookupStrategy_;

strongIds_

template <typename TStrongId, typename TLookupStrategy = HashedLookupStrategy, bool TAllowRemoval = true>

std::vector<StrongId_t> helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::strongIds_

Strong ID values for each entity slot.

Definition at line 96 of file EntityRegistry.ixx.

96 std::vector<StrongId_t> strongIds_;

versions_

template <typename TStrongId, typename TLookupStrategy = HashedLookupStrategy, bool TAllowRemoval = true>

std::vector<VersionId> helios::core::ecs::EntityRegistry< TStrongId, TLookupStrategy, TAllowRemoval >::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<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.