Finished all the new Tween Events

src/tweens/events/TWEEN_ACTIVE_EVENT.js

@@ -9,14 +9,18 @@
  * 
  * This event is dispatched by a Tween when it becomes active within the Tween Manager.
  * 
+ * An 'active' Tween is one that is now progressing, although it may not yet be updating
+ * any target properties, due to settings such as `delay`. If you need an event for when
+ * the Tween starts actually updating its first property, see `TWEEN_START`.
+ * 
  * Listen to it from a Tween instance using `Tween.on('active', listener)`, i.e.:
  * 
  * ```javascript
  * var tween = this.tweens.add({
  *     targets: image,
+ *     x: 500,
  *     ease: 'Power1',
- *     duration: 3000,
+ *     duration: 3000
- *     tweens: [ { x: 600 }, { y: 500 }, { x: 100 }, { y: 100 } ]
  * });
  * tween.on('active', listener);
  * ```
@@ -25,5 +29,6 @@
  * @since 3.19.0
  * 
  * @param {Phaser.Tweens.Tween} tween - A reference to the Tween instance that emitted the event.
+ * @param {any[]} targets - An array of references to the target/s the Tween is operating on.
  */
 module.exports = 'active';

src/tweens/events/TWEEN_COMPLETE_EVENT.js

@@ -7,16 +7,21 @@
 /**
  * The Tween Complete Event.
  * 
- * This event is dispatched by a Tween when it completes playback.
+ * This event is dispatched by a Tween when it completes playback entirely, factoring in repeats and loops.
+ * 
+ * If the Tween has been set to loop or repeat infinitely, this event will not be dispatched
+ * unless the `Tween.stop` method is called.
+ * 
+ * If a Tween has a `completeDelay` set, this event will fire after that delay expires.
  * 
  * Listen to it from a Tween instance using `Tween.on('complete', listener)`, i.e.:
  * 
  * ```javascript
  * var tween = this.tweens.add({
  *     targets: image,
+ *     x: 500,
  *     ease: 'Power1',
- *     duration: 3000,
+ *     duration: 3000
- *     tweens: [ { x: 600 }, { y: 500 }, { x: 100 }, { y: 100 } ]
  * });
  * tween.on('complete', listener);
  * ```
@@ -25,5 +30,6 @@
  * @since 3.19.0
  * 
  * @param {Phaser.Tweens.Tween} tween - A reference to the Tween instance that emitted the event.
+ * @param {any[]} targets - An array of references to the target/s the Tween is operating on.
  */
 module.exports = 'complete';

src/tweens/events/TWEEN_LOOP_EVENT.js

@@ -0,0 +1,38 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+/**
+ * The Tween Loop Event.
+ * 
+ * This event is dispatched by a Tween when it loops.
+ * 
+ * This event will only be dispatched if the Tween has a loop count set.
+ * 
+ * If a Tween has a `loopDelay` set, this event will fire after that delay expires.
+ * 
+ * The difference between `loop` and `repeat` is that `repeat` is a property setting,
+ * where-as `loop` applies to the entire Tween.
+ * 
+ * Listen to it from a Tween instance using `Tween.on('loop', listener)`, i.e.:
+ * 
+ * ```javascript
+ * var tween = this.tweens.add({
+ *     targets: image,
+ *     x: 500,
+ *     ease: 'Power1',
+ *     duration: 3000,
+ *     loop: 6
+ * });
+ * tween.on('loop', listener);
+ * ```
+ *
+ * @event Phaser.Tweens.Events#TWEEN_LOOP
+ * @since 3.19.0
+ * 
+ * @param {Phaser.Tweens.Tween} tween - A reference to the Tween instance that emitted the event.
+ * @param {any[]} targets - An array of references to the target/s the Tween is operating on.
+ */
+module.exports = 'loop';

src/tweens/events/TWEEN_REPEAT_EVENT.js

