Adding the Scene Events.

Author: photonstorm

src/scene/Systems.js

@@ -7,6 +7,7 @@
 var Class = require('../utils/Class');
 var CONST = require('./const');
 var DefaultPlugins = require('../plugins/DefaultPlugins');
+var Events = require('./events');
 var GetPhysicsPlugins = require('./GetPhysicsPlugins');
 var GetScenePlugins = require('./GetScenePlugins');
 var NOOP = require('../utils/NOOP');
@@ -301,6 +302,7 @@ var Systems = new Class({
      *
      * @method Phaser.Scenes.Systems#init
      * @protected
+     * @fires Phaser.Scenes.Events#BOOT
      * @since 3.0.0
      *
      * @param {Phaser.Game} game - A reference to the Phaser Game instance.
@@ -323,7 +325,7 @@ var Systems = new Class({
 
         pluginManager.addToScene(this, DefaultPlugins.Global, [ DefaultPlugins.CoreScene, GetScenePlugins(this), GetPhysicsPlugins(this) ]);
 
-        this.events.emit('boot', this);
+        this.events.emit(Events.BOOT, this);
 
         this.settings.isBooted = true;
     },
@@ -352,27 +354,31 @@ var Systems = new Class({
      * Frame or Set Timeout call to the main Game instance.
      *
      * @method Phaser.Scenes.Systems#step
+     * @fires Phaser.Scenes.Events#PRE_UPDATE
+     * @fires Phaser.Scenes.Events#_UPDATE
+     * @fires Phaser.Scenes.Events#POST_UPDATE
      * @since 3.0.0
      *
      * @param {number} time - The time value from the most recent Game step. Typically a high-resolution timer value, or Date.now().
      * @param {number} delta - The delta value since the last frame. This is smoothed to avoid delta spikes by the TimeStep class.
      */
     step: function (time, delta)
     {
-        this.events.emit('preupdate', time, delta);
+        this.events.emit(Events.PRE_UPDATE, time, delta);
 
-        this.events.emit('update', time, delta);
+        this.events.emit(Events.UPDATE, time, delta);
 
         this.sceneUpdate.call(this.scene, time, delta);
 
-        this.events.emit('postupdate', time, delta);
+        this.events.emit(Events.POST_UPDATE, time, delta);
     },
 
     /**
      * Called automatically by the Scene Manager.
      * Instructs the Scene to render itself via its Camera Manager to the renderer given.
      *
      * @method Phaser.Scenes.Systems#render
+     * @fires Phaser.Scenes.Events#RENDER
      * @since 3.0.0
      *
      * @param {(Phaser.Renderer.Canvas.CanvasRenderer|Phaser.Renderer.WebGL.WebGLRenderer)} renderer - The renderer that invoked the render call.
@@ -385,7 +391,7 @@ var Systems = new Class({
 
         this.cameras.render(renderer, displayList);
 
-        this.events.emit('render', renderer);
+        this.events.emit(Events.RENDER, renderer);
     },
 
     /**
@@ -415,6 +421,7 @@ var Systems = new Class({
      * A paused Scene still renders, it just doesn't run ANY of its update handlers or systems.
      *
      * @method Phaser.Scenes.Systems#pause
+     * @fires Phaser.Scenes.Events#PAUSE
      * @since 3.0.0
      * 
      * @param {object} [data] - A data object that will be passed in the 'pause' event.
@@ -429,7 +436,7 @@ var Systems = new Class({
 
             this.settings.active = false;
 
-            this.events.emit('pause', this, data);
+            this.events.emit(Events.PAUSE, this, data);
         }
 
         return this;
@@ -439,6 +446,7 @@ var Systems = new Class({
      * Resume this Scene from a paused state.
      *
      * @method Phaser.Scenes.Systems#resume
+     * @fires Phaser.Scenes.Events#RESUME
      * @since 3.0.0
      *
      * @param {object} [data] - A data object that will be passed in the 'resume' event.
@@ -453,7 +461,7 @@ var Systems = new Class({
 
             this.settings.active = true;
 
-            this.events.emit('resume', this, data);
+            this.events.emit(Events.RESUME, this, data);
         }
 
         return this;
@@ -468,6 +476,7 @@ var Systems = new Class({
      * from other Scenes may still invoke changes within it, so be careful what is left active.
      *
      * @method Phaser.Scenes.Systems#sleep
+     * @fires Phaser.Scenes.Events#SLEEP
      * @since 3.0.0
      * 
      * @param {object} [data] - A data object that will be passed in the 'sleep' event.
@@ -481,7 +490,7 @@ var Systems = new Class({
         this.settings.active = false;
         this.settings.visible = false;
 
-        this.events.emit('sleep', this, data);
+        this.events.emit(Events.SLEEP, this, data);
 
         return this;
     },
@@ -490,6 +499,7 @@ var Systems = new Class({
      * Wake-up this Scene if it was previously asleep.
      *
      * @method Phaser.Scenes.Systems#wake
+     * @fires Phaser.Scenes.Events#WAKE
      * @since 3.0.0
      *
      * @param {object} [data] - A data object that will be passed in the 'wake' event.
@@ -505,7 +515,7 @@ var Systems = new Class({
         settings.active = true;
         settings.visible = true;
 
-        this.events.emit('wake', this, data);
+        this.events.emit(Events.WAKE, this, data);
 
         if (settings.isTransition)
         {
@@ -654,6 +664,8 @@ var Systems = new Class({
      * Called automatically by the SceneManager.
      *
      * @method Phaser.Scenes.Systems#start
+     * @fires Phaser.Scenes.Events#START
+     * @fires Phaser.Scenes.Events#READY
      * @since 3.0.0
      *
      * @param {object} data - Optional data object that may have been passed to this Scene from another.
@@ -671,10 +683,10 @@ var Systems = new Class({
         this.settings.visible = true;
 
         //  For plugins to listen out for
-        this.events.emit('start', this);
+        this.events.emit(Events.START, this);
 
         //  For user-land code to listen out for
-        this.events.emit('ready', this, data);
+        this.events.emit(Events.READY, this, data);
     },
 
     /**
@@ -685,6 +697,7 @@ var Systems = new Class({
      * to free-up resources.
      *
      * @method Phaser.Scenes.Systems#shutdown
+     * @fires Phaser.Scenes.Events#SHUTDOWN
      * @since 3.0.0
      * 
      * @param {object} [data] - A data object that will be passed in the 'shutdown' event.
@@ -701,7 +714,7 @@ var Systems = new Class({
         this.settings.active = false;
         this.settings.visible = false;
 
-        this.events.emit('shutdown', this, data);
+        this.events.emit(Events.SHUTDOWN, this, data);
     },
 
     /**
@@ -711,6 +724,7 @@ var Systems = new Class({
      *
      * @method Phaser.Scenes.Systems#destroy
      * @private
+     * @fires Phaser.Scenes.Events#DESTROY
      * @since 3.0.0
      */
     destroy: function ()
@@ -720,7 +734,7 @@ var Systems = new Class({
         this.settings.active = false;
         this.settings.visible = false;
 
-        this.events.emit('destroy', this);
+        this.events.emit(Events.DESTROY, this);
 
         this.events.removeAllListeners();
 

src/scene/events/BOOT_EVENT.js

@@ -0,0 +1,18 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Scene Systems Boot Event.
+ * 
+ * This event is dispatched by a Scene during the Scene Systems boot process. Primarily used by Scene Plugins.
+ * 
+ * Listen to it from a Scene using `this.scene.events.on('boot', listener)`.
+ * 
+ * @event Phaser.Scenes.Events#BOOT
+ * 
+ * @param {Phaser.Scenes.Systems} sys - A reference to the Scene Systems class of the Scene that emitted this event.
+ */
+module.exports = 'boot';

src/scene/events/DESTROY_EVENT.js

@@ -0,0 +1,20 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Scene Systems Destroy Event.
+ * 
+ * This event is dispatched by a Scene during the Scene Systems destroy process.
+ * 
+ * Listen to it from a Scene using `this.scene.events.on('destroy', listener)`.
+ * 
+ * You should destroy any resources that may be in use by your Scene in this event handler.
+ * 
+ * @event Phaser.Scenes.Events#DESTROY
+ * 
+ * @param {Phaser.Scenes.Systems} sys - A reference to the Scene Systems class of the Scene that emitted this event.
+ */
+module.exports = 'destroy';

src/scene/events/PAUSE_EVENT.js

@@ -0,0 +1,20 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Scene Systems Pause Event.
+ * 
+ * This event is dispatched by a Scene when it is paused, either directly via the `pause` method, or as an
+ * action from another Scene.
+ * 
+ * Listen to it from a Scene using `this.scene.events.on('pause', listener)`.
+ * 
+ * @event Phaser.Scenes.Events#PAUSE
+ * 
+ * @param {Phaser.Scenes.Systems} sys - A reference to the Scene Systems class of the Scene that emitted this event.
+ * @param {any} [data] - An optional data object that was passed to this Scene when it was paused.
+ */
+module.exports = 'pause';

src/scene/events/POST_UPDATE_EVENT.js

@@ -0,0 +1,30 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Scene Systems Post Update Event.
+ * 
+ * This event is dispatched by a Scene during the main game loop step.
+ * 
+ * The event flow for a single step of a Scene is as follows:
+ * 
+ * 1) [PRE_UPDATE]{Phaser.Scenes.Events#PRE_UPDATE}
+ * 2) [UPDATE]{Phaser.Scenes.Events#UPDATE}
+ * 3) The Scene.update method is called, if it exists
+ * 4) [POST_UPDATE]{Phaser.Scenes.Events#POST_UPDATE}
+ * 5) [RENDER]{Phaser.Scenes.Events#RENDER}
+ * 
+ * Listen to it from a Scene using `this.scene.events.on('postupdate', listener)`.
+ * 
+ * A Scene will only run its step if it is active.
+ * 
+ * @event Phaser.Scenes.Events#POST_UPDATE
+ * 
+ * @param {Phaser.Scenes.Systems} sys - A reference to the Scene Systems class of the Scene that emitted this event.
+ * @param {number} time - The current time. Either a High Resolution Timer value if it comes from Request Animation Frame, or Date.now if using SetTimeout.
+ * @param {number} delta - The delta time in ms since the last frame. This is a smoothed and capped value based on the FPS rate.
+ */
+module.exports = 'postupdate';

src/scene/events/PRE_UPDATE_EVENT.js

@@ -0,0 +1,30 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Scene Systems Pre Update Event.
+ * 
+ * This event is dispatched by a Scene during the main game loop step.
+ * 
+ * The event flow for a single step of a Scene is as follows:
+ * 
+ * 1) [PRE_UPDATE]{Phaser.Scenes.Events#PRE_UPDATE}
+ * 2) [UPDATE]{Phaser.Scenes.Events#UPDATE}
+ * 3) The Scene.update method is called, if it exists
+ * 4) [POST_UPDATE]{Phaser.Scenes.Events#POST_UPDATE}
+ * 5) [RENDER]{Phaser.Scenes.Events#RENDER}
+ * 
+ * Listen to it from a Scene using `this.scene.events.on('preupdate', listener)`.
+ * 
+ * A Scene will only run its step if it is active.
+ * 
+ * @event Phaser.Scenes.Events#PRE_UPDATE
+ * 
+ * @param {Phaser.Scenes.Systems} sys - A reference to the Scene Systems class of the Scene that emitted this event.
+ * @param {number} time - The current time. Either a High Resolution Timer value if it comes from Request Animation Frame, or Date.now if using SetTimeout.
+ * @param {number} delta - The delta time in ms since the last frame. This is a smoothed and capped value based on the FPS rate.
+ */
+module.exports = 'preupdate';

src/scene/events/READY_EVENT.js

@@ -0,0 +1,21 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Scene Systems Ready Event.
+ * 
+ * This event is dispatched by a Scene during the Scene Systems start process.
+ * By this point in the process the Scene is now fully active and rendering.
+ * This event is meant for your game code to use, as all plugins have responded to the earlier 'start' event.
+ * 
+ * Listen to it from a Scene using `this.scene.events.on('ready', listener)`.
+ * 
+ * @event Phaser.Scenes.Events#READY
+ * 
+ * @param {Phaser.Scenes.Systems} sys - A reference to the Scene Systems class of the Scene that emitted this event.
+ * @param {any} [data] - An optional data object that was passed to this Scene when it was started.
+ */
+module.exports = 'ready';

src/scene/events/RENDER_EVENT.js

@@ -0,0 +1,29 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Scene Systems Render Event.
+ * 
+ * This event is dispatched by a Scene during the main game loop step.
+ * 
+ * The event flow for a single step of a Scene is as follows:
+ * 
+ * 1) [PRE_UPDATE]{Phaser.Scenes.Events#PRE_UPDATE}
+ * 2) [UPDATE]{Phaser.Scenes.Events#UPDATE}
+ * 3) The Scene.update method is called, if it exists
+ * 4) [POST_UPDATE]{Phaser.Scenes.Events#POST_UPDATE}
+ * 5) [RENDER]{Phaser.Scenes.Events#RENDER}
+ * 
+ * Listen to it from a Scene using `this.scene.events.on('render', listener)`.
+ * 
+ * A Scene will only render if it is visible and active.
+ * By the time this event is dispatched, the Scene will have already been rendered.
+ * 
+ * @event Phaser.Scenes.Events#RENDER
+ * 
+ * @param {(Phaser.Renderer.Canvas.CanvasRenderer|Phaser.Renderer.WebGL.WebGLRenderer)} renderer - The renderer that rendered the Scene.
+ */
+module.exports = 'render';

src/scene/events/RESUME_EVENT.js

@@ -0,0 +1,20 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Scene Systems Resume Event.
+ * 
+ * This event is dispatched by a Scene when it is resumed from a paused state, either directly via the `resume` method,
+ * or as an action from another Scene.
+ * 
+ * Listen to it from a Scene using `this.scene.events.on('resume', listener)`.
+ * 
+ * @event Phaser.Scenes.Events#RESUME
+ * 
+ * @param {Phaser.Scenes.Systems} sys - A reference to the Scene Systems class of the Scene that emitted this event.
+ * @param {any} [data] - An optional data object that was passed to this Scene when it was resumed.
+ */
+module.exports = 'resume';