melonjs 10.1.0 → 10.2.2

package/src/renderable/container.js

@@ -17,15 +17,16 @@ var deferredRemove = function (child, keepalive) {
 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
+ * @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 {
@@ -47,7 +48,7 @@ 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
@@ -64,7 +65,7 @@ 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
@@ -74,7 +75,7 @@ class Container extends Renderable {
         /**
          * 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
@@ -84,7 +85,7 @@ class Container extends Renderable {
         /**
          * 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
@@ -94,7 +95,7 @@ class Container extends Renderable {
         /**
          * 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
@@ -106,7 +107,7 @@ class Container extends Renderable {
          * @name onChildChange
          * @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
@@ -117,7 +118,7 @@ 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
@@ -186,7 +187,7 @@ class Container extends Renderable {
      * @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) {
@@ -249,8 +250,8 @@ class Container extends Renderable {
      * @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) {
@@ -308,7 +309,7 @@ class Container extends Renderable {
      * @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) => {
@@ -370,7 +371,8 @@ class Container extends Renderable {
      * @name getChildAt
      * @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) {
@@ -387,6 +389,7 @@ class Container extends Renderable {
      * @memberOf me.Container.prototype
      * @function
      * @param {me.Renderable} child
+     * @returns {number} index
      */
     getChildIndex(child) {
         return this.getChildren().indexOf(child);
@@ -398,6 +401,7 @@ class Container extends Renderable {
      * @memberOf me.Container
      * @function
      * @param {me.Renderable} child
+     * @returns {me.Renderable} child
      */
     getNextChild(child) {
         var index = this.getChildren().indexOf(child) - 1;
@@ -413,7 +417,7 @@ class Container extends Renderable {
      * @memberOf me.Container.prototype
      * @function
      * @param {me.Renderable} child
-     * @return {Boolean}
+     * @returns {boolean}
      */
     hasChild(child) {
         return this === child.ancestor;
@@ -427,9 +431,9 @@ class Container extends Renderable {
      * @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");
@@ -448,6 +452,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") {
@@ -476,18 +483,18 @@ class Container extends Renderable {
      * @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));
             }
         });
 
@@ -503,8 +510,8 @@ class Container extends Renderable {
      * @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);
@@ -518,23 +525,21 @@ class Container extends Renderable {
      * @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
      * @public
      * @function
-     * @return {me.Renderable[]} an array of renderable object
+     * @returns {me.Renderable[]} an array of renderable object
      */
     getChildren() {
         if (typeof this.children === "undefined") {
@@ -549,7 +554,7 @@ class Container extends Renderable {
      * @name updateBounds
      * @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) {
 
@@ -578,7 +583,7 @@ class Container extends Renderable {
      * @name isAttachedToRoot
      * @memberOf me.Container.prototype
      * @function
-     * @returns Boolean
+     * @returns {boolean}
      */
     isAttachedToRoot() {
         if (this.root === true) {
@@ -597,7 +602,7 @@ class Container extends Renderable {
 
     /**
      * update the cointainer's bounding rect (private)
-     * @private
+     * @ignore
      * @name updateBoundsPos
      * @memberOf me.Container.prototype
      * @function
@@ -638,7 +643,7 @@ class Container extends Renderable {
      * @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)) {
@@ -657,7 +662,7 @@ class Container extends Renderable {
      * @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)) {
@@ -709,16 +714,16 @@ class Container extends Renderable {
      * @name setChildsProperty
      * @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;
         });
     }
 
@@ -794,7 +799,7 @@ class Container extends Renderable {
      * @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
@@ -883,7 +888,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;
@@ -929,7 +941,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

@@ -13,16 +13,16 @@ import * as stringUtil from "./../utils/string.js";
  * @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',
+ * @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 +54,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 +75,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 +107,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) {
@@ -174,9 +168,9 @@ class ImageLayer extends Sprite {
      * @name resize
      * @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,
@@ -239,9 +233,11 @@ class ImageLayer extends Sprite {
         else {
             this.pos.y = y;
         }
+
+        this.isDirty = true;
     }
 
-   /*
+   /**
     * override the default predraw function
     * as repeat and anchor are managed directly in the draw method
     * @ignore
@@ -257,8 +253,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

@@ -0,0 +1,211 @@
+import Sprite from "./sprite.js";
+
+/**
+ * @classdesc
+ * A NineSliceSprite is similar to a Sprite, but it uses 9-slice scaling to strech its inner area to fit the size of the Renderable,
+ * by proportionally scaling a sprite by splitting it in a grid of nine parts (with only parts 1, 3, 7, 9 not being scaled). <br>
+ * <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
+ * @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, {
+ *     image : game.texture,
+ *     region : "grey_panel",
+ *     width : this.width,
+ *     height : this.height
+ * });
+ */
+
+class NineSliceSprite extends Sprite {
+
+    /**
+     * @ignore
+     */
+    constructor(x, y, settings) {
+        // call the super constructor
+        super(x, y, settings);
+
+        // ensure mandatory properties are defined
+        if ((typeof settings.width !== "number") || (typeof settings.height !== "number")) {
+            throw new Error("height and width properties are mandatory");
+        }
+
+        // override the renderable sprite with the given one
+        // resize based on the active frame
+        this.width = settings.width;
+        this.height = settings.height;
+    }
+
+    /**
+     * @ignore
+     */
+    draw(renderer) {
+        // the frame to draw
+        var frame = this.current;
+
+        // cache the current position and size
+        var dx = this.pos.x,
+            dy = this.pos.y;
+
+        var w = frame.width,
+            h = frame.height;
+
+        // frame offset in the texture/atlas
+        var frame_offset = frame.offset;
+        var g_offset = this.offset;
+
+
+        // remove image's TexturePacker/ShoeBox rotation
+        if (frame.angle !== 0) {
+            renderer.translate(-dx, -dy);
+            renderer.rotate(frame.angle);
+            dx -= h;
+            w = frame.height;
+            h = frame.width;
+        }
+
+        var sx = g_offset.x + frame_offset.x,
+            sy = g_offset.y + frame_offset.y;
+
+        // should this be configurable ?
+        var corner_width = frame.width / 4,
+            corner_height = frame.height / 4;
+
+        // OPTIMIZE ME !
+
+        // DRAW CORNERS
+
+        // Top Left
+        renderer.drawImage(
+            this.image,
+            sx,                          // sx
+            sy,                          // sy
+            corner_width, corner_height, // sw,sh
+            dx, dy,                      // dx,dy
+            corner_width, corner_height  // dw,dh
+        );
+
+        // Top Right
+        renderer.drawImage(
+            this.image,
+            sx + w - corner_width,          // sx
+            sy,                             // sy
+            corner_width, corner_height,    // sw,sh
+            dx + this.width - corner_width, // dx
+            dy,                             // dy
+            corner_width, corner_height     // dw,dh
+        );
+        // Bottom Left
+        renderer.drawImage(
+            this.image,
+            sx,                                 // sx
+            sy + h - corner_height,             // sy
+            corner_width, corner_height,        // sw,sh
+            dx,                                 // dx
+            dy + this.height - corner_height,   // dy
+            corner_width, corner_height         // dw,dh
+        );
+        // Bottom Right
+        renderer.drawImage(
+            this.image,
+            sx + w - corner_width,              // sx
+            sy + h - corner_height,             // sy
+            corner_width, corner_height,        // sw,sh
+            dx + this.width - corner_width,     //dx
+            dy + this.height - corner_height,   // dy
+            corner_width, corner_height         // dw,dh
+        );
+
+
+        // DRAW SIDES and CENTER
+        var image_center_width = w - (corner_width << 1);
+        var image_center_height = h - (corner_height << 1);
+
+        var target_center_width = this.width - (corner_width << 1);
+        var target_center_height = this.height - (corner_height << 1);
+
+        //Top center
+        renderer.drawImage(
+            this.image,
+            sx + corner_width,         // sx
+            sy,                        // sy
+            image_center_width,        // sw
+            corner_height,             // sh
+            dx + corner_width,         // dx
+            dy,                        // dy
+            target_center_width,       // dw
+            corner_height              // dh
+        );
+
+        //Bottom center
+        renderer.drawImage(
+            this.image,
+            sx + corner_width,                  // sx
+            sy + h - corner_height,             // sy
+            image_center_width,                 // sw
+            corner_height,                      // sh
+            dx + corner_width,                  // dx
+            dy + this.height - corner_height,   // dx
+            target_center_width,                // dw
+            corner_height                       // dh
+        );
+
+        // Middle Left
+        renderer.drawImage(
+            this.image,
+            sx,                   // sx
+            sy + corner_height,   // sy
+            corner_width,         // sw
+            image_center_height,  // sh
+            dx,                   // dx
+            dy + corner_height,   // dy
+            corner_width,         // dw
+            target_center_height  // dh
+        );
+
+        // Middle Right
+        renderer.drawImage(
+            this.image,
+            sx + w - corner_width,          // sx
+            sy + corner_height,             // sy
+            corner_width,                   // sw
+            image_center_height,            // sh
+            dx + this.width - corner_width, // dx
+            dy + corner_height,             // dy
+            corner_width,                   // dw
+            target_center_height            // dh
+        );
+
+        // Middle Center
+        renderer.drawImage(
+            this.image,
+            sx + corner_width,    // sx
+            sy + corner_height,   // sy
+            image_center_width,   // sw
+            image_center_height,  // sh
+            dx + corner_width,    // dx
+            dy + corner_height,   // dy
+            target_center_width,  // dw
+            target_center_height  // dh
+        );
+    }
+};
+
+export default NineSliceSprite;