π’ Event Bus
A typed publish/subscribe bus that lets systems communicate without knowing each other, with immediate delivery on the main thread and a thread-safe deferred queue drained once per frame.
Overview#
The Event Bus enables decoupled communication between systems. One system publishes an event; others subscribe without knowing who publishes it. This removes direct dependencies (for example, Physics does not need to know about Audio).
Two delivery modes:
publish<T>()β immediate, calls listeners now (main thread)publishDeferred<T>()β enqueues for the nextdispatch()(thread-safe)
API#
EventBus#
namespace Caffeine::Events {
using ListenerHandle = u32;
class EventBus {
public:
// Subscribes a typed listener. Returns a handle for cancellation.
template<typename T>
ListenerHandle subscribe(std::function<void(const T&)> callback);
// Removes the listener. No-op for an invalid handle. No dangling pointers.
void unsubscribe(ListenerHandle handle);
// Immediate delivery: calls every listener now (safe snapshot).
template<typename T>
void publish(const T& event);
// Enqueues the event for the next dispatch(). Thread-safe.
template<typename T>
void publishDeferred(T event);
// Drains the deferred queue. Call once per frame from the GameLoop.
void dispatch();
// Number of pending events in the queue.
usize pendingCount() const;
// Removes every listener and empties the queue.
void clear();
};
} // namespace Caffeine::Events
Event type ID#
Each type T receives a unique runtime ID from the address of a local static
variable β no practical collisions and no manual registration:
namespace Caffeine::Events::Detail {
template<typename T>
u32 eventTypeId() {
static char s_sentinel = 0;
return static_cast<u32>(reinterpret_cast<uintptr_t>(&s_sentinel));
}
} // namespace Caffeine::Events::Detail
Note: the 64-bit address is truncated to
u32. A theoretical collision is possible but negligible in practice (it would require two statics exactly 4 GiB apart with the same low 32 bits).
Predefined Events#
All live in src/caffeine/events/Events.hpp, namespace Caffeine::Events.
ECS#
struct OnEntityCreated { u32 entityId; };
struct OnEntityDestroyed { u32 entityId; };
Physics / Collision#
struct OnCollision2D {
u32 entityA;
u32 entityB;
Vec2 contactPoint;
Vec2 normal;
f32 impulse;
};
struct OnTrigger2D {
u32 triggerEntity;
u32 otherEntity;
bool entered; // true = enter, false = exit
};
Combat / Stats#
struct OnHealthChanged {
u32 entityId;
f32 previousHealth;
f32 currentHealth;
f32 maxHealth;
};
struct OnDeath {
u32 entityId;
u32 killerEntityId; // 0 = environmental / no killer
};
Progression#
struct OnScoreChanged {
u32 playerId;
i32 previousScore;
i32 currentScore;
i32 delta;
};
Scene#
struct OnLevelLoaded { u32 levelId; c8 levelName[64]; };
struct OnLevelUnloaded { u32 levelId; };
Input#
struct OnActionPressed { u32 actionId; u32 playerId; };
struct OnActionReleased { u32 actionId; u32 playerId; };
Map surfaces#
struct OnMapSurfaceChunkRequest {
u32 surfaceEntityId = 0;
i32 chunkX = 0;
i32 chunkY = 0;
f32 worldMinX = 0.0f;
f32 worldMinY = 0.0f;
f32 chunkSize = 0.0f;
};
Usage Examples#
Basic setup#
Caffeine::Events::EventBus bus;
// Subscribe
Caffeine::Events::ListenerHandle h = bus.subscribe<Caffeine::Events::OnDeath>(
[](const Caffeine::Events::OnDeath& e) {
if (e.killerEntityId == 0) {
// environmental death
}
});
// Publish immediately (main thread)
bus.publish(Caffeine::Events::OnDeath{ entityId, killerId });
// Cancel
bus.unsubscribe(h);
Deferred publication (from a worker thread)#
// PhysicsSystem running on a job worker:
bus.publishDeferred(Caffeine::Events::OnCollision2D{
entityA, entityB, contactPoint, normal, impulse
});
// GameLoop, at the start of the fixed update:
bus.dispatch(); // delivers every queued event
Communication between systems without coupling#
// AudioSystem (does not know PhysicsSystem)
bus.subscribe<Caffeine::Events::OnCollision2D>(
[&audio](const Caffeine::Events::OnCollision2D& e) {
audio.playSFX("impact.caf");
});
// ScoreSystem (knows nothing about gameplay internals)
bus.subscribe<Caffeine::Events::OnDeath>(
[&score](const Caffeine::Events::OnDeath& e) {
score.add(100);
});
// PhysicsSystem publishes; both receive
bus.publishDeferred(Caffeine::Events::OnCollision2D{ /* ... */ });
Integration in the GameLoop#
- Frame N:
InputManager.beginFrame()+ injected events +InputManager.endFrame()(if used)EventBus.dispatch()β delivers deferred events from frame N-1World.update(fixedDt)PhysicsSystem β publishDeferred(OnCollision2D)CombatSystem β publish(OnDeath)(immediate)...
render(alpha)
- Frame N+1:
EventBus.dispatch()β delivers theOnCollision2Devents from frame N...
Design Decisions#
| Decision | Rationale |
|---|---|
Type-erased void* internally |
Allows std::unordered_map<u32, vector<Record>> without a virtual per type |
Snapshot before iterating in publish() |
A listener may call unsubscribe() without invalidating iteration |
| Mutex only on the deferred queue | publish() and subscribe() are main-thread only; only publishDeferred() needs a lock |
ListenerHandle = u32 |
No pending pointers; unsubscribe by ID, not by reference |
Detail::eventTypeId<T>() via static char |
Zero registration cost; unique ID guaranteed by the static address |
unsubscribe() with a linear search |
O(types Γ listeners); acceptable because unsubscribe is rare (not a hot path) |
Thread Safety#
| Operation | Thread-safe? | Reason |
|---|---|---|
subscribe() |
Main thread only | Modifies m_listeners without a lock |
unsubscribe() |
Main thread only | Modifies m_listeners without a lock |
publish() |
Main thread only | Reads m_listeners without a lock |
publishDeferred() |
β Any thread | Protected by m_queueMutex |
dispatch() |
Main thread only | Swaps the queue under the lock, then dispatches without it |
Acceptance Criteria#
| Criterion | Result |
|---|---|
| 1K events/frame without noticeable overhead | β
1000Γ publish() = 0.085ms total |
publish() < 0.1ms (hot path) |
β 0.086Β΅s/call (10K reps, Release) |
publishDeferred thread-safe |
β 8 threads Γ 125 events = 1000/1000 without a race |
Deferred events delivered on the next dispatch() |
β Zero delivered before, all afterwards |
Zero live listeners after unsubscribe |
β 0 callbacks after unsubscribe (immediate and deferred) |
Tests#
tests/test_eventbus.cpp β 18 test cases, 39 assertions:
| Test | Coverage |
|---|---|
| subscribe + immediate publish | Base flow |
| Multiple listeners on the same type | Fan-out |
| unsubscribe removes the listener | Correct cancellation |
| Invalid unsubscribe handle | Safe no-op |
| Isolated event types | No cross-talk |
| publish with no listeners | Safe no-op |
| publishDeferred does not deliver immediately | Queue behaviour |
| dispatch delivers everything | Guaranteed delivery |
| dispatch empties the queue | Post-dispatch state |
| Deferred delivery order | FIFO preserved |
| clear removes listeners and queue | Full reset |
| Unique handles per subscription | IDs do not collide |
| Selective unsubscribe among several | Surgical precision |
| Deferred with mixed types | Multi-type queue |
Predefined OnEntityCreated |
ECS event |
Predefined OnDeath |
Combat event |
Predefined OnScoreChanged + dispatch |
Progression event |
8 threads Γ 125 publishDeferred |
Thread safety |
Dependencies#
- Upstream:
Caffeine::Core::Types,src/caffeine/math/Vec2.hpp - Downstream (real use in code):
PhysicsSystem2D(src/caffeine/physics) publishes collisions;ScriptEngine(src/caffeine/script) exposeson/emitto Lua;UISystem(src/caffeine/ui) andSceneEditor(doppio-archived/src/doppio/editor/) consume events - Related docs: Physics 2D, Audio,
Game UI, GameLoop (calls
dispatch())
π Related Topics#
| Topic | Description |
|---|---|
| Concurrency & Runtime | Event Bus in the context of the Game Loop |
| Game Systems | Events connect gameplay systems |
References#
docs/architecture_specs.mdβ Β§6 Event Bus../physics/physics-2d.mdβ publishesOnCollision2Dcore/game-loop.mdβ callseventBus.dispatch()- Transversal Topic Index