SpawnManager Class

Manager for processing spawn and despawn commands. More...

Declaration

class helios::engine::runtime::spawn::SpawnManager { ... }

Public Member Typedefs Index

using	EngineRoleTag = helios::engine::common::tags::ManagerRole

Public Constructors Index

	SpawnManager ()=default
	Default constructor. More...

Public Member Functions Index

bool	submit (const SpawnCommand command) noexcept
	Submits a spawn command for deferred processing. More...
void	addScheduler (std::unique_ptr< helios::engine::runtime::spawn::scheduling::SpawnScheduler > scheduler)
	Adds a spawn scheduler to this manager. More...
bool	submit (const DespawnCommand command) noexcept
	Submits a despawn command for deferred processing. More...
bool	submit (const ScheduledSpawnPlanCommand scheduledSpawnPlanCommand) noexcept
	Submits a scheduled spawn plan command for deferred processing. More...
void	flush (helios::engine::runtime::world::UpdateContext &updateContext) noexcept
	Flushes pending commands, processing despawns then spawns. More...
SpawnManager &	addSpawnProfile (const SpawnProfileId &spawnProfileId, std::unique_ptr< const SpawnProfile > spawnProfile)
	Adds a spawn profile for a profile ID. More...
const SpawnProfile *	spawnProfile (const SpawnProfileId &spawnProfileId) const
	Returns a spawn profile by ID. More...
void	init (helios::engine::runtime::world::GameWorld &gameWorld) noexcept
	Initializes the manager with the game world. More...
void	reset ()
	Resets all schedulers, profiles, and pending commands. More...
std::span< std::unique_ptr< helios::engine::runtime::spawn::scheduling::SpawnScheduler > >	spawnSchedulers ()
	Returns a span of all registered spawn schedulers. More...

Private Member Functions Index

void	ensureBounds (helios::engine::ecs::GameObject go, helios::math::aabbf &bounds)
	Ensures that the bounds are properly computed.. More...
void	executeScheduledSpawnPlanCommands (std::span< ScheduledSpawnPlanCommand > commands, helios::engine::runtime::world::UpdateContext &updateContext)
	Processes scheduled spawn plan commands. More...
void	spawnObjects (std::span< SpawnCommand > commands, helios::engine::runtime::world::UpdateContext &updateContext)
	Processes spawn commands, acquiring and initializing objects. More...
void	despawnObjects (std::span< DespawnCommand > commands, helios::engine::runtime::world::UpdateContext &updateContext)
	Processes despawn commands, releasing objects back to pools. More...

Private Member Attributes Index

std::vector< std::unique_ptr< helios::engine::runtime::spawn::scheduling::SpawnScheduler > >	spawnSchedulers_
	Collection of schedulers that manage spawn rules and conditions. More...
std::vector< SpawnCommand >	spawnCommands_
	Queue of pending spawn commands. More...
std::vector< DespawnCommand >	despawnCommands_
	Queue of pending despawn commands. More...
std::vector< ScheduledSpawnPlanCommand >	scheduledSpawnPlanCommands_
	Queue of pending scheduled spawn plan commands. More...
helios::engine::runtime::pooling::GameObjectPoolManager *	gameObjectPoolManager_ = nullptr
	Pointer to the pool manager for acquire/release operations. More...
std::unordered_map< helios::engine::runtime::spawn::types::SpawnProfileId, std::unique_ptr< const SpawnProfile > >	spawnProfiles_
	Map from profile IDs to their spawn profiles. More...

Description

Manager for processing spawn and despawn commands.

SpawnManager is a Manager that handles the lifecycle of pooled GameObjects. It receives commands via SpawnCommandHandler::submit() and queues them for deferred processing during the manager flush phase.

## Command Processing Order

During flush(), commands are processed in this order: 1. **Despawn commands** - Entities are returned to their pools 2. **Spawn commands** - Single entities are acquired and initialized 3. **Scheduled spawn plan commands** - Batch spawns from scheduler

## Spawn Profiles

Each spawn profile defines:

• Which pool to acquire entities from
• How to position spawned entities (SpawnPlacer)
• How to initialize spawned entities (SpawnInitializer)

## Integration

