Merge pull request phaserjs#1 from photonstorm/master

keeping up with phaser

Author: svipal

CHANGELOG.md

@@ -77,7 +77,7 @@ Extra special thanks to the following companies who's support makes Phaser possi
 * [Y8 Games](https://www.y8.com)
 * [Poki](https://developers.poki.com/)
 
-![Sponsors](https://phaser.io/images/github/sponsors-2019-08.png "Awesome  Sponsors")
+![Sponsors](https://phaser.io/images/github/sponsors-2019-12.png "Awesome  Sponsors")
 
 ![Phaser Newsletter](https://phaser.io/images/github/div-newsletter.png "Phaser Newsletter")
 

README.md

@@ -671,12 +671,12 @@ var Game = new Class({
      */
     runDestroy: function ()
     {
+        this.scene.destroy();
+        
         this.events.emit(Events.DESTROY);
 
         this.events.removeAllListeners();
 
-        this.scene.destroy();
-
         if (this.renderer)
         {
             this.renderer.destroy();

src/core/Game.js

@@ -15,14 +15,26 @@ var RequestAnimationFrame = require('../dom/RequestAnimationFrame');
 //          target: 60,
 //          forceSetTimeOut: false,
 //          deltaHistory: 10,
-//          panicMax: 120
+//          panicMax: 120,
+//          smoothStep: true
 //     }
 
 // http://www.testufo.com/#test=animation-time-graph
 
 /**
  * @classdesc
- * [description]
+ * The core runner class that Phaser uses to handle the game loop. It can use either Request Animation Frame,
+ * or SetTimeout, based on browser support and config settings, to create a continuous loop within the browser.
+ * 
+ * Each time the loop fires, `TimeStep.step` is called and this is then passed onto the core Game update loop,
+ * it is the core heartbeat of your game. It will fire as often as Request Animation Frame is capable of handling
+ * on the target device.
+ * 
+ * Note that there are lots of situations where a browser will stop updating your game. Such as if the player
+ * switches tabs, or covers up the browser window with another application. In these cases, the 'heartbeat'
+ * of your game will pause, and only resume when focus is returned to it by the player. There is no way to avoid
+ * this situation, all you can do is use the visibility events the browser, and Phaser, provide to detect when
+ * it has happened and then gracefully recover.
  *
  * @class TimeStep
  * @memberof Phaser.Core
@@ -49,7 +61,7 @@ var TimeStep = new Class({
         this.game = game;
 
         /**
-         * [description]
+         * The Request Animation Frame DOM Event handler.
          *
          * @name Phaser.Core.TimeStep#raf
          * @type {Phaser.DOM.RequestAnimationFrame}
@@ -141,7 +153,8 @@ var TimeStep = new Class({
         this.actualFps = this.targetFps;
 
         /**
-         * [description]
+         * The time at which the next fps rate update will take place.
+         * When an fps update happens, the `framesThisSecond` value is reset.
          *
          * @name Phaser.Core.TimeStep#nextFpsUpdate
          * @type {integer}
@@ -338,6 +351,22 @@ var TimeStep = new Class({
          * @since 3.18.0
          */
         this.now = 0;
+
+        /**
+         * Apply smoothing to the delta value used within Phasers internal calculations?
+         * 
+         * This can be changed in the Game Config via the `fps.smoothStep` property. The default is `true`.
+         * 
+         * Smoothing helps settle down the delta values after browser tab switches, or other situations
+         * which could cause significant delta spikes or dips. By default it has been enabled in Phaser 3
+         * since the first version, but is now exposed under this property (and the corresponding game config
+         * `smoothStep` value), to allow you to easily disable it, should you require.
+         *
+         * @name Phaser.Core.TimeStep#smoothStep
+         * @type {boolean}
+         * @since 3.22.0
+         */
+        this.smoothStep = GetValue(config, 'smoothStep', true);
     },
 
     /**
@@ -461,7 +490,7 @@ var TimeStep = new Class({
     step: function ()
     {
         //  Because the timestamp passed in from raf represents the beginning of the main thread frame that we’re currently in,
-        //  not the actual time now. As we want to compare this time value against Event timeStamps and the like, we need a
+        //  not the actual time now, and as we want to compare this time value against Event timeStamps and the like, we need a
         //  more accurate one:
 
         var time = window.performance.now();
@@ -485,55 +514,59 @@ var TimeStep = new Class({
         //  delta time (time is in ms)
         var dt = before;
 
+        //  Delta Average
+        var avg = before;
+
         //  When a browser switches tab, then comes back again, it takes around 10 frames before
         //  the delta time settles down so we employ a 'cooling down' period before we start
         //  trusting the delta values again, to avoid spikes flooding through our delta average
 
-        if (this._coolDown > 0 || !this.inFocus)
-        {
-            this._coolDown--;
-
-            dt = Math.min(dt, this._target);
-        }
-
-        if (dt > this._min)
-        {
-            //  Probably super bad start time or browser tab context loss,
-            //  so use the last 'sane' dt value
-
-            dt = history[idx];
-
-            //  Clamp delta to min (in case history has become corrupted somehow)
-            dt = Math.min(dt, this._min);
-        }
-
-        //  Smooth out the delta over the previous X frames
-
-        //  add the delta to the smoothing array
-        history[idx] = dt;
-
-        //  adjusts the delta history array index based on the smoothing count
-        //  this stops the array growing beyond the size of deltaSmoothingMax
-        this.deltaIndex++;
-
-        if (this.deltaIndex > max)
+        if (this.smoothStep)
         {
-            this.deltaIndex = 0;
+            if (this._coolDown > 0 || !this.inFocus)
+            {
+                this._coolDown--;
+    
+                dt = Math.min(dt, this._target);
+            }
+    
+            if (dt > this._min)
+            {
+                //  Probably super bad start time or browser tab context loss,
+                //  so use the last 'sane' dt value
+    
+                dt = history[idx];
+    
+                //  Clamp delta to min (in case history has become corrupted somehow)
+                dt = Math.min(dt, this._min);
+            }
+    
+            //  Smooth out the delta over the previous X frames
+    
+            //  add the delta to the smoothing array
+            history[idx] = dt;
+    
+            //  adjusts the delta history array index based on the smoothing count
+            //  this stops the array growing beyond the size of deltaSmoothingMax
+            this.deltaIndex++;
+    
+            if (this.deltaIndex > max)
+            {
+                this.deltaIndex = 0;
+            }
+    
+            //  Loop the history array, adding the delta values together
+            avg = 0;
+    
+            for (var i = 0; i < max; i++)
+            {
+                avg += history[i];
+            }
+    
+            //  Then divide by the array length to get the average delta
+            avg /= max;
         }
 
-        //  Delta Average
-        var avg = 0;
-
-        //  Loop the history array, adding the delta values together
-
-        for (var i = 0; i < max; i++)
-        {
-            avg += history[i];
-        }
-
-        //  Then divide by the array length to get the average delta
-        avg /= max;
-
         //  Set as the world delta value
         this.delta = avg;
 
@@ -667,7 +700,7 @@ var TimeStep = new Class({
      * @method Phaser.Core.TimeStep#stop
      * @since 3.0.0
      *
-     * @return {Phaser.Core.TimeStep} The TimeStep object.
+     * @return {this} The TimeStep object.
      */
     stop: function ()
     {

src/core/TimeStep.js

@@ -7,4 +7,5 @@
  * @property {boolean} [forceSetTimeOut=false] - Use setTimeout instead of requestAnimationFrame to run the game loop.
  * @property {integer} [deltaHistory=10] - Calculate the average frame delta from this many consecutive frame intervals.
  * @property {integer} [panicMax=120] - The amount of frames the time step counts before we trust the delta values again.
+ * @property {boolean} [smoothStep=true] - Apply delta smoothing during the game update to help avoid spikes?
  */

src/core/typedefs/FPSConfig.js

@@ -353,24 +353,37 @@ var Curve = new Class({
      * @method Phaser.Curves.Curve#getSpacedPoints
      * @since 3.0.0
      *
-     * @param {integer} [divisions] - [description]
+     * @param {integer} [divisions] - The number of evenly spaced points from the curve to return. If falsy, step param will be used to calculate the number of points.
+     * @param {number} [step] - Step between points. Used to calculate the number of points to return when divisions is falsy. Ignored if divisions is positive.     
+     * @param {(array|Phaser.Math.Vector2[])} [out] - An optional array to store the points in.
      *
      * @return {Phaser.Math.Vector2[]} [description]
      */
-    getSpacedPoints: function (divisions)
+    getSpacedPoints: function (divisions, stepRate, out)
     {
-        if (divisions === undefined) { divisions = this.defaultDivisions; }
+        if (out === undefined) { out = []; }
 
-        var points = [];
+        //  If divisions is a falsey value (false, null, 0, undefined, etc) then we calculate it based on the stepRate instead.
+        if (!divisions)
+        {
+            if (!stepRate)
+            {
+                divisions = this.defaultDivisions;
+            }
+            else
+            {
+                divisions = this.getLength() / stepRate;
+            }
+        }
 
         for (var d = 0; d <= divisions; d++)
         {
             var t = this.getUtoTmapping(d / divisions, null, divisions);
 
-            points.push(this.getPoint(t));
+            out.push(this.getPoint(t));
         }
 
-        return points;
+        return out;
     },
 
     /**

src/curves/Curve.js

@@ -194,6 +194,41 @@ var LineCurve = new Class({
         return tangent.normalize();
     },
 
+    //  Override default Curve.getUtoTmapping
+
+    /**
+     * [description]
+     *
+     * @method Phaser.Curves.Line#getUtoTmapping
+     * @since 3.0.0
+     *
+     * @param {number} u - [description]
+     * @param {integer} distance - [description]
+     * @param {integer} [divisions] - [description]
+     *
+     * @return {number} [description]
+     */
+    getUtoTmapping: function (u, distance, divisions)
+    {
+        var t;
+
+        if (distance)
+        {
+            var arcLengths = this.getLengths(divisions);
+            var lineLength = arcLengths[arcLengths.length - 1];
+            //  Cannot overshoot the curve
+            var targetLineLength = Math.min(distance, lineLength);
+
+            t = targetLineLength / lineLength;
+        }
+        else
+        {
+            t = u;
+        }        
+
+        return t;
+    },
+
     //  Override default Curve.draw because this is better than calling getPoints on a line!
 
     /**

src/curves/LineCurve.js

@@ -63,7 +63,7 @@ var GameObjectCreator = new Class({
         /**
          * A reference to the Scene Update List.
          *
-         * @name Phaser.GameObjects.GameObjectCreator#updateList;
+         * @name Phaser.GameObjects.GameObjectCreator#updateList
          * @type {Phaser.GameObjects.UpdateList}
          * @protected
          * @since 3.0.0

src/gameobjects/GameObjectCreator.js

@@ -62,7 +62,7 @@ var GameObjectFactory = new Class({
         /**
          * A reference to the Scene Update List.
          *
-         * @name Phaser.GameObjects.GameObjectFactory#updateList;
+         * @name Phaser.GameObjects.GameObjectFactory#updateList
          * @type {Phaser.GameObjects.UpdateList}
          * @protected
          * @since 3.0.0
@@ -105,7 +105,7 @@ var GameObjectFactory = new Class({
 
     /**
      * Adds an existing Game Object to this Scene.
-     * 
+     *
      * If the Game Object renders, it will be added to the Display List.
      * If it has a `preUpdate` method, it will be added to the Update List.
      *
@@ -167,8 +167,19 @@ var GameObjectFactory = new Class({
 
 });
 
-//  Static method called directly by the Game Object factory functions
-
+/**
+ * Static method called directly by the Game Object factory functions.
+ * With this method you can register a custom GameObject factory in the GameObjectFactory,
+ * providing a name (`factoryType`) and the constructor (`factoryFunction`) in order
+ * to be called when you call to Phaser.Scene.add[ factoryType ] method.
+ *
+ * @method Phaser.GameObjects.GameObjectFactory.register
+ * @static
+ * @since 3.0.0
+ *
+ * @param {string} factoryType - The key of the factory that you will use to call to Phaser.Scene.add[ factoryType ] method.
+ * @param {function} factoryFunction - The constructor function to be called when you invoke to the Phaser.Scene.add method.
+ */
 GameObjectFactory.register = function (factoryType, factoryFunction)
 {
     if (!GameObjectFactory.prototype.hasOwnProperty(factoryType))
@@ -177,6 +188,17 @@ GameObjectFactory.register = function (factoryType, factoryFunction)
     }
 };
 
+/**
+ * Static method called directly by the Game Object factory functions.
+ * With this method you can remove a custom GameObject factory registered in the GameObjectFactory,
+ * providing a its `factoryType`.
+ *
+ * @method Phaser.GameObjects.GameObjectFactory.remove
+ * @static
+ * @since 3.0.0
+ *
+ * @param {string} factoryType - The key of the factory that you want to remove from the GameObjectFactory.
+ */
 GameObjectFactory.remove = function (factoryType)
 {
     if (GameObjectFactory.prototype.hasOwnProperty(factoryType))

src/gameobjects/GameObjectFactory.js

@@ -20,8 +20,8 @@ var ParseXMLBitmapFont = require('./ParseXMLBitmapFont');
  * @param {string} textureKey - The key of the BitmapFont's texture.
  * @param {string} frameKey - The key of the BitmapFont texture's frame.
  * @param {string} xmlKey - The key of the XML data of the font to parse.
- * @param {integer} xSpacing - The x-axis spacing to add between each letter.
- * @param {integer} ySpacing - The y-axis spacing to add to the line height.
+ * @param {integer} [xSpacing] - The x-axis spacing to add between each letter.
+ * @param {integer} [ySpacing] - The y-axis spacing to add to the line height.
  *
  * @return {boolean} Whether the parsing was successful or not.
  */