Added Scene Transition Events

Author: photonstorm

src/scene/SceneManager.js

@@ -6,6 +6,7 @@
 
 var Class = require('../utils/Class');
 var CONST = require('./const');
+var Events = require('./events');
 var GetValue = require('../utils/object/GetValue');
 var NOOP = require('../utils/NOOP');
 var Scene = require('./Scene');
@@ -439,6 +440,7 @@ var SceneManager = new Class({
      *
      * @method Phaser.Scenes.SceneManager#bootScene
      * @private
+     * @fires Phaser.Scenes.Events#TRANSITION_INIT
      * @since 3.0.0
      *
      * @param {Phaser.Scene} scene - The Scene to boot.
@@ -456,7 +458,7 @@ var SceneManager = new Class({
 
             if (settings.isTransition)
             {
-                sys.events.emit('transitioninit', settings.transitionFrom, settings.transitionDuration);
+                sys.events.emit(Events.TRANSITION_INIT, settings.transitionFrom, settings.transitionDuration);
             }
         }
 
@@ -589,6 +591,7 @@ var SceneManager = new Class({
      *
      * @method Phaser.Scenes.SceneManager#create
      * @private
+     * @fires Phaser.Scenes.Events#TRANSITION_INIT
      * @since 3.0.0
      *
      * @param {Phaser.Scene} scene - The Scene to create.
@@ -607,7 +610,7 @@ var SceneManager = new Class({
 
         if (settings.isTransition)
         {
-            sys.events.emit('transitionstart', settings.transitionFrom, settings.transitionDuration);
+            sys.events.emit(Events.TRANSITION_START, settings.transitionFrom, settings.transitionDuration);
         }
 
         //  If the Scene has an update function we'll set it now, otherwise it'll remain as NOOP

src/scene/ScenePlugin.js

@@ -6,6 +6,7 @@
 
 var Clamp = require('../math/Clamp');
 var Class = require('../utils/Class');
+var Events = require('./events');
 var GetFastValue = require('../utils/object/GetFastValue');
 var PluginCache = require('../plugins/PluginCache');
 
@@ -251,7 +252,7 @@ var ScenePlugin = new Class({
      *
      * This Scene can either be sent to sleep at the end of the transition, or stopped. The default is to stop.
      *
-     * There are also 5 transition related events: This scene will emit the event `transitionto` when
+     * There are also 5 transition related events: This scene will emit the event `transitionout` when
      * the transition begins, which is typically the frame after calling this method.
      *
      * The target Scene will emit the event `transitioninit` when that Scene's `init` method is called.
@@ -270,6 +271,7 @@ var ScenePlugin = new Class({
      * override this understand that until the target Scene completes it might never be unlocked for input events.
      *
      * @method Phaser.Scenes.ScenePlugin#transition
+     * @fires Phaser.Scenes.Events#TRANSITION_OUT
      * @since 3.5.0
      *
      * @param {Phaser.Scenes.ScenePlugin.SceneTransitionConfig} config - The transition configuration object.
@@ -334,7 +336,7 @@ var ScenePlugin = new Class({
             this.manager.start(key, GetFastValue(config, 'data'));
         }
 
-        this.systems.events.emit('transitionout', target, duration);
+        this.systems.events.emit(Events.TRANSITION_OUT, target, duration);
 
         this.systems.events.on('update', this.step, this);
 
@@ -396,6 +398,7 @@ var ScenePlugin = new Class({
      *
      * @method Phaser.Scenes.ScenePlugin#transitionComplete
      * @private
+     * @fires Phaser.Scenes.Events#TRANSITION_COMPLETE
      * @since 3.5.0
      */
     transitionComplete: function ()
@@ -407,7 +410,7 @@ var ScenePlugin = new Class({
         this.systems.events.off('update', this.step, this);
 
         //  Notify target scene
-        targetSys.events.emit('transitioncomplete', this.scene);
+        targetSys.events.emit(Events.TRANSITION_COMPLETE, this.scene);
 
         //  Clear target scene settings
         targetSettings.isTransition = false;

src/scene/Systems.js

@@ -519,7 +519,7 @@ var Systems = new Class({
 
         if (settings.isTransition)
         {
-            this.events.emit('transitionwake', settings.transitionFrom, settings.transitionDuration);
+            this.events.emit(Events.TRANSITION_WAKE, settings.transitionFrom, settings.transitionDuration);
         }
 
         return this;

src/scene/events/TRANSITION_COMPLETE_EVENT.js

@@ -7,10 +7,21 @@
 /**
  * The Scene Transition Complete Event.
  * 
- * This event is dispatched by a Scene when the Scene Transition process completes.
+ * This event is dispatched by the Target Scene of a transition.
+ * 
+ * It happens when the transition process has completed. This occurs when the duration timer equals or exceeds the duration
+ * of the transition.
  * 
  * Listen to it from a Scene using `this.scene.events.on('transitioncomplete', listener)`.
  * 
+ * The Scene Transition event flow is as follows:
+ * 
+ * 1) [TRANSITION_OUT]{Phaser.Scenes.Events#TRANSITION_OUT} - the Scene that started the transition will emit this event.
+ * 2) [TRANSITION_INIT]{Phaser.Scenes.Events#TRANSITION_INIT} - the Target Scene will emit this event if it has an `init` method.
+ * 3a) [TRANSITION_START]{Phaser.Scenes.Events#TRANSITION_START} - the Target Scene will emit this event after its `create` method is called, OR ...
+ * 3b) [TRANSITION_WAKE]{Phaser.Scenes.Events#TRANSITION_WAKE} - the Target Scene will emit this event if it was asleep and has been woken-up to be transitioned to.
+ * 4) [TRANSITION_COMPLETE]{Phaser.Scenes.Events#TRANSITION_COMPLETE} - the Target Scene will emit this event when the transition finishes.
+ * 
  * @event Phaser.Scenes.Events#TRANSITION_COMPLETE
  * 
  * @param {Phaser.Scene} scene -The Scene on which the transitioned completed.

src/scene/events/TRANSITION_INIT_EVENT.js

@@ -7,10 +7,21 @@
 /**
  * The Scene Transition Init Event.
  * 
- * This event is dispatched by a Scene during the Scene Transition process.
+ * This event is dispatched by the Target Scene of a transition.
+ * 
+ * It happens immediately after the `Scene.init` method is called. If the Scene does not have an `init` method,
+ * this event is not dispatched.
  * 
  * Listen to it from a Scene using `this.scene.events.on('transitioninit', listener)`.
  * 
+ * The Scene Transition event flow is as follows:
+ * 
+ * 1) [TRANSITION_OUT]{Phaser.Scenes.Events#TRANSITION_OUT} - the Scene that started the transition will emit this event.
+ * 2) [TRANSITION_INIT]{Phaser.Scenes.Events#TRANSITION_INIT} - the Target Scene will emit this event if it has an `init` method.
+ * 3a) [TRANSITION_START]{Phaser.Scenes.Events#TRANSITION_START} - the Target Scene will emit this event after its `create` method is called, OR ...
+ * 3b) [TRANSITION_WAKE]{Phaser.Scenes.Events#TRANSITION_WAKE} - the Target Scene will emit this event if it was asleep and has been woken-up to be transitioned to.
+ * 4) [TRANSITION_COMPLETE]{Phaser.Scenes.Events#TRANSITION_COMPLETE} - the Target Scene will emit this event when the transition finishes.
+ * 
  * @event Phaser.Scenes.Events#TRANSITION_INIT
  * 
  * @param {Phaser.Scene} from - A reference to the Scene that is being transitioned from.

src/scene/events/TRANSITION_OUT_EVENT.js

@@ -0,0 +1,27 @@
+/**
+ * @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 Transition Out Event.
+ * 
+ * This event is dispatched by a Scene when it initiates a transition to another Scene.
+ * 
+ * Listen to it from a Scene using `this.scene.events.on('transitionout', listener)`.
+ * 
+ * The Scene Transition event flow is as follows:
+ * 
+ * 1) [TRANSITION_OUT]{Phaser.Scenes.Events#TRANSITION_OUT} - the Scene that started the transition will emit this event.
+ * 2) [TRANSITION_INIT]{Phaser.Scenes.Events#TRANSITION_INIT} - the Target Scene will emit this event if it has an `init` method.
+ * 3a) [TRANSITION_START]{Phaser.Scenes.Events#TRANSITION_START} - the Target Scene will emit this event after its `create` method is called, OR ...
+ * 3b) [TRANSITION_WAKE]{Phaser.Scenes.Events#TRANSITION_WAKE} - the Target Scene will emit this event if it was asleep and has been woken-up to be transitioned to.
+ * 4) [TRANSITION_COMPLETE]{Phaser.Scenes.Events#TRANSITION_COMPLETE} - the Target Scene will emit this event when the transition finishes.
+ * 
+ * @event Phaser.Scenes.Events#TRANSITION_OUT
+ * 
+ * @param {Phaser.Scene} target - A reference to the Scene that is being transitioned to.
+ * @param {number} duration - The duration of the transition in ms.
+ */
+module.exports = 'transitionout';

src/scene/events/TRANSITION_START_EVENT.js

@@ -7,10 +7,24 @@
 /**
  * The Scene Transition Start Event.
  * 
- * This event is dispatched by a Scene during the Scene Transition process.
+ * This event is dispatched by the Target Scene of a transition, only if that Scene was not asleep.
+ * 
+ * It happens immediately after the `Scene.create` method is called. If the Scene does not have a `create` method,
+ * this event is dispatched anyway.
+ * 
+ * If the Target Scene was sleeping then the [TRANSITION_WAKE]{Phaser.Scenes.Events#TRANSITION_WAKE} event is
+ * dispatched instead of this event.
  * 
  * Listen to it from a Scene using `this.scene.events.on('transitionstart', listener)`.
  * 
+ * The Scene Transition event flow is as follows:
+ * 
+ * 1) [TRANSITION_OUT]{Phaser.Scenes.Events#TRANSITION_OUT} - the Scene that started the transition will emit this event.
+ * 2) [TRANSITION_INIT]{Phaser.Scenes.Events#TRANSITION_INIT} - the Target Scene will emit this event if it has an `init` method.
+ * 3a) [TRANSITION_START]{Phaser.Scenes.Events#TRANSITION_START} - the Target Scene will emit this event after its `create` method is called, OR ...
+ * 3b) [TRANSITION_WAKE]{Phaser.Scenes.Events#TRANSITION_WAKE} - the Target Scene will emit this event if it was asleep and has been woken-up to be transitioned to.
+ * 4) [TRANSITION_COMPLETE]{Phaser.Scenes.Events#TRANSITION_COMPLETE} - the Target Scene will emit this event when the transition finishes.
+ * 
  * @event Phaser.Scenes.Events#TRANSITION_START
  * 
  * @param {Phaser.Scene} from - A reference to the Scene that is being transitioned from.

src/scene/events/TRANSITION_WAKE_EVENT.js

@@ -0,0 +1,28 @@
+/**
+ * @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 Transition Wake Event.
+ * 
+ * This event is dispatched by the Target Scene of a transition, only if that Scene was asleep before
+ * the transition began. If the Scene was not asleep the [TRANSITION_START]{Phaser.Scenes.Events#TRANSITION_START} event is dispatched instead.
+ * 
+ * Listen to it from a Scene using `this.scene.events.on('transitionwake', listener)`.
+ * 
+ * The Scene Transition event flow is as follows:
+ * 
+ * 1) [TRANSITION_OUT]{Phaser.Scenes.Events#TRANSITION_OUT} - the Scene that started the transition will emit this event.
+ * 2) [TRANSITION_INIT]{Phaser.Scenes.Events#TRANSITION_INIT} - the Target Scene will emit this event if it has an `init` method.
+ * 3a) [TRANSITION_START]{Phaser.Scenes.Events#TRANSITION_START} - the Target Scene will emit this event after its `create` method is called, OR ...
+ * 3b) [TRANSITION_WAKE]{Phaser.Scenes.Events#TRANSITION_WAKE} - the Target Scene will emit this event if it was asleep and has been woken-up to be transitioned to.
+ * 4) [TRANSITION_COMPLETE]{Phaser.Scenes.Events#TRANSITION_COMPLETE} - the Target Scene will emit this event when the transition finishes.
+ * 
+ * @event Phaser.Scenes.Events#TRANSITION_WAKE
+ * 
+ * @param {Phaser.Scene} from - A reference to the Scene that is being transitioned from.
+ * @param {number} duration - The duration of the transition in ms.
+ */
+module.exports = 'transitionwake';

src/scene/events/index.js

@@ -23,7 +23,9 @@ module.exports = {
     START: require('./START_EVENT'),
     TRANSITION_COMPLETE: require('./TRANSITION_COMPLETE_EVENT'),
     TRANSITION_INIT: require('./TRANSITION_INIT_EVENT'),
+    TRANSITION_OUT: require('./TRANSITION_OUT_EVENT'),
     TRANSITION_START: require('./TRANSITION_START_EVENT'),
+    TRANSITION_WAKE: require('./TRANSITION_WAKE_EVENT'),
     UPDATE: require('./UPDATE_EVENT'),
     WAKE: require('./WAKE_EVENT')