reverse no longer needs the argument. play and playReverse can now take an Animation instance as an argument, not just a key.

Author: photonstorm

src/gameobjects/components/Animation.js

@@ -4,12 +4,16 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
+var BaseAnimation = require('../../animations/Animation');
 var Class = require('../../utils/Class');
 
 /**
  * This event is dispatched when an animation starts playing.
  * 
  * Listen for it on the Game Object: `sprite.on('animationstart', listener)`
+ * 
+ * You can also listen for a specific animation by appending a hyphen and its key to the event name. For example,
+ * if you have an animation called `explode`, you can listen for `sprite.on('animationstart-explode', listener)`.
  *
  * @event Phaser.GameObjects.Components.Animation#onStartEvent
  * @param {Phaser.Animations.Animation} animation - Reference to the currently playing animation.
@@ -21,6 +25,9 @@ var Class = require('../../utils/Class');
  * This event is dispatched when an animation restarts.
  * 
  * Listen for it on the Game Object: `sprite.on('animationrestart', listener)`
+ * 
+ * You can also listen for a specific animation by appending a hyphen and its key to the event name. For example,
+ * if you have an animation called `explode`, you can listen for `sprite.on('animationrestart-explode', listener)`.
  *
  * @event Phaser.GameObjects.Components.Animation#onRestartEvent
  * @param {Phaser.Animations.Animation} animation - Reference to the currently playing animation.
@@ -32,6 +39,9 @@ var Class = require('../../utils/Class');
  * This event is dispatched when an animation repeats.
  * 
  * Listen for it on the Game Object: `sprite.on('animationrepeat', listener)`
+ * 
+ * You can also listen for a specific animation by appending a hyphen and its key to the event name. For example,
+ * if you have an animation called `explode`, you can listen for `sprite.on('animationrepeat-explode', listener)`.
  *
  * @event Phaser.GameObjects.Components.Animation#onRepeatEvent
  * @param {Phaser.Animations.Animation} animation - Reference to the currently playing animation.
@@ -45,6 +55,9 @@ var Class = require('../../utils/Class');
  * based on the animation frame rate and other factors like timeScale and delay.
  * 
  * Listen for it on the Game Object: `sprite.on('animationupdate', listener)`
+ * 
+ * You can also listen for a specific animation by appending a hyphen and its key to the event name. For example,
+ * if you have an animation called `explode`, you can listen for `sprite.on('animationupdate-explode', listener)`.
  *
  * @event Phaser.GameObjects.Components.Animation#onUpdateEvent
  * @param {Phaser.Animations.Animation} animation - Reference to the currently playing animation.
@@ -56,6 +69,9 @@ var Class = require('../../utils/Class');
  * This event is dispatched when an animation completes playing, either naturally or via Animation.stop.
  * 
  * Listen for it on the Game Object: `sprite.on('animationcomplete', listener)`
+ * 
+ * You can also listen for a specific animation by appending a hyphen and its key to the event name. For example,
+ * if you have an animation called `explode`, you can listen for `sprite.on('animationcomplete-explode', listener)`.
  *
  * @event Phaser.GameObjects.Components.Animation#onCompleteEvent
  * @param {Phaser.Animations.Animation} animation - Reference to the currently playing animation.
@@ -508,13 +524,15 @@ var Animation = new Class({
     },
 
     /**
-     * Plays an Animation on the Game Object that owns this Animation Component.
+     * Plays an Animation on a Game Object that has the Animation component, such as a Sprite.
+     * 
+     * Animations are stored in the global Animation Manager and are referenced by a unique string-based key.
      *
      * @method Phaser.GameObjects.Components.Animation#play
      * @fires Phaser.GameObjects.Components.Animation#onStartEvent
      * @since 3.0.0
      *
-     * @param {string} key - The string-based key of the animation to play, as defined previously in the Animation Manager.
+     * @param {(string|Phaser.Animations.Animation)} key - The string-based key of the animation to play, as defined previously in the Animation Manager. Or an Animation instance.
      * @param {boolean} [ignoreIfPlaying=false] - If an animation is already playing then ignore this call.
      * @param {integer} [startFrame=0] - Optionally start the animation playing from this frame index.
      *
@@ -525,6 +543,11 @@ var Animation = new Class({
         if (ignoreIfPlaying === undefined) { ignoreIfPlaying = false; }
         if (startFrame === undefined) { startFrame = 0; }
 
+        if (key instanceof BaseAnimation)
+        {
+            key = key.key;
+        }
+
         if (ignoreIfPlaying && this.isPlaying && this.currentAnim.key === key)
         {
             return this.parent;
@@ -543,7 +566,7 @@ var Animation = new Class({
      * @fires Phaser.GameObjects.Components.Animation#onStartEvent
      * @since 3.12.0
      *
-     * @param {string} key - The string-based key of the animation to play, as defined previously in the Animation Manager.
+     * @param {(string|Phaser.Animations.Animation)} key - The string-based key of the animation to play, as defined previously in the Animation Manager. Or an Animation instance.
      * @param {boolean} [ignoreIfPlaying=false] - If an animation is already playing then ignore this call.
      * @param {integer} [startFrame=0] - Optionally start the animation playing from this frame index.
      *
@@ -554,6 +577,11 @@ var Animation = new Class({
         if (ignoreIfPlaying === undefined) { ignoreIfPlaying = false; }
         if (startFrame === undefined) { startFrame = 0; }
 
+        if (key instanceof BaseAnimation)
+        {
+            key = key.key;
+        }
+
         if (ignoreIfPlaying && this.isPlaying && this.currentAnim.key === key)
         {
             return this.parent;
@@ -566,8 +594,7 @@ var Animation = new Class({
     },
 
     /**
-     * Load an Animation and fires 'onStartEvent' event,
-     * extracted from 'play' method
+     * Load an Animation and fires 'onStartEvent' event, extracted from 'play' method.
      *
      * @method Phaser.GameObjects.Components.Animation#_startAnimation
      * @fires Phaser.GameObjects.Components.Animation#onStartEvent
@@ -598,26 +625,33 @@ var Animation = new Class({
             gameObject.visible = true;
         }
 
-        gameObject.emit('animationstart', this.currentAnim, this.currentFrame, gameObject);
+        var frame = this.currentFrame;
+
+        anim.emit('start', anim, frame);
+
+        gameObject.emit('animationstart-' + key, anim, frame, gameObject);
+
+        gameObject.emit('animationstart', anim, frame, gameObject);
 
         return gameObject;
     },
 
     /**
-     * Reverse an Animation that is already playing on the Game Object.
+     * Reverse the Animation that is already playing on the Game Object.
      *
      * @method Phaser.GameObjects.Components.Animation#reverse
      * @since 3.12.0
      *
-     * @param {string} key - The string-based key of the animation to play, as defined previously in the Animation Manager.
-     *
      * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
      */
