GameLoop Class

Central orchestrator for the game update cycle. More...

Declaration

class helios::engine::runtime::gameloop::GameLoop { ... }

Base class

class	PassCommitListener
	Interface for receiving notifications when a pass reaches its commit point. More...

Public Constructors Index

	GameLoop ()=default
	Default constructor. More...

Public Member Functions Index

helios::engine::runtime::gameloop::Phase &	phase (helios::engine::runtime::gameloop::PhaseType phaseType)
	Returns a reference to the specified phase. More...
helios::engine::runtime::messaging::command::CommandBuffer &	commandBuffer ()
	Returns a reference to the command buffer. More...
void	init (helios::engine::runtime::world::GameWorld &gameWorld)
	Initializes the GameLoop and all registered phases and passes. More...
void	update (helios::engine::runtime::world::GameWorld &gameWorld, float deltaTime, const helios::input::InputSnapshot &inputSnapshot, std::span< const helios::rendering::ViewportSnapshot > viewportSnapshots) noexcept
	Executes one full frame update across all phases. More...

Protected Member Functions Index

void	onPassCommit (const CommitPoint commitPoint, helios::engine::runtime::world::UpdateContext &updateContext) noexcept override
	Commits pass-level state based on the specified CommitPoint flags. More...
void	phaseCommit (helios::engine::runtime::world::GameWorld &gameWorld, helios::engine::runtime::world::UpdateContext &updateContext)
	Commits phase-level events and flushes commands and managers. More...

Protected Member Attributes Index

helios::engine::runtime::gameloop::Phase	prePhase_ {*this}
	The pre-update phase, executed before main gameplay logic. More...
helios::engine::runtime::gameloop::Phase	mainPhase_ {*this}
	The main update phase for core gameplay systems. More...
helios::engine::runtime::gameloop::Phase	postPhase_ {*this}
	The post-update phase for cleanup and synchronization. More...
helios::engine::runtime::messaging::command::CommandBuffer	commandBuffer_ {}
	Buffer for deferred command execution. More...
helios::engine::runtime::messaging::event::GameLoopEventBus	phaseEventBus_ {}
	Event bus for phase-level event propagation. More...
helios::engine::runtime::messaging::event::GameLoopEventBus	passEventBus_ {}
	Event bus for pass-level event propagation. More...
helios::engine::runtime::messaging::event::GameLoopEventBus	frameEventBus_ {}
	Event bus for frame-level event propagation. More...

Private Member Attributes Index

bool	initialized_ = false
	Flag indicating whether init() has been called. More...

Protected Static Attributes Index

static const helios::util::log::Logger &	logger_ = ...
	The logger used with this GameLoop instance. More...

Description

Central orchestrator for the game update cycle.

The GameLoop manages the execution of game systems across three distinct phases: Pre, Main, and Post. Each phase can contain multiple passes, and each pass can have a configurable commit point for fine-grained synchronization control.

## Ownership

The GameLoop owns:

• **Three phases** (Pre, Main, Post), each containing passes with registered systems.
• **A CommandBuffer** for deferred command execution.
• **Three event buses** for different propagation scopes:
  • `phaseEventBus_`: Events readable in the next phase.
  • `passEventBus_`: Events readable in subsequent passes (within the same phase).
  • `frameEventBus_`: Events readable in the next frame.

## Commit Points

Commit points allow systems to specify when commands should be flushed, managers should process their requests, and pass-level events should be synchronized. This enables deterministic ordering and fine-grained control over the update cycle.

## Frame Lifecycle

``` ┌─────────────────────────────────────────────────────────────┐ │ FRAME N │ ├─────────────────┬─────────────────┬─────────────────────────┤ │ PRE PHASE │ MAIN PHASE │ POST PHASE │ │ (Input, Cmd) │ (Physics, AI) │ (Cleanup, Sync) │ ├─────────────────┼─────────────────┼─────────────────────────┤ │ phaseCommit() │ phaseCommit() │ phaseCommit() │ │ │ │ frameEventBus_.swap() │ └─────────────────┴─────────────────┴─────────────────────────┘ ```

See Also

Phase

See Also

Pass

See Also

CommitPoint

See Also

CommandBuffer

See Also

PassCommitListener

Definition at line 78 of file GameLoop.ixx.

Public Constructors

GameLoop()

helios::engine::runtime::gameloop::GameLoop::GameLoop ()

default

Default constructor.

Creates a GameLoop with empty phases. Systems must be added to the phases via `phase(PhaseType).addPass().addSystem<T>()` before calling `init()`.

Definition at line 243 of file GameLoop.ixx.

Public Member Functions

commandBuffer()

helios::engine::runtime::messaging::command::CommandBuffer & helios::engine::runtime::gameloop::GameLoop::commandBuffer ()