SpawnManager registers itself with the GameWorld for each profile ID, allowing commands to route to the correct handler.

Example: ```cpp auto spawnManager = std::make_unique<SpawnManager>();

spawnManager->addSpawnProfile(bulletProfileId, std::make_unique<SpawnProfile>( SpawnProfile{ .gameObjectPoolId = bulletPoolId, .spawnPlacer = std::make_unique<EmitterSpawnPlacer>(), .spawnInitializer = std::make_unique<EmitterInitializer>() } ));

gameWorld.addManager(std::move(spawnManager)); ```

See Also

SpawnCommand

See Also

DespawnCommand

See Also

ScheduledSpawnPlanCommand

See Also

SpawnProfile

See Also

SpawnCommandHandler

Definition at line 105 of file SpawnManager.ixx.

Public Member Typedefs

EngineRoleTag

using helios::engine::runtime::spawn::SpawnManager::EngineRoleTag = helios::engine::common::tags::ManagerRole

Definition at line 368 of file SpawnManager.ixx.

368 using EngineRoleTag = helios::engine::common::tags::ManagerRole;

Public Constructors

SpawnManager()

helios::engine::runtime::spawn::SpawnManager::SpawnManager ()

default

Default constructor.

Definition at line 373 of file SpawnManager.ixx.

Referenced by addSpawnProfile.

Public Member Functions

addScheduler()

void helios::engine::runtime::spawn::SpawnManager::addScheduler (std::unique_ptr< helios::engine::runtime::spawn::scheduling::SpawnScheduler > scheduler)

inline

Adds a spawn scheduler to this manager.

Schedulers evaluate spawn rules and produce spawn plans based on game conditions. Multiple schedulers can be added for different spawn categories.

Parameters

scheduler

The scheduler to add. Ownership is transferred.

Definition at line 396 of file SpawnManager.ixx.

396 void addScheduler(std::unique_ptr<helios::engine::runtime::spawn::scheduling::SpawnScheduler> scheduler) {

397 spawnSchedulers_.push_back(std::move(scheduler));

398 }

addSpawnProfile()

SpawnManager & helios::engine::runtime::spawn::SpawnManager::addSpawnProfile (const SpawnProfileId & spawnProfileId, std::unique_ptr< const SpawnProfile > spawnProfile)

inline

Adds a spawn profile for a profile ID.

Registers a spawn profile that defines how entities should be spawned for this profile. The profile contains the pool ID, placer, and initializer.

Parameters

spawnProfileId	The unique ID for this profile.
spawnProfile	The profile configuration. Ownership transferred.

Returns

Reference to this manager for chaining.

Precondition

No profile is already registered for this ID.

Definition at line 467 of file SpawnManager.ixx.

467 SpawnManager& addSpawnProfile(

468 const SpawnProfileId& spawnProfileId,

469 std::unique_ptr<const SpawnProfile> spawnProfile) {

470

471 assert(!spawnProfiles_.contains(spawnProfileId) && "SpawnProfileId already added");

472

473 spawnProfiles_[spawnProfileId] = std::move(spawnProfile);

474

475 return *this;

476 }

References SpawnManager and spawnProfile.

flush()

void helios::engine::runtime::spawn::SpawnManager::flush (helios::engine::runtime::world::UpdateContext & updateContext)

inline noexcept

Flushes pending commands, processing despawns then spawns.

Parameters

gameWorld	The game world.
updateContext	The current update context.

Definition at line 433 of file SpawnManager.ixx.

433 void flush(

434 helios::engine::runtime::world::UpdateContext& updateContext

435 ) noexcept {

436 if (!despawnCommands_.empty()) {

437 despawnObjects(despawnCommands_, updateContext);

438 despawnCommands_.clear();

439 }

440

441 if (!spawnCommands_.empty()) {

442 spawnObjects(spawnCommands_, updateContext);

443 spawnCommands_.clear();

444 }

445

446 if (!scheduledSpawnPlanCommands_.empty()) {

447 executeScheduledSpawnPlanCommands(scheduledSpawnPlanCommands_, updateContext);

448 scheduledSpawnPlanCommands_.clear();

449 }

450 };

init()

