Refactoring how events are handled internally and in the docs

Author: photonstorm

src/animations/Animation.js

@@ -7,53 +7,11 @@
 var Clamp = require('../math/Clamp');
 var Class = require('../utils/Class');
 var EventEmitter = require('eventemitter3');
+var Events = require('./events');
 var FindClosestInSorted = require('../utils/array/FindClosestInSorted');
 var Frame = require('./AnimationFrame');
 var GetValue = require('../utils/object/GetValue');
 
-/**
- * @typedef {object} JSONAnimation
- *
- * @property {string} key - The key that the animation will be associated with. i.e. sprite.animations.play(key)
- * @property {string} type - A frame based animation (as opposed to a bone based animation)
- * @property {JSONAnimationFrame[]} frames - [description]
- * @property {integer} frameRate - The frame rate of playback in frames per second (default 24 if duration is null)
- * @property {integer} duration - How long the animation should play for in milliseconds. If not given its derived from frameRate.
- * @property {boolean} skipMissedFrames - Skip frames if the time lags, or always advanced anyway?
- * @property {integer} delay - Delay before starting playback. Value given in milliseconds.
- * @property {integer} repeat - Number of times to repeat the animation (-1 for infinity)
- * @property {integer} repeatDelay - Delay before the animation repeats. Value given in milliseconds.
- * @property {boolean} yoyo - Should the animation yoyo? (reverse back down to the start) before repeating?
- * @property {boolean} showOnStart - Should sprite.visible = true when the animation starts to play?
- * @property {boolean} hideOnComplete - Should sprite.visible = false when the animation finishes?
- */
-
-/**
- * @typedef {object} AnimationFrameConfig
- *
- * @property {string} key - The key that the animation will be associated with. i.e. sprite.animations.play(key)
- * @property {(string|number)} frame - [description]
- * @property {number} [duration=0] - [description]
- * @property {boolean} [visible] - [description]
- */
-
-/**
- * @typedef {object} AnimationConfig
- *
- * @property {string} [key] - The key that the animation will be associated with. i.e. sprite.animations.play(key)
- * @property {AnimationFrameConfig[]} [frames] - An object containing data used to generate the frames for the animation
- * @property {string} [defaultTextureKey=null] - The key of the texture all frames of the animation will use. Can be overridden on a per frame basis.
- * @property {integer} [frameRate] - The frame rate of playback in frames per second (default 24 if duration is null)
- * @property {integer} [duration] - How long the animation should play for in milliseconds. If not given its derived from frameRate.
- * @property {boolean} [skipMissedFrames=true] - Skip frames if the time lags, or always advanced anyway?
- * @property {integer} [delay=0] - Delay before starting playback. Value given in milliseconds.
- * @property {integer} [repeat=0] - Number of times to repeat the animation (-1 for infinity)
- * @property {integer} [repeatDelay=0] - Delay before the animation repeats. Value given in milliseconds.
- * @property {boolean} [yoyo=false] - Should the animation yoyo? (reverse back down to the start) before repeating?
- * @property {boolean} [showOnStart=false] - Should sprite.visible = true when the animation starts to play?
- * @property {boolean} [hideOnComplete=false] - Should sprite.visible = false when the animation finishes?
- */
-
 /**
  * @classdesc
  * A Frame based Animation.
@@ -72,7 +30,7 @@ var GetValue = require('../utils/object/GetValue');
  *
  * @param {Phaser.Animations.AnimationManager} manager - [description]
  * @param {string} key - [description]
- * @param {AnimationConfig} config - [description]
+ * @param {Phaser.Animations.Animation.Config} config - [description]
  */
 var Animation = new Class({
 
@@ -266,7 +224,7 @@ var Animation = new Class({
      * @method Phaser.Animations.Animation#addFrame
      * @since 3.0.0
      *
-     * @param {(string|AnimationFrameConfig[])} config - [description]
+     * @param {(string|Phaser.Animations.AnimationFrame.Config[])} config - [description]
      *
      * @return {Phaser.Animations.Animation} This Animation object.
      */
@@ -282,7 +240,7 @@ var Animation = new Class({
      * @since 3.0.0
      *
      * @param {integer} index - [description]
-     * @param {(string|AnimationFrameConfig[])} config - [description]
+     * @param {(string|Phaser.Animations.AnimationFrame.Config[])} config - [description]
      *
      * @return {Phaser.Animations.Animation} This Animation object.
      */
@@ -395,7 +353,7 @@ var Animation = new Class({
      * @since 3.0.0
      *
      * @param {Phaser.Textures.TextureManager} textureManager - [description]
-     * @param {(string|AnimationFrameConfig[])} frames - [description]
+     * @param {(string|Phaser.Animations.AnimationFrame.Config[])} frames - [description]
      * @param {string} [defaultTextureKey] - [description]
      *
      * @return {Phaser.Animations.AnimationFrame[]} [description]
@@ -774,6 +732,9 @@ var Animation = new Class({
      * [description]
      *
      * @method Phaser.Animations.Animation#repeatAnimation
+     * @fires Phaser.Animations.Events#ANIMATION_REPEAT
+     * @fires Phaser.Animations.Events#SPRITE_ANIMATION_REPEAT
+     * @fires Phaser.Animations.Events#SPRITE_ANIMATION_KEY_REPEAT
      * @since 3.0.0
      *
      * @param {Phaser.GameObjects.Components.Animation} component - [description]
@@ -806,11 +767,11 @@ var Animation = new Class({
                 var frame = component.currentFrame;
                 var parent = component.parent;
 
-                this.emit('repeat', this, frame);
+                this.emit(Events.ANIMATION_REPEAT, this, frame);
 
-                parent.emit('animationrepeat-' + this.key, this, frame, component.repeatCounter, parent);
+                parent.emit(Events.SPRITE_ANIMATION_KEY_REPEAT + this.key, this, frame, component.repeatCounter, parent);
 
-                parent.emit('animationrepeat', this, frame, component.repeatCounter, parent);
+                parent.emit(Events.SPRITE_ANIMATION_REPEAT, this, frame, component.repeatCounter, parent);
             }
         }
     },

src/animations/AnimationFrame.js

@@ -6,14 +6,6 @@
 
 var Class = require('../utils/Class');
 
-/**
- * @typedef {object} JSONAnimationFrame
- *
- * @property {string} key - The key of the Texture this AnimationFrame uses.
- * @property {(string|integer)} frame - The key of the Frame within the Texture that this AnimationFrame uses.
- * @property {number} duration - Additional time (in ms) that this frame should appear for during playback.
- */
-
 /**
  * @classdesc
  * A single frame in an Animation sequence.
@@ -149,7 +141,7 @@ var AnimationFrame = new Class({
      * @method Phaser.Animations.AnimationFrame#toJSON
      * @since 3.0.0
      *
-     * @return {JSONAnimationFrame} The AnimationFrame data.
+     * @return {Phaser.Animations.AnimationFrame.JSONConfig} The AnimationFrame data.
      */
     toJSON: function ()
     {

src/animations/AnimationManager.js

@@ -8,6 +8,7 @@ var Animation = require('./Animation');
 var Class = require('../utils/Class');
 var CustomMap = require('../structs/Map');
 var EventEmitter = require('eventemitter3');
+var Events = require('./events');
 var GetValue = require('../utils/object/GetValue');
 var Pad = require('../utils/string/Pad');
 
@@ -129,7 +130,7 @@ var AnimationManager = new Class({
      * Adds an existing Animation to the Animation Manager.
      *
      * @method Phaser.Animations.AnimationManager#add
-     * @fires AddAnimationEvent
+     * @fires Phaser.Animations.Events#ADD_ANIMATION
      * @since 3.0.0
      *
      * @param {string} key - The key under which the Animation should be added. The Animation will be updated with it. Must be unique.
@@ -141,15 +142,16 @@ var AnimationManager = new Class({
     {
         if (this.anims.has(key))
         {
-            console.warn('Animation with key', key, 'already exists');
+            console.warn('Animation key exists: ' + key);
+
             return;
         }
 
         animation.key = key;
 
         this.anims.set(key, animation);
 
-        this.emit('add', key, animation);
+        this.emit(Events.ADD_ANIMATION, key, animation);
 
         return this;
     },
@@ -185,7 +187,7 @@ var AnimationManager = new Class({
      * If you wish to re-use an existing key, call `AnimationManager.remove` first, then this method.
      *
      * @method Phaser.Animations.AnimationManager#create
-     * @fires AddAnimationEvent
+     * @fires Phaser.Animations.Events#ADD_ANIMATION
      * @since 3.0.0
      *
      * @param {AnimationConfig} config - The configuration settings for the Animation.
@@ -208,7 +210,7 @@ var AnimationManager = new Class({
 
                 this.anims.set(key, anim);
 
-                this.emit('add', key, anim);
+                this.emit(Events.ADD_ANIMATION, key, anim);
             }
         }
 
@@ -470,7 +472,7 @@ var AnimationManager = new Class({
      * Pause all animations.
      *
      * @method Phaser.Animations.AnimationManager#pauseAll
-     * @fires PauseAllAnimationEvent
+     * @fires Phaser.Animations.Events#PAUSE_ALL
      * @since 3.0.0
      *
      * @return {Phaser.Animations.AnimationManager} This Animation Manager.
@@ -481,7 +483,7 @@ var AnimationManager = new Class({
         {
             this.paused = true;
 
-            this.emit('pauseall');
+            this.emit(Events.PAUSE_ALL);
         }
 
         return this;
@@ -524,7 +526,7 @@ var AnimationManager = new Class({
      * Remove an animation.
      *
      * @method Phaser.Animations.AnimationManager#remove
-     * @fires RemoveAnimationEvent
+     * @fires Phaser.Animations.Events#REMOVE_ANIMATION
      * @since 3.0.0
      *
      * @param {string} key - The key of the animation to remove.
@@ -537,7 +539,7 @@ var AnimationManager = new Class({
 
         if (anim)
         {
-            this.emit('remove', key, anim);
+            this.emit(Events.REMOVE_ANIMATION, key, anim);
 
             this.anims.delete(key);
         }
@@ -549,7 +551,7 @@ var AnimationManager = new Class({
      * Resume all paused animations.
      *
      * @method Phaser.Animations.AnimationManager#resumeAll
-     * @fires ResumeAllAnimationEvent
+     * @fires Phaser.Animations.Events#RESUME_ALL
      * @since 3.0.0
      *
      * @return {Phaser.Animations.AnimationManager} This Animation Manager.
@@ -560,7 +562,7 @@ var AnimationManager = new Class({
         {
             this.paused = false;
 
-            this.emit('resumeall');
+            this.emit(Events.RESUME_ALL);
         }
 
         return this;

src/animations/events/ADD_ANIMATION_EVENT.js

@@ -0,0 +1,14 @@
+/**
+ * The Add Animation Event.
+ * 
+ * This event is dispatched when a new animation is added to the global Animation Manager.
+ * 
+ * This can happen either as a result of an animation instance being added to the Animation Manager,
+ * or the Animation Manager creating a new animation directly.
+ *
+ * @event Phaser.Animations.Events#ADD_ANIMATION
+ * 
+ * @param {string} key - The key of the Animation that was added to the global Animation Manager.
+ * @param {Phaser.Animations.Animation} animation - An instance of the newly created Animation.
+ */
+module.exports = 'add';

src/animations/events/ANIMATION_COMPLETE_EVENT.js

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ *
+ * @event Phaser.Animations.Events#ANIMATION_COMPLETE
+ * 
+ * @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.
+ */
+module.exports = 'complete';

src/animations/events/ANIMATION_REPEAT_EVENT.js

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ *
+ * @event Phaser.Animations.Events#ANIMATION_REPEAT
+ * 
+ * @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.
+ */
+module.exports = 'repeat';

src/animations/events/ANIMATION_RESTART_EVENT.js

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ *
+ * @event Phaser.Animations.Events#ANIMATION_RESTART
+ * 
+ * @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.
+ */
+module.exports = 'restart';

src/animations/events/ANIMATION_START_EVENT.js

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ *
+ * @event Phaser.Animations.Events#ANIMATION_START
+ * 
+ * @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.
+ */
+module.exports = 'start';

src/animations/events/PAUSE_ALL_EVENT.js

@@ -0,0 +1,11 @@
+/**
+ * The Pause All Animations Event.
+ * 
+ * This event is dispatched when the global Animation Manager is told to pause.
+ * 
+ * When this happens all current animations will stop updating, although it doesn't necessarily mean
+ * that the game has paused as well.
+ *
+ * @event Phaser.Animations.Events#PAUSE_ALL
+ */
+module.exports = 'pauseall';

src/animations/events/REMOVE_ANIMATION_EVENT.js

@@ -0,0 +1,11 @@
+/**
+ * The Remove Animation Event.
+ * 
+ * This event is dispatched when an animation is removed from the global Animation Manager.
+ *
+ * @event Phaser.Animations.Events#REMOVE_ANIMATION
+ * 
+ * @param {string} key - The key of the Animation that was removed from the global Animation Manager.
+ * @param {Phaser.Animations.Animation} animation - An instance of the removed Animation.
+ */
+module.exports = 'remove';