Skip to main content

GameLoopEventBus.ixx File

Type-safe event bus for inter-system communication within the game loop. More...

Included Headers​

#include <helios.core.buffer.TypeIndexedDoubleBuffer> #include <helios.core.data.TypeIndexer>

Namespaces Index​

namespacehelios
namespaceengine

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

namespaceruntime

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

namespacemessaging

Communication infrastructure for commands and events. More...

namespaceevent

Event bus for inter-system communication within the game loop. More...

Classes Index​

structGameLoopEventBusGroup

Tag type for the game loop event bus index space. More...

Description​

Type-safe event bus for inter-system communication within the game loop.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file GameLoopEventBus.ixx
3 * @brief Type-safe event bus for inter-system communication within the game loop.
4 */
5module;
6
7export module helios.engine.runtime.messaging.event.GameLoopEventBus;
8
9import helios.core.data.TypeIndexer;
10import helios.core.buffer.TypeIndexedDoubleBuffer;
11
12
13export namespace helios::engine::runtime::messaging::event {
14
15 /**
16 * @struct GameLoopEventBusGroup
17 * @brief Tag type for the game loop event bus index space.
18 *
19 * @details Used as a template parameter for TypeIndexer to create a dedicated
20 * index space for game loop events, separate from other typed buffer systems.
21 */
22 struct GameLoopEventBusGroup {};
23
24 /**
25 * @typedef GameLoopEventBus
26 * @brief Double-buffered event bus for decoupled inter-system communication.
27 *
28 * @details GameLoopEventBus is a type alias for TypeIndexedDoubleBuffer configured
29 * with a dedicated index space for game loop events. It enables systems to publish
30 * events during their update phase, which become available for consumption after
31 * the buffer swap.
32 *
33 * ## Phase/Pass Event Model
34 *
35 * The GameLoop uses multiple event buses to control event visibility:
36 *
37 * - **Pass Events:** Events written with `push()` are available to subsequent passes
38 * within the **same phase only**. They are **always cleared** at the end of the phase.
39 *
40 * - **Phase Events:** Events written with `phasePush()` are preserved across phase
41 * boundaries and available in subsequent phases of the same frame.
42 *
43 * This allows fine-grained control over event propagation:
44 *
45 * ```
46 * ┌─────────────────────────────────────────────────────────────┐
47 * │ FRAME │
48 * ├─────────────────────────────────────────────────────────────┤
49 * │ PRE PHASE │
50 * │ Pass 1: push<InputEvent>() → available in Pass 2 │
51 * │ Pass 2: read<InputEvent>() ✓ works │
52 * │ phasePush<SpawnReq>() → available in MAIN │
53 * │ [Phase Commit] ← Pass events CLEARED │
54 * │ │
55 * │ MAIN PHASE │
56 * │ Pass 1: read<InputEvent>() ✗ EMPTY (cleared!) │
57 * │ read<SpawnReq>() ✓ works (phasePush) │
58 * │ push<CollisionEvent>() → available in Pass 2 │
59 * │ Pass 2: read<CollisionEvent>() ✓ works │
60 * │ [Phase Commit] ← Pass events CLEARED │
61 * │ │
62 * │ POST PHASE │
63 * │ Pass 1: read<CollisionEvent>() ✗ EMPTY (cleared!) │
64 * │ read<SpawnReq>() ✓ works (phasePush) │
65 * │ [Phase Commit] ← All events CLEARED for next frame │
66 * └─────────────────────────────────────────────────────────────┘
67 * ```
68 *
69 * ## Usage Example
70 *
71 * ```cpp
72 * // Define an event type
73 * struct CollisionEvent {
74 * Guid entityA;
75 * Guid entityB;
76 * vec3f contactPoint;
77 * };
78 *
79 * // In collision detection system (Main Phase, Pass 1)
80 * // Use push() for events only needed within this phase
81 * eventBus.push<CollisionEvent>(entityA, entityB, contact);
82 *
83 * // In damage system (Main Phase, Pass 2) - same phase, works!
84 * for (const auto& evt : eventBus.read<CollisionEvent>()) {
85 * applyDamage(evt.entityA, evt.entityB);
86 * }
87 *
88 * // For events needed in subsequent phases, use phasePush()
89 * eventBus.phasePush<SpawnRequestEvent>(poolId, position);
90 * ```
91 *
92 * @warning Pass events (`push()`) are **always cleared** at phase boundaries.
93 * They are NOT available in subsequent phases. Use `phasePush()` for
94 * events that must survive into subsequent phases.
95 *
96 * @see helios::core::buffer::TypeIndexedDoubleBuffer
97 * @see UpdateContext — Provides access to the event bus in systems
98 * @see GameLoop — Manages event bus lifecycle and commit points
99 */
100 using GameLoopEventBus = helios::core::buffer::TypeIndexedDoubleBuffer<
101 helios::core::data::TypeIndexer<GameLoopEventBusGroup>
102 >;
103
104
105
106}

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.