TimeStep.now is a new property that holds the exact performance.now value, as set at the start of the current game step. Also, completed jsdocs.

Author: photonstorm

src/core/TimeStep.js

@@ -185,37 +185,39 @@ var TimeStep = new Class({
         this.forceSetTimeOut = GetValue(config, 'forceSetTimeOut', false);
 
         /**
-         * [description]
+         * The time, calculated at the start of the current step, as smoothed by the delta value.
          *
          * @name Phaser.Core.TimeStep#time
-         * @type {integer}
+         * @type {number}
          * @default 0
          * @since 3.0.0
          */
         this.time = 0;
 
         /**
-         * [description]
+         * The time at which the game started running. This value is adjusted if the game is then
+         * paused and resumes.
          *
          * @name Phaser.Core.TimeStep#startTime
-         * @type {integer}
+         * @type {number}
          * @default 0
          * @since 3.0.0
          */
         this.startTime = 0;
 
         /**
-         * [description]
+         * The time, as returned by `performance.now` of the previous step.
          *
          * @name Phaser.Core.TimeStep#lastTime
-         * @type {integer}
+         * @type {number}
          * @default 0
          * @since 3.0.0
          */
         this.lastTime = 0;
 
         /**
-         * [description]
+         * The current frame the game is on. This counter is incremented once every game step, regardless of how much
+         * time has passed and is unaffected by delta smoothing.
          *
          * @name Phaser.Core.TimeStep#frame
          * @type {integer}
@@ -226,7 +228,8 @@ var TimeStep = new Class({
         this.frame = 0;
 
         /**
-         * [description]
+         * Is the browser currently considered in focus by the Page Visibility API?
+         * This value is set in the `blur` method, which is called automatically by the Game instance.
          *
          * @name Phaser.Core.TimeStep#inFocus
          * @type {boolean}
@@ -237,18 +240,18 @@ var TimeStep = new Class({
         this.inFocus = true;
 
         /**
-         * [description]
+         * The timestamp at which the game became paused, as determined by the Page Visibility API.
          *
          * @name Phaser.Core.TimeStep#_pauseTime
-         * @type {integer}
+         * @type {number}
          * @private
          * @default 0
          * @since 3.0.0
          */
         this._pauseTime = 0;
 
         /**
-         * [description]
+         * An internal counter to allow for the browser 'cooling down' after coming back into focus.
          *
          * @name Phaser.Core.TimeStep#_coolDown
          * @type {integer}
@@ -259,7 +262,7 @@ var TimeStep = new Class({
         this._coolDown = 0;
 
         /**
-         * [description]
+         * The delta time, in ms, since the last game step. This is a clamped and smoothed average value.
          *
          * @name Phaser.Core.TimeStep#delta
          * @type {integer}
@@ -269,7 +272,7 @@ var TimeStep = new Class({
         this.delta = 0;
 
         /**
-         * [description]
+         * Internal index of the delta history position.
          *
          * @name Phaser.Core.TimeStep#deltaIndex
          * @type {integer}
@@ -279,7 +282,7 @@ var TimeStep = new Class({
         this.deltaIndex = 0;
 
         /**
-         * [description]
+         * Internal array holding the previous delta values, used for delta smoothing.
          *
          * @name Phaser.Core.TimeStep#deltaHistory
          * @type {integer[]}
@@ -288,7 +291,9 @@ var TimeStep = new Class({
         this.deltaHistory = [];
 
         /**
-         * [description]
+         * The maximum number of delta values that are retained in order to calculate a smoothed moving average.
+         * 
+         * This can be changed in the Game Config via the `fps.deltaHistory` property. The default is 10.
          *
          * @name Phaser.Core.TimeStep#deltaSmoothingMax
          * @type {integer}
@@ -298,7 +303,10 @@ var TimeStep = new Class({
         this.deltaSmoothingMax = GetValue(config, 'deltaHistory', 10);
 
         /**
-         * [description]
+         * The number of frames that the cooldown is set to after the browser panics over the FPS rate, usually
+         * as a result of switching tabs and regaining focus.
+         * 
+         * This can be changed in the Game Config via the `fps.panicMax` property. The default is 120.
          *
          * @name Phaser.Core.TimeStep#panicMax
          * @type {integer}
@@ -309,19 +317,31 @@ var TimeStep = new Class({
 
         /**
          * The actual elapsed time in ms between one update and the next.
-         * Unlike with `delta` no smoothing, capping, or averaging is applied to this value.
-         * So please be careful when using this value in calculations.
+         * 
+         * Unlike with `delta`, no smoothing, capping, or averaging is applied to this value.
+         * So please be careful when using this value in math calculations.
          *
          * @name Phaser.Core.TimeStep#rawDelta
          * @type {number}
          * @default 0
          * @since 3.0.0
          */
         this.rawDelta = 0;
+
+        /**
+         * The time, as returned by `performance.now` at the very start of the current step.
+         * This can differ from the `time` value in that it isn't calculated based on the delta value.
+         *
+         * @name Phaser.Core.TimeStep#now
+         * @type {number}
+         * @default 0
+         * @since 3.18.0
+         */
+        this.now = 0;
     },
 
     /**
-     * Called when the DOM window.onBlur event triggers.
+     * Called by the Game instance when the DOM window.onBlur event triggers.
      *
      * @method Phaser.Core.TimeStep#blur
      * @since 3.0.0
@@ -332,7 +352,7 @@ var TimeStep = new Class({
     },
 
     /**
-     * Called when the DOM window.onFocus event triggers.
+     * Called by the Game instance when the DOM window.onFocus event triggers.
      *
      * @method Phaser.Core.TimeStep#focus
      * @since 3.0.0
@@ -369,7 +389,8 @@ var TimeStep = new Class({
     },
 
     /**
-     * [description]
+     * Resets the time, lastTime, fps averages and delta history.
+     * Called automatically when a browser sleeps them resumes.
      *
      * @method Phaser.Core.TimeStep#resetDelta
      * @since 3.0.0
@@ -442,8 +463,11 @@ var TimeStep = new Class({
         //  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
         //  more accurate one:
+
         var time = window.performance.now();
 
+        this.now = time;
+
         var before = time - this.lastTime;
 
         if (before < 0)
@@ -558,7 +582,7 @@ var TimeStep = new Class({
     },
 
     /**
-     * Manually calls TimeStep.step, passing in the performance.now value to it.
+     * Manually calls `TimeStep.step`.
      *
      * @method Phaser.Core.TimeStep#tick
      * @since 3.0.0
@@ -608,7 +632,7 @@ var TimeStep = new Class({
 
         this.running = true;
 
-        this.step(window.performance.now());
+        this.step();
     },
 
     /**