UpdateContext.ixx File

Per-frame context passed to systems during game loop updates. More...

Included Headers

#include <span> #include <optional> #include <helios.engine.ecs.View> #include <helios.engine.ecs.GameObject> #include <helios.engine.ecs.EntityResolver> #include <helios.engine.ecs.EntityHandle> #include <helios.engine.runtime.world.ResourceRegistry> #include <helios.engine.runtime.messaging.event.GameLoopEventBus> #include <helios.engine.runtime.world.Level> #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
	Compile-time typed command buffering and handler routing. More...
namespace	world
	World state management, resource registry, and per-frame update context. More...

Classes Index

class	UpdateContext
	Per-frame context passed to systems during game loop updates. More...

Description

Per-frame context passed to systems during game loop updates.

File Listing

The file content with the documentation metadata removed is:

1/**

2 * @file UpdateContext.ixx

3 * @brief Per-frame context passed to systems during game loop updates.

4 */

5module;

6

7#include <span>

8#include <optional>

9

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

11

12import helios.input.InputSnapshot;

13import helios.rendering.ViewportSnapshot;

14

15import helios.engine.runtime.world.Level;

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

17

18import helios.engine.runtime.world.ResourceRegistry;

19

20import helios.engine.ecs.EntityResolver;

21import helios.engine.ecs.GameObject;

22import helios.engine.ecs.EntityHandle;

23

24import helios.engine.ecs.View;

25

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

27 class EngineCommandBuffer;

28}

29

30using namespace helios::engine::runtime::messaging::command;

31

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

33

34 class Session;

35

36

37 /**

38 * @brief Per-frame context passed to systems during game loop updates.

39 *

40 * @details UpdateContext bundles all state that systems need for a single

41 * frame update: timing, input, resource access, entity resolution, event

42 * buses, and the active level. It is constructed by the GameLoop each

43 * frame and passed to every System::update() call.

44 *

45 * ## Resource Access

46 *

47 * - `queueCommand<T>(args...)` — submits a command to the EngineCommandBuffer

48 * - `session()` — cross-frame state (tracked game/match states)

49 * - `level()` — current Level with arena bounds

50 *

51 * ## Entity Access

52 *

53 * - `find(handle)` — resolves an EntityHandle to a GameObject (validates

54 * the handle's version via the EntityResolver)

55 * - `entityResolver()` — direct access to the callable resolver

56 *

57 * ## Event Propagation

58 *

59 * | Level | Push | Read | Scope |

60 * |-------|------|------|-------|

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

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

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

64 *

65 * @see GameLoop

66 * @see ResourceRegistry

67 * @see EngineCommandBuffer

68 * @see Session

69 * @see EntityResolver

70 * @see InputSnapshot

71 */

72 class UpdateContext {

73

74 private:

75 /**

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

77 */

78 float deltaTime_ = 0.0f;

79

80 /**

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

82 */

83 float totalTime_ = 0.0f;

84

85 /**

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

87 */

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

89

90 /**

91 * @brief Reference to the current game session for state tracking.

92 */

93 helios::engine::runtime::world::Session& session_;

94

95 /**

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

97 *

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

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

100 */

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

102

103 /**

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

105 */

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

107

108 /**

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

110 *

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

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

113 */

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

115

116 /**

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

118 */

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

120

121 /**

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

123 *

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

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

126 * swapped at the end of the Post phase.

127 */

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

129

130 /**

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

132 */

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

134

135 /**

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

137 */

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

139

140 /**

141 * @brief Reference to the ResourceRegistry for O(1) resource lookup.

142 */

143 helios::engine::runtime::world::ResourceRegistry& resourceRegistry_;

144

145 /**

146 * @brief Callable for resolving EntityHandles to GameObjects.

147 */

148 helios::engine::ecs::EntityResolver entityResolver_;

149

150 /**

151 * @brief Pointer to the active Level, or nullptr if no level is loaded.

152 */

153 const Level* level_;

154

155 public:

156

157

158 /**

159 * @brief Constructs an UpdateContext with all per-frame dependencies.

160 *

161 * @param resourceRegistry Reference to the ResourceRegistry for resource lookup.

162 * @param entityResolver Callable for resolving EntityHandles to GameObjects.

163 * @param session Reference to the current game session.

164 * @param deltaTime Time since last frame in seconds.

165 * @param totalTime Accumulated time since the first frame in seconds.

166 * @param phaseEventBus Reference to the phase-level event bus.

167 * @param passEventBus Reference to the pass-level event bus.

168 * @param frameEventBus Reference to the frame-level event bus.

169 * @param inputSnapshot Immutable input state for this frame.

170 * @param viewportSnapshots Immutable snapshot of viewport states.

171 * @param level Pointer to the active Level, or nullptr.

172 */

173 UpdateContext(

174 helios::engine::runtime::world::ResourceRegistry& resourceRegistry,

175 helios::engine::ecs::EntityResolver entityResolver,

176 helios::engine::runtime::world::Session& session,

177 const float deltaTime,

178 const float totalTime,

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

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

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

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

183 std::span<const helios::rendering::ViewportSnapshot> viewportSnapshots,

184 const Level* level

185 ) :

186 resourceRegistry_(resourceRegistry),

187 entityResolver_(entityResolver),

188 session_(session),

189 deltaTime_(deltaTime),

190 totalTime_(totalTime),

191 phaseEventSink_(phaseEventBus.writeSink()),

192 phaseEventSource_(phaseEventBus.readSource()),

193 passEventSink_(passEventBus.writeSink()),

194 passEventSource_(passEventBus.readSource()),

195 frameEventSink_(frameEventBus.writeSink()),

196 frameEventSource_(frameEventBus.readSource()),

197 inputSnapshot_(inputSnapshot),

198 viewportSnapshots_(viewportSnapshots),

199 level_(level)

200 {

201

202 }

203

204 /**

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

206 *

207 * @return A span of const ViewportSnapshot objects.

208 */

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

210 return viewportSnapshots_;

211 }

