Merge pull request phaserjs#5185 from samme/feature/tween-stop-event

Add tween 'stop' event and 'onStop' callback

Author: photonstorm

src/tweens/events/TWEEN_STOP_EVENT.js

@@ -0,0 +1,30 @@
+/**
+ * @author       samme
+ * @copyright    2020 Photon Storm Ltd.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+/**
+ * The Tween Stop Event.
+ *
+ * This event is dispatched by a Tween when it is stopped.
+ *
+ * Listen to it from a Tween instance using `Tween.on('stop', listener)`, i.e.:
+ *
+ * ```javascript
+ * var tween = this.tweens.add({
+ *     targets: image,
+ *     x: 500,
+ *     ease: 'Power1',
+ *     duration: 3000
+ * });
+ * tween.on('stop', listener);
+ * ```
+ *
+ * @event Phaser.Tweens.Events#TWEEN_STOP
+ * @since 3.24.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 = 'stop';

src/tweens/events/index.js

@@ -21,6 +21,7 @@ module.exports = {
     TWEEN_LOOP: require('./TWEEN_LOOP_EVENT'),
     TWEEN_REPEAT: require('./TWEEN_REPEAT_EVENT'),
     TWEEN_START: require('./TWEEN_START_EVENT'),
+    TWEEN_STOP: require('./TWEEN_STOP_EVENT'),
     TWEEN_UPDATE: require('./TWEEN_UPDATE_EVENT'),
     TWEEN_YOYO: require('./TWEEN_YOYO_EVENT')
 

src/tweens/tween/ReservedProps.js

@@ -15,7 +15,7 @@
 //  flipY: flip Y the GameObject on tween end//  hold: The time the tween will pause before running a yoyo
 //  hold: The time the tween will pause before running a yoyo
 //  loop: The time the tween will pause before starting either a yoyo or returning to the start for a repeat
-//  loopDelay: 
+//  loopDelay:
 //  offset: Used when the Tween is part of a Timeline
 //  paused: Does the tween start in a paused state, or playing?
 //  props: The properties being tweened by the tween
@@ -53,6 +53,9 @@ module.exports = [
     'onStart',
     'onStartParams',
     'onStartScope',
+    'onStop',
+    'onStopParams',
+    'onStopScope',
     'onUpdate',
     'onUpdateParams',
     'onUpdateScope',

src/tweens/tween/Tween.js

@@ -331,6 +331,7 @@ var Tween = new Class({
             onLoop: null,
             onRepeat: null,
             onStart: null,
+            onStop: null,
             onUpdate: null,
             onYoyo: null
         };
@@ -1107,6 +1108,8 @@ var Tween = new Class({
                 }
             }
 
+            this.dispatchTweenEvent(Events.TWEEN_STOP, this.callbacks.onStop);
+
             this.removeAllListeners();
 
             this.state = TWEEN_CONST.PENDING_REMOVE;
@@ -1575,6 +1578,7 @@ var Tween = new Class({
 
 //  onActive = 'active' event = When the Tween is moved from the pending to the active list in the manager, even if playback delayed
 //  onStart = 'start' event = When the Tween starts playing from a delayed state (will happen same time as onActive if no delay)
+//  onStop = 'stop' event = When the Tween is stopped
 //  onYoyo = 'yoyo' event = When the Tween starts a yoyo
 //  onRepeat = 'repeat' event = When a TweenData repeats playback (if any)
 //  onComplete = 'complete' event = When the Tween finishes all playback (can sometimes never happen if repeat -1), also when 'stop' called
@@ -1587,6 +1591,7 @@ Tween.TYPES = [
     'onLoop',
     'onRepeat',
     'onStart',
+    'onStop',
     'onUpdate',
     'onYoyo'
 ];

src/tweens/typedefs/NumberTweenBuilderConfig.js

@@ -31,6 +31,9 @@
  * @property {Phaser.Types.Tweens.TweenOnStartCallback} [onStart] - A function to call when the tween starts.
  * @property {array} [onStartParams] - Additional parameters to pass to `onStart`.
  * @property {any} [onStartScope] - Scope (this) for `onStart`.
+ * @property {Phaser.Types.Tweens.TweenOnStopCallback} [onStop] - A function to call when the tween is stopped.
+ * @property {array} [onStopParams] - Additional parameters to pass to `onStop`.
+ * @property {any} [onStopScope] - Scope (this) for `onStop`.
  * @property {Phaser.Types.Tweens.TweenOnUpdateCallback} [onUpdate] - A function to call each time the tween steps. Called once per property per target.
  * @property {array} [onUpdateParams] - Additional parameters to pass to `onUpdate`.
  * @property {any} [onUpdateScope] - Scope (this) for `onUpdate`.

src/tweens/typedefs/TweenBuilderConfig.js

@@ -33,6 +33,9 @@
  * @property {Phaser.Types.Tweens.TweenOnStartCallback} [onStart] - A function to call when the tween starts playback, after any delays have expired.
  * @property {array} [onStartParams] - Additional parameters to pass to `onStart`.
  * @property {any} [onStartScope] - Scope (this) for `onStart`.
+ * @property {Phaser.Types.Tweens.TweenOnStopCallback} [onStop] - A function to call when the tween is stopped.
+ * @property {array} [onStopParams] - Additional parameters to pass to `onStop`.
+ * @property {any} [onStopScope] - Scope (this) for `onStop`.
  * @property {Phaser.Types.Tweens.TweenOnUpdateCallback} [onUpdate] - A function to call each time the tween steps. Called once per property per target.
  * @property {array} [onUpdateParams] - Additional parameters to pass to `onUpdate`.
  * @property {any} [onUpdateScope] - Scope (this) for `onUpdate`.

src/tweens/typedefs/TweenOnStopCallback.js

@@ -0,0 +1,8 @@
+/**
+ * @callback Phaser.Types.Tweens.TweenOnStopCallback
+ * @since 3.24.0
+ *
+ * @param {Phaser.Tweens.Tween} tween - The tween.
+ * @param {array} targets - The tween targets.
+ * @param {...any} param - Any value passed in `onStopParams`.
+ */