Restored animation complete key event.

CHANGELOG.md

@@ -254,7 +254,7 @@ If you use Animations in your game, please read the following important API chan
 The Animation API has had a significant overhaul to improve playback handling. Instead of just playing an animation based on its global key, you can now supply a new `PlayAnimationConfig` object instead, which allows you to override any of the default animation settings, such as `duration`, `delay` and `yoyo` (see below for the full list). This means you no longer have to create lots of duplicate animations just to change properties such as `duration`, and can now set them dynamically at run-time as well.
 
 * The `Animation` class no longer extends `EventEmitter`, as it no longer emits any events directly. This means you cannot now listen for events directly from an Animation instance. All of the events are now dispatched by the Game Objects instead.
-* All of the `SPRITE_ANIMATION_KEY` events have been removed. Instead, please use the new events which all carry the `frameKey` parameter, which can be used to handle frame specific events.
+* All of the `SPRITE_ANIMATION_KEY` events have been removed. Instead, please use the new events which all carry the `frameKey` parameter, which can be used to handle frame specific events. The only exception to this is `ANIMATION_COMPLETE_KEY`, which is a key specific version of the completion event.
 * `ANIMATION_UPDATE_EVENT` is a new event that is emitted from a Sprite when an animation updates, i.e. its frame changes.
 * `ANIMATION_STOP_EVENT` is a new event that is emitted from a Sprite when its current animation is stopped. This can happen if any of the `stop` methods are called, or a new animation is played prior to this one reaching completion. Fix #4894 (thanks @scott20145)
 * The Game Object `Component.Animation` component has been renamed to `AnimationState` and has moved namespace. It's now in `Phaser.Animations` instead of `GameObjects.Components` to help differentiate it from the `Animation` class when browsing the documentation.

src/animations/AnimationState.js

@@ -1056,7 +1056,7 @@ var AnimationState = new Class({
             this.parent.setVisible(false);
         }
 
-        this.emitEvents(Events.ANIMATION_COMPLETE);
+        this.emitEvents(Events.ANIMATION_COMPLETE, Events.ANIMATION_COMPLETE_KEY);
     },
 
     /**
@@ -1068,13 +1068,20 @@ var AnimationState = new Class({
      *
      * @param {string} event - The Animation Event to dispatch.
      */
-    emitEvents: function (event)
+    emitEvents: function (event, keyEvent)
     {
         var anim = this.currentAnim;
         var frame = this.currentFrame;
         var gameObject = this.parent;
 
-        gameObject.emit(event, anim, frame, gameObject, frame.textureFrame);
+        var frameKey = frame.textureFrame;
+
+        gameObject.emit(event, anim, frame, gameObject, frameKey);
+
+        if (keyEvent)
+        {
+            gameObject.emit(keyEvent + anim.key, anim, frame, gameObject, frameKey);
+        }
     },
 
     /**

src/animations/events/ANIMATION_COMPLETE_EVENT.js

@@ -23,6 +23,7 @@
  * 2. `ANIMATION_UPDATE` (repeated for however many frames the animation has)
  * 3. `ANIMATION_REPEAT` (only if the animation is set to repeat, it then emits more update events after this)
  * 4. `ANIMATION_COMPLETE` (only if there is a finite, or zero, repeat count)
+ * 5. `ANIMATION_COMPLETE_KEY` (only if there is a finite, or zero, repeat count)
  *
  * If the animation is stopped directly, the `ANIMATION_STOP` event is dispatched instead of `ANIMATION_COMPLETE`.
  *

src/animations/events/ANIMATION_COMPLETE_KEY_EVENT.js

@@ -0,0 +1,44 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2020 Photon Storm Ltd.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+/**
+ * The Animation Complete Dynamic Key Event.
+ *
+ * This event is dispatched by a Sprite when an animation playing on it completes playback.
+ * This happens when the animation gets to the end of its sequence, factoring in any delays
+ * or repeats it may have to process.
+ *
+ * An animation that is set to loop, or repeat forever, will never fire this event, because
+ * it never actually completes. If you need to handle this, listen for the `ANIMATION_STOP`
+ * event instead, as this is emitted when the animation is stopped directly.
+ *
+ * The difference between this and the `ANIMATION_COMPLETE` event is that this one has a
+ * dynamic event name that contains the name of the animation within it. For example,
+ * if you had an animation called `explode` you could listen for the completion of that
+ * specific animation by using: `sprite.on('animationcomplete-explode', listener)`. Or, if you
+ * wish to use types: `sprite.on(Phaser.Animations.Events.ANIMATION_COMPLETE_KEY + 'explode', listener)`.
+ *
+ * The animation event flow is as follows:
+ *
+ * 1. `ANIMATION_START`
+ * 2. `ANIMATION_UPDATE` (repeated for however many frames the animation has)
+ * 3. `ANIMATION_REPEAT` (only if the animation is set to repeat, it then emits more update events after this)
+ * 4. `ANIMATION_COMPLETE` (only if there is a finite, or zero, repeat count)
+ * 5. `ANIMATION_COMPLETE_KEY` (only if there is a finite, or zero, repeat count)
+ *
+ * If the animation is stopped directly, the `ANIMATION_STOP` event is dispatched instead of `ANIMATION_COMPLETE`.
+ *
+ * If the animation is restarted while it is already playing, `ANIMATION_RESTART` is emitted.
+ *
+ * @event Phaser.Animations.Events#ANIMATION_COMPLETE_KEY
+ * @since 3.50.0
+ *
+ * @param {Phaser.Animations.Animation} animation - A reference to the Animation that completed.
+ * @param {Phaser.Animations.AnimationFrame} frame - The current Animation Frame of the Animation.
+ * @param {Phaser.GameObjects.Sprite} gameObject - A reference to the Game Object on which the animation updated.
+ * @param {string} frameKey - The unique key of the Animation Frame within the Animation.
+ */
+module.exports = 'animationcomplete-';

