Skip to main content

DelayedComponentEnablerInitializer.ixx File

Initializer that schedules delayed activation of specified components. More...

Included Headers​

#include <cassert> #include <typeindex> #include <vector> #include <helios.engine.ecs.types.ComponentTypeId> #include <helios.engine.mechanics.lifecycle.components.DelayedComponentEnabler> #include <helios.engine.ecs.GameObject> #include <helios.engine.runtime.spawn.types.SpawnContext> #include <helios.engine.runtime.spawn.types.SpawnPlanCursor> #include <helios.engine.runtime.spawn.behavior.SpawnInitializer>

Namespaces Index​

namespacehelios
namespaceengine

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

namespaceruntime

Runtime infrastructure for game execution and lifecycle orchestration. More...

namespacespawn

Entity spawning infrastructure for the helios engine. More...

namespacebehavior

Spawn behavior strategies for positioning and initializing entities. More...

namespaceinitializers

Concrete SpawnInitializer implementations. More...

Classes Index​

classDelayedComponentEnablerInitializer<ComponentTypes>

Initializer that schedules delayed activation of arbitrary components. More...

Description​

Initializer that schedules delayed activation of specified components.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file DelayedComponentEnablerInitializer.ixx
3 * @brief Initializer that schedules delayed activation of specified components.
4 */
5module;
6
7#include <cassert>
8#include <typeindex>
9#include <vector>
10
11export module helios.engine.runtime.spawn.behavior.initializers.DelayedComponentEnablerInitializer;
12
13
14import helios.engine.runtime.spawn.behavior.SpawnInitializer;
15import helios.engine.runtime.spawn.types.SpawnPlanCursor;
16import helios.engine.runtime.spawn.types.SpawnContext;
17import helios.engine.ecs.GameObject;
18
19import helios.engine.mechanics.lifecycle.components.DelayedComponentEnabler;
20import helios.engine.ecs.types.ComponentTypeId;
21
22using namespace helios::engine::runtime::spawn::types;
23export namespace helios::engine::runtime::spawn::behavior::initializers {
24
25 /**
26 * @brief Initializer that schedules delayed activation of arbitrary components.
27 *
28 * @details DelayedComponentEnablerInitializer defers the activation of specified
29 * components until a calculated delay has elapsed. This enables gameplay patterns
30 * such as:
31 * - **Collision immunity:** Newly spawned entities ignore collisions briefly
32 * - **Visibility fade-in:** Rendering components activate after spawn animation
33 * - **AI activation:** Behavior components enable after entity is fully placed
34 * - **Staggered waves:** Sequential spawns activate progressively
35 *
36 * The delay for each entity is calculated as:
37 * `delay = (batchPosition + 1) * baseDelay`
38 *
39 * An optional cycle length resets the batch position via modulo, useful for
40 * repeating spawn patterns where delay should not grow indefinitely.
41 *
42 * @tparam ComponentTypes The component types whose activation should be deferred.
43 *
44 * @note The entity must have a DelayedComponentEnabler component attached.
45 * The specified ComponentTypes must exist on the entity.
46 *
47 * @see SpawnInitializer
48 * @see DelayedComponentEnabler
49 */
50 template<typename... ComponentTypes>
51 class DelayedComponentEnablerInitializer final : public SpawnInitializer {
52
53 /**
54 * @brief Base delay in seconds between activations.
55 */
56 const float delay_;
57
58 /**
59 * @brief Cycle length for repeating delay patterns.
60 *
61 * If non-zero, position indices wrap around after this many spawns.
62 * If zero, positions increase indefinitely.
63 */
64 const size_t cycleLength_;
65
66 /**
67 * @brief Type IDs of components whose activation should be deferred.
68 */
69 std::vector<helios::engine::ecs::types::ComponentTypeId> deferredComponents_;
70
71 public:
72
73 /**
74 * @brief Constructs the initializer with delay and optional cycle length.
75 *
76 * @param delay Base delay in seconds between each activation step.
77 * @param cycleLength Number of positions before the delay pattern repeats.
78 * Zero means no cycling (default).
79 */
80 DelayedComponentEnablerInitializer(const float delay, const size_t cycleLength = 0) :
81 delay_(delay),
82 cycleLength_(cycleLength),
83 deferredComponents_{helios::engine::ecs::types::ComponentTypeId::id<ComponentTypes>() ...}
84 {}
85
86 /**
87 * @brief Schedules delayed activation of the configured component types.
88 *
89 * @details Searches the entity's components for matches against the template
90 * ComponentTypes. Each matching component is registered with the entity's
91 * DelayedComponentEnabler for deferred activation. The delay duration depends
92 * on the spawn batch position and the configured base delay.
93 *
94 * @param gameObject The entity to initialize.
95 * @param cursor Provides batch position for delay calculation.
96 * @param spawnContext Context data (unused).
97 */
98 void initialize(
99 helios::engine::ecs::GameObject gameObject,
100 const SpawnPlanCursor& cursor,
101 const SpawnContext& spawnContext
102 ) override {
103
104 bool deferFound = false;
105
106 auto position = cycleLength_ != 0 ? cursor.position % cycleLength_ : cursor.position;
107
108 for (auto typeId : gameObject.componentTypeIds()) {
109
110 // Find the component that should be deferred.
111 const bool deferThisComponent = std::find(
112 deferredComponents_.begin(), deferredComponents_.end(), typeId
113 ) != deferredComponents_.end();
114
115 if (deferThisComponent) {
116 deferFound = true;
117 auto* dec = gameObject.get<helios::engine::mechanics::lifecycle::components::DelayedComponentEnabler>();
118 assert(dec && "Missing DelayedComponentEnabler");
119
120 dec->defer(gameObject, typeId, (position + 1) * delay_);
121 }
122 }
123
124 assert(deferFound && "Unexpected missing deferrable component");
125 }
126
127 };
128
129}
130
131

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.