Added Animation.chain method to queue an animation to start when the current one ends.

Author: photonstorm

CHANGELOG.md

@@ -145,6 +145,7 @@ one set of bindings ever created, which makes things a lot cleaner.
 * The Animation class now emits the `start` event when played (either forward, or in reverse) by any Game Object.
 * The Animation class now emits the `restart` event when it restarts playing on any Game Object.
 * The Animation class now emits the `complete` event when it finishes playing on any Game Object.
+* The Animation Component has a new method called `chain` which allows you to line-up another animation to start playing as soon as the current one stops, no matter how it stops (either by reaching its natural end, or directly by having stop called on it). You can chain a new animation at any point, including before the current one starts playing, during it, or when it ends (via its `animationcomplete` callback). Chained animations are specific to a Game Object, meaning different Game Objects can have different chained animations without impacting the global animation they're playing.
 
 ### Updates
 

src/gameobjects/components/Animation.js

@@ -156,6 +156,16 @@ var Animation = new Class({
          */
         this.currentFrame = null;
 
+        /**
+         * The key of the next Animation to be loaded into this Animation Controller when the current animation completes.
+         *
+         * @name Phaser.GameObjects.Components.Animation#nextAnim
+         * @type {?string}
+         * @default null
+         * @since 3.16.0
+         */
+        this.nextAnim = null;
+
         /**
          * Time scale factor.
          *
@@ -363,6 +373,34 @@ var Animation = new Class({
         this._pendingStopValue;
     },
 
+    /**
+     * Sets an animation to be played immediately after the current one completes.
+     * 
+     * The current animation must enter a 'completed' state for this to happen, i.e. finish all of its repeats, delays, etc.
+     * 
+     * An animation set to repeat forever will never enter a completed state.
+     * 
+     * Call this method with no arguments to reset the chained animation.
+     *
+     * @method Phaser.GameObjects.Components.Animation#chain
+     * @since 3.16.0
+     *
+     * @param {(string|Phaser.Animations.Animation)} [key] - The string-based key of the animation to play next, as defined previously in the Animation Manager. Or an Animation instance.
+     *
+     * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
+     */
+    chain: function (key)
+    {
+        if (key instanceof BaseAnimation)
+        {
+            key = key.key;
+        }
+
+        this.nextAnim = key;
+
+        return this.parent;
+    },
+
     /**
      * Sets the amount of time, in milliseconds, that the animation will be delayed before starting playback.
      *
@@ -842,6 +880,8 @@ var Animation = new Class({
 
     /**
      * Immediately stops the current animation from playing and dispatches the `animationcomplete` event.
+     * 
+     * If there is another animation queued (via the `chain` method) then it will start playing immediately.
      *
      * @method Phaser.GameObjects.Components.Animation#stop
      * @fires Phaser.GameObjects.Components.Animation#onCompleteEvent
@@ -865,6 +905,15 @@ var Animation = new Class({
 
         gameObject.emit('animationcomplete', anim, frame, gameObject);
 
+        if (this.nextAnim)
+        {
+            var key = this.nextAnim;
+
+            this.nextAnim = null;
+
+            this.play(key);
+        }
+
         return gameObject;
     },