melonjs 10.9.0 → 10.12.0

package/src/renderable/container.js

@@ -18,7 +18,7 @@ var globalFloatingCounter = 0;
 
 /**
  * @classdesc
- * me.Container represents a collection of child objects
+ * Container represents a collection of child objects
  * @augments Renderable
  */
 class Container extends Renderable {
@@ -100,10 +100,9 @@ class Container extends Renderable {
          * a callback to be extended, triggered after a child has been added or removed
          * @name onChildChange
          * @memberof Container#
-         * @function
          * @param {number} index added or removed child index
          */
-        this.onChildChange = function (/* index */) {
+        this.onChildChange = function (index) {   // eslint-disable-line no-unused-vars
             // to be extended
         };
 
@@ -157,7 +156,6 @@ class Container extends Renderable {
      * reset the container, removing all childrens, and reseting transforms.
      * @name reset
      * @memberof Container
-     * @function
      */
     reset() {
         // cancel any sort operation
@@ -189,11 +187,12 @@ class Container extends Renderable {
      * Adding a child to the container will automatically remove it from its other container.
      * Meaning a child can only have one parent.  This is important if you add a renderable
      * to a container then add it to the me.game.world container it will move it out of the
-     * orginal container.  Then when the me.game.world.reset() is called the renderable
-     * will not be in any container.
+     * orginal container. Then when the me.game.world.reset() is called the renderable
+     * will not be in any container. <br>
+     * if the given child implements a onActivateEvent method, that method will be called
+     * once the child is added to this container.
      * @name addChild
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {Renderable} child
      * @param {number} [z] forces the z index of the child to the specified value
      * @returns {Renderable} the added child
@@ -256,8 +255,7 @@ 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 Container.prototype
-     * @function
+     * @memberof Container
      * @param {Renderable} child
      * @param {number} index
      * @returns {Renderable} the added child
@@ -315,8 +313,7 @@ class Container extends Renderable {
      *    - The index of element in the array. <br>
      *    - The array forEach() was called upon. <br>
      * @name forEach
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {Function} callback fnction to execute on each element
      * @param {object} [thisArg] value to use as this(i.e reference Object) when executing callback.
      * @example
@@ -352,8 +349,7 @@ class Container extends Renderable {
     /**
      * Swaps the position (z-index) of 2 children
      * @name swapChildren
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {Renderable} child
      * @param {Renderable} child2
      */
@@ -380,8 +376,7 @@ class Container extends Renderable {
     /**
      * Returns the Child at the specified index
      * @name getChildAt
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {number} index
      * @returns {Renderable} the child at the specified index
      */
@@ -397,8 +392,7 @@ class Container extends Renderable {
     /**
      * Returns the index of the given Child
      * @name getChildIndex
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {Renderable} child
      * @returns {number} index
      */
@@ -410,7 +404,6 @@ class Container extends Renderable {
      * Returns the next child within the container or undefined if none
      * @name getNextChild
      * @memberof Container
-     * @function
      * @param {Renderable} child
      * @returns {Renderable} child
      */
@@ -425,8 +418,7 @@ class Container extends Renderable {
     /**
      * Returns true if contains the specified Child
      * @name hasChild
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {Renderable} child
      * @returns {boolean}
      */
@@ -439,9 +431,8 @@ class Container extends Renderable {
      * note : avoid calling this function every frame since
      * it parses the whole object tree each time
      * @name getChildByProp
-     * @memberof Container.prototype
+     * @memberof Container
      * @public
-     * @function
      * @param {string} prop Property name
      * @param {string|RegExp|number|boolean} value Value of the property
      * @returns {Renderable[]} Array of childs
@@ -491,9 +482,8 @@ class Container extends Renderable {
     /**
      * returns the list of childs with the specified class type
      * @name getChildByType
-     * @memberof Container.prototype
+     * @memberof Container
      * @public
-     * @function
      * @param {object} classType
      * @returns {Renderable[]} Array of children
      */
@@ -518,9 +508,8 @@ class Container extends Renderable {
      * note : avoid calling this function every frame since
      * it parses the whole object list each time
      * @name getChildByName
-     * @memberof Container.prototype
+     * @memberof Container
      * @public
-     * @function
      * @param {string|RegExp|number|boolean} name child name
      * @returns {Renderable[]} Array of children
      */
@@ -533,9 +522,8 @@ class Container extends Renderable {
      * note : avoid calling this function every frame since
      * it parses the whole object list each time
      * @name getChildByGUID
-     * @memberof Container.prototype
+     * @memberof Container
      * @public
-     * @function
      * @param {string|RegExp|number|boolean} guid child GUID
      * @returns {Renderable} corresponding child or null
      */
@@ -547,9 +535,8 @@ class Container extends Renderable {
     /**
      * return all child in this container
      * @name getChildren
-     * @memberof Container.prototype
+     * @memberof Container
      * @public
-     * @function
      * @returns {Renderable[]} an array of renderable object
      */
     getChildren() {
@@ -563,8 +550,7 @@ class Container extends Renderable {
      * update the bounding box for this shape.
      * @ignore
      * @name updateBounds
-     * @memberof Renderable.prototype
-     * @function
+     * @memberof Renderable
      * @returns {Bounds} this shape bounding box Rectangle object
      */
     updateBounds(forceUpdateChildBounds = false) {
@@ -592,8 +578,7 @@ class Container extends Renderable {
      * Checks if this container is root or if it's attached to the root container.
      * @private
      * @name isAttachedToRoot
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @returns {boolean}
      */
     isAttachedToRoot() {
@@ -615,8 +600,7 @@ class Container extends Renderable {
      * update the cointainer's bounding rect (private)
      * @ignore
      * @name updateBoundsPos
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      */
     updateBoundsPos(newX, newY) {
         // call the parent method
@@ -648,11 +632,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
+     * Invokes the removeChildNow in a defer, to ensure the child is removed safely after the update & draw stack has completed. <br>
+     * if the given child implements a onDeactivateEvent() method, that method will be called once the child is removed from this container.
      * @name removeChild
-     * @memberof Container.prototype
+     * @memberof Container
      * @public
-     * @function
      * @param {Renderable} child
      * @param {boolean} [keepalive=False] True to prevent calling child.destroy()
      */
@@ -670,8 +654,7 @@ class Container extends Renderable {
      * (removal is immediate and unconditional)<br>
      * Never use keepalive=true with objects from {@link pool}. Doing so will create a memory leak.
      * @name removeChildNow
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {Renderable} child
      * @param {boolean} [keepalive=False] True to prevent calling child.destroy()
      */
@@ -723,8 +706,7 @@ class Container extends Renderable {
     /**
      * Automatically set the specified property of all childs to the given value
      * @name setChildsProperty
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {string} prop property name
      * @param {object} value property value
      * @param {boolean} [recursive=false] recursively apply the value to child containers if true
@@ -741,8 +723,7 @@ class Container extends Renderable {
     /**
      * Move the child in the group one step forward (z depth).
      * @name moveUp
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {Renderable} child
      */
     moveUp(child) {
@@ -758,8 +739,7 @@ class Container extends Renderable {
     /**
      * Move the child in the group one step backward (z depth).
      * @name moveDown
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {Renderable} child
      */
     moveDown(child) {
@@ -775,8 +755,7 @@ class Container extends Renderable {
     /**
      * Move the specified child to the top(z depth).
      * @name moveToTop
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {Renderable} child
      */
     moveToTop(child) {
@@ -795,8 +774,7 @@ class Container extends Renderable {
     /**
      * Move the specified child the bottom (z depth).
      * @name moveToBottom
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @param {Renderable} child
      */
     moveToBottom(child) {
@@ -815,9 +793,8 @@ class Container extends Renderable {
     /**
      * Manually trigger the sort of all the childs in the container</p>
      * @name sort
-     * @memberof Container.prototype
+     * @memberof Container
      * @public
-     * @function
      * @param {boolean} [recursive=false] recursively sort all containers if true
      */
     sort(recursive) {
@@ -910,8 +887,7 @@ class Container extends Renderable {
      * container update function. <br>
      * automatically called by the game manager {@link game}
      * @name update
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @protected
      * @param {number} dt time since the last update in milliseconds.
      * @returns {boolean} true if the Container is dirty
@@ -960,16 +936,14 @@ class Container extends Renderable {
     }
 
     /**
-     * draw the container. <br>
-     * automatically called by the game manager {@link game}
+      * draw this renderable (automatically called by melonJS)
      * @name draw
-     * @memberof Container.prototype
-     * @function
+     * @memberof Container
      * @protected
-     * @param {CanvasRenderer|WebGLRenderer} renderer a renderer object
-     * @param {Rect|Bounds} [rect] the area or viewport to (re)draw
+     * @param {CanvasRenderer|WebGLRenderer} renderer a renderer instance
+     * @param {Camera2d} [viewport] the viewport to (re)draw
      */
-    draw(renderer, rect) {
+    draw(renderer, viewport) {
         var isFloating = false;
         var bounds = this.getBounds();
 
@@ -1011,7 +985,7 @@ class Container extends Renderable {
                     obj.preDraw(renderer);
 
                     // draw the object
-                    obj.draw(renderer, rect);
+                    obj.draw(renderer, viewport);
 
                     // postdraw (clean-up);
                     obj.postDraw(renderer);

package/src/renderable/dragndrop.js

@@ -33,7 +33,6 @@ export class Draggable extends Renderable {
      * transformed events.
      * @name initEvents
      * @memberof Draggable
-     * @function
      * @private
      */
     initEvents() {
@@ -57,7 +56,6 @@ export class Draggable extends Renderable {
      * Gets called when the user starts dragging the entity
      * @name dragStart
      * @memberof Draggable
-     * @function
      * @param {object} e the pointer event
      * @returns {boolean} false if the object is being dragged
      */
@@ -74,7 +72,6 @@ export class Draggable extends Renderable {
      * Gets called when the user drags this entity around
      * @name dragMove
      * @memberof Draggable
-     * @function
      * @param {object} e the pointer event
      */
     dragMove(e) {
@@ -88,7 +85,6 @@ export class Draggable extends Renderable {
      * Gets called when the user stops dragging the entity
      * @name dragEnd
      * @memberof Draggable
-     * @function
      * @returns {boolean} false if the object stopped being dragged
      */
     dragEnd() {
@@ -102,7 +98,6 @@ export class Draggable extends Renderable {
      * Destructor
      * @name destroy
      * @memberof Draggable
-     * @function
      * @ignore
      */
     destroy() {
@@ -173,7 +168,6 @@ export class DropTarget extends Renderable {
      * Sets the collision method which is going to be used to check a valid drop
      * @name setCheckMethod
      * @memberof DropTarget
-     * @function
      * @param {string} checkMethod the checkmethod (defaults to CHECKMETHOD_OVERLAP)
      */
     setCheckMethod(checkMethod) {
@@ -188,7 +182,6 @@ export class DropTarget extends Renderable {
      * Checks if a dropped entity is dropped on the current entity
      * @name checkOnMe
      * @memberof DropTarget
-     * @function
      * @param {object} e the triggering event
      * @param {Draggable} draggable the draggable object that is dropped
      */
@@ -203,10 +196,9 @@ export class DropTarget extends Renderable {
      * Gets called when a draggable entity is dropped on the current entity
      * @name drop
      * @memberof DropTarget
-     * @function
      * @param {Draggable} draggable the draggable object that is dropped
      */
-    drop() {
+    drop(draggable) {  // eslint-disable-line no-unused-vars
 
     }
 
@@ -214,7 +206,6 @@ export class DropTarget extends Renderable {
      * Destructor
      * @name destroy
      * @memberof DropTarget
-     * @function
      * @ignore
      */
     destroy() {

package/src/renderable/imagelayer.js

@@ -75,7 +75,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 {Vector2d}
+             * @member {Vector2d}
              * @default <0.0,0.0>
              * @name ImageLayer#anchorPoint
              */
@@ -159,13 +159,12 @@ class ImageLayer extends Sprite {
     /**
      * resize the Image Layer to match the given size
      * @name resize
-     * @memberof ImageLayer.prototype
-     * @function
+     * @memberof ImageLayer
      * @param {number} w new width
      * @param {number} h new height
      */
     resize(w, h) {
-        super.resize(
+        return super.resize(
             this.repeatX ? Infinity : w,
             this.repeatY ? Infinity : h
         );
@@ -174,7 +173,6 @@ class ImageLayer extends Sprite {
     /**
      * createPattern function
      * @ignore
-     * @function
      */
     createPattern() {
         this._pattern = renderer.createPattern(this.image, this._repeat);
@@ -183,7 +181,6 @@ class ImageLayer extends Sprite {
     /**
      * updateLayer function
      * @ignore
-     * @function
      */
     updateLayer(vpos) {
         var rx = this.ratio.x,
@@ -246,15 +243,14 @@ class ImageLayer extends Sprite {
     }
 
     /**
-     * draw the ImageLayer. <br>
-     * automatically called by the game manager {@link game}
+     * draw this ImageLayer (automatically called by melonJS)
      * @name draw
-     * @memberof ImageLayer.prototype
-     * @function
+     * @memberof ImageLayer
      * @protected
-     * @param {CanvasRenderer|WebGLRenderer} renderer a renderer object
+     * @param {CanvasRenderer|WebGLRenderer} renderer a renderer instance
+     * @param {Camera2d} [viewport] the viewport to (re)draw
      */
-    draw(renderer) {
+    draw(renderer, viewport) {
         var width = this.width,
             height = this.height,
             bw = viewport.bounds.width,

package/src/renderable/light2d.js

@@ -0,0 +1,118 @@
+import pool from "./../system/pooling.js";
+import Renderable from "./renderable.js";
+
+/** @ignore */
+function createGradient(light) {
+    var context = light.texture.context;
+    var x1 = light.texture.width / 2;
+    var y1 = light.texture.height / 2;
+    var gradient = context.createRadialGradient(x1, y1, 0, x1, y1, light.radius);
+
+    light.texture.clear();
+
+    gradient.addColorStop( 0, light.color.toRGBA(light.intensity));
+    gradient.addColorStop( 1, light.color.toRGBA(0.0));
+
+    context.beginPath();
+    context.fillStyle = gradient;
+    context.arc(x1, y1, light.radius, 0, Math.PI * 2, false);
+    context.fill();
+}
+
+/**
+ * @classdesc
+ * A 2D point light.
+ * Note: this is a very experimental and work in progress feature, that provides a simple spot light effect.
+ * The light effect is best rendered in WebGL, as they are few limitations when using the Canvas Renderer
+ * (multiple lights are not supported, alpha component of the ambient light is ignored)
+ * @see stage.lights
+ */
+class Light2d extends Renderable {
+   /**
+    * @param {number} x - The horizontal position of the light.
+    * @param {number} y - The vertical position of the light.
+    * @param {number} radius - The radius of the light.
+    * @param {Color|string} [color="#FFF"] the color of the light
+    * @param {number} [intensity=0.7] - The intensity of the light.
+    */
+    constructor(x, y, radius, color = "#FFF", intensity = 0.7) {
+        // call the parent constructor
+        super(x, y, radius * 2, radius * 2);
+
+        /**
+         * the color of the light
+         * @type {Color}
+         * @default "#FFF"
+         */
+        this.color = pool.pull("Color").parseCSS(color);
+
+        /**
+         * The radius of the light
+         * @type {number}
+         */
+        this.radius = radius;
+
+        /**
+         * The intensity of the light
+         * @type {number}
+         * @default 0.7
+         */
+        this.intensity = intensity;
+
+        /**
+         * the default blend mode to be applied when rendering this light
+         * @type {string}
+         * @default "lighter"
+         * @see CanvasRenderer#setBlendMode
+         * @see WebGLRenderer#setBlendMode
+         */
+        this.blendMode = "lighter";
+
+        /** @ignore */
+        this.visibleArea = pool.pull("Ellipse", this.centerX, this.centerY, this.width, this.height);
+
+        /** @ignore */
+        this.texture = pool.pull("CanvasTexture", this.width, this.height, { offscreenCanvas: false });
+
+        this.anchorPoint.set(0, 0);
+
+        createGradient(this);
+    }
+
+    /**
+     * returns a geometry representing the visible area of this light
+     * @name getVisibleArea
+     * @memberof Light2d
+     * @returns {Ellipse} the light visible mask
+     */
+    getVisibleArea() {
+        return this.visibleArea.setShape(this.getBounds().centerX, this.getBounds().centerY, this.width, this.height);
+    }
+
+    /**
+     * draw this Light2d (automatically called by melonJS)
+     * @name draw
+     * @memberof Light2d
+     * @protected
+     * @param {CanvasRenderer|WebGLRenderer} renderer a renderer instance
+     * @param {Camera2d} [viewport] the viewport to (re)draw
+     */
+    draw(renderer, viewport) {   // eslint-disable-line no-unused-vars
+        renderer.drawImage(this.texture.canvas, this.getBounds().x, this.getBounds().y);
+    }
+
+    /**
+     * Destroy function<br>
+     * @ignore
+     */
+    destroy() {
+        pool.push(this.color);
+        this.color = undefined;
+        pool.push(this.texture);
+        this.texture = undefined;
+        pool.push(this.visibleArea);
+        this.visibleArea = undefined;
+        super.destroy();
+    }
+};
+export default Light2d;