UpdateContext.ixx File

Context struct passed to components during per-frame updates. More...

Included Headers

#include <span> #include <helios.engine.runtime.messaging.event.GameLoopEventBus> #include <helios.rendering.ViewportSnapshot> #include <helios.input.InputSnapshot>

Namespaces Index

namespace	helios
namespace	engine
	Main engine module aggregating core infrastructure and game systems. More...
namespace	runtime
	Runtime infrastructure for game execution and lifecycle orchestration. More...
namespace	messaging
	Communication infrastructure for commands and events. More...
namespace	command
	Command pattern implementation for deferred action execution. More...
namespace	world
	World state management and per-frame update context. More...

Classes Index

struct	UpdateContext
	Context passed to systems and components during per-frame updates. More...

Description

Context struct passed to components during per-frame updates.

File Listing

The file content with the documentation metadata removed is:

1/**

2 * @file UpdateContext.ixx

3 * @brief Context struct passed to components during per-frame updates.

4 */

5module;

6

7#include <span>

8

9

10export module helios.engine.runtime.world.UpdateContext;

11

12import helios.input.InputSnapshot;

13import helios.rendering.ViewportSnapshot;

14

15import helios.engine.runtime.messaging.event.GameLoopEventBus;

16

17export namespace helios::engine::runtime::messaging::command {

18 class CommandBuffer;

19}

20

21

