Skip to main content

README.md File

Namespaces Index​

namespacegameloop

Central game loop orchestration module. More...

File Listing​

The file content with the documentation metadata removed is:

 # helios::engine::runtime::gameloop
 
 Central game loop orchestration module providing phased system execution.
 
 The `gameloop` module provides the core infrastructure for managing the game update cycle. It organizes systems into a hierarchical structure of phases and passes, enabling deterministic execution order and event synchronization.
 
 ## Architecture
 
 The game loop follows a three-phase architecture:
 
 **Pre Phase** — Processes input and generates commands. Systems in this phase read player input and enqueue commands into the CommandBuffer.
 
 **Main Phase** — Executes core gameplay simulation. This includes physics, AI, game logic, and collision detection systems.
 
 **Post Phase** — Handles cleanup and synchronization. Systems in this phase synchronize the gameplay state with the scene graph and clear dirty flags.
 
 Each phase contains one or more passes. A pass groups related systems and can optionally define a commit point for event synchronization within the phase.
 
 Commands can be enqueued into the CommandBuffer during any phase, not just the Pre phase. After each phase completes, the CommandBuffer is flushed and all registered managers process their pending requests. This ensures that spawn/despawn operations and other deferred actions are executed at well-defined points in the update cycle.
 
 ## Key Components
 
 **GameLoop** is the central orchestrator that owns the three phases, the CommandBuffer, and the event buses. It drives the frame update by iterating through all phases and committing events and commands after each phase.
 
 **Phase** represents a distinct stage in the update cycle. Phases contain passes and are executed in fixed order (Pre → Main → Post).
 
 **Pass** contains a registry of systems that execute sequentially. Passes support commit points to synchronize pass-level events before the next pass begins.
 
 ## Usage
 
 ```cpp
 #include "helios/engine/gameloop/GameLoop.ixx"
 
 helios.engine.runtime.gameloop.GameLoop gameLoop;
 
 // Configure Pre phase
 gameLoop.phase(PhaseType.Pre)
  .addPass()
  .add<InputSystem>(&inputManager);
 
 // Configure Main phase
 gameLoop.phase(PhaseType.Main)
  .addPass()
  .add<MovementSystem>(&gameWorld)
  .add<HeadingSystem>(&gameWorld)
  .addCommitPoint()
  .addPass()
  // due to the previous commit point, CollisionSystem
  // can read all events pushed to the PassEventBus
  // by the systems in the previous pass.
  .add<CollisionSystem>(&gameWorld);
 
 // Configure Post phase
 gameLoop.phase(PhaseType.Post)
  .addPass()
  .add<SceneSyncSystem>(&gameWorld, &scene)
  .add<TransformClearSystem>(&gameWorld);
 
 // Initialize once before the first update
 gameLoop.init(gameWorld);
 
 // In your main loop
 while (running) {
  gameLoop.update(gameWorld, deltaTime, inputSnapshot);
  renderer.render(scene);
 }
 ```
 
 ## Event Synchronization
 
 The game loop provides two levels of event synchronization:
 
 **Pass-level events** are synchronized at commit points within a phase. This allows systems in the next pass to react to events generated by the previous pass - within the same phase. Pass-level events are discarded at the end of the phase and do not carry over to the next phase.
 
 **Phase-level events** are synchronized after each phase completes. Only events written via `phasePush()` are available to systems in the following phase. Commands are flushed and managers process their requests at phase boundaries.
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │ FRAME UPDATE │
 ├─────────────────────────────────────────────────────────────────────────┤
 │ │
 │ ┌─────────────── PRE PHASE ───────────────┐ │
 │ │ Pass 1 Pass 2 │ │
 │ │ ┌──────┐ ┌──────┐ │ │
 │ │ │Sys A │──┬────▶│Sys B │ │ │
 │ │ └──────┘ │ └──────┘ │ │
 │ │ │ │ │
 │ │ passPush() │ │
 │ │ (commit point) │ │
 │ └─────────────────────────────────────────┘ │
 │ │ │
 │ phasePush() │
 │ ▼ │
 │ ┌────────────── MAIN PHASE ───────────────┐ │
 │ │ Pass 1 Pass 2 │ │
 │ │ ┌──────┐ ┌──────┐ │ │
 │ │ │Sys C │──┬────▶│Sys D │ │ ◀── reads phase events │
 │ │ └──────┘ │ └──────┘ │ from Pre phase │
 │ │ │ │ │
 │ │ passPush() │ │
 │ │ (commit point) │ │
 │ └─────────────────────────────────────────┘ │
 │ │ │
 │ phasePush() │
 │ ▼ │
 │ ┌────────────── POST PHASE ───────────────┐ │
 │ │ Pass 1 │ │
 │ │ ┌──────┐ ┌──────┐ │ ◀── reads phase events │
 │ │ │Sys E │ │Sys F │ │ from Main phase │
 │ │ └──────┘ └──────┘ │ │
 │ └─────────────────────────────────────────┘ │
 │ │
 │ Legend: │
 │ passPush() → events available in next pass (same phase) │
 │ phasePush() → events available in next phase │
 │ ─────────── → pass events discarded at phase boundary │
 │ │
 └─────────────────────────────────────────────────────────────────────────┘
 ```
 
 
 ---
 <details>
 <summary>Doxygen</summary><p>
 @namespace helios::engine::runtime::gameloop
 @brief Central game loop orchestration module.
 @details Provides the GameLoop, Phase, and Pass classes for managing phased system execution with deterministic ordering and event synchronization.
 </p></details>
 

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.