Skip to main content

DelayedComponentEnabler.ixx File

Component for scheduling delayed activation of other components. More...

Included Headers​

#include <cassert> #include <span> #include <typeindex> #include <memory> #include <vector> #include <helios.core.types> #include <helios.engine.core.data.SpawnProfileId> #include <helios.engine.core.data.ComponentTypeId> #include <helios.engine.ecs.GameObject>

Namespaces Index​

namespacehelios
namespaceengine

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

namespacemechanics

High-level gameplay systems and components for game logic. More...

namespacelifecycle

Lifecycle management for entity components. More...

namespacecomponents

Components for managing entity lifecycle states. More...

Classes Index​

classDelayedComponentEnabler

Component that manages delayed activation of other components. More...

structDeferredComponent

Internal structure tracking a deferred component. More...

Description​

Component for scheduling delayed activation of other components.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file DelayedComponentEnabler.ixx
3 * @brief Component for scheduling delayed activation of other components.
4 */
5module;
6
7#include <cassert>
8#include <span>
9#include <typeindex>
10#include <memory>
11#include <vector>
12
13export module helios.engine.mechanics.lifecycle.components.DelayedComponentEnabler;
14
15
16
17import helios.engine.ecs.GameObject;
18import helios.engine.core.data.SpawnProfileId;
19import helios.engine.core.data.ComponentTypeId;
20import helios.core.types;
21
22export namespace helios::engine::mechanics::lifecycle::components {
23
24 /**
25 * @brief Component that manages delayed activation of other components.
26 *
27 * @details DelayedComponentEnabler maintains a list of components that should
28 * be activated after a specified delay. This is useful for gameplay patterns
29 * where newly spawned entities need temporary immunity or staggered activation:
30 * - **Collision immunity:** Projectiles ignore collisions briefly after spawn
31 * - **AI warmup:** Behavior components activate after positioning completes
32 * - **Visual fade-in:** Rendering components enable after spawn effects
33 * - **Staggered waves:** Sequential entities activate progressively
34 *
35 * The component works in conjunction with DelayedComponentEnablerSystem, which
36 * decrements timers each frame and enables components when their delay expires.
37 *
38 * @note Components are disabled immediately when deferred and re-enabled
39 * automatically by the system when the delay reaches zero.
40 *
41 * @see DelayedComponentEnablerSystem
42 * @see DelayedComponentEnablerInitializer
43 */
44 class DelayedComponentEnabler {
45
46 /**
47 * @brief Internal structure tracking a deferred component.
48 */
49 struct DeferredComponent {
50 /**
51 * @brief Remaining time in seconds until activation.
52 */
53 float delta;
54
55 /**
56 * @brief Type identifier of the deferred component.
57 */
58 helios::engine::core::data::ComponentTypeId componentTypeId;
59 };
60
61 /**
62 * @brief List of components pending delayed activation.
63 */
64 std::vector<DeferredComponent> deferredComponents_;
65
66 public:
67
68 /**
69 * @brief Default constructor.
70 */
71 DelayedComponentEnabler() = default;
72
73 /**
74 * @brief Copy constructor for cloning during spawn.
75 *
76 * @param other The source component to copy from.
77 */
78 DelayedComponentEnabler(const DelayedComponentEnabler& other)
79 : deferredComponents_(other.deferredComponents_) {}
80
81 DelayedComponentEnabler& operator=(const DelayedComponentEnabler&) = default;
82 DelayedComponentEnabler(DelayedComponentEnabler&&) noexcept = default;
83 DelayedComponentEnabler& operator=(DelayedComponentEnabler&&) noexcept = default;
84
85 /**
86 * @brief Returns a view of all currently deferred components.
87 *
88 * @return Span of DeferredComponent entries with remaining delays.
89 */
90 std::span<DeferredComponent> deferredComponents() noexcept {
91 return deferredComponents_;
92 }
93
94 /**
95 * @brief Removes activated components from the deferred list.
96 *
97 * @details Called by the system after enabling components to clean up
98 * entries that have completed their delay period.
99 *
100 * @param removeList Component type IDs to remove from tracking.
101 */
102 void sync(std::span<helios::engine::core::data::ComponentTypeId> removeList) {
103 std::erase_if(deferredComponents_, [&](const DeferredComponent& dc) {
104 return std::ranges::find(removeList, dc.componentTypeId) != removeList.end();
105 });
106 }
107
108 /**
109 * @brief Schedules a component for delayed activation.
110 *
111 * @details The specified component is immediately disabled and added to
112 * the deferred list. If the component is already deferred, its delay is
113 * updated to the new value.
114 *
115 * @param componentTypeId Type identifier of the component to defer.
116 * @param delta Delay in seconds before activation.
117 *
118 * @note Asserts if delta <= 0 or if the component does not exist on the entity.
119 */
120 void defer(
121 helios::engine::ecs::GameObject gameObject,
122 helios::engine::core::data::ComponentTypeId componentTypeId, const float delta) {
123 assert(delta > 0 && "delta must be greater than 0");
124
125 const bool hasCmp = gameObject.has(componentTypeId);
126 assert(hasCmp && "ComponentTypeId not part of GameObject");
127
128 const auto it = std::ranges::find_if(deferredComponents_,
129 [componentTypeId](const auto& item) {
130 return item.componentTypeId == componentTypeId;
131 });
132
133 gameObject.disableComponent(componentTypeId);
134
135 if (it == deferredComponents_.end()) {
136 deferredComponents_.push_back({delta, componentTypeId});
137 } else {
138 it->delta = delta;
139 }
140 }
141
142
143 };
144
145}

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.