GameObjectPool Class

A reusable object pool for GameObjects. More...

Declaration

class helios::engine::game::GameObjectPool { ... }

Private Member Typedefs Index

using	Factory = std::function< std::unique_ptr< helios::engine::game::GameObject >()>
	Factory function type for creating new GameObjects. More...

Public Constructors Index

	GameObjectPool (helios::engine::game::GameWorld &gameWorld, Factory gameObjectFactory, size_t poolSize)
	Constructs a new GameObjectPool. More...

Public Member Functions Index

helios::util::Guid	guid () const noexcept
	Returns the unique identifier of this pool. More...
helios::engine::game::GameObject *	acquire ()
	Acquires the next available GameObject from the pool. More...
bool	release (const helios::engine::game::GameObject *gameObject)
	Releases a GameObject back to the pool. More...
bool	release (const helios::util::Guid &guid)
	Releases a GameObject back to the pool by its Guid. More...
std::vector< helios::engine::game::GameObject * >	inactiveGameObjects ()
	Retrieves all currently inactive GameObjects. More...
size_t	activeCount () const noexcept
	Returns the number of active game objects. More...
size_t	inactiveCount () const noexcept
	Returns the number of inactive game objects. More...

Protected Member Functions Index

void	warmup ()
	Pre-allocates all pooled objects and adds them to the GameWorld. More...

Protected Member Attributes Index

std::unordered_map< helios::util::Guid, size_t >	activeIndex_
	Maps active GameObject Guids to their index in activeGameObjects_. More...
std::vector< helios::util::Guid >	activeGameObjects_
	List of Guids for currently active (in-use) GameObjects. More...
std::vector< helios::util::Guid >	inactiveGameObjects_
	List of Guids for currently inactive (available) GameObjects. More...
size_t	poolSize_ = 0
	The maximum number of objects this pool manages. More...
helios::engine::game::GameWorld &	gameWorld_
	Reference to the GameWorld that owns the pooled GameObjects. More...
Factory	gameObjectFactory_
	Factory function used to create new GameObjects during warmup. More...
const helios::util::Guid	guid_
	Unique identifier for this pool instance. More...

Description

A reusable object pool for GameObjects.

GameObjectPool implements the Object Pool pattern to efficiently manage GameObjects that are frequently created and destroyed. Instead of allocating new objects at runtime, the pool pre-allocates a fixed number of objects during warmup and recycles them.

The pool tracks objects by their Guid and validates them against the GameWorld on acquire to handle external removal gracefully.

Typical use cases:

• Projectile/bullet spawning
• Particle systems
• Enemy wave spawning

Example usage: ```cpp auto factory = []() { auto bullet = std::make_unique<GameObject>(); bullet->addComponent<Move2DComponent>(); return bullet; };

GameObjectPool bulletPool(gameWorld, factory, 100);

// Acquire an object from the pool if (auto* bullet = bulletPool.acquire()) { bullet->get<Move2DComponent>()->setVelocity({0, 1, 0}); }

// Release the object back to the pool bulletPool.release(bullet); ```

Definition at line 72 of file GameObjectPool.ixx.

Private Member Typedefs

Factory

using helios::engine::game::GameObjectPool::Factory = std::function<std::unique_ptr<helios::engine::game::GameObject>()>

Factory function type for creating new GameObjects.

The factory is invoked during pool warmup to create all pooled objects. It should return a fully configured GameObject ready for use.

Definition at line 80 of file GameObjectPool.ixx.

80 using Factory = std::function<std::unique_ptr<helios::engine::game::GameObject>()>;

Public Constructors

GameObjectPool()

helios::engine::game::GameObjectPool::GameObjectPool (helios::engine::game::GameWorld & gameWorld, Factory gameObjectFactory, size_t poolSize)

inline explicit

Constructs a new GameObjectPool.

Parameters

gameWorld	Reference to the GameWorld that will own the pooled objects.
gameObjectFactory	Factory function to create new GameObjects.
poolSize	Number of objects to pre-allocate in the pool.

info

The pool immediately calls warmup() to pre-allocate all objects.

Definition at line 150 of file GameObjectPool.ixx.

150 explicit GameObjectPool(

151 helios::engine::game::GameWorld& gameWorld,

152 Factory gameObjectFactory,

153 size_t poolSize

154 ) :

155 poolSize_(poolSize),

156 gameWorld_(gameWorld),

157 gameObjectFactory_(std::move(gameObjectFactory)),

158 guid_(helios::util::Guid::generate()) {

159

160 activeGameObjects_.reserve(poolSize);

161 inactiveGameObjects_.reserve(poolSize);

162

163 warmup();

164 }

References activeGameObjects_, gameObjectFactory_, gameWorld_, guid_, inactiveGameObjects_, poolSize_ and warmup.