inline

Returns a reference to the command buffer.

Returns

Reference to the CommandBuffer owned by this GameLoop.

Definition at line 275 of file GameLoop.ixx.

275 helios::engine::runtime::messaging::command::CommandBuffer& commandBuffer() {

276 return commandBuffer_;

277 }

Reference commandBuffer_.

init()

void helios::engine::runtime::gameloop::GameLoop::init (helios::engine::runtime::world::GameWorld & gameWorld)

inline

Initializes the GameLoop and all registered phases and passes.

Iterates through all phases (Pre, Main, Post) and calls their `init()` methods, which in turn initialize all registered passes and systems. Systems receive a reference to the GameWorld for component queries and entity access.

Must be called exactly once before the first `update()` call.

Parameters

gameWorld

Reference to the game world to initialize with.

Precondition

Must not have been called before (asserts on multiple calls).

See Also

Phase::init()

See Also

Pass::init()

See Also

System::init()

Definition at line 297 of file GameLoop.ixx.

297 void init(helios::engine::runtime::world::GameWorld& gameWorld) {

298

299 assert(!initialized_ && "init() already called");

300

301 for (auto phase : {helios::engine::runtime::gameloop::PhaseType::Pre,

302 helios::engine::runtime::gameloop::PhaseType::Main,

303 helios::engine::runtime::gameloop::PhaseType::Post}) {

304 switch (phase) {

305 case helios::engine::runtime::gameloop::PhaseType::Pre:

306 prePhase_.init(gameWorld);

307 prePhase_.addPassCommitListener(this);

308 break;

309 case helios::engine::runtime::gameloop::PhaseType::Main:

310 mainPhase_.init(gameWorld);

311 mainPhase_.addPassCommitListener(this);

312 break;

313 case helios::engine::runtime::gameloop::PhaseType::Post:

314 postPhase_.init(gameWorld);

315 postPhase_.addPassCommitListener(this);

316 break;

317 }

318 }

319

320 initialized_ = true;

321 }

References helios::engine::runtime::gameloop::Main, mainPhase_, phase, helios::engine::runtime::gameloop::Post, postPhase_, helios::engine::runtime::gameloop::Pre and prePhase_.

phase()

helios::engine::runtime::gameloop::Phase & helios::engine::runtime::gameloop::GameLoop::phase (helios::engine::runtime::gameloop::PhaseType phaseType)

inline

Returns a reference to the specified phase.

Parameters

phaseType

The type of phase to retrieve (Pre, Main, or Post).

Returns

Reference to the requested Phase.

Definition at line 252 of file GameLoop.ixx.

252 helios::engine::runtime::gameloop::Phase& phase(helios::engine::runtime::gameloop::PhaseType phaseType) {

253

254 switch (phaseType) {

255 case helios::engine::runtime::gameloop::PhaseType::Pre:

256 return prePhase_;

257 break;

258 case helios::engine::runtime::gameloop::PhaseType::Main:

259 return mainPhase_;

260 break;

261 case helios::engine::runtime::gameloop::PhaseType::Post:

262 return postPhase_;

263 break;

264 }

265

266 std::unreachable();

267

268 }

References helios::engine::runtime::gameloop::Main, mainPhase_, helios::engine::runtime::gameloop::Post, postPhase_, helios::engine::runtime::gameloop::Pre and prePhase_.

Referenced by init and update.

update()

void helios::engine::runtime::gameloop::GameLoop::update (helios::engine::runtime::world::GameWorld & gameWorld, float deltaTime, const helios::input::InputSnapshot & inputSnapshot, std::span< const helios::rendering::ViewportSnapshot > viewportSnapshots)

inline noexcept

Executes one full frame update across all phases.

Iterates through Pre, Main, and Post phases, updating all registered systems and committing events and commands after each phase. The frame lifecycle:

1. **Pre Phase:** Input processing, command generation, preparation 2. **Main Phase:** Core gameplay logic, physics, collision detection 3. **Post Phase:** Cleanup, synchronization, rendering preparation

After each phase, `phaseCommit()` is called to:

• Swap phase event buffers (events become readable in next phase)
• Clear pass event buffers
• Flush command buffer
• Flush managers

After the Post phase, the frame event bus is swapped, making frame-level events readable in the next frame.

Parameters

gameWorld	Reference to the game world.
deltaTime	Time elapsed since the last frame in seconds.
inputSnapshot	Snapshot of the current input state.
viewportSnapshots	Snapshots of viewports registered with an id.

Precondition

init() must have been called before the first update.

See Also

Phase

See Also

phaseCommit()

See Also

UpdateContext

Definition at line 353 of file GameLoop.ixx.