void helios::engine::runtime::spawn::SpawnManager::init (helios::engine::runtime::world::GameWorld & gameWorld)

inline noexcept

Initializes the manager with the game world.

Acquires a reference to the GameObjectPoolManager and registers this manager as the SpawnCommandHandler for all configured spawn profiles.

Parameters

gameWorld

The game world to initialize with.

Definition at line 504 of file SpawnManager.ixx.

504 void init(helios::engine::runtime::world::GameWorld& gameWorld) noexcept {

505

506 assert(gameWorld.hasManager<helios::engine::runtime::pooling::GameObjectPoolManager>() && "Unexpected missing GameObjectPoolManager");

507 gameObjectPoolManager_ = gameWorld.tryManager<helios::engine::runtime::pooling::GameObjectPoolManager>();

508

509 gameWorld.registerCommandHandler<SpawnCommand, DespawnCommand, ScheduledSpawnPlanCommand>(*this);

510 }

reset()

void helios::engine::runtime::spawn::SpawnManager::reset ()

inline

Resets all schedulers, profiles, and pending commands.

Called during level transitions or game restarts to clear all spawn state. Resets each scheduler, calls `onReset()` on all placers and initializers, and clears all pending command queues.

Definition at line 519 of file SpawnManager.ixx.

519 void reset() {

520

521 for (auto& scheduler: spawnSchedulers_) {

522 scheduler->reset();

523 }

524

525 for (auto& [_, profile]: spawnProfiles_) {

526 profile->spawnPlacer->onReset();

527 profile->spawnInitializer->onReset();

528 }

529

530

531 despawnCommands_.clear();

532 spawnCommands_.clear();

533 scheduledSpawnPlanCommands_.clear();

534 }

spawnProfile()

const SpawnProfile * helios::engine::runtime::spawn::SpawnManager::spawnProfile (const SpawnProfileId & spawnProfileId)

inline nodiscard

Returns a spawn profile by ID.

Parameters

spawnProfileId

The profile ID to look up.

Returns

Pointer to the profile, or nullptr if not found.

Definition at line 485 of file SpawnManager.ixx.

485 [[nodiscard]] const SpawnProfile* spawnProfile(

486 const SpawnProfileId& spawnProfileId) const {

487

488 if (!spawnProfiles_.contains(spawnProfileId)) {

489 return nullptr;

490 }

491

492 return spawnProfiles_.find(spawnProfileId)->second.get();

493 }

Referenced by addSpawnProfile.

spawnSchedulers()

std::span< std::unique_ptr< helios::engine::runtime::spawn::scheduling::SpawnScheduler > > helios::engine::runtime::spawn::SpawnManager::spawnSchedulers ()

inline

Returns a span of all registered spawn schedulers.

Returns

Span of spawn scheduler unique pointers.

Definition at line 541 of file SpawnManager.ixx.

541 std::span<std::unique_ptr<helios::engine::runtime::spawn::scheduling::SpawnScheduler>> spawnSchedulers() {

542 return spawnSchedulers_;

543 }

submit()

bool helios::engine::runtime::spawn::SpawnManager::submit (const SpawnCommand command)

inline noexcept

Submits a spawn command for deferred processing.

Parameters

command

The spawn command to queue.

Returns

Always returns true.

Definition at line 382 of file SpawnManager.ixx.

382 bool submit(const SpawnCommand command) noexcept {

383 spawnCommands_.push_back(command);

384 return true;

385 }

submit()

bool helios::engine::runtime::spawn::SpawnManager::submit (const DespawnCommand command)

inline noexcept

Submits a despawn command for deferred processing.

Parameters

command

The despawn command to queue.

Returns

Always returns true.

Definition at line 407 of file SpawnManager.ixx.

407 bool submit(const DespawnCommand command) noexcept {

408 despawnCommands_.push_back(command);

409 return true;

410 }

submit()

bool helios::engine::runtime::spawn::SpawnManager::submit (const ScheduledSpawnPlanCommand scheduledSpawnPlanCommand)

inline noexcept

Submits a scheduled spawn plan command for deferred processing.

Parameters

scheduledSpawnPlanCommand

The scheduled plan command to queue.

Returns

Always returns true.