-    reverse: function (key)
+    reverse: function ()
     {
-        if (!this.isPlaying || this.currentAnim.key !== key) { return this.parent; }
-        this._reverse = !this._reverse;
-        this.forward = !this.forward;
+        if (this.isPlaying)
+        {
+            this._reverse = !this._reverse;
+
+            this.forward = !this.forward;
+        }
 
         return this.parent;
     },
@@ -774,19 +808,26 @@ var Animation = new Class({
     {
         if (includeDelay === undefined) { includeDelay = false; }
 
-        this.currentAnim.getFirstTick(this, includeDelay);
+        var anim = this.currentAnim;
+
+        anim.getFirstTick(this, includeDelay);
 
         this.forward = true;
         this.isPlaying = true;
         this.pendingRepeat = false;
         this._paused = false;
 
         //  Set frame
-        this.updateFrame(this.currentAnim.frames[0]);
+        this.updateFrame(anim.frames[0]);
 
         var gameObject = this.parent;
+        var frame = this.currentFrame;
+
+        anim.emit('restart', anim, frame);
 
-        gameObject.emit('animationrestart', this.currentAnim, this.currentFrame, gameObject);
+        gameObject.emit('animationrestart-' + anim.key, anim, frame, gameObject);
+
+        gameObject.emit('animationrestart', anim, frame, gameObject);
 
         return this.parent;
     },
@@ -807,8 +848,14 @@ var Animation = new Class({
         this.isPlaying = false;
 
         var gameObject = this.parent;
+        var anim = this.currentAnim;
+        var frame = this.currentFrame;
 
-        gameObject.emit('animationcomplete', this.currentAnim, this.currentFrame, gameObject);
+        anim.on('complete', anim, frame);
+
+        gameObject.emit('animationcomplete-' + anim.key, anim, frame, gameObject);
+
+        gameObject.emit('animationcomplete', anim, frame, gameObject);
 
         return gameObject;
     },
@@ -856,7 +903,7 @@ var Animation = new Class({
      * @fires Phaser.GameObjects.Components.Animation#onCompleteEvent
      * @since 3.4.0
      *
-     * @param {Phaser.Animations.AnimationFrame} delay - The frame to check before stopping this animation.
+     * @param {Phaser.Animations.AnimationFrame} frame - The frame to check before stopping this animation.
      *
      * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
      */
@@ -1010,6 +1057,10 @@ var Animation = new Class({
 
             var anim = this.currentAnim;
 
+            anim.emit('update', anim, animationFrame);
+
+            gameObject.emit('animationupdate-' + anim.key, anim, animationFrame, gameObject);
+
             gameObject.emit('animationupdate', anim, animationFrame, gameObject);
 
             if (this._pendingStop === 3 && this._pendingStopValue === animationFrame)