353 void update(

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

355 float deltaTime,

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

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

358 ) noexcept {

359

360 assert(initialized_ && "GameLoop not initialized");

361

362 auto updateContext = helios::engine::runtime::world::UpdateContext(

363 commandBuffer_,

364 gameWorld,

365 deltaTime,

366 phaseEventBus_,

367 passEventBus_,

368 frameEventBus_,

369 inputSnapshot,

370 viewportSnapshots

371 );

372

373

374 // gameloop phases

375 for (auto phase : {helios::engine::runtime::gameloop::PhaseType::Pre,

376 helios::engine::runtime::gameloop::PhaseType::Main,

377 helios::engine::runtime::gameloop::PhaseType::Post}) {

378

379 switch (phase) {

380 case helios::engine::runtime::gameloop::PhaseType::Pre:

381 prePhase_.update(updateContext);

382 phaseCommit(gameWorld, updateContext);

383 break;

384 case helios::engine::runtime::gameloop::PhaseType::Main:

385 mainPhase_.update(updateContext);

386 phaseCommit(gameWorld, updateContext);

387

388 break;

389 case helios::engine::runtime::gameloop::PhaseType::Post:

390 postPhase_.update(updateContext);

391 phaseCommit(gameWorld, updateContext);

392 frameEventBus_.swapBuffers();

393 break;

394 }

395

396

397 }

398 }

References commandBuffer_, frameEventBus_, helios::engine::runtime::gameloop::Main, mainPhase_, passEventBus_, phase, phaseCommit, phaseEventBus_, helios::engine::runtime::gameloop::Post, postPhase_, helios::engine::runtime::gameloop::Pre and prePhase_.

Protected Member Functions

onPassCommit()

void helios::engine::runtime::gameloop::GameLoop::onPassCommit (const CommitPoint commitPoint, helios::engine::runtime::world::UpdateContext & updateContext)

inline noexcept protected virtual

Commits pass-level state based on the specified CommitPoint flags.

Called after each pass that has a commit point configured. The CommitPoint flags determine which synchronization actions are performed:

• **PassEvents:** Swaps pass event bus buffers, making events pushed via `UpdateContext::pushPass()` readable in subsequent passes.
• **FlushCommands:** Executes pending commands from the CommandBuffer.
• **FlushManagers:** Processes manager requests (e.g., spawning from pools).

The order is: PassEvents → FlushCommands → FlushManagers. Commands must be flushed before managers to ensure spawn requests are generated before being processed.

Parameters

commitPoint	The flags specifying which actions to perform.
updateContext	The current update context.

See Also

CommitPoint

See Also

Pass::addCommitPoint()

See Also

UpdateContext::pushPass()

See Also

UpdateContext::readPass()

Definition at line 184 of file GameLoop.ixx.

184 void onPassCommit(

185 const CommitPoint commitPoint,

186 helios::engine::runtime::world::UpdateContext& updateContext) noexcept override {

187

188

189 if ((commitPoint & CommitPoint::PassEvents) == CommitPoint::PassEvents) {

190 passEventBus_.swapBuffers();

191 }

192

193 // commands must be executed before Managers

194 if ((commitPoint & CommitPoint::FlushCommands) == CommitPoint::FlushCommands) {

195 commandBuffer_.flush(updateContext.gameWorld());

196 }

197

198 if ((commitPoint & CommitPoint::FlushManagers) == CommitPoint::FlushManagers) {

199 updateContext.gameWorld().flushManagers(updateContext);

200 }

201

202 }

References commandBuffer_, helios::engine::runtime::gameloop::FlushCommands, helios::engine::runtime::gameloop::FlushManagers, passEventBus_ and helios::engine::runtime::gameloop::PassEvents.

phaseCommit()

void helios::engine::runtime::gameloop::GameLoop::phaseCommit (helios::engine::runtime::world::GameWorld & gameWorld, helios::engine::runtime::world::UpdateContext & updateContext)

inline protected

Commits phase-level events and flushes commands and managers.

Called after each phase completes. This method: 1. Swaps phase event bus buffers, making events readable in the next phase. 2. Clears pass event buffers for the new phase. 3. Flushes the command buffer, executing deferred commands. 4. Flushes managers, allowing to process any request generated by the commands.

Parameters

gameWorld	Reference to the game world.
updateContext	The current update context.

See Also

UpdateContext::pushPhase()

See Also

UpdateContext::readPhase()

Definition at line 219 of file GameLoop.ixx.

219 void phaseCommit(

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

221 helios::engine::runtime::world::UpdateContext& updateContext) {

222 phaseEventBus_.swapBuffers();

223 passEventBus_.clearAll();

224

225 // command buffer generates request for managers, so this comes first

226 commandBuffer_.flush(updateContext.gameWorld());

227

228 // managers process requests

229 gameWorld.flushManagers(updateContext);

230 }