Definition at line 420 of file SpawnManager.ixx.

420 bool submit(

421 const ScheduledSpawnPlanCommand scheduledSpawnPlanCommand

422 ) noexcept {

423 scheduledSpawnPlanCommands_.push_back(scheduledSpawnPlanCommand);

424 return true;

425 }

Private Member Functions

despawnObjects()

void helios::engine::runtime::spawn::SpawnManager::despawnObjects (std::span< DespawnCommand > commands, helios::engine::runtime::world::UpdateContext & updateContext)

inline

Processes despawn commands, releasing objects back to pools.

Parameters

commands	Span of despawn commands to process.
gameWorld	The game world.
updateContext	The current update context.

Definition at line 349 of file SpawnManager.ixx.

349 void despawnObjects(

350 std::span<DespawnCommand> commands,

351 helios::engine::runtime::world::UpdateContext& updateContext) {

352

353 for (auto& despawnCommand : commands) {

354 const auto spawnProfileId = despawnCommand.spawnProfileId();

355

356 const auto it = spawnProfiles_.find(spawnProfileId);

357 assert(it != spawnProfiles_.end() && "SpawnProfile not part of SpawnManager");

358 const auto spawnProfile = it->second.get();

359 auto gameObjectPoolId = spawnProfile->gameObjectPoolId;

360

361 gameObjectPoolManager_->release(gameObjectPoolId, despawnCommand.entityHandle());

362

363 }

364 }

ensureBounds()

void helios::engine::runtime::spawn::SpawnManager::ensureBounds (helios::engine::ecs::GameObject go, helios::math::aabbf & bounds)

inline

Ensures that the bounds are properly computed..

Checks if the bounding box was initialized (i.e. has valid min/max values: min <= max). If the bounds are inverted (min > max), it recomputes the world AABB using the GameObject's components (ModelAabb, ScaleState, RotationState, SceneNode, TranslationState).

Parameters

go	The GameObject to compute bounds for.
bounds	The bounding box to check and potentially update.

See Also

helios::engine::modules::physics::collision::Bounds::computeWorldAabb

Definition at line 159 of file SpawnManager.ixx.

159 void ensureBounds(helios::engine::ecs::GameObject go, helios::math::aabbf& bounds) {

160 if (bounds.min()[0] > bounds.max()[0]) {

161 const auto* mab = go.get<helios::engine::modules::rendering::model::components::ModelAabbComponent>();

162 const auto* sca = go.get<helios::engine::modules::spatial::transform::components::ScaleStateComponent>();

163 auto* rsc = go.get<helios::engine::modules::spatial::transform::components::RotationStateComponent>();

164 const auto* scn = go.get<helios::engine::modules::scene::components::SceneNodeComponent>();

165 const auto* tsc = go.get<helios::engine::modules::spatial::transform::components::TranslationStateComponent>();

166

167 assert(mab && scn && tsc && sca && rsc && "Missing Components for AABB computation");

168 bounds = helios::engine::modules::physics::collision::Bounds::computeWorldAabb(

169 *mab, *scn, *tsc, *sca, *rsc

170 );

171 }

172 }

executeScheduledSpawnPlanCommands()

void helios::engine::runtime::spawn::SpawnManager::executeScheduledSpawnPlanCommands (std::span< ScheduledSpawnPlanCommand > commands, helios::engine::runtime::world::UpdateContext & updateContext)

inline

Processes scheduled spawn plan commands.

Iterates through each plan, acquires entities from the pool, positions them using the profile's placer, initializes them using the profile's initializer, and pushes a frame event for confirmation.

Parameters

commands	Span of scheduled spawn plan commands to process.
gameWorld	The game world.
updateContext	The current update context.

Definition at line 185 of file SpawnManager.ixx.

