Finished all the new Tween Events

Author: photonstorm

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,
- *     tweens: [ { x: 600 }, { y: 500 }, { x: 100 }, { y: 100 } ]
+ *     duration: 3000
  * });
  * 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,
- *     tweens: [ { x: 600 }, { y: 500 }, { x: 100 }, { y: 100 } ]
+ *     duration: 3000
  * });
  * 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,
- *     tweens: [ { x: 600 }, { y: 500 }, { x: 100 }, { y: 100 } ]
+ *     duration: 3000
  * });
  * 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')
 
 };