Merge branch 'master' into containers

Author: bitnenfer

CHANGELOG.md

@@ -49,6 +49,7 @@ being passed to the simulation. The default value is 1 to remain consistent with
 * The ComputedSize Component now has `setSize` and `setDisplaySize` methods. This component is used for Game Objects that have a non-texture based size.
 * The GamepadManager now extends EventEmitter directly, just like the KeyboardManager does.
 * The Gamepad Axis threshold has been increased from 0.05 to 0.1.
+* Utils.Array.FindClosestInSorted has a new optional argument `key` which will allow you to scan a top-level property of any object in the given sorted array and get the closest match to it.
 
 ### Animation Component Updates
 
@@ -67,6 +68,7 @@ We have refactored the Animation API to make it more consistent with the rest of
 * `play` now returns the parent Game Object instead of the component.
 * `progress` method has been removed.
 * `getProgress` returns the animation progress value.
+* `setProgress` lets you jump the animation to a specific progress point.
 * `repeat` method has been removed.
 * `getRepeat` returns the animation repeat value.
 * `setRepeat` sets the number of times the current animation will repeat.
@@ -88,6 +90,8 @@ We have refactored the Animation API to make it more consistent with the rest of
 * `updateFrame` now supports animation frames with custom pivot points and injects these into the Game Object origin.
 * `destroy` now removes events, references to the Animation Manager and parent Game Object, clears the current animation and frame and empties internal arrays.
 * Changing the `yoyo` property on an Animation Component would have no effect as it only ever checked the global property, it now checks the local one properly allowing you to specify a `yoyo` on a per Game Object basis.
+* Animation.destroy now properly clears the global animation object.
+* Animation.getFrameByProgress will return the Animation Frame that is closest to the given progress value. For example, in a 5 frame animation calling this method with a value of 0.5 would return the middle frame.
 
 ### Examples, Documentation and TypeScript
 

src/animations/Animation.js

@@ -4,7 +4,9 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
+var Clamp = require('../math/Clamp');
 var Class = require('../utils/Class');
+var FindClosestInSorted = require('../utils/array/FindClosestInSorted');
 var Frame = require('./AnimationFrame');
 var GetValue = require('../utils/object/GetValue');
 
@@ -340,8 +342,8 @@ var Animation = new Class({
          */
         this.paused = false;
 
-        this.manager.on('pauseall', this.pause.bind(this));
-        this.manager.on('resumeall', this.resume.bind(this));
+        this.manager.on('pauseall', this.pause, this);
+        this.manager.on('resumeall', this.resume, this);
     },
 
     /**
@@ -632,6 +634,23 @@ var Animation = new Class({
         component.updateFrame(this.frames[startFrame]);
     },
 
+    /**
+     * Returns the frame closest to the given progress value between 0 and 1.
+     *
+     * @method Phaser.Animations.Animation#getFrameByProgress
+     * @since 3.4.0
+     *
+     * @param {float} value - A value between 0 and 1.
+     *
+     * @return {Phaser.Animations.AnimationFrame} [description]
+     */
+    getFrameByProgress: function (value)
+    {
+        value = Clamp(value, 0, 1);
+
+        return FindClosestInSorted(value, this.frames, 'progress');
+    },
+
     /**
      * [description]
      *
@@ -927,7 +946,19 @@ var Animation = new Class({
      */
     destroy: function ()
     {
-        //  TODO
+        this.manager.off('pauseall', this.pause, this);
+        this.manager.off('resumeall', this.resume, this);
+
+        this.manager.remove(this.key);
+
+        for (var i = 0; i < this.frames.length; i++)
+        {
+            this.frames[i].destroy();
+        }
+
+        this.frames = [];
+
+        this.manager = null;
     }
 
 });

src/gameobjects/components/Animation.js

@@ -507,10 +507,9 @@ var Animation = new Class({
 
     /**
      * Takes a value between 0 and 1 and uses it to set how far this animation is through playback.
-     * Does not factor in repeats or yoyos.
+     * Does not factor in repeats or yoyos, but does handle playing forwards or backwards.
      *
      * @method Phaser.GameObjects.Components.Animation#setProgress
-     * @todo
      * @since 3.4.0
      *
      * @param {float} [value=0] - [description]
@@ -519,6 +518,13 @@ var Animation = new Class({
      */
     setProgress: function (value)
     {
+        if (!this.forward)
+        {
+            value = 1 - value;
+        }
+
+        this.setCurrentFrame(this.animationManager.getFrameByProgress(value));
+
         return this.parent;
     },
 

src/utils/array/FindClosestInSorted.js

@@ -12,31 +12,64 @@
  *
  * @param {number} value - The value to search for in the array.
  * @param {array} array - The array to search, which must be sorted.
+ * @param {string} [key] - An optional property key. If specified the array elements property will be checked against value.
  *
- * @return {number} The nearest value found in the array.
+ * @return {number|object} The nearest value found in the array, or if a `key` was given, the nearest object with the matching property value.
  */
-var FindClosestInSorted = function (value, array)
+var FindClosestInSorted = function (value, array, key)
 {
     if (!array.length)
     {
         return NaN;
     }
-    else if (array.length === 1 || value < array[0])
+    else if (array.length === 1)
     {
         return array[0];
     }
 
     var i = 1;
+    var low;
+    var high;
 
-    while (array[i] < value)
+    if (key)
     {
-        i++;
+        if (value < array[0][key])
+        {
+            return array[0];
+        }
+
+        while (array[i][key] < value)
+        {
+            i++;
+        }
+    }
+    else
+    {
+        while (array[i] < value)
+        {
+            i++;
+        }
     }
 
-    var low = array[i - 1];
-    var high = (i < array.length) ? array[i] : Number.POSITIVE_INFINITY;
+    if (i > array.length)
+    {
+        i = array.length;
+    }
 
-    return ((high - value) <= (value - low)) ? high : low;
+    if (key)
+    {
+        low = array[i - 1][key];
+        high = array[i][key];
+
+        return ((high - value) <= (value - low)) ? array[i] : array[i - 1];
+    }
+    else
+    {
+        low = array[i - 1];
+        high = array[i];
+
+        return ((high - value) <= (value - low)) ? high : low;
+    }
 };
 
 module.exports = FindClosestInSorted;