Skip to main content

Phase.ixx File

Represents a phase within the game loop containing multiple passes. More...

Included Headers​

#include <memory> #include <vector> #include <helios.engine.runtime.world.Session> #include <helios.engine.runtime.world.GameWorld> #include <helios.engine.mechanics.gamestate.types> #include <helios.engine.runtime.gameloop.CommitPoint> #include <helios.engine.runtime.world.UpdateContext> #include <helios.engine.runtime.gameloop.TypedPass> #include <helios.engine.runtime.gameloop.Pass> #include <helios.engine.runtime.gameloop.PassCommitListener>

Namespaces Index​

namespacehelios
namespaceengine

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

namespaceruntime

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

namespacegameloop

Central game loop orchestration module. More...

Classes Index​

classPhase

Represents a phase in the game loop containing multiple passes. More...

Description​

Represents a phase within the game loop containing multiple passes.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file Phase.ixx
3 * @brief Represents a phase within the game loop containing multiple passes.
4 */
5module;
6
7#include <memory>
8#include <vector>
9
10export module helios.engine.runtime.gameloop.Phase;
11
12import helios.engine.runtime.gameloop.PassCommitListener;
13import helios.engine.runtime.gameloop.Pass;
14import helios.engine.runtime.gameloop.TypedPass;
15
16import helios.engine.runtime.world.UpdateContext;
17import helios.engine.runtime.world.GameWorld;
18
19import helios.engine.runtime.world.Session;
20
21import helios.engine.runtime.gameloop.CommitPoint;
22
23import helios.engine.mechanics.gamestate.types;
24
25using namespace helios::engine::mechanics::gamestate::types;
26using namespace helios::engine::runtime::world;
27
28export namespace helios::engine::runtime::gameloop {
29 class GameLoop;
30
31
32 /**
33 * @brief Enumeration of game loop phase types.
34 *
35 * The game loop is divided into three sequential phases:
36 * - **Pre:** Input processing and command generation.
37 * - **Main:** Core gameplay simulation (physics, AI, game logic).
38 * - **Post:** Synchronization, cleanup, and preparation for rendering.
39 */
40 enum class PhaseType {
41 /**
42 * @brief Pre-update phase for input and command processing.
43 */
44 Pre,
45
46 /**
47 * @brief Main update phase for core gameplay systems.
48 */
49 Main,
50
51 /**
52 * @brief Post-update phase for cleanup and scene synchronization.
53 */
54 Post
55 };
56
57 /**
58 * @brief Represents a phase in the game loop containing multiple passes.
59 *
60 * A Phase groups related systems into passes that are executed sequentially.
61 * Each pass can contain multiple systems and may have a commit point for
62 * event synchronization.
63 *
64 * Commit points allow fine-grained control over when commands are flushed,
65 * managers are processed, and pass-level events are synchronized. See
66 * CommitPoint for available synchronization options.
67 *
68 * Phases are owned by the GameLoop and should not be created directly.
69 *
70 * @see Pass
71 * @see CommitPoint
72 * @see GameLoop
73 */
74 class Phase {
75
76 friend class helios::engine::runtime::gameloop::GameLoop;
77
78 /**
79 * @brief Collection of listeners to be notified when a pass commits.
80 *
81 * @details Listeners are notified after each pass completes, receiving the
82 * pass's configured CommitPoint flags. The GameLoop registers itself as a
83 * listener to handle event buffer swapping, command flushing, and manager
84 * processing based on the commit point configuration.
85 *
86 * @see PassCommitListener
87 * @see notifyPassCommitListeners()
88 */
89 std::vector<PassCommitListener*> passCommitListeners_;
90
91
92
93 /**
94 * @brief Initializes all passes within this phase.
95 *
96 * @param gameWorld Reference to the game world.
97 */
98 void init(GameWorld& gameWorld){
99 for (auto& pass : passEntries_) {
100 // every pass contains systems that are updated here
101 pass->init(gameWorld);
102 }
103 };
104
105 /**
106 * @brief Updates all passes within this phase.
107 *
108 * @details Iterates through all passes, updating their systems and then
109 * invoking the commit action based on the pass's configured CommitPoint.
110 * The commit point determines whether pass-level events are synchronized,
111 * the command buffer is flushed, or managers are processed.
112 *
113 * Passes are conditionally executed based on their configured game state.
114 * A pass is only updated if its `runsIn()` state matches the current game state.
115 *
116 * @param gameWorld The game world where the update occurred.
117 * @param updateContext The current update context.
118 * @param gameState The current game state used to filter pass execution.
119 *
120 * @see CommitPoint
121 * @see Pass::addCommitPoint()
122 * @see Pass::runsIn()
123 */
124 void update(GameWorld& gameWorld, UpdateContext& updateContext){
125
126 for (auto& pass : passEntries_) {
127
128 if (pass->shouldRun(updateContext)) {
129 pass->update(updateContext);
130 notifyPassCommitListeners(pass->commitPoint(), gameWorld, updateContext);
131 }
132
133 }
134 };
135
136 /**
137 * @brief Notifies all registered listeners about a pass commit.
138 *
139 * @details Called after each pass completes its update cycle. Each registered
140 * PassCommitListener receives the commit point flags, allowing it to perform
141 * the appropriate synchronization actions (event swapping, command flushing,
142 * manager processing).
143 *
144 * @param commitPoint The CommitPoint flags from the completed pass.
145 * @param gameWorld The game world where the commit occured.
146 * @param updateContext The current update context.
147 *
148 * @return Always returns true.
149 *
150 * @see PassCommitListener::onPassCommit()
151 * @see addPassCommitListener()
152 */
153 bool notifyPassCommitListeners(CommitPoint commitPoint, GameWorld& gameWorld, UpdateContext& updateContext) {
154
155 for (const auto& passCommitListener : passCommitListeners_) {
156 passCommitListener->onPassCommit(commitPoint, gameWorld, updateContext);
157 }
158 return true;
159 }
160
161 /**
162 * @brief Collection of passes belonging to this phase.
163 */
164 std::vector<std::unique_ptr<Pass>> passEntries_;
165
166 /**
167 * @brief Reference to the owning GameLoop.
168 */
169 helios::engine::runtime::gameloop::GameLoop& gameloop_;
170
171 public:
172
173 /**
174 * @brief Constructs a Phase with a reference to its owning GameLoop.
175 *
176 * @param gameloop Reference to the parent GameLoop.
177 */
178 explicit Phase(helios::engine::runtime::gameloop::GameLoop& gameloop) : gameloop_(gameloop) {
179
180 }
181
182
183 /**
184 * @brief Registers a listener to be notified when passes commit.
185 *
186 * @details The listener will receive notifications for all passes within this phase.
187 * The GameLoop typically registers itself to handle event synchronization,
188 * command buffer flushing, and manager processing based on commit point flags.
189 *
190 * Duplicate registrations are prevented; attempting to add the same listener
191 * twice will return false and leave the listener list unchanged.
192 *
193 * @param passCommitListener Pointer to the listener to register. Must remain
194 * valid for the lifetime of this Phase or until removed.
195 *
196 * @return True if the listener was added, false if it was already registered.
197 *
198 * @see PassCommitListener
199 * @see notifyPassCommitListeners()
200 */
201 bool addPassCommitListener(PassCommitListener* passCommitListener) {
202
203 for (int i = 0; i < passCommitListeners_.size(); i++) {
204 if (passCommitListeners_[i] == passCommitListener) {
205 return false;
206 }
207 }
208
209 passCommitListeners_.emplace_back(passCommitListener);
210
211 return true;
212 }
213
214 /**
215 * @brief Creates and adds a new typed pass to this phase.
216 *
217 * @details The state parameter specifies in which states this pass
218 * should execute. Passes are skipped if the current state does not
219 * match the configured mask (using bitwise AND).
220 *
221 * @tparam StateType The state enum type (e.g., GameState, MatchState).
222 *
223 * @param t The state mask specifying when this pass should run.
224 *
225 * @return Reference to the newly created Pass for method chaining.
226 *
227 * @see TypedPass
228 * @see Session::state()
229 */
230 template<typename StateType>
231 Pass& addPass(const StateType t) {// const helios::engine::mechanics::gamestate::types::GameState gameState = helios::engine::mechanics::gamestate::types::GameState::Any) {
232
233 auto entry = std::make_unique<TypedPass<StateType>>(*this, t);
234 auto* raw = entry.get();
235 passEntries_.emplace_back(std::move(entry));
236
237 return *raw;
238 }
239
240 /**
241 * @brief Returns a reference to the owning GameLoop.
242 *
243 * @return Reference to the parent GameLoop.
244 */
245 [[nodiscard]] helios::engine::runtime::gameloop::GameLoop& gameLoop() noexcept {
246 return gameloop_;
247 }
248
249
250 };
251
252}

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.