melonjs 10.2.0 → 10.3.0

package/src/renderable/container.js

@@ -20,13 +20,12 @@ var globalFloatingCounter = 0;
  * @classdesc
  * me.Container represents a collection of child objects
  * @class Container
- * @extends me.Renderable
- * @memberOf me
- * @constructor
- * @param {Number} [x=0] position of the container (accessible via the inherited pos.x property)
- * @param {Number} [y=0] position of the container (accessible via the inherited pos.y property)
- * @param {Number} [w=me.game.viewport.width] width of the container
- * @param {Number} [h=me.game.viewport.height] height of the container
+ * @augments me.Renderable
+ * @memberof me
+ * @param {number} [x=0] position of the container (accessible via the inherited pos.x property)
+ * @param {number} [y=0] position of the container (accessible via the inherited pos.y property)
+ * @param {number} [w=me.game.viewport.width] width of the container
+ * @param {number} [h=me.game.viewport.height] height of the container
  */
 
 class Container extends Renderable {
@@ -48,10 +47,10 @@ class Container extends Renderable {
         /**
          * whether the container is the root of the scene
          * @public
-         * @type Boolean
+         * @type {boolean}
          * @default false
          * @name root
-         * @memberOf me.Container
+         * @memberof me.Container
          */
         this.root = root;
 
@@ -65,49 +64,49 @@ class Container extends Renderable {
          * The property of the child object that should be used to sort on <br>
          * value : "x", "y", "z"
          * @public
-         * @type String
+         * @type {string}
          * @default me.game.sortOn
          * @name sortOn
-         * @memberOf me.Container
+         * @memberof me.Container
          */
         this.sortOn = game.sortOn;
 
         /**
          * Specify if the children list should be automatically sorted when adding a new child
          * @public
-         * @type Boolean
+         * @type {boolean}
          * @default true
          * @name autoSort
-         * @memberOf me.Container
+         * @memberof me.Container
          */
         this.autoSort = true;
 
         /**
          * Specify if the children z index should automatically be managed by the parent container
          * @public
-         * @type Boolean
+         * @type {boolean}
          * @default true
          * @name autoDepth
-         * @memberOf me.Container
+         * @memberof me.Container
          */
         this.autoDepth = true;
 
         /**
          * Specify if the container draw operation should clip his children to its own bounds
          * @public
-         * @type Boolean
+         * @type {boolean}
          * @default false
          * @name clipping
-         * @memberOf me.Container
+         * @memberof me.Container
          */
         this.clipping = false;
 
         /**
          * a callback to be extended, triggered after a child has been added or removed
          * @name onChildChange
-         * @memberOf me.Container#
+         * @memberof me.Container#
          * @function
-         * @param {Number} index added or removed child index
+         * @param {number} index added or removed child index
          */
         this.onChildChange = function (/* index */) {
             // to be extended
@@ -118,10 +117,10 @@ class Container extends Renderable {
          * all child bounds when updated (this is expensive and disabled by default,
          * only enable if necessary)
          * @public
-         * @type Boolean
+         * @type {boolean}
          * @default false
          * @name enableChildBoundsUpdate
-         * @memberOf me.Container
+         * @memberof me.Container
          */
         this.enableChildBoundsUpdate = false;
 
@@ -149,7 +148,7 @@ class Container extends Renderable {
     /**
      * reset the container, removing all childrens, and reseting transforms.
      * @name reset
-     * @memberOf me.Container
+     * @memberof me.Container
      * @function
      */
     reset() {
@@ -183,11 +182,11 @@ class Container extends Renderable {
      * orginal container.  Then when the me.game.world.reset() is called the renderable
      * will not be in any container.
      * @name addChild
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      * @param {me.Renderable} child
      * @param {number} [z] forces the z index of the child to the specified value
-     * @return {me.Renderable} the added child
+     * @returns {me.Renderable} the added child
      */
     addChild(child, z) {
         if (child.ancestor instanceof Container) {
@@ -247,11 +246,11 @@ class Container extends Renderable {
      * Add a child to the container at the specified index<br>
      * (the list won't be sorted after insertion)
      * @name addChildAt
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      * @param {me.Renderable} child
-     * @param {Number} index
-     * @return {me.Renderable} the added child
+     * @param {number} index
+     * @returns {me.Renderable} the added child
      */
     addChildAt(child, index) {
         if (index >= 0 && index < this.getChildren().length) {
@@ -306,10 +305,10 @@ class Container extends Renderable {
      *    - The index of element in the array. <br>
      *    - The array forEach() was called upon. <br>
      * @name forEach
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      * @param {Function} callback fnction to execute on each element
-     * @param {Object} [thisArg] value to use as this(i.e reference Object) when executing callback.
+     * @param {object} [thisArg] value to use as this(i.e reference Object) when executing callback.
      * @example
      * // iterate through all children of the root container
      * me.game.world.forEach((child) => {
@@ -343,7 +342,7 @@ class Container extends Renderable {
     /**
      * Swaps the position (z-index) of 2 children
      * @name swapChildren
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      * @param {me.Renderable} child
      * @param {me.Renderable} child2
@@ -369,9 +368,10 @@ class Container extends Renderable {
     /**
      * Returns the Child at the specified index
      * @name getChildAt
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
-     * @param {Number} index
+     * @param {number} index
+     * @returns {me.Renderable} the child at the specified index
      */
     getChildAt(index) {
         if (index >= 0 && index < this.getChildren().length) {
@@ -385,9 +385,10 @@ class Container extends Renderable {
     /**
      * Returns the index of the given Child
      * @name getChildIndex
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      * @param {me.Renderable} child
+     * @returns {number} index
      */
     getChildIndex(child) {
         return this.getChildren().indexOf(child);
@@ -396,9 +397,10 @@ class Container extends Renderable {
     /**
      * Returns the next child within the container or undefined if none
      * @name getNextChild
-     * @memberOf me.Container
+     * @memberof me.Container
      * @function
      * @param {me.Renderable} child
+     * @returns {me.Renderable} child
      */
     getNextChild(child) {
         var index = this.getChildren().indexOf(child) - 1;
@@ -411,10 +413,10 @@ class Container extends Renderable {
     /**
      * Returns true if contains the specified Child
      * @name hasChild
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      * @param {me.Renderable} child
-     * @return {Boolean}
+     * @returns {boolean}
      */
     hasChild(child) {
         return this === child.ancestor;
@@ -425,12 +427,12 @@ class Container extends Renderable {
      * note : avoid calling this function every frame since
      * it parses the whole object tree each time
      * @name getChildByProp
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @public
      * @function
-     * @param {String} prop Property name
-     * @param {String|RegExp|Number|Boolean} value Value of the property
-     * @return {me.Renderable[]} Array of childs
+     * @param {string} prop Property name
+     * @param {string|RegExp|number|boolean} value Value of the property
+     * @returns {me.Renderable[]} Array of childs
      * @example
      * // get the first child object called "mainPlayer" in a specific container :
      * var ent = myContainer.getChildByProp("name", "mainPlayer");
@@ -449,6 +451,9 @@ class Container extends Renderable {
     getChildByProp(prop, value)    {
         var objList = [];
 
+        /**
+         * @ignore
+         */
         function compare(obj, prop) {
             var v = obj[prop];
             if (value instanceof RegExp && typeof(v) === "string") {
@@ -474,21 +479,21 @@ class Container extends Renderable {
     /**
      * returns the list of childs with the specified class type
      * @name getChildByType
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @public
      * @function
-     * @param {Object} class type
-     * @return {me.Renderable[]} Array of children
+     * @param {object} classType
+     * @returns {me.Renderable[]} Array of children
      */
-    getChildByType(_class) {
+    getChildByType(classType) {
         var objList = [];
 
         this.forEach((child) => {
-            if (child instanceof _class) {
+            if (child instanceof classType) {
                 objList.push(child);
             }
             if (child instanceof Container) {
-                objList = objList.concat(child.getChildByType(_class));
+                objList = objList.concat(child.getChildByType(classType));
             }
         });
 
@@ -501,11 +506,11 @@ class Container extends Renderable {
      * note : avoid calling this function every frame since
      * it parses the whole object list each time
      * @name getChildByName
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @public
      * @function
-     * @param {String|RegExp|Number|Boolean} name child name
-     * @return {me.Renderable[]} Array of children
+     * @param {string|RegExp|number|boolean} name child name
+     * @returns {me.Renderable[]} Array of children
      */
     getChildByName(name) {
         return this.getChildByProp("name", name);
@@ -516,26 +521,24 @@ class Container extends Renderable {
      * note : avoid calling this function every frame since
      * it parses the whole object list each time
      * @name getChildByGUID
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @public
      * @function
-     * @param {String|RegExp|Number|Boolean} GUID child GUID
-     * @return {me.Renderable} corresponding child or null
+     * @param {string|RegExp|number|boolean} guid child GUID
+     * @returns {me.Renderable} corresponding child or null
      */
     getChildByGUID(guid) {
         var obj = this.getChildByProp("GUID", guid);
         return (obj.length > 0) ? obj[0] : null;
     }
 
-
     /**
      * return all child in this container
-
      * @name getChildren
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @public
      * @function
-     * @return {me.Renderable[]} an array of renderable object
+     * @returns {me.Renderable[]} an array of renderable object
      */
     getChildren() {
         if (typeof this.children === "undefined") {
@@ -548,9 +551,9 @@ class Container extends Renderable {
      * update the bounding box for this shape.
      * @ignore
      * @name updateBounds
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
-     * @return {me.Bounds} this shape bounding box Rectangle object
+     * @returns {me.Bounds} this shape bounding box Rectangle object
      */
     updateBounds(forceUpdateChildBounds = false) {
 
@@ -577,9 +580,9 @@ class Container extends Renderable {
      * Checks if this container is root or if it's attached to the root container.
      * @private
      * @name isAttachedToRoot
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
-     * @returns Boolean
+     * @returns {boolean}
      */
     isAttachedToRoot() {
         if (this.root === true) {
@@ -598,9 +601,9 @@ class Container extends Renderable {
 
     /**
      * update the cointainer's bounding rect (private)
-     * @private
+     * @ignore
      * @name updateBoundsPos
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      */
     updateBoundsPos(newX, newY) {
@@ -635,11 +638,11 @@ class Container extends Renderable {
     /**
      * Invokes the removeChildNow in a defer, to ensure the child is removed safely after the update & draw stack has completed
      * @name removeChild
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @public
      * @function
      * @param {me.Renderable} child
-     * @param {Boolean} [keepalive=False] True to prevent calling child.destroy()
+     * @param {boolean} [keepalive=False] True to prevent calling child.destroy()
      */
     removeChild(child, keepalive) {
         if (this.hasChild(child)) {
@@ -655,10 +658,10 @@ class Container extends Renderable {
      * (removal is immediate and unconditional)<br>
      * Never use keepalive=true with objects from {@link me.pool}. Doing so will create a memory leak.
      * @name removeChildNow
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      * @param {me.Renderable} child
-     * @param {Boolean} [keepalive=False] True to prevent calling child.destroy()
+     * @param {boolean} [keepalive=False] True to prevent calling child.destroy()
      */
     removeChildNow(child, keepalive) {
         if (this.hasChild(child) && (this.getChildIndex(child) >= 0)) {
@@ -708,25 +711,25 @@ class Container extends Renderable {
     /**
      * Automatically set the specified property of all childs to the given value
      * @name setChildsProperty
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
-     * @param {String} property property name
-     * @param {Object} value property value
-     * @param {Boolean} [recursive=false] recursively apply the value to child containers if true
+     * @param {string} prop property name
+     * @param {object} value property value
+     * @param {boolean} [recursive=false] recursively apply the value to child containers if true
      */
-    setChildsProperty(prop, val, recursive) {
+    setChildsProperty(prop, value, recursive) {
         this.forEach((child) => {
             if ((recursive === true) && (child instanceof Container)) {
-                child.setChildsProperty(prop, val, recursive);
+                child.setChildsProperty(prop, value, recursive);
             }
-            child[prop] = val;
+            child[prop] = value;
         });
     }
 
     /**
      * Move the child in the group one step forward (z depth).
      * @name moveUp
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      * @param {me.Renderable} child
      */
@@ -741,7 +744,7 @@ class Container extends Renderable {
     /**
      * Move the child in the group one step backward (z depth).
      * @name moveDown
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      * @param {me.Renderable} child
      */
@@ -756,7 +759,7 @@ class Container extends Renderable {
     /**
      * Move the specified child to the top(z depth).
      * @name moveToTop
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      * @param {me.Renderable} child
      */
@@ -774,7 +777,7 @@ class Container extends Renderable {
     /**
      * Move the specified child the bottom (z depth).
      * @name moveToBottom
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @function
      * @param {me.Renderable} child
      */
@@ -792,10 +795,10 @@ class Container extends Renderable {
     /**
      * Manually trigger the sort of all the childs in the container</p>
      * @name sort
-     * @memberOf me.Container.prototype
+     * @memberof me.Container.prototype
      * @public
      * @function
-     * @param {Boolean} [recursive=false] recursively sort all containers if true
+     * @param {boolean} [recursive=false] recursively sort all containers if true
      */
     sort(recursive) {
         // do nothing if there is already a pending sort
@@ -884,7 +887,14 @@ class Container extends Renderable {
     }
 
     /**
-     * @ignore
+     * container update function. <br>
+     * automatically called by the game manager {@link me.game}
+     * @name update
+     * @memberof me.Container.prototype
+     * @function
+     * @protected
+     * @param {number} dt time since the last update in milliseconds.
+     * @returns {boolean} true if the Container is dirty
      */
     update(dt) {
         var isFloating = false;
@@ -930,7 +940,14 @@ class Container extends Renderable {
     }
 
     /**
-     * @ignore
+     * draw the container. <br>
+     * automatically called by the game manager {@link me.game}
+     * @name draw
+     * @memberof me.Container.prototype
+     * @function
+     * @protected
+     * @param {me.CanvasRenderer|me.WebGLRenderer} renderer a renderer object
+     * @param {me.Rect|me.Bounds} [rect] the area or viewport to (re)draw
      */
     draw(renderer, rect) {
         var isFloating = false;

package/src/renderable/imagelayer.js

@@ -10,19 +10,18 @@ import * as stringUtil from "./../utils/string.js";
  * @classdesc
  * a generic Image Layer Object
  * @class ImageLayer
- * @extends me.Renderable
- * @memberOf me
- * @constructor
- * @param {Number} x x coordinate
- * @param {Number} y y coordinate
- * @param {Object} settings ImageLayer properties
- * @param {HTMLImageElement|HTMLCanvasElement|String} settings.image Image reference. See {@link me.loader.getImage}
- * @param {String} [settings.name="me.ImageLayer"] layer name
- * @param {Number} [settings.z=0] z-index position
- * @param {Number|me.Vector2d} [settings.ratio=1.0] Scrolling ratio to be applied. See {@link me.ImageLayer#ratio}
- * @param {String} [settings.repeat='repeat'] define if and how an Image Layer should be repeated (accepted values are 'repeat',
+ * @augments me.Renderable
+ * @memberof me
+ * @param {number} x x coordinate
+ * @param {number} y y coordinate
+ * @param {object} settings ImageLayer properties
+ * @param {HTMLImageElement|HTMLCanvasElement|string} settings.image Image reference. See {@link me.loader.getImage}
+ * @param {string} [settings.name="me.ImageLayer"] layer name
+ * @param {number} [settings.z=0] z-index position
+ * @param {number|me.Vector2d} [settings.ratio=1.0] Scrolling ratio to be applied. See {@link me.ImageLayer#ratio}
+ * @param {string} [settings.repeat='repeat'] define if and how an Image Layer should be repeated (accepted values are 'repeat',
 'repeat-x', 'repeat-y', 'no-repeat'). See {@link me.ImageLayer#repeat}
- * @param {Number|me.Vector2d} [settings.anchorPoint=0.0] Image origin. See {@link me.ImageLayer#anchorPoint}
+ * @param {number|me.Vector2d} [settings.anchorPoint=0.0] Image origin. See {@link me.ImageLayer#anchorPoint}
  * @example
  * // create a repetitive background pattern on the X axis using the citycloud image asset
  * me.game.world.addChild(new me.ImageLayer(0, 0, {
@@ -54,7 +53,7 @@ class ImageLayer extends Sprite {
          * - a number, to change the value for both axis <br>
          * - a json expression like `json:{"x":0.5,"y":0.5}` if you wish to specify a different value for both x and y
          * @public
-         * @type me.Vector2d
+         * @type {me.Vector2d}
          * @default <1.0,1.0>
          * @name me.ImageLayer#ratio
          */
@@ -75,14 +74,14 @@ class ImageLayer extends Sprite {
              * By default, its upper-left corner is anchored to the viewport bounds upper left corner.<br>
              * The anchorPoint is a unit vector where each component falls in range [0.0,1.0].<br>
              * Some common examples:<br>
-             * * &lt;0.0,0.0&gt; : (Default) Anchor image to the upper-left corner of viewport bounds
-             * * &lt;0.5,0.5&gt; : Center the image within viewport bounds
-             * * &lt;1.0,1.0&gt; : Anchor image to the lower-right corner of viewport bounds
+             * - &lt;0.0,0.0&gt; : (Default) Anchor image to the upper-left corner of viewport bounds
+             * - &lt;0.5,0.5&gt; : Center the image within viewport bounds
+             * - &lt;1.0,1.0&gt; : Anchor image to the lower-right corner of viewport bounds
              * To specify a value through Tiled, use one of the following format : <br>
              * - a number, to change the value for both axis <br>
              * - a json expression like `json:{"x":0.5,"y":0.5}` if you wish to specify a different value for both x and y
              * @public
-             * @type me.Vector2d
+             * @type {me.Vector2d}
              * @default <0.0,0.0>
              * @name me.ImageLayer#anchorPoint
              */
@@ -107,26 +106,20 @@ class ImageLayer extends Sprite {
      * Define if and how an Image Layer should be repeated.<br>
      * By default, an Image Layer is repeated both vertically and horizontally.<br>
      * Acceptable values : <br>
-     * * 'repeat' - The background image will be repeated both vertically and horizontally <br>
-     * * 'repeat-x' - The background image will be repeated only horizontally.<br>
-     * * 'repeat-y' - The background image will be repeated only vertically.<br>
-     * * 'no-repeat' - The background-image will not be repeated.<br>
+     * - 'repeat' - The background image will be repeated both vertically and horizontally <br>
+     * - 'repeat-x' - The background image will be repeated only horizontally.<br>
+     * - 'repeat-y' - The background image will be repeated only vertically.<br>
+     * - 'no-repeat' - The background-image will not be repeated.<br>
      * @public
-     * @type String
+     * @type {string}
      * @default 'repeat'
      * @name me.ImageLayer#repeat
      */
 
-    /**
-     * @ignore
-     */
     get repeat() {
         return this._repeat;
     }
 
-    /**
-     * @ignore
-     */
     set repeat(value) {
         this._repeat = value;
         switch (this._repeat) {
@@ -172,11 +165,11 @@ class ImageLayer extends Sprite {
     /**
      * resize the Image Layer to match the given size
      * @name resize
-     * @memberOf me.ImageLayer.prototype
+     * @memberof me.ImageLayer.prototype
      * @function
-     * @param {Number} w new width
-     * @param {Number} h new height
-    */
+     * @param {number} w new width
+     * @param {number} h new height
+     */
     resize(w, h) {
         super.resize(
             this.repeatX ? Infinity : w,
@@ -243,7 +236,7 @@ class ImageLayer extends Sprite {
         this.isDirty = true;
     }
 
-   /*
+   /**
     * override the default predraw function
     * as repeat and anchor are managed directly in the draw method
     * @ignore
@@ -259,8 +252,13 @@ class ImageLayer extends Sprite {
     }
 
     /**
-     * draw the image layer
-     * @ignore
+     * draw the ImageLayer. <br>
+     * automatically called by the game manager {@link me.game}
+     * @name draw
+     * @memberof me.ImageLayer.prototype
+     * @function
+     * @protected
+     * @param {me.CanvasRenderer|me.WebGLRenderer} renderer a renderer object
      */
     draw(renderer) {
         var width = this.width,

package/src/renderable/nineslicesprite.js

@@ -7,22 +7,21 @@ import Sprite from "./sprite.js";
  * <img src="images/9-slice-scaling.png"/><br>
  * @see https://en.wikipedia.org/wiki/9-slice_scaling
  * @class NineSliceSprite
- * @extends me.Sprite
- * @memberOf me
- * @constructor
- * @param {Number} x the x coordinates of the sprite object
- * @param {Number} y the y coordinates of the sprite object
- * @param {Object} settings Configuration parameters for the Sprite object
- * @param {Number} settings.width the width of the Renderable over which the sprite needs to be stretched
- * @param {Number} settings.height the height of the Renderable over which the sprite needs to be stretched
- * @param {me.Renderer.Texture|HTMLImageElement|HTMLCanvasElement|String} settings.image reference to a texture, spritesheet image or to a texture atlas
- * @param {String} [settings.name=""] name of this object
- * @param {String} [settings.region] region name of a specific region to use when using a texture atlas, see {@link me.Renderer.Texture}
- * @param {Number} [settings.framewidth] Width of a single frame within the spritesheet
- * @param {Number} [settings.frameheight] Height of a single frame within the spritesheet
- * @param {String|me.Color} [settings.tint] a tint to be applied to this sprite
- * @param {Number} [settings.flipX] flip the sprite on the horizontal axis
- * @param {Number} [settings.flipY] flip the sprite on the vertical axis
+ * @augments me.Sprite
+ * @memberof me
+ * @param {number} x the x coordinates of the sprite object
+ * @param {number} y the y coordinates of the sprite object
+ * @param {object} settings Configuration parameters for the Sprite object
+ * @param {number} settings.width the width of the Renderable over which the sprite needs to be stretched
+ * @param {number} settings.height the height of the Renderable over which the sprite needs to be stretched
+ * @param {me.Renderer.Texture|HTMLImageElement|HTMLCanvasElement|string} settings.image reference to a texture, spritesheet image or to a texture atlas
+ * @param {string} [settings.name=""] name of this object
+ * @param {string} [settings.region] region name of a specific region to use when using a texture atlas, see {@link me.Renderer.Texture}
+ * @param {number} [settings.framewidth] Width of a single frame within the spritesheet
+ * @param {number} [settings.frameheight] Height of a single frame within the spritesheet
+ * @param {string|me.Color} [settings.tint] a tint to be applied to this sprite
+ * @param {number} [settings.flipX] flip the sprite on the horizontal axis
+ * @param {number} [settings.flipY] flip the sprite on the vertical axis
  * @param {me.Vector2d} [settings.anchorPoint={x:0.5, y:0.5}] Anchor point to draw the frame at (defaults to the center of the frame).
  * @example
  * this.panelSprite = new me.NineSliceSprite(0, 0, {