212

213

214 /**

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

216 *

217 * @return Delta time in seconds.

218 */

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

220 return deltaTime_;

221 }

222

223 /**

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

225 *

226 * @return Total time in seconds.

227 */

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

229 return totalTime_;

230 }

231

232 /**

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

234 *

235 * @return Const ref to the current InputSnapshot.

236 */

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

238 return inputSnapshot_;

239 }

240

241 /**

242 * @brief Resolves an EntityHandle to a GameObject.

243 *

244 * @details Validates the handle via the EntityResolver and returns

245 * a lightweight GameObject wrapper if the entity is still alive.

246 *

247 * @param handle The entity handle to resolve.

248 *

249 * @return A GameObject if the handle is valid, std::nullopt otherwise.

250 */

251 [[nodiscard]] std::optional<helios::engine::ecs::GameObject> find(helios::engine::ecs::EntityHandle handle) const noexcept {

252 return entityResolver_(handle);

253 }

254

255

256 /**

257 * @brief Returns the EntityResolver for direct handle validation.

258 *

259 * @return Reference to the EntityResolver.

260 */

261 [[nodiscard]] helios::engine::ecs::EntityResolver& entityResolver() noexcept {

262 return entityResolver_;

263 }

264

265 /**

266 * @brief Returns the active Level.

267 *

268 * @return Pointer to the Level, or nullptr if no level is loaded.

269 */

270 [[nodiscard]] const Level* level() noexcept {

271 return level_;

272 }

273

274

275 /**

276 * @brief Submits a command to the EngineCommandBuffer.

277 *

278 * @details Constructs and enqueues a command of type T. The command

279 * will be executed during the next commit point (phase or pass boundary).

280 *

281 * @tparam T The command type to submit.

282 * @tparam Args Constructor argument types for T.

283 *

284 * @param args Arguments forwarded to the command constructor.

285 */

286 template<typename T, typename ...Args>

287 void queueCommand(Args&&...args) const noexcept {

288 resourceRegistry_.tryGet<EngineCommandBuffer>()->add<T>(std::forward<Args>(args)...);

289 }

290

291 /**

292 * @brief Returns the session for game/match state access.

293 *

294 * @return Ref to the Session used with this UpdateContext.

295 */

296 [[nodiscard]] helios::engine::runtime::world::Session& session() const noexcept {

297 return session_;

298 }

299

300

301 /**

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

303 *

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

305 * phase, after a commit point is reached.

306 *

307 * @tparam E The event type to push.

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

309 *

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

311 *

312 * @see readPass()

313 * @see Pass::addCommitPoint()

314 */

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

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

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

318 }

319

320 /**

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

322 *

323 * Events pushed here become readable in subsequent phases,

324 * after the current phase commits.

325 *

326 * @tparam E The event type to push.

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

328 *

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

330 *

331 * @see readPhase()

332 * @see GameLoop

333 */

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

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

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

337 }

338

339 /**

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

341 *

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

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

344 * configured in GameLoop::phaseCommit().

345 *

346 * @tparam E The event type to read.

347 *

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

349 *

350 * @see pushPhase()

351 * @see GameLoop

352 */

353 template<typename E>

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

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

356 }

357

358 /**

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

360 *

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

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

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

364 *

365 * @tparam E The event type to read.

366 *

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

368 *

369 * @see pushPass()

370 * @see Pass::addCommitPoint()

371 */

372 template<typename E>

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

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

375 }

376

377 /**

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

379 *

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

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

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

383 *

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

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

386 * - Spawn confirmations for UI updates

387 * - Audio/VFX triggers

388 *

389 * @tparam E The event type to read.

390 *

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

392 *

393 * @see pushFrame()

394 * @see GameLoop

395 */

396 template<typename E>

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

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

399 }

400

401 /**

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

403 *

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

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

406 * phase in GameLoop.

407 *

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

409 * should persist beyond the current phase.

410 *

411 * @tparam E The event type to push.

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

413 *

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

415 *

416 * @see readFrame()

417 * @see GameLoop

418 */

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

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

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

422 }

423

424

425 /**

426 * @brief Creates a View for querying entities with the given component types.

427 *

428 * @details Convenience shortcut that avoids accessing the GameWorld

429 * directly. Delegates to the EntityManager owned by the

430 * EntityResolver.

431 *

432 * @tparam Components The component types to query.

433 *

434 * @return A View over all entities possessing every requested component.

435 *

436 * @see helios::engine::ecs::View

437 */

438 template <typename... Components>

439 [[nodiscard]] auto view() {

440 return helios::engine::ecs::View<Components...>(entityResolver_.em);

441 }

442

443 /**

444 * @copydoc view()

445 */

446 template <typename... Components>

447 [[nodiscard]] auto view() const {

448 return helios::engine::ecs::View<const Components...>(entityResolver_.em);

449 }

450

451 };

452}

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.