• Public
  • Public/Protected
  • All

Class EventDispatcher

Excalibur's internal event dispatcher implementation. Callbacks are fired immediately after an event is published. Typically you will use Class.eventDispatcher since most classes in Excalibur inherit from Class. You will rarely create an EventDispatcher yourself.

When working with events, be sure to keep in mind the order of subscriptions and try not to create a situation that requires specific things to happen in order. Events are best used for input events, tying together disparate objects, or for UI updates.

Excalibur events follow the convention that the name of the thrown event for listening will be the same as the Event object in all lower case with the 'Event' suffix removed.

For example:

  • PreDrawEvent event object and "predraw" as the event name
actor.on('predraw', (evtObj: PreDrawEvent) => {
   // do some pre drawing

Example: Actor events

Actors implement an EventDispatcher (Actor.eventDispatcher) so they can send and receive events. For example, they can enable Pointer events (mouse/touch) and you can respond to them by subscribing to the event names. You can also emit any other kind of event for your game just by using a custom string value and implementing a class that inherits from GameEvent.

var player = new ex.Actor(...);

// Enable pointer events for this actor
player.enableCapturePointer = true;
// subscribe to pointerdown event
player.on("pointerdown", function (evt: ex.Input.PointerEvent) {
  console.log("Player was clicked!");
// turn off subscription
// subscribe to custom event
player.on("death", function (evt) {
  console.log("Player died:", evt);
// trigger custom event
player.emit("death", new DeathEvent());

Example: Pub/Sub with Excalibur

You can also create an EventDispatcher for any arbitrary object, for example a global game event aggregator (shown below as vent). Anything in your game can subscribe to it, if the event aggregator is in the global scope. Warning: This can easily get out of hand. Avoid this usage, it just serves as an example.

// create a publisher on an empty object
var vent = new ex.EventDispatcher({});
// handler for an event
var subscription = function (event) {
// add a subscription
vent.on("someevent", subscription);
// publish an event somewhere in the game
vent.emit("someevent", new ex.GameEvent());


  • EventDispatcher





  • Parameters

    • target: any

      The object that will be the recipient of events from this event dispatcher

    Returns EventDispatcher


Private _handlers

_handlers: object

Type declaration

  • [key: string]: function[]

Private _log

_log: Logger = Logger.getInstance()

Private _target

_target: any

Private _wiredEventDispatchers

_wiredEventDispatchers: EventDispatcher[] = []



  • emit(eventName: string, event?: GameEvent): void
  • Emits an event for target


    • eventName: string

      The name of the event to publish

    • Optional event: GameEvent

      Optionally pass an event data object to the handler

    Returns void


  • off(eventName: string, handler?: function): void
  • Unsubscribe an event handler(s) from an event. If a specific handler is specified for an event, only that handler will be unsubscribed. Otherwise all handlers will be unsubscribed for that event.


    • eventName: string

      The name of the event to unsubscribe

    • Optional handler: function

      Optionally the specific handler to unsubscribe

    Returns void


  • on(eventName: string, handler: function): void
  • Subscribe an event handler to a particular event name, multiple handlers per event name are allowed.


    • eventName: string

      The name of the event to subscribe to

    • handler: function

      The handler callback to fire on this event

    Returns void


  • Unwires this event dispatcher from another


    Returns void


  • Wires this event dispatcher to also recieve events from another


    Returns void