The object that will be the recipient of events from this event dispatcher
Clears any existing handlers or wired event dispatchers on this event dispatcher
Emits an event for target
The name of the event to publish
Optionally pass an event data object to the handler
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.
The name of the event to unsubscribe
Optionally the specific handler to unsubscribe
Subscribe an event handler to a particular event name, multiple handlers per event name are allowed.
The name of the event to subscribe to
The handler callback to fire on this event
Once listens to an event one time, then unsubscribes from that event
The name of the event to subscribe to once
The handler of the event that will be auto unsubscribed
Unwires this event dispatcher from another
Wires this event dispatcher to also receive events from another
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:
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());