References commandBuffer_, helios::engine::runtime::world::GameWorld::flushManagers, helios::engine::runtime::world::UpdateContext::gameWorld, passEventBus_ and phaseEventBus_.

Referenced by update.

Protected Member Attributes

commandBuffer_

helios::engine::runtime::messaging::command::CommandBuffer helios::engine::runtime::gameloop::GameLoop::commandBuffer_ {}

protected

Buffer for deferred command execution.

Definition at line 117 of file GameLoop.ixx.

117 helios::engine::runtime::messaging::command::CommandBuffer commandBuffer_{};

Referenced by commandBuffer, onPassCommit, phaseCommit and update.

frameEventBus_

helios::engine::runtime::messaging::event::GameLoopEventBus helios::engine::runtime::gameloop::GameLoop::frameEventBus_ {}

protected

Event bus for frame-level event propagation.

Events pushed via `UpdateContext::pushFrame()` are buffered here and become readable in the next frame via `UpdateContext::readFrame()`. The buffer swap occurs at the end of the Post phase.

Frame-level events persist across all phases within a frame and are useful for cross-frame communication (e.g., collision events that should be processed in the next frame).

See Also

UpdateContext::pushFrame()

See Also

UpdateContext::readFrame()

Definition at line 158 of file GameLoop.ixx.

158 helios::engine::runtime::messaging::event::GameLoopEventBus frameEventBus_{};

Referenced by update.

mainPhase_

helios::engine::runtime::gameloop::Phase helios::engine::runtime::gameloop::GameLoop::mainPhase_ {*this}

protected

The main update phase for core gameplay systems.

Definition at line 107 of file GameLoop.ixx.

107 helios::engine::runtime::gameloop::Phase mainPhase_{*this};

Referenced by init, phase and update.

passEventBus_

helios::engine::runtime::messaging::event::GameLoopEventBus helios::engine::runtime::gameloop::GameLoop::passEventBus_ {}

protected

Event bus for pass-level event propagation.

Events pushed via `UpdateContext::pushPass()` are buffered here and become readable in subsequent passes via `UpdateContext::readPass()`. The buffer swap occurs when a pass has a commit point.

See Also

UpdateContext::pushPass()

See Also

UpdateContext::readPass()

See Also

Pass::addCommitPoint()

Definition at line 142 of file GameLoop.ixx.

142 helios::engine::runtime::messaging::event::GameLoopEventBus passEventBus_{};

Referenced by onPassCommit, phaseCommit and update.

phaseEventBus_

helios::engine::runtime::messaging::event::GameLoopEventBus helios::engine::runtime::gameloop::GameLoop::phaseEventBus_ {}

protected

Event bus for phase-level event propagation.

Events pushed via `UpdateContext::pushPhase()` are buffered here and become readable in the next phase via `UpdateContext::readPhase()`. The buffer swap occurs in phaseCommit().

See Also

UpdateContext::pushPhase()

See Also

UpdateContext::readPhase()

Definition at line 129 of file GameLoop.ixx.

129 helios::engine::runtime::messaging::event::GameLoopEventBus phaseEventBus_{};

Referenced by phaseCommit and update.

postPhase_

helios::engine::runtime::gameloop::Phase helios::engine::runtime::gameloop::GameLoop::postPhase_ {*this}

protected

The post-update phase for cleanup and synchronization.

Definition at line 112 of file GameLoop.ixx.

112 helios::engine::runtime::gameloop::Phase postPhase_{*this};

Referenced by init, phase and update.

prePhase_

helios::engine::runtime::gameloop::Phase helios::engine::runtime::gameloop::GameLoop::prePhase_ {*this}

protected

The pre-update phase, executed before main gameplay logic.

Definition at line 102 of file GameLoop.ixx.

102 helios::engine::runtime::gameloop::Phase prePhase_{*this};

Referenced by init, phase and update.

Private Member Attributes

initialized_

bool helios::engine::runtime::gameloop::GameLoop::initialized_ = false

Flag indicating whether init() has been called.

Used to assert that init() is called exactly once before the first update() and to prevent multiple initializations.

Definition at line 87 of file GameLoop.ixx.

87 bool initialized_ = false;

Protected Static Attributes

logger_

const helios::util::log::Logger& helios::engine::runtime::gameloop::GameLoop::logger_

protected static

The logger used with this GameLoop instance.

Initialiser

= helios::util::log::LogManager::loggerForScope( HELIOS_LOG_SCOPE)

Definition at line 95 of file GameLoop.ixx.

95 inline static const helios::util::log::Logger& logger_ = helios::util::log::LogManager::loggerForScope(

---

The documentation for this class was generated from the following file:

• GameLoop.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.