Public Member Functions

acquire()

helios::engine::game::GameObject * helios::engine::game::GameObjectPool::acquire ()

inline nodiscard

Acquires the next available GameObject from the pool.

Retrieves an inactive GameObject, validates it against the GameWorld, marks it as active, and returns it. If a Guid references an object that no longer exists in the GameWorld (e.g., externally removed), it is silently discarded and the next available object is tried.

Returns

Pointer to an activated GameObject, or nullptr if the pool is exhausted.

info

The returned object is marked as active and tracked internally. Call release() to return it to the pool when done.

Definition at line 190 of file GameObjectPool.ixx.

190 [[nodiscard]] helios::engine::game::GameObject* acquire() {

191

192 if (inactiveGameObjects_.empty()) {

193 return nullptr;

194 }

195

196 while (!inactiveGameObjects_.empty()) {

197

198 auto guid = inactiveGameObjects_.back();

199 auto* gameObject = gameWorld_.find(guid);

200

201 inactiveGameObjects_.pop_back();

202

203 if (gameObject == nullptr) {

204 continue;

205 }

206

207 activeIndex_[guid] = activeGameObjects_.size();

208 activeGameObjects_.push_back(guid);

209 gameObject->setActive(true);

210

211 return gameObject;

212 }

213

214 return nullptr;

215

216 }

References activeGameObjects_, activeIndex_, gameWorld_, guid and inactiveGameObjects_.

activeCount()

size_t helios::engine::game::GameObjectPool::activeCount ()

inline nodiscard noexcept

Returns the number of active game objects.

Returns

The number of active game objects.

Definition at line 313 of file GameObjectPool.ixx.

313 [[nodiscard]] size_t activeCount() const noexcept {

314 return activeGameObjects_.size();

315 }

Reference activeGameObjects_.

guid()

helios::util::Guid helios::engine::game::GameObjectPool::guid ()

inline nodiscard noexcept

Returns the unique identifier of this pool.

Returns

The Guid assigned to this pool instance.

Definition at line 171 of file GameObjectPool.ixx.

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

172 return guid_;

173 }

Reference guid_.

Referenced by acquire, inactiveGameObjects, release and warmup.

inactiveCount()

size_t helios::engine::game::GameObjectPool::inactiveCount ()

inline nodiscard noexcept

Returns the number of inactive game objects.

Returns

The number of inactive game objects.

Definition at line 322 of file GameObjectPool.ixx.

322 [[nodiscard]] size_t inactiveCount() const noexcept {

323 return inactiveGameObjects_.size();

324 }

Reference inactiveGameObjects_.

inactiveGameObjects()

std::vector< helios::engine::game::GameObject * > helios::engine::game::GameObjectPool::inactiveGameObjects ()

inline

Retrieves all currently inactive GameObjects.

Iterates the inactive Guid list and resolves each to a GameObject pointer. Objects that no longer exist in the GameWorld are silently skipped.

Returns

Vector of pointers to inactive GameObjects. The vector may be smaller than the inactive count if some objects were externally removed.

info

This operation has O(n) complexity where n is the number of inactive objects.

Definition at line 288 of file GameObjectPool.ixx.

288 std::vector<helios::engine::game::GameObject*> inactiveGameObjects() {

289

290 std::vector<helios::engine::game::GameObject*> gameObjects{};

291

292 for (int i = inactiveGameObjects_.size() - 1; i >= 0; i--) {

293

294 auto guid = inactiveGameObjects_[i];

295 auto* gameObject = gameWorld_.find(guid);

296

297 if (gameObject == nullptr) {

298 continue;

299 }

300

301 gameObjects.push_back(gameObject);

302 }

303

304 return gameObjects;

305

306 }

References gameWorld_, guid and inactiveGameObjects_.

release()

bool helios::engine::game::GameObjectPool::release (const helios::engine::game::GameObject * gameObject)

inline

Releases a GameObject back to the pool.

Parameters

gameObject

Pointer to the GameObject to release. May be nullptr.

Returns

True if the object was successfully released, false if gameObject was nullptr or not tracked by this pool.

Definition at line 226 of file GameObjectPool.ixx.

226 bool release(const helios::engine::game::GameObject* gameObject) {

227 return gameObject != nullptr ? release(gameObject->guid()) : false;

228 }

References helios::engine::game::GameObject::guid and release.

Referenced by release.

release()

bool helios::engine::game::GameObjectPool::release (const helios::util::Guid & guid)

inline

Releases a GameObject back to the pool by its Guid.

Validates the Guid against both the GameWorld and the active tracking list. Uses swap-and-pop for O(1) removal from the active list. The object is marked inactive and added to the inactive list for future acquisition.

