📢 Event Bus
Um bus publish/subscribe tipado que permite aos sistemas comunicar sem se conhecerem, com entrega imediata na main thread e uma fila diferida thread-safe consumida uma vez por frame.
Visão Geral#
O Event Bus permite comunicação desacoplada entre sistemas. Um sistema publica um evento; outros se inscrevem sem conhecer quem publica. Isso elimina dependências diretas (ex: Physics não precisa conhecer Audio).
Dois modos de entrega:
publish<T>()— imediato, chama listeners agora (main thread)publishDeferred<T>()— enfileira para o próximodispatch()(thread-safe)
API#
EventBus#
namespace Caffeine::Events {
using ListenerHandle = u32;
class EventBus {
public:
// Inscreve um listener tipado. Retorna handle para cancelamento.
template<typename T>
ListenerHandle subscribe(std::function<void(const T&)> callback);
// Remove o listener. No-op se handle inválido. Zero dangling pointers.
void unsubscribe(ListenerHandle handle);
// Entrega imediata: chama todos os listeners agora (snapshot seguro).
template<typename T>
void publish(const T& event);
// Enfileira evento para o próximo dispatch(). Thread-safe.
template<typename T>
void publishDeferred(T event);
// Processa toda a fila diferida. Chamar uma vez por frame, no GameLoop.
void dispatch();
// Número de eventos pendentes na fila.
usize pendingCount() const;
// Remove todos os listeners e esvazia a fila.
void clear();
};
} // namespace Caffeine::Events
Tipo ID de Evento#
Cada tipo T recebe um ID único em runtime via endereço de variável static local — zero colisão prática, zero registro manual:
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
Nota: o endereço de 64 bits é truncado para
u32. Colisão teórica é possível mas desprezível na prática (exigiria dois statics a exatamente 4 GiB de distância com os mesmos 32 bits baixos).
Eventos Pré-definidos#
Todos em src/caffeine/events/Events.hpp, namespace Caffeine::Events.
ECS#
struct OnEntityCreated { u32 entityId; };
struct OnEntityDestroyed { u32 entityId; };
Física / Colisão#
struct OnCollision2D {
u32 entityA;
u32 entityB;
Vec2 contactPoint;
Vec2 normal;
f32 impulse;
};
struct OnTrigger2D {
u32 triggerEntity;
u32 otherEntity;
bool entered; // true = enter, false = exit
};
Combate / Stats#
struct OnHealthChanged {
u32 entityId;
f32 previousHealth;
f32 currentHealth;
f32 maxHealth;
};
struct OnDeath {
u32 entityId;
u32 killerEntityId; // 0 = environmental / no killer
};
Progressão#
struct OnScoreChanged {
u32 playerId;
i32 previousScore;
i32 currentScore;
i32 delta;
};
Cena#
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;
};
Exemplos de Uso#
Setup básico#
Caffeine::Events::EventBus bus;
// Inscrever
ListenerHandle h = bus.subscribe<OnDeath>([](const OnDeath& e) {
if (e.killerEntityId == 0) {
// morte ambiental
}
});
// Publicar imediato (main thread)
bus.publish(OnDeath{ entityId, killerId });
// Cancelar
bus.unsubscribe(h);
Publicação diferida (de worker thread)#
// PhysicsSystem rodando em job worker:
bus.publishDeferred(OnCollision2D{
entityA, entityB, contactPoint, normal, impulse
});
// GameLoop, início do fixed update:
bus.dispatch(); // entrega todos os eventos enfileirados
Comunicação entre sistemas sem acoplamento#
// AudioSystem (não conhece PhysicsSystem)
bus.subscribe<OnCollision2D>([&audio](const OnCollision2D& e) {
audio.playSFX("impact.caf");
});
// ScoreSystem (não conhece nada de gameplay)
bus.subscribe<OnDeath>([&score](const OnDeath& e) {
score.add(100);
});
// PhysicsSystem publica, ambos recebem
bus.publishDeferred(OnCollision2D{ ... });
Integração no GameLoop#
Frame N:InputManager.beginFrame()+ eventos injetados +InputManager.endFrame()(se usado)EventBus.dispatch() ← entrega diferidos do frame N-1World.update(fixedDt)PhysicsSystem → publishDeferred(OnCollision2D)CombatSystem → publish(OnDeath) ← imediato...
render(alpha)
Frame N+1:EventBus.dispatch() ← entrega os OnCollision2D do frame N...
Decisões de Design#
| Decisão | Justificativa |
|---|---|
Type-erased void* internamente |
Permite std::unordered_map<u32, vector<Record>> sem virtual por tipo |
Snapshot antes de iterar em publish() |
Listener pode chamar unsubscribe() sem invalidar iteração |
| Mutex apenas na fila deferred | publish() e subscribe() são main-thread only; só publishDeferred() precisa de lock |
ListenerHandle = u32 |
Sem ponteiros pendentes; unsubscribe por ID, não por referência |
Detail::eventTypeId<T>() via static char |
Zero custo de registro; ID único garantido por endereço de static |
unsubscribe() com busca linear |
O(tipos × listeners); aceitável porque unsubscribe é raro (não hot path) |
Thread Safety#
| Operação | Thread-safe? | Motivo |
|---|---|---|
subscribe() |
Main thread only | Modifica m_listeners sem lock |
unsubscribe() |
Main thread only | Modifica m_listeners sem lock |
publish() |
Main thread only | Lê m_listeners sem lock |
publishDeferred() |
✅ Qualquer thread | Protegido por m_queueMutex |
dispatch() |
Main thread only | Consome fila após swap; não precisa de lock |
Critérios de Aceitação#
| Critério | Resultado |
|---|---|
| 1K eventos/frame sem overhead perceptível | ✅ 1000× publish() = 0.085ms total |
publish() < 0.1ms (hot path) |
✅ 0.086µs/call (10K reps, Release) |
publishDeferred thread-safe |
✅ 8 threads × 125 eventos = 1000/1000 sem race |
Eventos diferidos entregues no próximo dispatch() |
✅ Zero entregues antes, todos depois |
Zero listeners mortos após unsubscribe |
✅ 0 callbacks após unsubscribe (imediato e deferred) |
Testes#
tests/test_eventbus.cpp — 18 casos de teste, 39 asserções:
| Teste | Cobertura |
|---|---|
| subscribe + publish imediato | Fluxo base |
| Múltiplos listeners no mesmo tipo | Fan-out |
| unsubscribe remove listener | Cancelamento correto |
| unsubscribe handle inválido | No-op seguro |
| Tipos de evento isolados | Sem cross-talk |
| publish sem listeners | No-op seguro |
| publishDeferred não entrega imediatamente | Fila correta |
| dispatch entrega todos | Entrega garantida |
| dispatch esvazia fila | Estado pós-dispatch |
| Ordem de entrega deferred | FIFO preservado |
| clear remove listeners e fila | Reset completo |
| Handles únicos por subscription | IDs não colidem |
| Unsubscribe seletivo entre vários | Precisão cirúrgica |
| Deferred com tipos mistos | Multi-type queue |
OnEntityCreated predefinido |
Evento ECS |
OnDeath predefinido |
Evento combate |
OnScoreChanged predefinido + dispatch |
Evento progressão |
8 threads × 125 publishDeferred |
Thread safety |
Dependências#
- Upstream:
Caffeine::Core::Types,src/caffeine/math/Vec2.hpp - Downstream (uso real no código):
PhysicsSystem2D(src/caffeine/physics) publica colisão;ScriptEngine(src/caffeine/script) expõeon/emitpara Lua;UISystem(src/caffeine/ui) eSceneEditor(doppio-archived/src/doppio/editor/) consomem eventos - Docs relacionados: Physics 2D, Audio,
Game UI, GameLoop (chama
dispatch())
🔗 Tópicos Relacionados#
| Tópico | Descrição |
|---|---|
| Concorrência & Runtime | Event Bus no contexto do Game Loop |
| Sistemas de Jogo | Eventos conectam sistemas de gameplay |
Referências#
docs/architecture_specs.md— §6 Event Bus../physics/physics-2d.md— publicaOnCollision2Dcore/game-loop.md— chamaeventBus.dispatch()- Índice de Tópicos Transversais