Deleted un-used events, renamed Sprite events and added lots more documentation.

Author: photonstorm

src/animations/events/ANIMATION_COMPLETE_EVENT.js

@@ -6,17 +6,34 @@
 
 /**
  * The Animation Complete Event.
- * 
- * This event is dispatched by an Animation instance when it completes, i.e. finishes playing or is manually stopped.
- * 
- * Be careful with the volume of events this could generate. If a group of Sprites all complete the same
- * animation at the same time, this event will invoke its handler for each one of them.
+ *
+ * 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.
+ *
+ * Listen for it on the Sprite using `sprite.on('animationcomplete', 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)
+ *
+ * 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
- * @since 3.16.1
- * 
+ * @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 that the Animation completed on.
- * @param {Phaser.GameObjects.Sprite} gameObject - A reference to the Game Object on which the animation 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 = 'complete';
+module.exports = 'animationcomplete';

src/animations/events/ANIMATION_REPEAT_EVENT.js

@@ -6,16 +6,31 @@
 
 /**
  * The Animation Repeat Event.
- * 
- * This event is dispatched when a currently playing animation repeats.
- * 
- * The event is dispatched directly from the Animation object itself. Which means that listeners
- * bound to this event will be invoked every time the Animation repeats, for every Game Object that may have it.
+ *
+ * This event is dispatched by a Sprite when an animation repeats playing on it.
+ * This happens if the animation was created, or played, with a `repeat` value specified.
+ *
+ * An animation will repeat when it reaches the end of its sequence.
+ *
+ * Listen for it on the Sprite using `sprite.on('animationrepeat', 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)
+ *
+ * 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_REPEAT
- * @since 3.16.1
- * 
- * @param {Phaser.Animations.Animation} animation - A reference to the Animation that repeated.
- * @param {Phaser.Animations.AnimationFrame} frame - The current Animation Frame that the Animation was on when it repeated.
+ * @since 3.50.0
+ *
+ * @param {Phaser.Animations.Animation} animation - A reference to the Animation that has repeated.
+ * @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 repeated.
+ * @param {string} frameKey - The unique key of the Animation Frame within the Animation.
  */
-module.exports = 'repeat';
+module.exports = 'animationrepeat';

src/animations/events/ANIMATION_RESTART_EVENT.js

@@ -6,17 +6,29 @@
 
 /**
  * The Animation Restart Event.
- * 
- * This event is dispatched by an Animation instance when it restarts.
- * 
- * Be careful with the volume of events this could generate. If a group of Sprites all restart the same
- * animation at the same time, this event will invoke its handler for each one of them.
+ *
+ * This event is dispatched by a Sprite when an animation restarts playing on it.
+ * This only happens when the `Sprite.anims.restart` method is called.
+ *
+ * Listen for it on the Sprite using `sprite.on('animationrestart', 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)
+ *
+ * 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_RESTART
- * @since 3.16.1
- * 
- * @param {Phaser.Animations.Animation} animation - A reference to the Animation that restarted playing.
- * @param {Phaser.Animations.AnimationFrame} frame - The current Animation Frame that the Animation restarted with.
- * @param {Phaser.GameObjects.Sprite} gameObject - A reference to the Game Object on which the animation restarted playing.
+ * @since 3.50.0
+ *
+ * @param {Phaser.Animations.Animation} animation - A reference to the Animation that has restarted.
+ * @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 restarted.
+ * @param {string} frameKey - The unique key of the Animation Frame within the Animation.
  */
-module.exports = 'restart';
+module.exports = 'animationrestart';

src/animations/events/ANIMATION_START_EVENT.js

@@ -6,17 +6,30 @@
 
 /**
  * The Animation Start Event.
- * 
- * This event is dispatched by an Animation instance when it starts playing.
- * 
- * Be careful with the volume of events this could generate. If a group of Sprites all play the same
- * animation at the same time, this event will invoke its handler for each one of them.
+ *
+ * This event is dispatched by a Sprite when an animation starts playing on it.
+ * This happens when the animation is played, factoring in any delay that may have been specified.
+ * This event happens after the delay has expired and prior to the first update event.
+ *
+ * Listen for it on the Sprite using `sprite.on('animationstart', 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)
+ *
+ * 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_START
- * @since 3.16.1
- * 
- * @param {Phaser.Animations.Animation} animation - A reference to the Animation that started playing.
- * @param {Phaser.Animations.AnimationFrame} frame - The current Animation Frame that the Animation started with.
- * @param {Phaser.GameObjects.Sprite} gameObject - A reference to the Game Object on which the animation started playing.
+ * @since 3.50.0
+ *
+ * @param {Phaser.Animations.Animation} animation - A reference to the Animation that has started.
+ * @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 started.
+ * @param {string} frameKey - The unique key of the Animation Frame within the Animation.
  */
-module.exports = 'start';
+module.exports = 'animationstart';

src/animations/events/ANIMATION_STOP_EVENT.js

@@ -7,15 +7,29 @@
 /**
  * The Animation Stop Event.
  *
- * This event is dispatched by an Animation instance when playback is forcibly stopped on it,
- * i.e. `Sprite.stop()`, or similar, is called. Or, a new animation is started before the
- * previous one completes.
+ * This event is dispatched by a Sprite when an animation is stopped on it. An animation
+ * will only be stopeed if a method such as `Sprite.stop` or `Sprite.anims.stopAfterDelay`
+ * is called. It can also be emitted if a new animation is started before the current one completes.
+ *
+ * Listen for it on the Sprite using `sprite.on('animationstop', 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)
+ *
+ * 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_STOP
  * @since 3.50.0
  *
- * @param {Phaser.Animations.Animation} animation - A reference to the Animation that was stopped.
- * @param {Phaser.Animations.AnimationFrame} frame - The current Animation Frame that the Animation stopped on.
+ * @param {Phaser.Animations.Animation} animation - A reference to the Animation that has stopped.
+ * @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 stopped.
+ * @param {string} frameKey - The unique key of the Animation Frame within the Animation.
  */
-module.exports = 'stop';
+module.exports = 'animationstop';

src/animations/events/ANIMATION_UPDATE_EVENT.js

@@ -7,16 +7,33 @@
 /**
  * The Animation Update Event.
  *
- * This event is dispatched by an animation when it updates. This happens when the animation changes frame,
- * based on the animation frame rate and other factors like `timeScale` and `delay`.
+ * This event is dispatched by a Sprite when an animation playing on it updates. This happens when the animation changes frame.
+ * An animation will change frame based on the frme rate and other factors like `timeScale` and `delay`. It can also change
+ * frame when stopped or restarted.
  *
- * Listen for it on the Animation using `anim.on('update', listener)`
+ * Listen for it on the Sprite using `sprite.on('animationupdate', listener)`
+ *
+ * If an animation is playing faster than the game frame-rate can handle, it's entirely possible for it to emit several
+ * update events in a single game frame, so please be aware of this in your code. The **final** event received that frame
+ * is the one that is rendered to the game.
+ *
+ * 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)
+ *
+ * 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_UPDATE
  * @since 3.50.0
  *
- * @param {Phaser.Animations.Animation} animation - A reference to the Animation that has updated on the Sprite.
+ * @param {Phaser.Animations.Animation} animation - A reference to the Animation that has updated.
  * @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 = 'update';
+module.exports = 'animationupdate';