A large refactor to how the internal game timers and physics calculations has been made. We've now swapped to using a fixed time step internally across Phaser, instead of the variable one we had before that caused glitchse on low-fps systems. Thanks to pjbaron for his help with all of these related changes.

photonstorm · photonstorm · commit a0cc4c3777f3 · 2014-11-08T18:54:54.000Z
We have separated the logic and render updates to permit slow motion and time slicing effects. We've fixed time calling to fix physics problems caused by variable time updates (i.e. collisions sometimes missing, objects tunneling, etc)

Once per frame calling for rendering and tweening to keep things as smooth as possible

Calculates a `suggestedFps` value (in multiples of 5 fps) based on a 2 second average of actual elapsed time values in the `Time.update` method.  This is recalculated every 2 seconds so it could be used on a level-by-level basis if a game varies dramatically. I.e. if the fps rate consistently drops, you can adjust your game effects accordingly.

Game loop now tries to "catch up" frames if it is falling behind by iterating the logic update. This will help if the logic is occasionally causing things to run too slow, or if the renderer occasionally pushes the combined frame time over the FPS time. It's not a band-aid for a game that floods a low powered device however, so you still need to code accordingly. But it should help capture issues such as gc spikes or temporarily overloaded CPUs.

It now detects 'spiralling' which happens if a lot of frames are pushed out in succession meaning the CPU can never "catch up". It skips frames instead of trying to catch them up in this case. Note: the time value passed to the logic update functions is always constant regardless of these shenanigans.

Signals to the game program if there is a problem which might be fixed by lowering the desiredFps

Time.desiredFps is the new desired frame rate for your game.

Time.suggestedFps is the suggested frame rate for the game based on system load.

Time.slowMotion allows you to push the game into a slow motion mode. The default value is 1.0. 2.0 would be half speed, and so on.