22export namespace helios::engine::runtime::world {

23

24

25

26 class GameWorld;

27

28 /**

29 * @brief Context passed to systems and components during per-frame updates.

30 *

31 * @details Provides all necessary state for systems to perform their update logic,

32 * including frame timing, input state, command buffer access, and event propagation.

33 *

34 * The UpdateContext serves as the central communication hub within the game loop,

35 * offering three levels of event propagation:

36 *

37 * ## Event Levels

38 *

39 * | Level | Push Method | Read Method | Scope |

40 * |-------|-------------|-------------|-------|

41 * | Pass | `pushPass()` | `readPass()` | Within same phase, after commit point |

42 * | Phase | `pushPhase()` | `readPhase()` | Across phases within same frame |

43 * | Frame | `pushFrame()` | `readFrame()` | Across frames |

44 *

45 * **Pass-level events** are pushed via `pushPass()` and become readable in subsequent

46 * passes within the same phase after a commit point is reached. Cleared at phase end.

47 *

48 * **Phase-level events** are pushed via `pushPhase()` and become readable in subsequent

49 * phases after the current phase commits. Cleared at frame end.

50 *

51 * **Frame-level events** are pushed via `pushFrame()` and become readable in the next

52 * frame. Useful for cross-frame communication (e.g., collision responses, spawn confirmations).

53 *

54 * @see GameLoop

55 * @see Pass

56 * @see CommandBuffer

57 * @see InputSnapshot

58 */

59 struct UpdateContext {

60

61 private:

62 /**

63 * @brief Time elapsed since the last frame, in seconds.

64 */

65 float deltaTime_ = 0.0f;

66

67 /**

68 * @brief Time elapsed since the first frame, in seconds.

69 */

70 float totalTime_ = 0.0f;

71

72 /**

73 * @brief Immutable snapshot of input state for the current frame.

74 */

75 const helios::input::InputSnapshot& inputSnapshot_;

76

77 /**

78 * @brief Buffer for queueing commands to be executed at end of frame.

79 */

80 helios::engine::runtime::messaging::command::CommandBuffer& commandBuffer_;

81

82 /**

83 * @brief Reference to the game world for entity lookups.

84 */

85 helios::engine::runtime::world::GameWorld& gameWorld_;

86

87 /**

88 * @brief Sink for pushing phase-level events during update.

89 *

90 * Used by systems and components to publish events (e.g., collision,

91 * spawn requests) that will be processed in the next phase of the game loop.

92 */

93 helios::engine::runtime::messaging::event::GameLoopEventBus::WriteSink phaseEventSink_;

94

95 /**

96 * @brief Source for reading phase-level events from the previous phase.

97 */

98 const helios::engine::runtime::messaging::event::GameLoopEventBus::ReadSource phaseEventSource_;

99

100 /**

101 * @brief Sink for pushing pass-level events during update.

102 *

103 * Used by systems and components to publish events that will be processed

104 * in subsequent passes within the same phase, after a commit point.

105 */

106 helios::engine::runtime::messaging::event::GameLoopEventBus::WriteSink passEventSink_;

107

108 /**

109 * @brief Source for reading pass-level events from previous passes.

110 */

111 const helios::engine::runtime::messaging::event::GameLoopEventBus::ReadSource passEventSource_;

112

113 /**

114 * @brief Sink for pushing frame-level events during update.

115 *

116 * Used by systems and components to publish events that will be processed

117 * in the next frame. Frame-level events persist across all phases and are

118 * swapped at the end of the Post phase.

119 */

120 helios::engine::runtime::messaging::event::GameLoopEventBus::WriteSink frameEventSink_;

121

122 /**

123 * @brief Source for reading frame-level events from the previous frame.

124 */

125 const helios::engine::runtime::messaging::event::GameLoopEventBus::ReadSource frameEventSource_;

126

127 /**

128 * @brief Immutable snapshot of all viewport states for this frame.

129 */

130 std::span<const helios::rendering::ViewportSnapshot> viewportSnapshots_;

131

132 public:

133

134

135 /**

136 * @brief Constructs an UpdateContext with required dependencies.

137 *

138 * @param commandBuffer Reference to the command buffer for queueing commands.

139 * @param gameWorld Reference to the game world for entity lookups.

140 * @param deltaTime Time since last frame / update in seconds.

141 * @param phaseEventBus Reference to the phase-level event bus for cross-phase communication.

142 * @param passEventBus Reference to the pass-level event bus for cross-pass communication.

143 * @param frameEventBus Reference to the frame-level event bus for cross-frame communication.

144 * @param inputSnapshot The input snapshot for this frame.

145 * @param viewportSnapshots Immutable snapshot of viewport states.

146 */

147 UpdateContext(

148 helios::engine::runtime::messaging::command::CommandBuffer& commandBuffer,

149 helios::engine::runtime::world::GameWorld& gameWorld,

150 const float deltaTime,

151 helios::engine::runtime::messaging::event::GameLoopEventBus& phaseEventBus,

152 helios::engine::runtime::messaging::event::GameLoopEventBus& passEventBus,

153 helios::engine::runtime::messaging::event::GameLoopEventBus& frameEventBus,

154 const helios::input::InputSnapshot& inputSnapshot,

155 std::span<const helios::rendering::ViewportSnapshot> viewportSnapshots

156 ) : commandBuffer_(commandBuffer), gameWorld_(gameWorld),

157 deltaTime_(deltaTime),

158 totalTime_(totalTime_ + deltaTime),

159 phaseEventSink_(phaseEventBus.writeSink()),

160 phaseEventSource_(phaseEventBus.readSource()),

161 passEventSink_(passEventBus.writeSink()),

162 passEventSource_(passEventBus.readSource()),

163 frameEventSink_(frameEventBus.writeSink()),

164 frameEventSource_(frameEventBus.readSource()),

165 inputSnapshot_(inputSnapshot),

166 viewportSnapshots_(viewportSnapshots)

167 {

168

169 }

170

171 /**

172 * @brief Returns the viewport snapshots for this frame.

173 *

174 * @return A span of const ViewportSnapshot objects.

175 */

176 [[nodiscard]] std::span<const helios::rendering::ViewportSnapshot> viewportSnapshots() const noexcept {

177 return viewportSnapshots_;

178 }

179

180

181 /**

182 * @brief Returns the time elapsed since the last frame, in seconds.

183 *

184 * @return Delta time in seconds.

185 */

186 [[nodiscard]] float deltaTime() const noexcept {

187 return deltaTime_;

188 }

189

190 /**

191 * @brief Returns the time elapsed since the first frame, in seconds.

192 *

193 * @return Total time in seconds.

194 */

195 [[nodiscard]] float totalTime() const noexcept {

196 return totalTime_;

197 }

198

199 /**

200 * @brief Returns the immutable input snapshot for this frame.

201 *

202 * @return Const ref to the current InputSnapshot.

203 */

204 [[nodiscard]] const helios::input::InputSnapshot& inputSnapshot() const noexcept {

205 return inputSnapshot_;

206 }

207

208 /**

209 * @brief Returns the command buffer for queueing commands.

210 *

211 * @return Ref to the CommandBuffer used with this UpdateContext.

212 */

213 [[nodiscard]] helios::engine::runtime::messaging::command::CommandBuffer& commandBuffer() const noexcept {

214 return commandBuffer_;

215 }

216

217 /**

218 * @brief Returns the game world for entity lookups.

219 *

220 * @return Ref to the GameWorld used with this UpdateContext.

221 */

222 [[nodiscard]] helios::engine::runtime::world::GameWorld& gameWorld() const noexcept {

223 return gameWorld_;

224 }

225

226 /**

227 * @brief Pushes an event to the pass-level event bus.

228 *

229 * Events pushed here become readable in subsequent passes within the same

230 * phase, after a commit point is reached.

231 *

232 * @tparam E The event type to push.

233 * @tparam Args Constructor argument types for the event.

234 *

235 * @param args Arguments forwarded to the event constructor.

236 *

237 * @see readPass()

238 * @see Pass::addCommitPoint()

239 */

240 template<typename E, typename... Args>

241 void pushPass(Args&&... args) {

242 passEventSink_.template push<E>(std::forward<Args>(args)...);

243 }

244

245 /**

246 * @brief Pushes an event to the phase-level event bus.

247 *

248 * Events pushed here become readable in subsequent phases,

249 * after the current phase commits.

250 *

251 * @tparam E The event type to push.

252 * @tparam Args Constructor argument types for the event.

253 *

254 * @param args Arguments forwarded to the event constructor.

255 *

256 * @see readPhase()

257 * @see GameLoop

258 */

259 template<typename E, typename... Args>

260 void pushPhase(Args&&... args) {

261 phaseEventSink_.template push<E>(std::forward<Args>(args)...);

262 }

263

264 /**

265 * @brief Reads events from the phase-level event bus.

266 *

267 * Returns events that were pushed during the previous phase via

268 * `pushPhase()`. The phase event bus is swapped at phase boundaries,

269 * configured in GameLoop::phaseCommit().

270 *

271 * @tparam E The event type to read.

272 *

273 * @return A span of const events of type E.

274 *

275 * @see pushPhase()

276 * @see GameLoop

277 */

278 template<typename E>

279 std::span<const E> readPhase() {

280 return phaseEventSource_.template read<E>();

281 }

282

283 /**

284 * @brief Reads events from the pass-level event bus.

285 *

286 * Returns events that were pushed during previous passes within the

287 * current phase via `pushPass()`. The pass event bus is swapped at

288 * commit points, configured via Pass::addCommitPoint().

289 *

290 * @tparam E The event type to read.

291 *

292 * @return A span of const events of type E.

293 *

294 * @see pushPass()

295 * @see Pass::addCommitPoint()

296 */

297 template<typename E>

298 std::span<const E> readPass() {

299 return passEventSource_.template read<E>();

300 }

301

302 /**

303 * @brief Reads events from the frame-level event bus.

304 *

305 * @details Returns events that were pushed during the previous frame via

306 * `pushFrame()`. The frame event bus is swapped at the end of the Post

307 * phase, making events readable in the subsequent frame.

308 *

309 * Frame-level events are useful for cross-frame communication, such as:

310 * - Collision events that trigger effects in the next frame

311 * - Spawn confirmations for UI updates

312 * - Audio/VFX triggers

313 *

314 * @tparam E The event type to read.

315 *

316 * @return A span of const events of type E.

317 *

318 * @see pushFrame()

319 * @see GameLoop

320 */

321 template<typename E>

322 std::span<const E> readFrame() {

323 return frameEventSource_.template read<E>();

324 }

325

326 /**

327 * @brief Pushes an event to the frame-level event bus.

328 *

329 * @details Events pushed here become readable in the next frame via

330 * `readFrame()`. The frame event bus is swapped at the end of the Post

331 * phase in GameLoop.

332 *

333 * Use frame-level events for cross-frame communication where events

334 * should persist beyond the current phase.

335 *

336 * @tparam E The event type to push.

337 * @tparam Args Constructor argument types for the event.

338 *

339 * @param args Arguments forwarded to the event constructor.

340 *

341 * @see readFrame()

342 * @see GameLoop

343 */

344 template<typename E, typename... Args>

345 void pushFrame(Args&&... args) {

346 frameEventSink_.template push<E>(std::forward<Args>(args)...);

347 }

348 };

349}

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.