185 void executeScheduledSpawnPlanCommands(

186 std::span<ScheduledSpawnPlanCommand> commands,

187 helios::engine::runtime::world::UpdateContext& updateContext

188 ) {

189

190 for (auto& scheduledSpawnPlanCommand: commands) {

191

192 const auto& spawnPlan = scheduledSpawnPlanCommand.spawnPlan();

193

194 const auto spawnProfileId = scheduledSpawnPlanCommand.spawnProfileId();

195 const auto spawnRuleId = spawnPlan.spawnRuleId;

196 const auto amount = spawnPlan.amount;

197

198 const auto it = spawnProfiles_.find(spawnProfileId);

199 assert(it != spawnProfiles_.end() && "SpawnProfile not part of SpawnManager");

200

201 const auto spawnProfile = it->second.get();

202

203 const auto gameObjectPoolId = spawnProfile->gameObjectPoolId;

204

205

206

207 const auto poolSnapshot = gameObjectPoolManager_->poolSnapshot(gameObjectPoolId);

208

209 if (amount == 0) {

210 assert(false && "Amount must not be 0");

211 }

212 if (!spawnProfiles_.contains(spawnProfileId)) {

213 assert(false && "SpawnManager does not manage this SpawnProfileId");

214 }

215

216

217

218 const auto spawnCount = std::min(amount, poolSnapshot.inactiveCount);

219 for (size_t i = 0; i < spawnCount; i++) {

220

221 auto go = gameObjectPoolManager_->acquire(gameObjectPoolId);

222 assert(go && "Failed to acquire GameObject");

223

224 auto* tsc = go->get<helios::engine::modules::spatial::transform::components::TranslationStateComponent>();

225

226 auto* sbp = go->get<helios::engine::mechanics::spawn::components::SpawnedByProfileComponent>();

227 assert(sbp && "unexpected missing SpawnedByProfileComponent");

228

229 auto* aabb = go->get<helios::engine::modules::physics::collision::components::AabbColliderComponent>();

230 assert(aabb && "unexpected missing AabbColliderComponent");

231

232 auto spawnCursor = SpawnPlanCursor{spawnCount, i};

233 const auto& spawnContext = scheduledSpawnPlanCommand.spawnContext();

234

235 const auto& emitter = spawnContext.emitterContext;

236 auto* ebc = go->get<helios::engine::mechanics::spawn::components::EmittedByComponent>();

237 if (emitter.has_value() && ebc) {

238 ebc->setSource(emitter.value().source);

239 }

240

241 if (tsc) {

242

243 auto bounds = aabb->bounds();

244 ensureBounds(go.value(), bounds);

245

246 const auto position = spawnProfile->spawnPlacer->getPosition(

247 go->entityHandle(),

248 bounds,

249 updateContext.level()->bounds(),

250 spawnCursor,

251 spawnContext

252

253 );

254 tsc->setTranslation(position);

255 }

256

257 assert(spawnProfile->spawnInitializer && "Unexpected missing spawn initializer");

258

259 spawnProfile->spawnInitializer->initialize(*go, spawnCursor, spawnContext);

260 sbp->setSpawnProfileId(spawnProfileId);

261 go->setActive(true);

262 }

263

264 updateContext.pushFrame<helios::engine::runtime::spawn::events::SpawnPlanCommandExecutedEvent>(

265 spawnRuleId, spawnCount

266 );

267 }

268 }

spawnObjects()

void helios::engine::runtime::spawn::SpawnManager::spawnObjects (std::span< SpawnCommand > commands, helios::engine::runtime::world::UpdateContext & updateContext)

inline

Processes spawn commands, acquiring and initializing objects.

Parameters

commands	Span of spawn commands to process.
gameWorld	The game world.
updateContext	The current update context.

Definition at line 278 of file SpawnManager.ixx.