Time.timeCap is no longer used and now deprecated. All timing is now handled by the fixed time-step code we've introduced.
diff --git a/README.md b/README.md
@@ -93,6 +93,17 @@ Version 2.1.4 - "Bethal" - in development
 * ScaleManager.documentWidth returns the document width in pixels.
 * ScaleManager.documentHeight returns the document height in pixels.
 * TilemapLayers have been given a decent performance boost on canvas with map shifting edge-redraw (thanks @pnstickne #1250)
+* A large refactor to how the internal game timers and physics calculations has been made. We've now swapped to using a fixed time step internally across Phaser, instead of the variable one we had before that caused glitchse on low-fps systems. Thanks to pjbaron for his help with all of these related changes.
+* We have separated the logic and render updates to permit slow motion and time slicing effects. We've fixed time calling to fix physics problems caused by variable time updates (i.e. collisions sometimes missing, objects tunneling, etc)
+* Once per frame calling for rendering and tweening to keep things as smooth as possible
+* Calculates a `suggestedFps` value (in multiples of 5 fps) based on a 2 second average of actual elapsed time values in the `Time.update` method.  This is recalculated every 2 seconds so it could be used on a level-by-level basis if a game varies dramatically. I.e. if the fps rate consistently drops, you can adjust your game effects accordingly.
+* Game loop now tries to "catch up" frames if it is falling behind by iterating the logic update. This will help if the logic is occasionally causing things to run too slow, or if the renderer occasionally pushes the combined frame time over the FPS time. It's not a band-aid for a game that floods a low powered device however, so you still need to code accordingly. But it should help capture issues such as gc spikes or temporarily overloaded CPUs.
+* It now detects 'spiralling' which happens if a lot of frames are pushed out in succession meaning the CPU can never "catch up". It skips frames instead of trying to catch them up in this case. Note: the time value passed to the logic update functions is always constant regardless of these shenanigans.
+* Signals to the game program if there is a problem which might be fixed by lowering the desiredFps
+* Time.desiredFps is the new desired frame rate for your game.
+* Time.suggestedFps is the suggested frame rate for the game based on system load.
+* Time.slowMotion allows you to push the game into a slow motion mode. The default value is 1.0. 2.0 would be half speed, and so on.
+* Time.timeCap is no longer used and now deprecated. All timing is now handled by the fixed time-step code we've introduced.
 
 ### Updates
 
diff --git a/src/core/Game.js b/src/core/Game.js
@@ -66,6 +66,18 @@ Phaser.Game = function (width, height, renderer, parent, state, transparent, ant
     */
     this.height = 600;
 
+    /**
+    * @property {integer} _width - Private internal var.
+    * @private
+    */
+    this._width = 800;
+
+    /**
+    * @property {integer} _height - Private internal var.
+    * @private
+    */
+    this._height = 600;
+
     /**
     * @property {boolean} transparent - Use a transparent canvas background or not.
     * @default
@@ -274,8 +286,36 @@ Phaser.Game = function (width, height, renderer, parent, state, transparent, ant
     */
     this._codePaused = false;
 
-    this._width = 800;
-    this._height = 600;
+    /**
+    * @property {number} _deltaTime - accumulate elapsed time until a logic update is due
+    * @private
+    */
+    this._deltaTime = 0;
+
+    /**
+     * @property {number} _lastCount - remember how many 'catch-up' iterations were used on the logicUpdate last frame
+     * @private
+     */
+    this._lastCount = 0;
+
+    /**
+     * @property {number} _spiralling - if the 'catch-up' iterations are spiralling out of control, this counter is incremented
+     * @private
+     */
+    this._spiralling = 0;
+
+    /**
+     * @property {Phaser.Signal} fpsProblemNotifier - if the game is struggling to maintain the desiredFps, this signal will be dispatched
+     *                                                to suggest that the program adjust it's fps closer to the Time.suggestedFps value
+     * @public
+     */
+    this.fpsProblemNotifier = new Phaser.Signal();
+
+    /**
+     * @property {number} _nextNotification - the soonest game.time.time value that the next fpsProblemNotifier can be dispatched
+     * @private
+     */
+    this._nextFpsNotification = 0;
 
     //  Parse the configuration object (if any)
     if (arguments.length === 1 && typeof arguments[0] === 'object')
@@ -650,12 +690,68 @@ Phaser.Game.prototype = {
     *
     * @method Phaser.Game#update
     * @protected
-    * @param {number} time - The current time as provided by RequestAnimationFrame.
+    * @param {number} time - The current time as provided by Date.now (see updateRAF in RequestAnimationFrame.js) in milliseconds
     */
     update: function (time) {
 
         this.time.update(time);
 
+        // if the logic time is spiralling upwards, skip a frame entirely
+        if (this._spiralling > 1)
+        {
+            // cause an event to warn the program that this CPU can't keep up with the current desiredFps rate
+            if (this.time.time > this._nextFpsNotification)
+            {
+                // only permit one fps notification per 10 seconds
+                this._nextFpsNotification = this.time.time + 1000 * 10;
+
+                // dispatch the notification signal
+                this.fpsProblemNotifier.dispatch();
+            }
+
+            // reset the _deltaTime accumulator which will cause all pending dropped frames to be permanently skipped
+            this._deltaTime = 0;
+            this._spiralling = 0;
+        }
+        else
+        {
+            // step size taking into account the slow motion speed
+            var slowStep = this.time.slowMotion * 1000.0 / this.time.desiredFps;
+
+            // accumulate time until the slowStep threshold is met or exceeded
+            this._deltaTime += Math.max(Math.min(1000, this.time.elapsed), 0);
+
+            // call the game update logic multiple times if necessary to "catch up" with dropped frames
+            var count = 0;
+
+            while (this._deltaTime >= slowStep)
+            {
+                this._deltaTime -= slowStep;
+                this.updateLogic(1.0 / this.time.desiredFps);
+                count++;
+            }
+
+            // detect spiralling (if the catch-up loop isn't fast enough, the number of iterations will increase constantly)
+            if (count > this._lastCount)
+            {
+                this._spiralling++;
+            }
+            else if (count < this._lastCount)
+            {
+                // looks like it caught up successfully, reset the spiral alert counter
+                this._spiralling = 0;
+            }
+
+            this._lastCount = count;
+        }
+
+        // call the game render update exactly once every frame
+        this.updateRender(this._deltaTime / slowStep);
+
+    },
+
+    updateLogic: function (timeStep) {
+
         if (!this._paused && !this.pendingStep)
         {
             if (this.stepping)
@@ -677,7 +773,6 @@ Phaser.Game.prototype = {
 
             this.state.update();
             this.stage.update();
-            this.tweens.update();
             this.sound.update();
             this.input.update();
             this.physics.update();
@@ -696,6 +791,15 @@ Phaser.Game.prototype = {
                 this.debug.preUpdate();
             }
         }
+    },
+
+    updateRender: function (elapsedTime) {
+
+        // update tweens once every frame along with the render logic (to keep them smooth in slowMotion scenarios)
+        if (!this._paused && !this.pendingStep)
+        {
+            this.tweens.update(elapsedTime);
+        }
 
         if (this.renderType != Phaser.HEADLESS)
         {
diff --git a/src/particles/arcade/Emitter.js b/src/particles/arcade/Emitter.js
@@ -265,7 +265,7 @@ Phaser.Particles.Arcade.Emitter.prototype.update = function () {
             }
         }
 
-        this._timer = this.game.time.now + this.frequency;
+        this._timer = this.game.time.now + this.frequency * this.game.time.slowMotion;
     }
 
     var i = this.children.length;
@@ -436,7 +436,7 @@ Phaser.Particles.Arcade.Emitter.prototype.start = function (explode, lifespan, f
         this.on = true;
         this._quantity += quantity;
         this._counter = 0;
-        this._timer = this.game.time.now + frequency;
+        this._timer = this.game.time.now + frequency * this.game.time.slowMotion;
     }
 
 };
diff --git a/src/system/RequestAnimationFrame.js b/src/system/RequestAnimationFrame.js
@@ -103,10 +103,12 @@ Phaser.RequestAnimationFrame.prototype = {
     /**
     * The update method for the requestAnimationFrame
     * @method Phaser.RequestAnimationFrame#updateRAF
+    * 
     */
-    updateRAF: function () {
+    updateRAF: function (rafTime) {
 
-        this.game.update(Date.now());
+        // floor the rafTime to make it equivalent to the Date.now() provided by updateSetTimeout (just below)
+        this.game.update(Math.floor(rafTime));
 
         this._timeOutID = window.requestAnimationFrame(this._onLoop);
 
diff --git a/src/time/Time.js b/src/time/Time.js
@@ -21,6 +21,7 @@ Phaser.Time = function (game) {
 
     /**
     * @property {number} time - Game time counter. If you need a value for in-game calculation please use Phaser.Time.now instead.
+    *                         - This always contains Date.now, but Phaser.Time.now will hold the high resolution RAF timer value (if RAF is available)
     * @protected
     */
     this.time = 0;
@@ -49,6 +50,35 @@ Phaser.Time = function (game) {
     */
     this.pausedTime = 0;
 
+    /**
+     * @property {number} desiredFps = 60 - The desired frame-rate for this project.
+     */
+    this.desiredFps = 60;
+
+    /**
+     * @property {number} suggestedFps = null - The suggested frame-rate for this project.
+     * NOTE: not available until after a few frames have passed, it is recommended to use this after a few seconds (eg. after the menus)
+     */
+    this.suggestedFps = null;
+
+    /**
+     * @property {number} _frameCount - count the number of calls to time.update since the last suggestedFps was calculated
+     * @private
+     */
+    this._frameCount = 0;
+
+    /**
+     * @property {number} _elapsedAcumulator - sum of the elapsed time since the last suggestedFps was calculated
+     * @private
+     */
+    this._elapsedAccumulator = 0;
+
+    /**
+     * @property {number} slowMotion = 1.0 - Scaling factor to make the game move smoothly in slow motion (1.0 = normal speed, 2.0 = half speed)
+     * @type {Number}
+     */
+    this.slowMotion = 1.0;
+
     /**
     * @property {boolean} advancedTiming - If true Phaser.Time will perform advanced profiling including the fps rate, fps min/max and msMin and msMax.
     * @default
@@ -93,9 +123,12 @@ Phaser.Time = function (game) {
     this.deltaCap = 0;
 
     /**
-    * @property {number} timeCap - If the difference in time between two frame updates exceeds this value, the frame time is reset to avoid huge elapsed counts.
+    * @property {number} timeCap - If the difference in time between two frame updates exceeds this value in ms, the frame time is reset to avoid huge elapsed counts.
+    *                            - assumes a desiredFps of 60
+    *
+    * DEPRECATED: this no longer has any effect since the change to fixed-time stepping in game.update  3rd November 2014
     */
-    this.timeCap = 1 / 60 * 1000;
+    this.timeCap = 1000 / 60;
 
     /**
     * @property {number} frames - The number of frames record in the last second. Only calculated if Time.advancedTiming is true.
@@ -113,9 +146,9 @@ Phaser.Time = function (game) {
     this.timeToCall = 0;
 
     /**
-    * @property {number} lastTime - Internal value used by timeToCall as part of the setTimeout loop
+    * @property {number} timeExpected - The time when the next call is expected when using setTimer to control the update loop
     */
-    this.lastTime = 0;
+    this.timeExpected = 0;
 
     /**
     * @property {Phaser.Timer} events - This is a Phaser.Timer object bound to the master clock to which you can add timed events.
@@ -242,25 +275,39 @@ Phaser.Time.prototype = {
     */
     update: function (time) {
 
+        // this.time always holds Date.now, this.now may hold the RAF high resolution time value if RAF is available (otherwise it also holds Date.now)
+        this.time = Date.now();
+
+        // 'now' is currently still holding the time of the last call, move it into prevTime
         this.prevTime = this.now;
 
+        // update 'now' to hold the current time
         this.now = time;
 
-        this.timeToCall = this.game.math.max(0, 16 - (time - this.lastTime));
+        // elapsed time between previous call and now
+        this.elapsed = this.now - this.prevTime;
 
-        this.elapsed = this.now - this.time;
+        // time to call this function again in ms in case we're using timers instead of RequestAnimationFrame to update the game
+        this.timeToCall = Math.floor(this.game.math.max(0, (1000.0 / this.desiredFps) - (this.timeCallExpected - time)));
 
-        //  spike-dislike
-        if (this.elapsed > this.timeCap)
+        // time when the next call is expected if using timers
+        this.timeCallExpected = time + this.timeToCall;
+
+        // count the number of time.update calls
+        this._frameCount++;
+        this._elapsedAccumulator += this.elapsed;
+
+        // occasionally recalculate the suggestedFps based on the accumulated elapsed time
+        if (this._frameCount >= this.desiredFps * 2)
         {
-            //  For some reason the time between now and the last time the game was updated was larger than our timeCap
-            //  This can happen if the Stage.disableVisibilityChange is true and you swap tabs, which makes the raf pause.
-            //  In this case we'll drop to some default values to stop the game timers going nuts.
-            this.elapsed = this.timeCap;
+            // this formula calculates suggestedFps in multiples of 5 fps
+            this.suggestedFps = Math.floor(200 / (this._elapsedAccumulator / this._frameCount)) * 5;
+            this._frameCount = 0;
+            this._elapsedAccumulator = 0;
         }
 
-        //  Calculate physics elapsed, ensure it's > 0, use 1/60 as a fallback
-        this.physicsElapsed = this.elapsed / 1000 || 1 / 60;
+        //  Set the physics elapsed time... this will always be 1 / this.desiredFps because we're using fixed time steps in game.update now
+        this.physicsElapsed = 1 / this.desiredFps;
 
         if (this.deltaCap > 0 && this.physicsElapsed > this.deltaCap)
         {
@@ -284,9 +331,6 @@ Phaser.Time.prototype = {
             }
         }
 
-        this.time = this.now;
-        this.lastTime = time + this.timeToCall;
-
         //  Paused but still running?
         if (!this.game.paused)
         {
@@ -322,7 +366,7 @@ Phaser.Time.prototype = {
     */
     gamePaused: function () {
 
-        this._pauseStarted = this.now;
+        this._pauseStarted = Date.now();
 
         this.events.pause();
 
@@ -343,8 +387,8 @@ Phaser.Time.prototype = {
     */
     gameResumed: function () {
 
-        //  Level out the elapsed timer to avoid spikes
-        this.time = this.now = Date.now();
+        // Set the parameter which stores Date.now() to make sure it's correct on resume
+        this.time = Date.now();
 
         this.pauseDuration = this.time - this._pauseStarted;
 
diff --git a/src/tween/Tween.js b/src/tween/Tween.js

Original file line number	Diff line number	Diff line change
`@@ -265,7 +265,7 @@ Phaser.Particles.Arcade.Emitter.prototype.update = function () {`
`265`	`265`	`}`
`266`	`266`	`}`
`267`	`267`
`268`		`- this._timer = this.game.time.now + this.frequency;`
	`268`	`+ this._timer = this.game.time.now + this.frequency * this.game.time.slowMotion;`
`269`	`269`	`}`
`270`	`270`
`271`	`271`	`var i = this.children.length;`
`@@ -436,7 +436,7 @@ Phaser.Particles.Arcade.Emitter.prototype.start = function (explode, lifespan, f`
`436`	`436`	`this.on = true;`
`437`	`437`	`this._quantity += quantity;`
`438`	`438`	`this._counter = 0;`
`439`		`- this._timer = this.game.time.now + frequency;`
	`439`	`+ this._timer = this.game.time.now + frequency * this.game.time.slowMotion;`
`440`	`440`	`}`
`441`	`441`
`442`	`442`	`};`