Parameters

guid	The unique identifier of the GameObject to release.

Returns

True if the object was successfully released, false if the Guid was not found in the GameWorld or not tracked as active.

Definition at line 243 of file GameObjectPool.ixx.

243 bool release(const helios::util::Guid& guid) {

244

245 auto* gameObject = gameWorld_.find(guid);

246 auto it = activeIndex_.find(guid);

247

248 if (!gameObject || it == activeIndex_.end()) {

249 return false;

250 }

251

252

253 size_t idx = it->second;

254 auto lastGuid = activeGameObjects_.back();

255

256 // swap the last guid in activeGameObjects with the

257 // guid to remove, effectively overwriting guid

258 // to release with a currently active guid

259 activeGameObjects_[idx] = lastGuid;

260 activeIndex_[lastGuid] = idx;

261

262 // the swap operation has create a duplicate entry,

263 // remove the one at the tail

264 activeGameObjects_.pop_back();

265

266 // clear the queried guid from active index and update

267 // inactiveGameObjects

268 activeIndex_.erase(it);

269 inactiveGameObjects_.push_back(guid);

270

271 gameObject->setActive(false);

272

273 return true;

274 }

References activeGameObjects_, activeIndex_, gameWorld_, guid and inactiveGameObjects_.

Protected Member Functions

warmup()

void helios::engine::game::GameObjectPool::warmup ()

inline protected

Pre-allocates all pooled objects and adds them to the GameWorld.

Creates poolSize_ GameObjects using the factory, sets them inactive, adds them to the GameWorld, and tracks their Guids for later acquisition. Called automatically during construction.

Definition at line 129 of file GameObjectPool.ixx.

129 void warmup() {

130 for (unsigned int i = 0; i < poolSize_; i++) {

131 std::unique_ptr<helios::engine::game::GameObject> gameObject = gameObjectFactory_();

132 gameObject->setActive(false);

133 helios::util::Guid guid = gameObject->guid();

134 std::ignore = gameWorld_.addGameObject(std::move(gameObject));

135 inactiveGameObjects_.push_back(guid);

136 }

137 }

References gameObjectFactory_, gameWorld_, guid, inactiveGameObjects_ and poolSize_.

Referenced by GameObjectPool.

Protected Member Attributes

activeGameObjects_

std::vector<helios::util::Guid> helios::engine::game::GameObjectPool::activeGameObjects_

protected

List of Guids for currently active (in-use) GameObjects.

Definition at line 94 of file GameObjectPool.ixx.

94 std::vector<helios::util::Guid> activeGameObjects_;

Referenced by acquire, activeCount, GameObjectPool and release.

activeIndex_

std::unordered_map<helios::util::Guid, size_t> helios::engine::game::GameObjectPool::activeIndex_

protected

Maps active GameObject Guids to their index in activeGameObjects_.

Enables O(1) lookup for release operations.

Definition at line 89 of file GameObjectPool.ixx.

89 std::unordered_map<helios::util::Guid, size_t> activeIndex_;

Referenced by acquire and release.

gameObjectFactory_

Factory helios::engine::game::GameObjectPool::gameObjectFactory_

protected

Factory function used to create new GameObjects during warmup.

Definition at line 114 of file GameObjectPool.ixx.

114 Factory gameObjectFactory_;

Referenced by GameObjectPool and warmup.

gameWorld_

helios::engine::game::GameWorld& helios::engine::game::GameObjectPool::gameWorld_

protected

Reference to the GameWorld that owns the pooled GameObjects.

Definition at line 109 of file GameObjectPool.ixx.

109 helios::engine::game::GameWorld& gameWorld_;

Referenced by acquire, GameObjectPool, inactiveGameObjects, release and warmup.

guid_

const helios::util::Guid helios::engine::game::GameObjectPool::guid_

protected

Unique identifier for this pool instance.

Definition at line 119 of file GameObjectPool.ixx.

119 const helios::util::Guid guid_;

Referenced by GameObjectPool and guid.

inactiveGameObjects_

std::vector<helios::util::Guid> helios::engine::game::GameObjectPool::inactiveGameObjects_

protected

List of Guids for currently inactive (available) GameObjects.

Definition at line 99 of file GameObjectPool.ixx.

99 std::vector<helios::util::Guid> inactiveGameObjects_;

Referenced by acquire, GameObjectPool, inactiveCount, inactiveGameObjects, release and warmup.

poolSize_

size_t helios::engine::game::GameObjectPool::poolSize_ = 0

protected

The maximum number of objects this pool manages.

Definition at line 104 of file GameObjectPool.ixx.

104 size_t poolSize_ = 0;

Referenced by GameObjectPool and warmup.

---

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

• GameObjectPool.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.