@@ -0,0 +1,39 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+/**
+ * The Tween Repeat Event.
+ * 
+ * This event is dispatched by a Tween when one of the properties it is tweening repeats.
+ * 
+ * This event will only be dispatched if the Tween has a property with a repeat count set.
+ * 
+ * If a Tween has a `repeatDelay` set, this event will fire after that delay expires.
+ * 
+ * The difference between `loop` and `repeat` is that `repeat` is a property setting,
+ * where-as `loop` applies to the entire Tween.
+ * 
+ * Listen to it from a Tween instance using `Tween.on('repeat', listener)`, i.e.:
+ * 
+ * ```javascript
+ * var tween = this.tweens.add({
+ *     targets: image,
+ *     x: 500,
+ *     ease: 'Power1',
+ *     duration: 3000,
+ *     repeat: 4
+ * });
+ * tween.on('repeat', listener);
+ * ```
+ *
+ * @event Phaser.Tweens.Events#TWEEN_REPEAT
+ * @since 3.19.0
+ * 
+ * @param {Phaser.Tweens.Tween} tween - A reference to the Tween instance that emitted the event.
+ * @param {string} key - The key of the property that just repeated.
+ * @param {any} target - The target that the property just repated on.
+ */
+module.exports = 'repeat';

src/tweens/events/TWEEN_START_EVENT.js

@@ -7,16 +7,20 @@
 /**
  * The Tween Start Event.
  * 
- * This event is dispatched by a Tween when it starts playback.
+ * This event is dispatched by a Tween when it starts tweening its first property.
+ * 
+ * A Tween will only emit this event once, as it can only start once.
+ * 
+ * If a Tween has a `delay` set, this event will fire after that delay expires.
  * 
  * Listen to it from a Tween instance using `Tween.on('start', listener)`, i.e.:
  * 
  * ```javascript
  * var tween = this.tweens.add({
  *     targets: image,
+ *     x: 500,
  *     ease: 'Power1',
- *     duration: 3000,
+ *     duration: 3000
- *     tweens: [ { x: 600 }, { y: 500 }, { x: 100 }, { y: 100 } ]
  * });
  * tween.on('start', listener);
  * ```
@@ -25,5 +29,6 @@
  * @since 3.19.0
  * 
  * @param {Phaser.Tweens.Tween} tween - A reference to the Tween instance that emitted the event.
+ * @param {any[]} targets - An array of references to the target/s the Tween is operating on.
  */
 module.exports = 'start';

src/tweens/events/TWEEN_UPDATE_EVENT.js

@@ -0,0 +1,35 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+/**
+ * The Tween Update Event.
+ * 
+ * This event is dispatched by a Tween every time it updates _any_ of the properties it is tweening.
+ * 
+ * A Tween that is changing 3 properties of a target will emit this event 3 times per change, once per property.
+ * 
+ * **Note:** This is a very high frequency event and may be dispatched multiple times, every single frame.
+ * 
+ * Listen to it from a Tween instance using `Tween.on('update', listener)`, i.e.:
+ * 
+ * ```javascript
+ * var tween = this.tweens.add({
+ *     targets: image,
+ *     x: 500,
+ *     ease: 'Power1',
+ *     duration: 3000,
+ * });
+ * tween.on('update', listener);
+ * ```
+ *
+ * @event Phaser.Tweens.Events#TWEEN_UPDATE
+ * @since 3.19.0
+ * 
+ * @param {Phaser.Tweens.Tween} tween - A reference to the Tween instance that emitted the event.
+ * @param {string} key - The property that was updated, i.e. `x` or `scale`.
+ * @param {any} target - The target object that was updated. Usually a Game Object, but can be of any type.
+ */
+module.exports = 'update';

src/tweens/events/TWEEN_YOYO_EVENT.js

