StateManager.restart allows you to quickly restart the *current* state, optionally clearing the world and cache.

Author: photonstorm

README.md

@@ -91,6 +91,7 @@ New Features
 * Sound.destroy will remove a sound and all local references it holds, optionally removing itself from the SoundManager as well.
 * SoundManager.removeByKey(key) will remove all sounds from the SoundManager that have a key matching the given value.
 * ArcadePhysics.Body.hitTest(x, y) will return a boolean based on if the given world coordinate are within the Body or not.
+* StateManager.restart allows you to quickly restart the *current* state, optionally clearing the world and cache.
 
 
 Bug Fixes

src/core/StateManager.js

@@ -206,7 +206,7 @@ Phaser.StateManager.prototype = {
     */
     remove: function (key) {
 
-        if (this.current == key)
+        if (this.current === key)
         {
             this.callbackContext = null;
 
@@ -257,6 +257,31 @@ Phaser.StateManager.prototype = {
 
     },
 
+    /**
+    * Restarts the current State. State.shutDown will be called (if it exists) before the State is restarted.
+    *
+    * @method Phaser.StateManager#restart
+    * @param {boolean} [clearWorld=true] - Clear everything in the world? This clears the World display list fully (but not the Stage, so if you've added your own objects to the Stage they will need managing directly)
+    * @param {boolean} [clearCache=false] - Clear the Game.Cache? This purges out all loaded assets. The default is false and you must have clearWorld=true if you want to clearCache as well.
+    * @param {...*} parameter - Additional parameters that will be passed to the State.init function if it has one.
+    */
+    restart: function (clearWorld, clearCache) {
+
+        if (typeof clearWorld === "undefined") { clearWorld = true; }
+        if (typeof clearCache === "undefined") { clearCache = false; }
+
+        //  Place the state in the queue. It will be started the next time the game loop starts.
+        this._pendingState = this.current;
+        this._clearWorld = clearWorld;
+        this._clearCache = clearCache;
+
+        if (arguments.length > 3)
+        {
+            this._args = Array.prototype.splice.call(arguments, 3);
+        }
+
+    },
+
     /**
     * Used by onInit and onShutdown when those functions don't exist on the state
     * @method Phaser.StateManager#dummy