Options
All
  • Public
  • Public/Protected
  • All
Menu

Class EventDispatcher<T>

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
player.off("pointerdown");
// 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) {
  console.log(event);
};
// add a subscription
vent.on('someevent', subscription);
// publish an event somewhere in the game
vent.emit('someevent', new ex.GameEvent());

Type parameters

  • T

Hierarchy

  • EventDispatcher

Implements

Index

Constructors

Methods

Constructors

constructor

Methods

clear

  • clear(): void
  • Clears any existing handlers or wired event dispatchers on this event dispatcher

    Returns void

emit

  • emit(eventName: string, event: GameEvent<T>): void
  • Emits an event for target

    Parameters

    • eventName: string

      The name of the event to publish

    • event: GameEvent<T>

      Optionally pass an event data object to the handler

    Returns void

off

  • 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.

    Parameters

    • eventName: string

      The name of the event to unsubscribe

    • Optional handler: function

      Optionally the specific handler to unsubscribe

    Returns void

on

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

    Parameters

    • eventName: string

      The name of the event to subscribe to

    • handler: function

      The handler callback to fire on this event

    Returns void

once

  • once(eventName: string, handler: function): void
  • Once listens to an event one time, then unsubscribes from that event

    Parameters

    • eventName: string

      The name of the event to subscribe to once

    • handler: function

      The handler of the event that will be auto unsubscribed

    Returns void

unwire

wire