Merge branch 'master' of https://github.com/photonstorm/phaser

CHANGELOG.md

@@ -33,6 +33,7 @@
 * Fixed `Math.Matrix4.makeRotationAxis()`.
 * Fixed an incorrect usage of `Math.abs()` in `Math.Quaternion.calculateW()` (thanks @qxzkjp).
 * Particle Emitter Managers can now be added to Containers (thanks @TadejZupancic)
+* Fixed a method signature issue with the Animation component's `remove()` handler when `Animation`s are removed from the `AnimationManager`. This prevented removed animations from stopping correctly.
 
 ## Version 3.9.0 - Yui - 24th May 2018
 

src/animations/Animation.js

@@ -510,8 +510,8 @@ var Animation = new Class({
      * @private
      * @since 3.0.0
      *
-     * @param {Phaser.GameObjects.Components.Animation} component - [description]
+     * @param {Phaser.GameObjects.Components.Animation} component - The Animation Component to load values into.
-     * @param {integer} startFrame - [description]
+     * @param {integer} startFrame - The start frame of the animation to load.
      */
     load: function (component, startFrame)
     {
@@ -547,7 +547,7 @@ var Animation = new Class({
      *
      * @param {float} value - A value between 0 and 1.
      *
-     * @return {Phaser.Animations.AnimationFrame} [description]
+     * @return {Phaser.Animations.AnimationFrame} The frame closest to the given progress value.
      */
     getFrameByProgress: function (value)
     {
@@ -557,12 +557,12 @@ var Animation = new Class({
     },
 
     /**
-     * [description]
+     * Advance the animation frame.
      *
      * @method Phaser.Animations.Animation#nextFrame
      * @since 3.0.0
      *
-     * @param {Phaser.GameObjects.Components.Animation} component - [description]
+     * @param {Phaser.GameObjects.Components.Animation} component - The Animation Component to advance.
      */
     nextFrame: function (component)
     {

src/gameobjects/BuildGameObject.js

@@ -11,21 +11,21 @@ var ScaleModes = require('../renderer/ScaleModes');
 /**
  * @typedef {object} GameObjectConfig
  *
- * @property {number} [x=0] - [description]
+ * @property {number} [x=0] - The x position of the Game Object.
- * @property {number} [y=0] - [description]
+ * @property {number} [y=0] - The y position of the Game Object.
- * @property {number} [depth=0] - [description]
+ * @property {number} [depth=0] - The depth of the GameObject.
- * @property {boolean} [flipX=false] - [description]
+ * @property {boolean} [flipX=false] - The horizontally flipped state of the Game Object.
- * @property {boolean} [flipY=false] - [description]
+ * @property {boolean} [flipY=false] - The vertically flipped state of the Game Object.
- * @property {?(number|object)} [scale=null] - [description]
+ * @property {?(number|object)} [scale=null] - The scale of the GameObject.
- * @property {?(number|object)} [scrollFactor=null] - [description]
+ * @property {?(number|object)} [scrollFactor=null] - The scroll factor of the GameObject.
- * @property {number} [rotation=0] - [description]
+ * @property {number} [rotation=0] - The rotation angle of the Game Object, in radians.
- * @property {?number} [angle=null] - [description]
+ * @property {?number} [angle=null] - The rotation angle of the Game Object, in degrees.
- * @property {number} [alpha=1] - [description]
+ * @property {number} [alpha=1] - The alpha (opacity) of the Game Object.
- * @property {?(number|object)} [origin=null] - [description]
+ * @property {?(number|object)} [origin=null] - The origin of the Game Object.
- * @property {number} [scaleMode=ScaleModes.DEFAULT] - [description]
+ * @property {number} [scaleMode=ScaleModes.DEFAULT] - The scale mode of the GameObject.
- * @property {number} [blendMode=BlendModes.DEFAULT] - [description]
+ * @property {number} [blendMode=BlendModes.DEFAULT] - The blend mode of the GameObject.
- * @property {boolean} [visible=true] - [description]
+ * @property {boolean} [visible=true] - The visible state of the Game Object.
- * @property {boolean} [add=true] - [description]
+ * @property {boolean} [add=true] - Add the GameObject to the scene.
  */
 
 /**
@@ -34,9 +34,9 @@ var ScaleModes = require('../renderer/ScaleModes');
  * @function Phaser.GameObjects.BuildGameObject
  * @since 3.0.0
  *
- * @param {Phaser.Scene} scene - [description]
+ * @param {Phaser.Scene} scene - A reference to the Scene.
- * @param {Phaser.GameObjects.GameObject} gameObject - [description]
+ * @param {Phaser.GameObjects.GameObject} gameObject - The initial GameObject.
- * @param {GameObjectConfig} config - [description]
+ * @param {GameObjectConfig} config - The config to build the GameObject with.
  *
  * @return {Phaser.GameObjects.GameObject} The built Game Object.
  */

src/gameobjects/BuildGameObjectAnimation.js

@@ -12,8 +12,8 @@ var GetAdvancedValue = require('../utils/object/GetAdvancedValue');
  * @function Phaser.GameObjects.BuildGameObjectAnimation
  * @since 3.0.0
  *
- * @param {Phaser.GameObjects.Sprite} sprite - [description]
+ * @param {Phaser.GameObjects.Sprite} sprite - The sprite to add an Animation component to.
- * @param {object} config - [description]
+ * @param {object} config - The animation config.
  *
  * @return {Phaser.GameObjects.Sprite} The updated Sprite.
  */

src/gameobjects/DisplayList.js

@@ -11,7 +11,11 @@ var StableSort = require('../utils/array/StableSort');
 
 /**
  * @classdesc
- * [description]
+ * The Display List plugin.
+ *
+ * Display Lists belong to a Scene and maintain the list of Game Objects to render every frame.
+ *
+ * Some of these Game Objects may also be part of the Scene's [Update List]{@link Phaser.GameObjects.UpdateList}, for updating.
  *
  * @class DisplayList
  * @extends Phaser.Structs.List.<Phaser.GameObjects.GameObject>
@@ -19,7 +23,7 @@ var StableSort = require('../utils/array/StableSort');
  * @constructor
  * @since 3.0.0
  *
- * @param {Phaser.Scene} scene - [description]
+ * @param {Phaser.Scene} scene - The Scene that this Display List belongs to.
  */
 var DisplayList = new Class({
 
@@ -32,7 +36,7 @@ var DisplayList = new Class({
         List.call(this, scene);
 
         /**
-         * [description]
+         * The flag the determines whether Game Objects should be sorted when `depthSort()` is called.
          *
          * @name Phaser.GameObjects.DisplayList#sortChildrenFlag
          * @type {boolean}
@@ -42,7 +46,7 @@ var DisplayList = new Class({
         this.sortChildrenFlag = false;
 
         /**
-         * [description]
+         * The Scene that this Display List belongs to.
          *
          * @name Phaser.GameObjects.DisplayList#scene
          * @type {Phaser.Scene}
@@ -51,7 +55,7 @@ var DisplayList = new Class({
         this.scene = scene;
 
         /**
-         * [description]
+         * The Scene's Systems.
          *
          * @name Phaser.GameObjects.DisplayList#systems
          * @type {Phaser.Scenes.Systems}
@@ -118,15 +122,15 @@ var DisplayList = new Class({
     },
 
     /**
-     * [description]
+     * Compare the depth of two Game Objects.
      *
      * @method Phaser.GameObjects.DisplayList#sortByDepth
      * @since 3.0.0
      *
-     * @param {Phaser.GameObjects.GameObject} childA - [description]
+     * @param {Phaser.GameObjects.GameObject} childA - The first Game Object.
-     * @param {Phaser.GameObjects.GameObject} childB - [description]
+     * @param {Phaser.GameObjects.GameObject} childB - The second Game Object.
      *
-     * @return {integer} [description]
+     * @return {integer} The difference between the depths of each Game Object.
      */
     sortByDepth: function (childA, childB)
     {
@@ -134,15 +138,15 @@ var DisplayList = new Class({
     },
 
     /**
-     * Given an array of Game Objects, sort the array and return it,
+     * Given an array of Game Objects, sort the array and return it, so that
-     * so that the objects are in index order with the lowest at the bottom.
+     * the objects are in index order with the lowest at the bottom.
      *
      * @method Phaser.GameObjects.DisplayList#sortGameObjects
      * @since 3.0.0
      *
-     * @param {Phaser.GameObjects.GameObject[]} gameObjects - [description]
+     * @param {Phaser.GameObjects.GameObject[]} gameObjects - The array of Game Objects to sort.
      *
-     * @return {array} [description]
+     * @return {array} The sorted array of Game Objects.
      */
     sortGameObjects: function (gameObjects)
     {
@@ -154,14 +158,16 @@ var DisplayList = new Class({
     },
 
     /**
+     * Get the top-most Game Object in the given array of Game Objects, after sorting it.
+     *
      * Note that the given array is sorted in place, even though it isn't returned directly it will still be updated.
      *
      * @method Phaser.GameObjects.DisplayList#getTopGameObject
      * @since 3.0.0
      *
-     * @param {Phaser.GameObjects.GameObject[]} gameObjects - [description]
+     * @param {Phaser.GameObjects.GameObject[]} gameObjects - The array of Game Objects.
      *
-     * @return {Phaser.GameObjects.GameObject} The top-most Game Object on the Display List.
+     * @return {Phaser.GameObjects.GameObject} The top-most Game Object in the array of Game Objects.
      */
     getTopGameObject: function (gameObjects)
     {

src/gameobjects/UpdateList.js

@@ -9,14 +9,18 @@ var PluginCache = require('../plugins/PluginCache');
 
 /**
  * @classdesc
- * [description]
+ * The Update List plugin.
+ *
+ * Update Lists belong to a Scene and maintain the list Game Objects to be updated every frame.
+ *
+ * Some or all of these Game Objects may also be part of the Scene's [Display List]{@link Phaser.GameObjects.DisplayList}, for Rendering.
  *
  * @class UpdateList
  * @memberOf Phaser.GameObjects
  * @constructor
  * @since 3.0.0
  *
- * @param {Phaser.Scene} scene - [description]
+ * @param {Phaser.Scene} scene - The Scene that the Update List belongs to.
  */
 var UpdateList = new Class({
 
@@ -25,7 +29,7 @@ var UpdateList = new Class({
     function UpdateList (scene)
     {
         /**
-         * [description]
+         * The Scene that the Update List belongs to.
          *
          * @name Phaser.GameObjects.UpdateList#scene
          * @type {Phaser.Scene}
@@ -34,7 +38,7 @@ var UpdateList = new Class({
         this.scene = scene;
 
         /**
-         * [description]
+         * The Scene's Systems.
          *
          * @name Phaser.GameObjects.UpdateList#systems
          * @type {Phaser.Scenes.Systems}
@@ -43,7 +47,7 @@ var UpdateList = new Class({
         this.systems = scene.sys;
 
         /**
-         * [description]
+         * The list of Game Objects.
          *
          * @name Phaser.GameObjects.UpdateList#_list
          * @type {array}
@@ -54,7 +58,7 @@ var UpdateList = new Class({
         this._list = [];
 
         /**
-         * [description]
+         * Game Objects that are pending insertion into the list.
          *
          * @name Phaser.GameObjects.UpdateList#_pendingInsertion
          * @type {array}
@@ -65,7 +69,7 @@ var UpdateList = new Class({
         this._pendingInsertion = [];
 
         /**
-         * [description]
+         * Game Objects that are pending removal from the list.
          *
          * @name Phaser.GameObjects.UpdateList#_pendingRemoval
          * @type {array}
@@ -111,14 +115,14 @@ var UpdateList = new Class({
     },
 
     /**
-     * [description]
+     * Add a Game Object to the Update List.
      *
      * @method Phaser.GameObjects.UpdateList#add
      * @since 3.0.0
      *
-     * @param {Phaser.GameObjects.GameObject} child - [description]
+     * @param {Phaser.GameObjects.GameObject} child - The Game Object to add.
      *
-     * @return {Phaser.GameObjects.GameObject} [description]
+     * @return {Phaser.GameObjects.GameObject} The added Game Object.
      */
     add: function (child)
     {
@@ -133,13 +137,12 @@ var UpdateList = new Class({
     },
 
     /**
-     * [description]
+     * The pre-update step.
+     *
+     * Handles Game Objects that are pending insertion to and removal from the list.
      *
      * @method Phaser.GameObjects.UpdateList#preUpdate
      * @since 3.0.0
-     *
-     * @param {number} time - [description]
-     * @param {number} delta - [description]
      */
     preUpdate: function ()
     {
@@ -177,13 +180,15 @@ var UpdateList = new Class({
     },
 
     /**
-     * [description]
+     * The update step.
+     *
+     * Pre-updates every active Game Object in the list.
      *
      * @method Phaser.GameObjects.UpdateList#update
      * @since 3.0.0
      *
-     * @param {number} time - [description]
+     * @param {number} time - The current timestamp.
-     * @param {number} delta - [description]
+     * @param {number} delta - The delta time elapsed since the last frame.
      */
     update: function (time, delta)
     {
@@ -199,14 +204,14 @@ var UpdateList = new Class({
     },
 
     /**
-     * [description]
+     * Remove a Game Object from the list.
      *
      * @method Phaser.GameObjects.UpdateList#remove
      * @since 3.0.0
      *
-     * @param {Phaser.GameObjects.GameObject} child - [description]
+     * @param {Phaser.GameObjects.GameObject} child - The Game Object to remove from the list.
      *
-     * @return {Phaser.GameObjects.GameObject} [description]
+     * @return {Phaser.GameObjects.GameObject} The removed Game Object.
      */
     remove: function (child)
     {
@@ -221,7 +226,7 @@ var UpdateList = new Class({
     },
 
     /**
-     * [description]
+     * Remove all Game Objects from the list.
      *
      * @method Phaser.GameObjects.UpdateList#removeAll
      * @since 3.0.0

src/gameobjects/bitmaptext/GetBitmapTextSize.js

@@ -5,14 +5,48 @@
  */
 
 /**
- * [description]
+ * @typedef {object} BitmapTextSize
+ *
+ * @property {GlobalBitmapTextSize} global - The position and size of the BitmapText, taking into consideration the position and scale of the Game Object.
+ * @property {LocalBitmapTextSize} local - The position and size of the BitmapText, taking just the font size into consideration.
+ */
+
+/**
+ * @typedef {object} GlobalBitmapTextSize
+ *
+ * @property {number} x - The x position of the BitmapText, taking into consideration the x coordinate of the Game Object.
+ * @property {number} y - The y position of the BitmapText, taking into consideration the y coordinate of the Game Object.
+ * @property {number} width - The width of the BitmapText, taking into consideration the x scale of the Game Object.
+ * @property {number} width - The height of the BitmapText, taking into consideration the y scale of the Game Object.
+ */
+
+/**
+ * @typedef {object} LocalBitmapTextSize
+ *
+ * @property {number} x - The x position of the BitmapText.
+ * @property {number} y - The y position of the BitmapText.
+ * @property {number} width - The width of the BitmapText.
+ * @property {number} width - The height of the BitmapText.
+ */
+
+/**
+ * Calculate the position, width and height of a BitmapText Game Object.
+ *
+ * Returns a BitmapTextSize object that contains global and local variants of the Game Objects x and y coordinates and
+ * its width and height.
+ *
+ * The global position and size take into consideration the Game Object's position and scale.
+ *
+ * The local position and size just takes into consideration the font data.
  *
  * @function GetBitmapTextSize
  * @since 3.0.0
  * @private
  *
- * @param {(Phaser.GameObjects.DynamicBitmapText|Phaser.GameObjects.BitmapText)} src - [description]
+ * @param {(Phaser.GameObjects.DynamicBitmapText|Phaser.GameObjects.BitmapText)} src - The BitmapText to calculate the position, width and height of.
- * @param {boolean} round - [description]
+ * @param {boolean} round - Whether to round the results to the nearest integer.
+ *
+ * @return {BitmapTextSize} The calculated position, width and height of the BitmapText.
  */
 var GetBitmapTextSize = function (src, round)
 {

src/gameobjects/bitmaptext/ParseFromAtlas.js

@@ -7,11 +7,19 @@
 var ParseXMLBitmapFont = require('./ParseXMLBitmapFont');
 
 /**
- * [description]
+ * Parse an XML Bitmap Font from an Atlas.
  *
  * @function ParseFromAtlas
  * @since 3.0.0
  * @private
+ *
+ * @param {Phaser.Scene} scene - The Scene to parse the Bitmap Font for.
+ * @param {string} fontName - The key of the font to add to the Bitmap Font cache.
+ * @param {string} textureKey - The key of the BitmapFont's texture.
+ * @param {string} frameKey - The key of the BitmapFont texture's frame.
+ * @param {string} xmlKey - The key of the XML data of the font to parse.
+ * @param {integer} xSpacing - The x-axis spacing to add between each letter.
+ * @param {integer} ySpacing - The y-axis spacing to add to the line height.
  */
 var ParseFromAtlas = function (scene, fontName, textureKey, frameKey, xmlKey, xSpacing, ySpacing)
 {

src/gameobjects/bitmaptext/ParseXMLBitmapFont.js

@@ -19,10 +19,10 @@ function getValue (node, attribute)
  * @since 3.0.0
  * @private
  *
- * @param {XMLDocument} xml - [description]
+ * @param {XMLDocument} xml - The XML Document to parse the font from.
- * @param {integer} [xSpacing=0] - [description]
+ * @param {integer} [xSpacing=0] - The x-axis spacing to add between each letter.
- * @param {integer} [ySpacing=0] - [description]
+ * @param {integer} [ySpacing=0] - The y-axis spacing to add to the line height.
- * @param {Phaser.Textures.Frame} [frame] - [description]
+ * @param {Phaser.Textures.Frame} [frame] - The texture frame to take into account while parsing.
  */
 var ParseXMLBitmapFont = function (xml, xSpacing, ySpacing, frame)
 {

src/gameobjects/components/Animation.js

@@ -381,8 +381,8 @@ var Animation = new Class({
      * @protected
      * @since 3.0.0
      *
-     * @param {string} key - [description]
+     * @param {string} key - The key of the animation to load.
-     * @param {integer} [startFrame=0] - [description]
+     * @param {integer} [startFrame=0] - The start frame of the animation to load.
      *
      * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
      */
@@ -549,7 +549,7 @@ var Animation = new Class({
      * @method Phaser.GameObjects.Components.Animation#setProgress
      * @since 3.4.0
      *
-     * @param {float} [value=0] - [description]
+     * @param {float} [value=0] - The progress value, between 0 and 1.
      *
      * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
      */
@@ -566,18 +566,19 @@ var Animation = new Class({
     },
 
     /**
-     * [description]
+     * Handle the removal of an animation from the Animation Manager.
      *
      * @method Phaser.GameObjects.Components.Animation#remove
      * @since 3.0.0
      *
-     * @param {Phaser.Animations.Animation} [event] - [description]
+     * @param {string} [key] - The key of the removed Animation.
+     * @param {Phaser.Animations.Animation} [animation] - The removed Animation.
      */
-    remove: function (event)
+    remove: function (key, animation)
     {
-        if (event === undefined) { event = this.currentAnim; }
+        if (animation === undefined) { animation = this.currentAnim; }
 
-        if (this.isPlaying && event.key === this.currentAnim.key)
+        if (this.isPlaying && animation.key === this.currentAnim.key)
         {
             this.stop();
 
@@ -610,7 +611,7 @@ var Animation = new Class({
      * @method Phaser.GameObjects.Components.Animation#setRepeat
      * @since 3.4.0
      *
-     * @param {integer} value - [description]
+     * @param {integer} value - The number of times that the animation should repeat.
      *
      * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
      */
@@ -662,7 +663,7 @@ var Animation = new Class({
      * @method Phaser.GameObjects.Components.Animation#restart
      * @since 3.0.0
      *
-     * @param {boolean} [includeDelay=false] - [description]
+     * @param {boolean} [includeDelay=false] - Whether to include the delay value of the animation when restarting.
      *
      * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
      */
@@ -812,10 +813,10 @@ var Animation = new Class({
      * @method Phaser.GameObjects.Components.Animation#update
      * @since 3.0.0
      *
-     * @param {number} timestamp - [description]
+     * @param {number} time - The current timestamp.
      * @param {number} delta - The delta time, in ms, elapsed since the last frame.
      */
-    update: function (timestamp, delta)
+    update: function (time, delta)
     {
         if (!this.currentAnim || !this.isPlaying || this.currentAnim.paused)
         {
@@ -882,7 +883,7 @@ var Animation = new Class({
      * @private
      * @since 3.0.0
      *
-     * @param {Phaser.Animations.AnimationFrame} animationFrame - [description]
+     * @param {Phaser.Animations.AnimationFrame} animationFrame - The animation frame to change to.
      */
     updateFrame: function (animationFrame)
     {
@@ -941,7 +942,9 @@ var Animation = new Class({
     },
 
     /**
-     * [description]
+     * Destroy this Animation component.
+     *
+     * Unregisters event listeners and cleans up its references.
      *
      * @method Phaser.GameObjects.Components.Animation#destroy
      * @since 3.0.0

src/gameobjects/components/Pipeline.js

@@ -15,7 +15,7 @@
 var Pipeline = {
 
     /**
-     * [description]
+     * The initial WebGL pipeline of this Game Object.
      *
      * @name Phaser.GameObjects.Components.Pipeline#defaultPipeline
      * @type {Phaser.Renderer.WebGL.WebGLPipeline}
@@ -26,7 +26,7 @@ var Pipeline = {
     defaultPipeline: null,
 
     /**
-     * [description]
+     * The current WebGL pipeline of this Game Object.
      *
      * @name Phaser.GameObjects.Components.Pipeline#pipeline
      * @type {Phaser.Renderer.WebGL.WebGLPipeline}

src/gameobjects/components/ToJSON.js

@@ -29,18 +29,17 @@
  * @property {object} data - The data of this Game Object.
  */
 
-//  Default Game Object JSON export
-//  Is extended further by Game Object specific implementations
-
 /**
- * [description]
+ * Export a Game Object as a JSON object.
+ *
+ * This is typically extended further by Game Object specific implementations.
  *
  * @method Phaser.GameObjects.Components.ToJSON
  * @since 3.0.0
  *
- * @param {Phaser.GameObjects.GameObject} gameObject - [description]
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object to export.
  *
- * @return {JSONGameObject} [description]
+ * @return {JSONGameObject} The exported Game Object.
  */
 var ToJSON = function (gameObject)
 {

src/gameobjects/rendertexture/RenderTextureCreator.js

@@ -12,10 +12,10 @@ var RenderTexture = require('./RenderTexture');
 /**
  * @typedef {object} RenderTextureConfig
  *
- * @property {number} [x=0] - [description]
+ * @property {number} [x=0] - The x coordinate of the RenderTexture's position.
- * @property {number} [y=0] - [description]
+ * @property {number} [y=0] - The y coordinate of the RenderTexture's position.
- * @property {number} [width=32] - [description]
+ * @property {number} [width=32] - The width of the RenderTexture.
- * @property {number} [height=32] - [description]
+ * @property {number} [height=32] - The height of the RenderTexture.
  */
 
 /**