@@ -0,0 +1,40 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+/**
+ * The Tween Yoyo Event.
+ * 
+ * This event is dispatched by a Tween whenever a property it is tweening yoyos.
+ * 
+ * This event will only be dispatched if the Tween has a property with `yoyo` set.
+ * 
+ * If the Tween has a `hold` value, this event is dispatched when the hold expires.
+ * 
+ * This event is dispatched for every property, and for every target, that yoyos.
+ * For example, if a Tween was updating 2 properties and had 10 targets, this event
+ * would be dispatched 20 times (twice per target). So be careful how you use it!
+ * 
+ * Listen to it from a Tween instance using `Tween.on('yoyo', listener)`, i.e.:
+ * 
+ * ```javascript
+ * var tween = this.tweens.add({
+ *     targets: image,
+ *     x: 500,
+ *     ease: 'Power1',
+ *     duration: 3000,
+ *     yoyo: true
+ * });
+ * tween.on('yoyo', listener);
+ * ```
+ *
+ * @event Phaser.Tweens.Events#TWEEN_YOYO
+ * @since 3.19.0
+ * 
+ * @param {Phaser.Tweens.Tween} tween - A reference to the Tween instance that emitted the event.
+ * @param {string} key - The property that yoyo'd, i.e. `x` or `scale`.
+ * @param {any} target - The target object that was yoyo'd. Usually a Game Object, but can be of any type.
+ */
+module.exports = 'yoyo';

src/tweens/events/index.js

@@ -18,6 +18,10 @@ module.exports = {
     TIMELINE_UPDATE: require('./TIMELINE_UPDATE_EVENT'),
     TWEEN_ACTIVE: require('./TWEEN_ACTIVE_EVENT'),
     TWEEN_COMPLETE: require('./TWEEN_COMPLETE_EVENT'),
-    TWEEN_START: require('./TWEEN_START_EVENT')
+    TWEEN_LOOP: require('./TWEEN_LOOP_EVENT'),
+    TWEEN_REPEAT: require('./TWEEN_REPEAT_EVENT'),
+    TWEEN_START: require('./TWEEN_START_EVENT'),
+    TWEEN_UPDATE: require('./TWEEN_UPDATE_EVENT'),
+    TWEEN_YOYO: require('./TWEEN_YOYO_EVENT')
 
 };

src/tweens/tween/Tween.js