278 void spawnObjects(

279 std::span<SpawnCommand> commands,

280 helios::engine::runtime::world::UpdateContext& updateContext) {

281

282 for (auto& spawnCommand: commands) {

283 const auto spawnProfileId = spawnCommand.spawnProfileId();

284 const auto spawnContext = spawnCommand.spawnContext();

285

286 const auto it = spawnProfiles_.find(spawnProfileId);

287 assert(it != spawnProfiles_.end() && "SpawnProfile not part of SpawnManager");

288

289 const auto spawnProfile = it->second.get();

290 const auto gameObjectPoolId = spawnProfile->gameObjectPoolId;

291

292 if (gameObjectPoolManager_->poolSnapshot(gameObjectPoolId).inactiveCount == 0) {

293 /**

294 * @todo log

295 */

296 continue;

297 }

298

299 auto go = gameObjectPoolManager_->acquire(gameObjectPoolId);

300 assert(go && "Failed to acquire GameObject");

301

302 auto* tsc = go->get<helios::engine::modules::spatial::transform::components::TranslationStateComponent>();

303 auto* sbp = go->get<helios::engine::mechanics::spawn::components::SpawnedByProfileComponent>();

304 assert(sbp && "unexpected missing SpawnedByProfileComponent");

305

306 auto* aabb = go->get<helios::engine::modules::physics::collision::components::AabbColliderComponent>();

307 assert(aabb && "unexpected missing AabbColliderComponent");

308

309 const auto& emitter = spawnContext.emitterContext;

310 auto* ebc = go->get<helios::engine::mechanics::spawn::components::EmittedByComponent>();

311 if (emitter.has_value() && ebc) {

312 ebc->setSource(emitter.value().source);

313 }

314

315 if (tsc) {

316

317 auto bounds = aabb->bounds();

318 ensureBounds(go.value(), bounds);

319

320 const auto position = spawnProfile->spawnPlacer->getPosition(

321 go->entityHandle(),

322 bounds,

323 updateContext.level()->bounds(),

324 {1, 1},

325 spawnContext

326

327 );

328 tsc->setTranslation(position);

329 }

330

331

332 assert(spawnProfile->spawnInitializer && "Unexpected missing spawn initializer");

333

334 spawnProfile->spawnInitializer->initialize(*go, {1, 1}, spawnContext);

335 sbp->setSpawnProfileId(spawnProfileId);

336

337 go->setActive(true);

338 }

339 }

Private Member Attributes

despawnCommands_

std::vector<DespawnCommand> helios::engine::runtime::spawn::SpawnManager::despawnCommands_

Queue of pending despawn commands.

Definition at line 126 of file SpawnManager.ixx.

126 std::vector<DespawnCommand> despawnCommands_;

gameObjectPoolManager_

helios::engine::runtime::pooling::GameObjectPoolManager* helios::engine::runtime::spawn::SpawnManager::gameObjectPoolManager_ = nullptr

Pointer to the pool manager for acquire/release operations.

Definition at line 136 of file SpawnManager.ixx.

136 helios::engine::runtime::pooling::GameObjectPoolManager* gameObjectPoolManager_ = nullptr;

scheduledSpawnPlanCommands_

std::vector<ScheduledSpawnPlanCommand> helios::engine::runtime::spawn::SpawnManager::scheduledSpawnPlanCommands_

Queue of pending scheduled spawn plan commands.

Definition at line 131 of file SpawnManager.ixx.

131 std::vector<ScheduledSpawnPlanCommand> scheduledSpawnPlanCommands_;

spawnCommands_

std::vector<SpawnCommand> helios::engine::runtime::spawn::SpawnManager::spawnCommands_

Queue of pending spawn commands.

Definition at line 121 of file SpawnManager.ixx.

121 std::vector<SpawnCommand> spawnCommands_;

spawnProfiles_

std::unordered_map< helios::engine::runtime::spawn::types::SpawnProfileId, std::unique_ptr<const SpawnProfile> > helios::engine::runtime::spawn::SpawnManager::spawnProfiles_

Map from profile IDs to their spawn profiles.

Definition at line 143 of file SpawnManager.ixx.

143 std::unique_ptr<const SpawnProfile>> spawnProfiles_;

spawnSchedulers_

std::vector<std::unique_ptr<helios::engine::runtime::spawn::scheduling::SpawnScheduler> > helios::engine::runtime::spawn::SpawnManager::spawnSchedulers_

Collection of schedulers that manage spawn rules and conditions.

Each scheduler owns and evaluates its registered spawn rules independently. When conditions are met, the scheduler produces ScheduledSpawnPlan instances for execution. Multiple schedulers allow grouping spawn rules by category (e.g., enemies, powerups, projectiles).

Definition at line 116 of file SpawnManager.ixx.

116 std::vector<std::unique_ptr<helios::engine::runtime::spawn::scheduling::SpawnScheduler>> spawnSchedulers_;

---

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

• SpawnManager.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.