src/animations/events/ANIMATION_REPEAT_EVENT.js

@@ -20,6 +20,7 @@
  * 2. `ANIMATION_UPDATE` (repeated for however many frames the animation has)
  * 3. `ANIMATION_REPEAT` (only if the animation is set to repeat, it then emits more update events after this)
  * 4. `ANIMATION_COMPLETE` (only if there is a finite, or zero, repeat count)
+ * 5. `ANIMATION_COMPLETE_KEY` (only if there is a finite, or zero, repeat count)
  *
  * If the animation is stopped directly, the `ANIMATION_STOP` event is dispatched instead of `ANIMATION_COMPLETE`.
  *

src/animations/events/ANIMATION_RESTART_EVENT.js

@@ -18,6 +18,7 @@
  * 2. `ANIMATION_UPDATE` (repeated for however many frames the animation has)
  * 3. `ANIMATION_REPEAT` (only if the animation is set to repeat, it then emits more update events after this)
  * 4. `ANIMATION_COMPLETE` (only if there is a finite, or zero, repeat count)
+ * 5. `ANIMATION_COMPLETE_KEY` (only if there is a finite, or zero, repeat count)
  *
  * If the animation is stopped directly, the `ANIMATION_STOP` event is dispatched instead of `ANIMATION_COMPLETE`.
  *

src/animations/events/ANIMATION_START_EVENT.js

@@ -19,6 +19,7 @@
  * 2. `ANIMATION_UPDATE` (repeated for however many frames the animation has)
  * 3. `ANIMATION_REPEAT` (only if the animation is set to repeat, it then emits more update events after this)
  * 4. `ANIMATION_COMPLETE` (only if there is a finite, or zero, repeat count)
+ * 5. `ANIMATION_COMPLETE_KEY` (only if there is a finite, or zero, repeat count)
  *
  * If the animation is stopped directly, the `ANIMATION_STOP` event is dispatched instead of `ANIMATION_COMPLETE`.
  *

src/animations/events/ANIMATION_STOP_EVENT.js

@@ -19,6 +19,7 @@
  * 2. `ANIMATION_UPDATE` (repeated for however many frames the animation has)
  * 3. `ANIMATION_REPEAT` (only if the animation is set to repeat, it then emits more update events after this)
  * 4. `ANIMATION_COMPLETE` (only if there is a finite, or zero, repeat count)
+ * 5. `ANIMATION_COMPLETE_KEY` (only if there is a finite, or zero, repeat count)
  *
  * If the animation is stopped directly, the `ANIMATION_STOP` event is dispatched instead of `ANIMATION_COMPLETE`.
  *

src/animations/events/ANIMATION_UPDATE_EVENT.js

@@ -23,6 +23,7 @@
  * 2. `ANIMATION_UPDATE` (repeated for however many frames the animation has)
  * 3. `ANIMATION_REPEAT` (only if the animation is set to repeat, it then emits more update events after this)
  * 4. `ANIMATION_COMPLETE` (only if there is a finite, or zero, repeat count)
+ * 5. `ANIMATION_COMPLETE_KEY` (only if there is a finite, or zero, repeat count)
  *
  * If the animation is stopped directly, the `ANIMATION_STOP` event is dispatched instead of `ANIMATION_COMPLETE`.
  *

src/animations/events/index.js

@@ -12,6 +12,7 @@ module.exports = {
 
     ADD_ANIMATION: require('./ADD_ANIMATION_EVENT'),
     ANIMATION_COMPLETE: require('./ANIMATION_COMPLETE_EVENT'),
+    ANIMATION_COMPLETE_KEY: require('./ANIMATION_COMPLETE_KEY_EVENT'),
     ANIMATION_REPEAT: require('./ANIMATION_REPEAT_EVENT'),
     ANIMATION_RESTART: require('./ANIMATION_RESTART_EVENT'),
     ANIMATION_START: require('./ANIMATION_START_EVENT'),