@@ -146,7 +146,7 @@ var Tween = new Class({
 
         /**
          * Time in ms/frames before the 'onStart' event fires.
-         * This is the largest `delay` value across all of the TweenDatas of this Tween.
+         * This is the shortest `delay` value across all of the TweenDatas of this Tween.
          *
          * @name Phaser.Tweens.Tween#startDelay
          * @type {number}
@@ -609,6 +609,7 @@ var Tween = new Class({
      * and emits the onActive event and callback.
      *
      * @method Phaser.Tweens.Tween#makeActive
+     * @fires Phaser.Tweens.Events#TWEEN_ACTIVE
      * @since 3.19.0
      */
     makeActive: function ()
@@ -632,6 +633,7 @@ var Tween = new Class({
      * Internal method that advances to the next state of the Tween during playback.
      *
      * @method Phaser.Tweens.Tween#nextState
+     * @fires Phaser.Tweens.Events#TWEEN_COMPLETE
      * @since 3.0.0
      */
     nextState: function ()
@@ -642,15 +644,6 @@ var Tween = new Class({
             this.progress = 0;
             this.loopCounter--;
 
-            var onLoop = this.callbacks.onLoop;
-
-            if (onLoop)
-            {
-                onLoop.params[1] = this.targets;
-
-                onLoop.func.apply(onLoop.scope, onLoop.params);
-            }
-
             this.resetTweenData(true);
 
             if (this.loopDelay > 0)
@@ -670,6 +663,8 @@ var Tween = new Class({
         }
         else
         {
+            this.emit(Events.TWEEN_COMPLETE, this, this.targets);
+
             var onComplete = this.callbacks.onComplete;
 
             if (onComplete)
@@ -955,6 +950,12 @@ var Tween = new Class({
 
     /**
      * Sets an event based callback to be invoked during playback.
+     * 
+     * The `type` can be: 'onActive', 'onComplete', 'onLoop', 'onRepeat', 'onStart',
+     * 'onUpdate' or 'onYoyo'.
+     * 
+     * Calling this method will replace a previously set callback for the
+     * given type, if any exists.
      *
      * @method Phaser.Tweens.Tween#setCallback
      * @since 3.0.0
@@ -962,7 +963,7 @@ var Tween = new Class({
      * @param {string} type - Type of the callback.
      * @param {function} callback - Callback function.
      * @param {array} [params] - An array of parameters for specified callbacks types.
-     * @param {object} [scope] - The context the callback will be invoked in.
+     * @param {any} [scope] - The context the callback will be invoked in.
      *
      * @return {this} This Tween instance.
      */
@@ -982,6 +983,7 @@ var Tween = new Class({
      * If you don't need a delay, or have an onComplete callback, then call `Tween.stop` instead.
      *
      * @method Phaser.Tweens.Tween#complete
+     * @fires Phaser.Tweens.Events#TWEEN_COMPLETE
      * @since 3.2.0
      *
      * @param {number} [delay=0] - The time to wait before invoking the complete callback. If zero it will fire immediately.
@@ -999,6 +1001,8 @@ var Tween = new Class({
         }
         else
         {
+            this.emit(Events.TWEEN_COMPLETE, this, this.targets);
+
             var onComplete = this.callbacks.onComplete;
 
             if (onComplete)
@@ -1081,6 +1085,9 @@ var Tween = new Class({
      * Internal method that advances the Tween based on the time values.
      *
      * @method Phaser.Tweens.Tween#update
+     * @fires Phaser.Tweens.Events#TWEEN_COMPLETE
+     * @fires Phaser.Tweens.Events#TWEEN_START
+     * @fires Phaser.Tweens.Events#TWEEN_LOOP
      * @since 3.0.0
      *
      * @param {number} timestamp - The current time. Either a High Resolution Timer value if it comes from Request Animation Frame, or Date.now if using SetTimeout.
@@ -1120,7 +1127,7 @@ var Tween = new Class({
                     {
                         this.hasStarted = true;
 
-                        this.emit(Events.TWEEN_START, this);
+                        this.emit(Events.TWEEN_START, this, this.targets);
 
                         var onStart = this.callbacks.onStart;
 
@@ -1159,6 +1166,17 @@ var Tween = new Class({
 
                 if (this.countdown <= 0)
                 {
+                    this.emit(Events.TWEEN_LOOP, this, this.targets);
+
+                    var onLoop = this.callbacks.onLoop;
+        
+                    if (onLoop)
+                    {
+                        onLoop.params[1] = this.targets;
+        
+                        onLoop.func.apply(onLoop.scope, onLoop.params);
+                    }
+
                     this.state = TWEEN_CONST.ACTIVE;
                 }
 
@@ -1181,6 +1199,8 @@ var Tween = new Class({
 
                 if (this.countdown <= 0)
                 {
+                    this.emit(Events.TWEEN_COMPLETE, this, this.targets);
+
                     var onComplete = this.callbacks.onComplete;
 
                     if (onComplete)
@@ -1201,6 +1221,8 @@ var Tween = new Class({
      * Internal method used as part of the playback process that sets a tween to play in reverse.
      *
      * @method Phaser.Tweens.Tween#setStateFromEnd
+     * @fires Phaser.Tweens.Events#TWEEN_REPEAT
+     * @fires Phaser.Tweens.Events#TWEEN_YOYO
      * @since 3.0.0
      *
      * @param {Phaser.Tweens.Tween} tween - The Tween to update.
@@ -1224,14 +1246,13 @@ var Tween = new Class({
                 tweenData.target.toggleFlipX();
             }
 
-            //  Problem: The flip and callback and so on gets called for every TweenData that triggers it at the same time.
-            //  If you're tweening several properties it can fire for all of them, at once.
-
             if (tweenData.flipY)
             {
                 tweenData.target.toggleFlipY();
             }
 
+            this.emit(Events.TWEEN_YOYO, this, tweenData.key, tweenData.target);
+
             var onYoyo = tween.callbacks.onYoyo;
 
             if (onYoyo)
@@ -1267,16 +1288,6 @@ var Tween = new Class({
                 tweenData.target.toggleFlipY();
             }
 
-            var onRepeat = tween.callbacks.onRepeat;
-
-            if (onRepeat)
-            {
-                //  Element 1 is reserved for the target of the repeat (and needs setting here)
-                onRepeat.params[1] = tweenData.target;
-
-                onRepeat.func.apply(onRepeat.scope, onRepeat.params);
-            }
-
             tweenData.start = tweenData.getStartValue(tweenData.target, tweenData.key, tweenData.start);
 
             tweenData.end = tweenData.getEndValue(tweenData.target, tweenData.key, tweenData.start);
@@ -1294,6 +1305,18 @@ var Tween = new Class({
             }
             else
             {
+                this.emit(Events.TWEEN_REPEAT, this, tweenData.key, tweenData.target);
+
+                var onRepeat = tween.callbacks.onRepeat;
+    
+                if (onRepeat)
+                {
+                    //  Element 1 is reserved for the target of the repeat (and needs setting here)
+                    onRepeat.params[1] = tweenData.target;
+    
+                    onRepeat.func.apply(onRepeat.scope, onRepeat.params);
+                }
+
                 return TWEEN_CONST.PLAYING_FORWARD;
             }
         }
@@ -1305,6 +1328,7 @@ var Tween = new Class({
      * Internal method used as part of the playback process that sets a tween to play from the start.
      *
      * @method Phaser.Tweens.Tween#setStateFromStart
+     * @fires Phaser.Tweens.Events#TWEEN_REPEAT
      * @since 3.0.0
      *
      * @param {Phaser.Tweens.Tween} tween - The Tween to update.
@@ -1333,16 +1357,6 @@ var Tween = new Class({
                 tweenData.target.toggleFlipY();
             }
 
-            var onRepeat = tween.callbacks.onRepeat;
-
-            if (onRepeat)
-            {
-                //  Element 1 is reserved for the target of the repeat (and needs setting here)
-                onRepeat.params[1] = tweenData.target;
-
-                onRepeat.func.apply(onRepeat.scope, onRepeat.params);
-            }
-
             tweenData.end = tweenData.getEndValue(tweenData.target, tweenData.key, tweenData.start);
 
             //  Delay?
@@ -1358,6 +1372,18 @@ var Tween = new Class({
             }
             else
             {
+                this.emit(Events.TWEEN_REPEAT, this, tweenData.key, tweenData.target);
+
+                var onRepeat = tween.callbacks.onRepeat;
+    
+                if (onRepeat)
+                {
+                    //  Element 1 is reserved for the target of the repeat (and needs setting here)
+                    onRepeat.params[1] = tweenData.target;
+    
+                    onRepeat.func.apply(onRepeat.scope, onRepeat.params);
+                }
+
                 return TWEEN_CONST.PLAYING_FORWARD;
             }
         }
@@ -1369,6 +1395,8 @@ var Tween = new Class({
      * Internal method that advances the TweenData based on the time value given.
      *
      * @method Phaser.Tweens.Tween#updateTweenData
+     * @fires Phaser.Tweens.Events#TWEEN_UPDATE
+     * @fires Phaser.Tweens.Events#TWEEN_REPEAT
      * @since 3.0.0
      *
      * @param {Phaser.Tweens.Tween} tween - The Tween to update.
@@ -1423,6 +1451,8 @@ var Tween = new Class({
                 tweenData.elapsed = elapsed;
                 tweenData.progress = progress;
 
+                this.emit(Events.TWEEN_UPDATE, this, tweenData.key, tweenData.target);
+
                 var onUpdate = tween.callbacks.onUpdate;
 
                 if (onUpdate)
@@ -1474,6 +1504,18 @@ var Tween = new Class({
 
                 if (tweenData.elapsed <= 0)
                 {
+                    this.emit(Events.TWEEN_REPEAT, this, tweenData.key, tweenData.target);
+
+                    var onRepeat = tween.callbacks.onRepeat;
+        
+                    if (onRepeat)
+                    {
+                        //  Element 1 is reserved for the target of the repeat (and needs setting here)
+                        onRepeat.params[1] = tweenData.target;
+        
+                        onRepeat.func.apply(onRepeat.scope, onRepeat.params);
+                    }
+
                     tweenData.elapsed = Math.abs(tweenData.elapsed);
 
                     tweenData.state = TWEEN_CONST.PLAYING_FORWARD;