A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file Dispatcher.hpp
* @brief Central event dispatcher using type-indexed signals
* @details Provides a type-safe event bus that routes events to
* registered handlers based on event type. Supports both
* immediate triggering and queued event processing.
*
* @author ESEngine Team
* @date 2026
*
* @copyright Copyright (c) 2026 ESEngine Team
* Licensed under the Apache License, Version 2.0.
*/
#pragma once
// =============================================================================
// Includes
// =============================================================================
#include "Connection.hpp"
#include "Signal.hpp"
#include "Sink.hpp"
#include "../core/Types.hpp"
#include <functional>
#include <memory>
#include <queue>
#include <unordered_map>
namespace esengine {
// =============================================================================
// Dispatcher Class
// =============================================================================
/**
* @brief Central event dispatcher for the application
*
* @details Dispatcher manages signals for different event types and provides
* a unified interface for event subscription and publication.
* Events are identified by their C++ type, providing compile-time
* type safety.
*
* @code
* struct PlayerDied { Entity player; };
* struct ScoreChanged { int newScore; };
*
* Dispatcher dispatcher;
*
* // Subscribe
* auto conn = dispatcher.sink<PlayerDied>().connect(
* [](const PlayerDied& e) { handlePlayerDeath(e); });
*
* // Trigger immediately
* dispatcher.trigger(PlayerDied{playerEntity});
*
* // Queue for later
* dispatcher.enqueue(ScoreChanged{100});
* dispatcher.update();
* @endcode
*/
class Dispatcher {
public:
Dispatcher() = default;
~Dispatcher() = default;
Dispatcher(const Dispatcher&) = delete;
Dispatcher& operator=(const Dispatcher&) = delete;
Dispatcher(Dispatcher&&) = delete;
Dispatcher& operator=(Dispatcher&&) = delete;
/**
* @brief Get a sink for subscribing to an event type
*
* @tparam Event The event type to subscribe to
* @return Sink for connecting callbacks
*
* @code
* auto conn = dispatcher.sink<MyEvent>().connect(handler);
* @endcode
*/
template<typename Event>
auto sink() -> Sink<Signal<void(const Event&)>> {
return Sink<Signal<void(const Event&)>>(assure<Event>());
}
/**
* @brief Trigger an event immediately
*
* @tparam Event The event type
* @param event The event to trigger
*
* @details All registered handlers are called synchronously
* in the order they were registered.
*/
template<typename Event>
void trigger(const Event& event) {
auto* signal = find<Event>();
if (signal) {
signal->publish(event);
}
}
/**
* @brief Trigger an event constructed in-place
*
* @tparam Event The event type
* @tparam Args Constructor argument types
* @param args Arguments to construct the event
*/
template<typename Event, typename... Args>
void trigger(Args&&... args) {
trigger(Event{std::forward<Args>(args)...});
}
/**
* @brief Queue an event for later processing
*
* @tparam Event The event type
* @param event The event to queue
*
* @details Events are processed when update() is called.
*/
template<typename Event>
void enqueue(const Event& event) {
eventQueue_.push({[this, event]() {
trigger(event);
}});
}
/**
* @brief Queue an event constructed in-place
*
* @tparam Event The event type
* @tparam Args Constructor argument types
* @param args Arguments to construct the event
*/
template<typename Event, typename... Args>
void enqueue(Args&&... args) {
enqueue(Event{std::forward<Args>(args)...});
}
/**
* @brief Process all queued events
*
* @details Call this once per frame to process queued events.
* Events are processed in FIFO order.
*/
void update() {
while (!eventQueue_.empty()) {
eventQueue_.front().dispatch();
eventQueue_.pop();
}
}
/**
* @brief Clear all queued events without processing
*/
void clearQueue() {
std::queue<QueuedEvent> empty;
std::swap(eventQueue_, empty);
}
/**
* @brief Check if there are queued events
* @return true if the queue is not empty
*/
[[nodiscard]] bool hasQueuedEvents() const {
return !eventQueue_.empty();
}
/**
* @brief Get the number of queued events
* @return Number of events in queue
*/
[[nodiscard]] usize queueSize() const {
return eventQueue_.size();
}
/**
* @brief Clear all signals and handlers
*/
void clear() {
signals_.clear();
clearQueue();
}
/**
* @brief Check if there are subscribers for an event type
*
* @tparam Event The event type
* @return true if there are subscribers
*/
template<typename Event>
[[nodiscard]] bool hasSubscribers() const {
auto* signal = find<Event>();
return signal && !signal->empty();
}
/**
* @brief Get the number of subscribers for an event type
*
* @tparam Event The event type
* @return Number of subscribers
*/
template<typename Event>
[[nodiscard]] usize subscriberCount() const {
auto* signal = find<Event>();
return signal ? signal->size() : 0;
}
private:
struct QueuedEvent {
std::function<void()> dispatch;
};
struct SignalWrapperBase {
virtual ~SignalWrapperBase() = default;
};
template<typename Event>
struct SignalWrapperTyped : SignalWrapperBase {
Signal<void(const Event&)> signal;
};
template<typename Event>
Signal<void(const Event&)>& assure() {
auto typeId = eventTypeId<Event>();
auto it = signals_.find(typeId);
if (it == signals_.end()) {
auto wrapper = makeUnique<SignalWrapperTyped<Event>>();
auto* ptr = &wrapper->signal;
signals_.emplace(typeId, std::move(wrapper));
return *ptr;
}
return static_cast<SignalWrapperTyped<Event>*>(it->second.get())->signal;
}
template<typename Event>
Signal<void(const Event&)>* find() {
auto typeId = eventTypeId<Event>();
auto it = signals_.find(typeId);
if (it != signals_.end()) {
return &static_cast<SignalWrapperTyped<Event>*>(it->second.get())->signal;
}
return nullptr;
}
template<typename Event>
const Signal<void(const Event&)>* find() const {
auto typeId = eventTypeId<Event>();
auto it = signals_.find(typeId);
if (it != signals_.end()) {
return &static_cast<const SignalWrapperTyped<Event>*>(it->second.get())->signal;
}
return nullptr;
}
std::unordered_map<TypeId, Unique<SignalWrapperBase>> signals_;
std::queue<QueuedEvent> eventQueue_;
};
} // namespace esengine