Add a 'revert' function that can revert the flow of a animation at any time (issue phaserjs#3837)

Author: khaleb85

src/animations/Animation.js

@@ -536,7 +536,14 @@ var Animation = new Class({
             component._yoyo = this.yoyo;
         }
 
-        component.updateFrame(this.frames[startFrame]);
+        var frame = this.frames[startFrame];
+
+        if(startFrame === 0 && !component.forward)
+        {
+            frame = this.getLastFrame();
+        }
+
+        component.updateFrame(frame);
     },
 
     /**
@@ -602,6 +609,18 @@ var Animation = new Class({
         }
     },
 
+    /**
+     * Returns the animation last frame.
+     *
+     * @method Phaser.Animations.Animation#getLastFrame
+     *
+     * @return {Phaser.Animations.AnimationFrame} component - The Animation Last Frame.
+     */
+    getLastFrame: function ()
+    {
+        return this.frames[this.frames.length - 1];
+    },
+
     /**
      * [description]
      *
@@ -622,8 +641,18 @@ var Animation = new Class({
 
             if (component.repeatCounter > 0)
             {
-                //  Repeat (happens before complete)
-                this.repeatAnimation(component);
+                if(!component.forward)
+                {
+                    component.currentFrame = this.getLastFrame();
+
+                    component.updateFrame(component.currentFrame);
+                    this.getNextTick(component);
+                }
+                else
+                {
+                    //  Repeat (happens before complete)
+                    this.repeatAnimation(component);
+                }
             }
             else
             {
@@ -705,9 +734,7 @@ var Animation = new Class({
         {
             component.repeatCounter--;
 
-            component.forward = true;
-
-            component.updateFrame(component.currentFrame.nextFrame);
+            component.updateFrame(component.currentFrame[(component.forward) ? 'nextFrame' : 'prevFrame']);
 
             if (component.isPlaying)
             {

src/gameobjects/components/Animation.js

@@ -520,6 +520,23 @@ var Animation = new Class({
         return gameObject;
     },
 
+    /**
+     * Revert an Animation that is already playing on the Game Object.
+     *
+     * @method Phaser.GameObjects.Components.Animation#revert
+     *
+     * @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.
+     */
+    revert: function (key)
+    {
+        if (!this.isPlaying || this.currentAnim.key !== key) { return this.parent; }
+        this.forward = !this.forward;
+
+        return this.parent;
+    },
+
     /**
      * Returns a value between 0 and 1 indicating how far this animation is through, ignoring repeats and yoyos.
      * If the animation has a non-zero repeat defined, `getProgress` and `getTotalProgress` will be different