feat: Animation improvements fromSpriteSheetCoordinates + EventEmitter

CHANGELOG.md

@@ -13,10 +13,57 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Deprecated
 
 - [[ex.Input.Gamepad]] `isButtonPressed` has been renamed to `isButtonHeld`
+- `ex.EventDispatcher` is marked deprecated, will eventually be removed in v0.29.0
 
 
 ### Added
 
+- Added new helper called `ex.Animation.fromSpriteSheetCoordinates` to help build animations more tersely from SpriteSheets
+  ```typescript
+   const spriteSheet = SpriteSheet.fromImageSource({...});
+      const anim = Animation.fromSpriteSheetCoordinates({
+    spriteSheet,
+    frameCoordinates: [
+      {x: 0, y: 5, duration: 100},
+      {x: 1, y: 5, duration: 200},
+      {x: 2, y: 5, duration: 100},
+      {x: 3, y: 5, duration: 500}
+    ],
+    strategy: AnimationStrategy.PingPong
+   });
+  ```
+
+- Added new `FrameEvent` to `ex.Animation` which includes the frame index of the current frame!
+  ```typescript
+    const anim = new Animation();
+
+    // TS autocompletes the handler
+    anim.on('frame', (frame: FrameEvent) => {
+      // Do stuff on frame
+    });
+  ```
+
+- Added new typed `ex.EventEmitter` which will eventually replace the old `ex.EventDispatcher`, this gives users a way of strongly typing the possible events that can be emitted using a type map. This is loosely typed you can still emit any event you want, you only get type completion suggestions for the type map.
+  ```typescript
+  export type AnimationEvents = {
+    frame: FrameEvent;
+    loop: Animation;
+    ended: Animation;
+  };
+
+  export class Animation {
+    public events = new EventEmitter<AnimationEvents>();
+    ...
+  }
+
+  const anim = new Animation();
+
+  // TS autocompletes the handler
+  anim.on('frame', (frame: FrameEvent) => {
+    // Do stuff on frame
+  });
+  ```
+
 - Added ability to perform arbitrary ray casts into `ex.Scene`, the `ex.PhysicsWorld` can be passed a variety of options to influence the types of ray cast hits that
 are returned
   ```typescript

src/engine/EventDispatcher.ts

@@ -1,6 +1,9 @@
 import { GameEvent } from './Events';
 import { Eventable } from './Interfaces/Evented';
 
+/**
+ * @deprecated Use [[EventEmitter]] will be removed in v0.29.0
+ */
 export class EventDispatcher<T = any> implements Eventable {
   private _handlers: { [key: string]: { (event: GameEvent<T>): void }[] } = {};
   private _wiredEventDispatchers: Eventable[] = [];

src/engine/EventEmitter.ts

@@ -0,0 +1,105 @@
+export type EventMap = Record<string, any>;
+export type EventKey<T extends EventMap> = string & keyof T;
+export type Handler<EventType> = (event: EventType) => void;
+
+/**
+ * Interface that represents a handle to a subscription that can be closed
+ */
+export interface Subscription {
+  close(): void;
+}
+
+/**
+ * Excalibur's typed event emitter, this allows events to be sent with any string to Type mapping
+ */
+export class EventEmitter<T extends EventMap> {
+  private _paused = false;
+  private _listeners: Record<string, Handler<any>[]> = {};
+  private _listenersOnce: Record<string, Handler<any>[]> = {};
+  private _pipes: EventEmitter<any>[] = [];
+
+  on<K extends EventKey<T>>(eventName: K, fn: Handler<T[K]>): Subscription;
+  on(eventName: string, fn: Handler<unknown>): Subscription;
+  on<K extends EventKey<T> | string>(eventName: K, fn: Handler<T[K]>): Subscription {
+    this._listeners[eventName] = this._listeners[eventName] ?? [];
+    this._listeners[eventName].push(fn);
+    return {
+      close: () => this.off(eventName, fn)
+    };
+  }
+
+  once<K extends EventKey<T>>(eventName: K, fn: Handler<T[K]>): Subscription;
+  once(eventName: string, fn: Handler<unknown>): Subscription;
+  once<K extends EventKey<T> | string>(eventName: K, fn: Handler<T[K]>): Subscription {
+    this._listenersOnce[eventName] = this._listenersOnce[eventName] ?? [];
+    this._listenersOnce[eventName].push(fn);
+    return {
+      close: () => this.off(eventName, fn)
+    };
+  }
+
+  off<K extends EventKey<T>>(eventName: K, fn: Handler<T[K]>): void;
+  off(eventName: string, fn: Handler<unknown>): void;
+  off(eventName: string): void;
+  off<K extends EventKey<T> | string>(eventName: K, fn?: Handler<T[K]>): void {
+    if (fn) {
+      const listenerIndex = this._listeners[eventName]?.indexOf(fn);
+      if (listenerIndex > -1) {
+        this._listeners[eventName]?.splice(listenerIndex, 1);
+      }
+      const onceIndex = this._listenersOnce[eventName]?.indexOf(fn);
+      if (onceIndex > -1) {
+        this._listenersOnce[eventName]?.splice(onceIndex, 1);
+      }
+    } else {
+      delete this._listeners[eventName];
+    }
+  }
+
+  emit<K extends EventKey<T>>(eventName: K, event: T[K]): void;
+  emit(eventName: string, event?: any): void;
+  emit<K extends EventKey<T> | string>(eventName: K, event?: T[K]): void {
+    if (this._paused) {
+      return;
+    }
+    this._listeners[eventName]?.forEach((fn) => fn(event));
+    const onces = this._listenersOnce[eventName];
+    this._listenersOnce[eventName] = [];
+    if (onces) {
+      onces.forEach((fn) => fn(event));
+    }
+    this._pipes.forEach((pipe) => {
+      pipe.emit(eventName, event);
+    });
+  }
+
+  pipe(emitter: EventEmitter<any>): Subscription {
+    if (this === emitter) {
+      throw Error('Cannot pipe to self');
+    }
+    this._pipes.push(emitter);
+    return {
+      close: () => {
+        let i = -1;
+        if ((i = this._pipes.indexOf(emitter)) > -1) {
+          this._pipes.splice(i, 1);
+        }
+      }
+    };
+  }
+
+  unpipe(emitter: EventEmitter<any>): void {
+    let i = -1;
+    if ((i = this._pipes.indexOf(emitter)) > -1) {
+      this._pipes.splice(i, 1);
+    }
+  }
+
+  pause(): void {
+    this._paused = true;
+  }
+
+  unpause(): void {
+    this._paused = false;
+  }
+}