Skip to main content

SpawnPoolConfig.ixx File

Fluent configuration for a complete spawn pool with profiles and scheduling. More...

Included Headers​

#include <memory> #include <vector> #include <helios.math> #include <helios.engine.runtime.spawn> #include <helios.engine.runtime.spawn.types> #include <helios.engine.runtime.pooling> #include <helios.engine.common.types.PrefabId> #include <helios.engine.runtime.pooling.types.GameObjectPoolId> #include <helios.engine.ecs>

Namespaces Index​

namespacehelios
namespaceengine

Main engine module aggregating core infrastructure and game systems. More...

namespacebuilder

Fluent builder pattern for constructing GameObjects. More...

namespacespawnSystem
namespacebuilders
namespaceconfigs

Classes Index​

classSpawnSystemConfigurator

Lightweight handle for chaining pool configurations. More...

classSpawnRuleConfig

Fluent configuration for a spawn rule bound to a profile. More...

classSpawnProfileConfig

Fluent configuration for a spawn profile bound to a pool. More...

classSpawnPoolConfig

ID-centric configuration for a spawn pool with associated profiles. More...

Description​

Fluent configuration for a complete spawn pool with profiles and scheduling.

This file contains SpawnSystemConfigurator, SpawnRuleConfig, SpawnProfileConfig, and SpawnPoolConfig in a single translation unit. These classes form a cyclic done()-chaining dependency (Rule → Profile → Pool → Configurator → Pool) so we will not split them in separate files.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file SpawnPoolConfig.ixx
3 * @brief Fluent configuration for a complete spawn pool with profiles and scheduling.
4 *
5 * @details This file contains SpawnSystemConfigurator, SpawnRuleConfig,
6 * SpawnProfileConfig, and SpawnPoolConfig in a single translation unit.
7 * These classes form a cyclic done()-chaining dependency
8 * (Rule → Profile → Pool → Configurator → Pool) so we will not split them in separate files.
9 */
10module;
11
12#include <memory>
13#include <vector>
14
15export module helios.engine.builder.spawnSystem.builders.configs.SpawnPoolConfig;
16
17import helios.engine.ecs;
18
19import helios.engine.runtime.pooling.types.GameObjectPoolId;
20import helios.engine.common.types.PrefabId;
21
22import helios.engine.runtime.pooling;
23
24import helios.engine.runtime.spawn;
25import helios.engine.runtime.spawn.types;
26
27import helios.math;
28
29using namespace helios::engine::runtime::spawn::types;
30export namespace helios::engine::builder::spawnSystem::builders::configs {
31
32 // Forward declarations for nested builder return types.
33 class SpawnPoolConfig;
34 class SpawnProfileConfig;
35 class SpawnRuleConfig;
36
37 /**
38 * @brief Lightweight handle for chaining pool configurations.
39 *
40 * Returned by commit() and commitCyclic() to allow starting
41 * the next pool() call. Holds only the two manager references.
42 */
43 class SpawnSystemConfigurator {
44
45 /**
46 * @brief The pool manager for pool registration.
47 */
48 helios::engine::runtime::pooling::GameObjectPoolManager& poolManager_;
49
50 /**
51 * @brief The spawn manager for profile and scheduler registration.
52 */
53 helios::engine::runtime::spawn::SpawnManager& spawnManager_;
54
55 public:
56
57 /**
58 * @brief Constructs a configurator with the given managers.
59 *
60 * @param poolManager The pool manager for pool registration.
61 * @param spawnManager The spawn manager for profile and scheduler registration.
62 */
63 SpawnSystemConfigurator(
64 helios::engine::runtime::pooling::GameObjectPoolManager& poolManager,
65 helios::engine::runtime::spawn::SpawnManager& spawnManager
66 ) noexcept : poolManager_(poolManager), spawnManager_(spawnManager) {}
67
68 /**
69 * @brief Begins ID-centric configuration of a spawn pool.
70 *
71 * @param poolId Unique pool identifier.
72 * @param prefab Template GameObject for cloning.
73 * @param poolSize Number of instances to pre-allocate.
74 *
75 * @return SpawnPoolConfig for fluent configuration.
76 */
77 [[nodiscard]] SpawnPoolConfig pool(
78 helios::engine::runtime::pooling::types::GameObjectPoolId poolId,
79 helios::engine::common::types::PrefabId prefabId,
80 size_t poolSize
81 );
82 };
83
84 /**
85 * @brief Fluent configuration for a spawn rule bound to a profile.
86 *
87 * Configures the condition and amount for a scheduled spawn rule.
88 * Returns to the parent SpawnProfileConfig via done().
89 */
90 class SpawnRuleConfig {
91
92 /**
93 * @brief Parent profile this rule belongs to.
94 */
95 SpawnProfileConfig& parent_;
96
97 /**
98 * @brief Unique identifier for this rule.
99 */
100 helios::engine::runtime::spawn::types::SpawnRuleId ruleId_;
101
102 /**
103 * @brief Condition determining when to spawn.
104 */
105 std::unique_ptr<const helios::engine::runtime::spawn::policy::SpawnCondition> condition_;
106
107 /**
108 * @brief Provider determining how many to spawn.
109 */
110 std::unique_ptr<const helios::engine::runtime::spawn::policy::amount::SpawnAmountProvider> amountProvider_;
111
112 public:
113
114 /**
115 * @brief Constructs a SpawnRuleConfig.
116 *
117 * @param parent The parent profile config.
118 * @param ruleId Unique identifier for this rule.
119 */
120 SpawnRuleConfig(
121 SpawnProfileConfig& parent,
122 helios::engine::runtime::spawn::types::SpawnRuleId ruleId
123 ) : parent_(parent), ruleId_(ruleId),
124 condition_(nullptr), amountProvider_(nullptr) {}
125
126 /**
127 * @brief Sets a timer-based spawn condition.
128 *
129 * @param intervalSeconds Seconds between spawn evaluations.
130 *
131 * @return Reference to this config for chaining.
132 */
133 SpawnRuleConfig& timerCondition(const float intervalSeconds) {
134 condition_ = std::make_unique<
135 helios::engine::runtime::spawn::policy::conditions::TimerSpawnCondition>(
136 intervalSeconds);
137 return *this;
138 }
139
140 /**
141 * @brief Sets a combined condition: timer + pool availability.
142 *
143 * @param intervalSeconds Seconds between spawn evaluations.
144 *
145 * @return Reference to this config for chaining.
146 */
147 SpawnRuleConfig& timerWithAvailabilityCondition(const float intervalSeconds) {
148 condition_ = std::make_unique<
149 helios::engine::runtime::spawn::policy::SpawnConditionAll>(
150 std::make_unique<helios::engine::runtime::spawn::policy::conditions::TimerSpawnCondition>(intervalSeconds),
151 std::make_unique<helios::engine::runtime::spawn::policy::conditions::RequestedAmountIsAvailableCondition>()
152 );
153 return *this;
154 }
155
156 /**
157 * @brief Sets a custom spawn condition.
158 *
159 * @param customCondition Ownership is transferred.
160 *
161 * @return Reference to this config for chaining.
162 */
163 SpawnRuleConfig& condition(
164 std::unique_ptr<const helios::engine::runtime::spawn::policy::SpawnCondition> customCondition
165 ) {
166 condition_ = std::move(customCondition);
167 return *this;
168 }
169
170 /**
171 * @brief Sets a fixed spawn amount.
172 *
173 * @param count Number of entities to spawn per trigger.
174 *
175 * @return Reference to this config for chaining.
176 */
177 SpawnRuleConfig& fixedAmount(const size_t count) {
178 amountProvider_ = std::make_unique<
179 helios::engine::runtime::spawn::policy::amount::FixedSpawnAmount>(count);
180 return *this;
181 }
182
183 /**
184 * @brief Sets a custom amount provider.
185 *
186 * @param customProvider Ownership is transferred.
187 *
188 * @return Reference to this config for chaining.
189 */
190 SpawnRuleConfig& amount(
191 std::unique_ptr<const helios::engine::runtime::spawn::policy::amount::SpawnAmountProvider> customProvider
192 ) {
193 amountProvider_ = std::move(customProvider);
194 return *this;
195 }
196
197 /**
198 * @brief Builds the SpawnRule from this configuration.
199 *
200 * @return The assembled SpawnRule.
201 */
202 [[nodiscard]] std::unique_ptr<helios::engine::runtime::spawn::policy::SpawnRule> build() {
203 return std::make_unique<helios::engine::runtime::spawn::policy::SpawnRule>(
204 std::move(condition_),
205 std::move(amountProvider_),
206 ruleId_
207 );
208 }
209
210 /**
211 * @brief Finalizes the rule and returns to the parent profile config.
212 *
213 * @return Reference to the parent SpawnProfileConfig.
214 */
215 SpawnProfileConfig& done();
216 };
217
218 /**
219 * @brief Fluent configuration for a spawn profile bound to a pool.
220 *
221 * Configures placement, initialization, and optional scheduling rules
222 * for a specific spawn profile. Returns to the parent SpawnPoolConfig
223 * via done().
224 */
225 class SpawnProfileConfig {
226
227 /**
228 * @brief Parent pool this profile belongs to.
229 */
230 SpawnPoolConfig& parent_;
231
232 /**
233 * @brief The spawn manager to register with.
234 */
235 helios::engine::runtime::spawn::SpawnManager& spawnManager_;
236
237 /**
238 * @brief Profile identifier.
239 */
240 helios::engine::runtime::spawn::types::SpawnProfileId profileId_;
241
242 /**
243 * @brief Pool to acquire entities from.
244 */
245 helios::engine::runtime::pooling::types::GameObjectPoolId poolId_;
246
247 /**
248 * @brief Placement strategy for spawned entities.
249 */
250 std::unique_ptr<helios::engine::runtime::spawn::behavior::SpawnPlacer> placer_;
251
252 /**
253 * @brief Initialization strategy for spawned entities.
254 */
255 std::unique_ptr<helios::engine::runtime::spawn::behavior::SpawnInitializer> initializer_;
256
257 /**
258 * @brief Scheduled rules for this profile.
259 */
260 std::vector<std::unique_ptr<SpawnRuleConfig>> rules_;
261
262 public:
263
264 /**
265 * @brief Constructs a SpawnProfileConfig.
266 *
267 * @param parent The parent pool config.
268 * @param spawnManager The spawn manager to register profiles with.
269 * @param profileId Unique identifier for the profile.
270 * @param poolId Pool from which entities are acquired.
271 */
272 SpawnProfileConfig(
273 SpawnPoolConfig& parent,
274 helios::engine::runtime::spawn::SpawnManager& spawnManager,
275 helios::engine::runtime::spawn::types::SpawnProfileId profileId,
276 helios::engine::runtime::pooling::types::GameObjectPoolId poolId
277 ) : parent_(parent), spawnManager_(spawnManager),
278 profileId_(profileId), poolId_(poolId) {}
279
280 /**
281 * @brief Configures emitter-relative placement and initialization.
282 *
283 * @return Reference to this config for chaining.
284 */
285 SpawnProfileConfig& emitterPlacement() {
286 placer_ = std::make_unique<
287 helios::engine::runtime::spawn::behavior::placements::EmitterSpawnPlacer>();
288 initializer_ = std::make_unique<
289 helios::engine::runtime::spawn::behavior::initializers::EmitterInitializer>();
290 return *this;
291 }
292
293 /**
294 * @brief Configures random placement within level bounds.
295 *
296 * @return Reference to this config for chaining.
297 */
298 SpawnProfileConfig& randomPlacement() {
299 placer_ = std::make_unique<
300 helios::engine::runtime::spawn::behavior::placements::RandomSpawnPlacer>();
301 return *this;
302 }
303
304 /**
305 * @brief Configures axis-aligned placement.
306 *
307 * @param axis Direction axis for spawn distribution.
308 * @param origin Starting point of the axis.
309 *
310 * @return Reference to this config for chaining.
311 */
312 SpawnProfileConfig& axisPlacement(
313 const helios::math::vec3f& axis,
314 const helios::math::vec3f& origin
315 ) {
316 placer_ = std::make_unique<
317 helios::engine::runtime::spawn::behavior::placements::AxisSpawnPlacer>(axis, origin);
318 return *this;
319 }
320
321 /**
322 * @brief Sets a custom spawn placer.
323 *
324 * @param customPlacer Ownership is transferred.
325 *
326 * @return Reference to this config for chaining.
327 */
328 SpawnProfileConfig& placer(
329 std::unique_ptr<helios::engine::runtime::spawn::behavior::SpawnPlacer> customPlacer
330 ) {
331 placer_ = std::move(customPlacer);
332 return *this;
333 }
334
335 /**
336 * @brief Configures a move initializer with random direction.
337 *
338 * @return Reference to this config for chaining.
339 */
340 SpawnProfileConfig& randomDirectionInitializer() {
341 initializer_ = std::make_unique<
342 helios::engine::runtime::spawn::behavior::initializers::MoveInitializer>(
343 helios::engine::runtime::spawn::behavior::initializers::DirectionType::Random);
344 return *this;
345 }
346
347 /**
348 * @brief Configures a move initializer with a fixed direction.
349 *
350 * @param direction The movement direction.
351 *
352 * @return Reference to this config for chaining.
353 */
354 SpawnProfileConfig& moveInitializer(const helios::math::vec3f& direction) {
355 initializer_ = std::make_unique<
356 helios::engine::runtime::spawn::behavior::initializers::MoveInitializer>(direction);
357 return *this;
358 }
359
360 /**
361 * @brief Sets a custom spawn initializer.
362 *
363 * @param customInitializer Ownership is transferred.
364 *
365 * @return Reference to this config for chaining.
366 */
367 SpawnProfileConfig& initializer(
368 std::unique_ptr<helios::engine::runtime::spawn::behavior::SpawnInitializer> customInitializer
369 ) {
370 initializer_ = std::move(customInitializer);
371 return *this;
372 }
373
374 /**
375 * @brief Begins configuration of a scheduled spawn rule for this profile.
376 *
377 * @param ruleId Unique identifier for the rule.
378 *
379 * @return Reference to the new rule config for chaining.
380 */
381 SpawnRuleConfig& scheduledBy(helios::engine::runtime::spawn::types::SpawnRuleId ruleId) {
382 rules_.push_back(std::make_unique<SpawnRuleConfig>(*this, ruleId));
383 return *rules_.back();
384 }
385
386 /**
387 * @brief Returns the profile ID.
388 *
389 * @return The spawn profile ID.
390 */
391 [[nodiscard]] helios::engine::runtime::spawn::types::SpawnProfileId profileId() const noexcept {
392 return profileId_;
393 }
394
395 /**
396 * @brief Commits the profile and builds any associated rules.
397 *
398 * @return Vector of built spawn rules (may be empty).
399 */
400 std::vector<std::pair<helios::engine::runtime::spawn::types::SpawnProfileId,
401 std::unique_ptr<helios::engine::runtime::spawn::policy::SpawnRule>>>
402 commit() {
403 spawnManager_.addSpawnProfile(
404 profileId_,
405 std::make_unique<SpawnProfile>(
406 SpawnProfile{
407 .gameObjectPoolId = poolId_,
408 .spawnPlacer = std::move(placer_),
409 .spawnInitializer = std::move(initializer_)
410 }
411 )
412 );
413
414 std::vector<std::pair<helios::engine::runtime::spawn::types::SpawnProfileId,
415 std::unique_ptr<helios::engine::runtime::spawn::policy::SpawnRule>>> result;
416 for (auto& rule : rules_) {
417 result.emplace_back(profileId_, rule->build());
418 }
419 return result;
420 }
421
422 /**
423 * @brief Finalizes the profile and returns to the parent pool config.
424 *
425 * @return Reference to the parent SpawnPoolConfig.
426 */
427 SpawnPoolConfig& done();
428 };
429
430 /**
431 * @brief ID-centric configuration for a spawn pool with associated profiles.
432 *
433 * @details Bundles a pool ID with its PrefabId, pool size, and one or more
434 * spawn profiles. Each profile can optionally have scheduled rules.
435 * Calling commit() registers the pool, all profiles, and any
436 * scheduled rules with a DefaultSpawnScheduler.
437 *
438 * @see SpawnProfileConfig
439 * @see SpawnRuleConfig
440 * @see SpawnSystemFactory
441 */
442 class SpawnPoolConfig {
443
444 /**
445 * @brief The pool manager to register with.
446 */
447 helios::engine::runtime::pooling::GameObjectPoolManager& poolManager_;
448
449 /**
450 * @brief The spawn manager to register profiles with.
451 */
452 helios::engine::runtime::spawn::SpawnManager& spawnManager_;
453
454 /**
455 * @brief Pool identifier.
456 */
457 helios::engine::runtime::pooling::types::GameObjectPoolId poolId_;
458
459 /**
460 * @brief Identifier of the prefab template for cloning.
461 */
462 helios::engine::common::types::PrefabId prefabId_;
463
464 /**
465 * @brief Number of instances to pre-allocate.
466 */
467 size_t size_;
468
469 /**
470 * @brief Profile configurations attached to this pool.
471 */
472 std::vector<std::unique_ptr<SpawnProfileConfig>> profiles_;
473
474
475
476 public:
477
478 /**
479 * @brief Constructs a SpawnPoolConfig.
480 *
481 * @param poolManager The pool manager to register pools with.
482 * @param spawnManager The spawn manager to register profiles with.
483 * @param poolId Unique identifier for the pool.
484 * @param prefabId Identifier of the prefab template for cloning.
485 * @param poolSize Number of instances to pre-allocate.
486 */
487 SpawnPoolConfig(
488 helios::engine::runtime::pooling::GameObjectPoolManager& poolManager,
489 helios::engine::runtime::spawn::SpawnManager& spawnManager,
490 helios::engine::runtime::pooling::types::GameObjectPoolId poolId,
491 helios::engine::common::types::PrefabId prefabId,
492 size_t poolSize
493 ) : poolManager_(poolManager), spawnManager_(spawnManager),
494 poolId_(poolId), prefabId_(prefabId), size_(poolSize) {}
495
496
497 /**
498 * @brief Begins configuration of a spawn profile for this pool.
499 *
500 * @param profileId Unique identifier for the profile.
501 *
502 * @return Reference to the new profile config for chaining.
503 */
504 SpawnProfileConfig& profile(helios::engine::runtime::spawn::types::SpawnProfileId profileId) {
505 profiles_.push_back(std::make_unique<SpawnProfileConfig>(
506 *this, spawnManager_, profileId, poolId_
507 ));
508 return *profiles_.back();
509 }
510
511 /**
512 * @brief Commits pool, all profiles, and registers scheduled rules.
513 *
514 * Profiles with scheduled rules are automatically registered
515 * with a DefaultSpawnScheduler per profile.
516 *
517 * @return Configurator for chaining the next pool() call.
518 */
519 SpawnSystemConfigurator commit() {
520 commitPool();
521 commitProfiles(false);
522 return SpawnSystemConfigurator{poolManager_, spawnManager_};
523 }
524
525 /**
526 * @brief Commits pool and profiles without creating any schedulers.
527 *
528 * @details Use this when profiles should be registered but scheduling
529 * is handled separately (e.g., via SchedulerBuilder). Rules attached
530 * via scheduledBy() are silently discarded.
531 *
532 * This enables reuse of the same profile configuration under different
533 * scheduling strategies:
534 *
535 * ```cpp
536 * // Register pool + profiles (no schedulers)
537 * spawns.pool(PoolId, PrefabId, 100)
538 * .profile(LeftId).axisPlacement(...).moveInitializer(...).done()
539 * .profile(RightId).axisPlacement(...).moveInitializer(...).done()
540 * .commitProfilesOnly();
541 *
542 * // Attach scheduling separately
543 * SchedulerBuilder sb(spawnManager);
544 * sb.cyclicScheduler(
545 * SchedulerConfig(LeftId, Rule1).timerCondition(5.0f).fixedAmount(10),
546 * SchedulerConfig(RightId, Rule2).timerCondition(5.0f).fixedAmount(10)
547 * );
548 * ```
549 *
550 * @return Configurator for chaining the next pool() call.
551 */
552 SpawnSystemConfigurator commitProfilesOnly() {
553 commitPool();
554 commitProfiles(true);
555 return SpawnSystemConfigurator{poolManager_, spawnManager_};
556 }
557
558 /**
559 * @brief Commits with all scheduled rules in a single CyclicSpawnScheduler.
560 *
561 * @details Use this when multiple profiles share a cyclic spawn
562 * pattern (e.g., wave-based edge spawning). All rules across all
563 * profiles are bundled into one CyclicSpawnScheduler.
564 *
565 * @tparam N Number of rules in the cyclic scheduler.
566 *
567 * @return Configurator for chaining the next pool() call.
568 */
569 template<std::size_t N>
570 SpawnSystemConfigurator commitCyclic() {
571 commitPool();
572
573 auto scheduler = std::make_unique<
574 helios::engine::runtime::spawn::scheduling::CyclicSpawnScheduler<N>>();
575
576 for (auto& profileConfig : profiles_) {
577 auto rules = profileConfig->commit();
578 for (auto& [profileId, rule] : rules) {
579 scheduler->addRule(profileId, std::move(rule));
580 }
581 }
582
583 spawnManager_.addScheduler(std::move(scheduler));
584 return SpawnSystemConfigurator{poolManager_, spawnManager_};
585 }
586
587 private:
588
589 /**
590 * @brief Registers the pool with the pool manager.
591 */
592 void commitPool() {
593
594 poolManager_.addPoolConfig(
595 std::make_unique<helios::engine::runtime::pooling::GameObjectPoolConfig>(
596 poolId_, prefabId_, size_
597 )
598 );
599 }
600
601 /**
602 * @brief Commits all profiles and optionally creates per-profile schedulers.
603 *
604 * @param skipSchedulers If true, profiles are committed without scheduler creation.
605 */
606 void commitProfiles(bool skipSchedulers) {
607 for (auto& profileConfig : profiles_) {
608 auto rules = profileConfig->commit();
609 if (!skipSchedulers && !rules.empty()) {
610 auto scheduler = std::make_unique<
611 helios::engine::runtime::spawn::scheduling::DefaultSpawnScheduler>();
612 for (auto& [profileId, rule] : rules) {
613 scheduler->addRule(profileId, std::move(rule));
614 }
615 spawnManager_.addScheduler(std::move(scheduler));
616 }
617 }
618 }
619 };
620
621 // Out-of-line definitions for done() and pool() methods.
622
623 inline SpawnProfileConfig& SpawnRuleConfig::done() {
624 return parent_;
625 }
626
627 inline SpawnPoolConfig& SpawnProfileConfig::done() {
628 return parent_;
629 }
630
631 inline SpawnPoolConfig SpawnSystemConfigurator::pool(
632 helios::engine::runtime::pooling::types::GameObjectPoolId poolId,
633 helios::engine::common::types::PrefabId prefabId,
634 size_t poolSize
635 ) {
636 return SpawnPoolConfig{poolManager_, spawnManager_, poolId, prefabId, poolSize};
637 }
638
639
640}
641
642
643
644
645
646
647

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.