melonjs 10.2.0 → 10.3.0

package/src/renderable/renderable.js

@@ -1,6 +1,6 @@
 import ObservableVector2d from "./../math/observable_vector2.js";
 import ObservableVector3d from "./../math/observable_vector3.js";
-import Rect from "./../shapes/rectangle.js";
+import Rect from "./../geometries/rectangle.js";
 import Container from "./container.js";
 import pool from "./../system/pooling.js";
 import { releaseAllPointerEvents } from "./../input/input.js";
@@ -10,13 +10,12 @@ import { clamp } from "./../math/math.js";
  * @classdesc
  * A base class for renderable objects.
  * @class Renderable
- * @extends me.Rect
- * @memberOf me
- * @constructor
- * @param {Number} x position of the renderable object (accessible through inherited pos.x property)
- * @param {Number} y position of the renderable object (accessible through inherited pos.y property)
- * @param {Number} width object width
- * @param {Number} height object height
+ * @augments me.Rect
+ * @memberof me
+ * @param {number} x position of the renderable object (accessible through inherited pos.x property)
+ * @param {number} y position of the renderable object (accessible through inherited pos.y property)
+ * @param {number} width object width
+ * @param {number} height object height
  */
 class Renderable extends Rect {
 
@@ -37,10 +36,10 @@ class Renderable extends Rect {
         /**
          * If true then physic collision and input events will not impact this renderable
          * @public
-         * @type Boolean
+         * @type {boolean}
          * @default true
          * @name isKinematic
-         * @memberOf me.Renderable
+         * @memberof me.Renderable
          */
         this.isKinematic = true;
 
@@ -50,7 +49,7 @@ class Renderable extends Rect {
          * @type {me.Body}
          * @see me.Body
          * @name body
-         * @memberOf me.Renderable#
+         * @memberof me.Renderable#
          * @example
          *  // define a new Player Class
          *  class PlayerEntity extends me.Sprite {
@@ -88,9 +87,9 @@ class Renderable extends Rect {
         /**
          * the renderable default transformation matrix
          * @public
-         * @type me.Matrix2d
+         * @type {me.Matrix2d}
          * @name currentTransform
-         * @memberOf me.Renderable#
+         * @memberof me.Renderable#
          */
         if (typeof this.currentTransform === "undefined") {
             this.currentTransform = pool.pull("Matrix2d");
@@ -102,19 +101,19 @@ class Renderable extends Rect {
         * a GUID will be allocated for any renderable object added <br>
         * to an object container (including the `me.game.world` container)
         * @public
-        * @type String
+        * @type {string}
         * @name GUID
-        * @memberOf me.Renderable
+        * @memberof me.Renderable
         */
         this.GUID = undefined;
 
         /**
          * an event handler that is called when the renderable leave or enter a camera viewport
          * @public
-         * @type function
+         * @type {Function}
          * @default undefined
          * @name onVisibilityChange
-         * @memberOf me.Renderable#
+         * @memberof me.Renderable#
          * @example
          * this.onVisibilityChange = function(inViewport) {
          *     if (inViewport === true) {
@@ -127,30 +126,30 @@ class Renderable extends Rect {
         /**
          * Whether the renderable object will always update, even when outside of the viewport<br>
          * @public
-         * @type Boolean
+         * @type {boolean}
          * @default false
          * @name alwaysUpdate
-         * @memberOf me.Renderable
+         * @memberof me.Renderable
          */
         this.alwaysUpdate = false;
 
         /**
          * Whether to update this object when the game is paused.
          * @public
-         * @type Boolean
+         * @type {boolean}
          * @default false
          * @name updateWhenPaused
-         * @memberOf me.Renderable
+         * @memberof me.Renderable
          */
         this.updateWhenPaused = false;
 
         /**
          * make the renderable object persistent over level changes<br>
          * @public
-         * @type Boolean
+         * @type {boolean}
          * @default false
          * @name isPersistent
-         * @memberOf me.Renderable
+         * @memberof me.Renderable
          */
         this.isPersistent = false;
 
@@ -158,10 +157,10 @@ class Renderable extends Rect {
          * If true, this renderable will be rendered using screen coordinates,
          * as opposed to world coordinates. Use this, for example, to define UI elements.
          * @public
-         * @type Boolean
+         * @type {boolean}
          * @default false
          * @name floating
-         * @memberOf me.Renderable
+         * @memberof me.Renderable
          */
         this.floating = false;
 
@@ -174,10 +173,10 @@ class Renderable extends Rect {
          * <i><b>Note:</b> Object created through Tiled will have their anchorPoint set to (0, 0) to match Tiled Level editor implementation.
          * To specify a value through Tiled, use a json expression like `json:{"x":0.5,"y":0.5}`. </i>
          * @public
-         * @type me.ObservableVector2d
+         * @type {me.ObservableVector2d}
          * @default <0.5,0.5>
          * @name anchorPoint
-         * @memberOf me.Renderable#
+         * @memberof me.Renderable#
          */
         if (this.anchorPoint instanceof ObservableVector2d) {
             this.anchorPoint.setMuted(0.5, 0.5).setCallback(this.onAnchorUpdate, this);
@@ -189,10 +188,10 @@ class Renderable extends Rect {
          * When enabled, an object container will automatically apply
          * any defined transformation before calling the child draw method.
          * @public
-         * @type Boolean
+         * @type {boolean}
          * @default true
          * @name autoTransform
-         * @memberOf me.Renderable
+         * @memberof me.Renderable
          * @example
          * // enable "automatic" transformation when the object is activated
          * onActivateEvent: function () {
@@ -213,7 +212,7 @@ class Renderable extends Rect {
          * @see me.Renderable#setOpacity
          * @see me.Renderable#getOpacity
          * @public
-         * @type Number
+         * @type {number}
          * @default 1.0
          * @name me.Renderable#alpha
          */
@@ -222,7 +221,7 @@ class Renderable extends Rect {
         /**
          * a reference to the parent object that contains this renderable
          * @public
-         * @type me.Container|me.Entity
+         * @type {me.Container|me.Entity}
          * @default undefined
          * @name me.Renderable#ancestor
          */
@@ -235,7 +234,7 @@ class Renderable extends Rect {
          * @type {me.Rect|me.Polygon|me.Line|me.Ellipse}
          * @name mask
          * @default undefined
-         * @memberOf me.Renderable#
+         * @memberof me.Renderable#
          * @example
          * // apply a mask in the shape of a Star
          * myNPCSprite.mask = new me.Polygon(myNPCSprite.width / 2, 0, [
@@ -260,7 +259,7 @@ class Renderable extends Rect {
          * @type {me.Color}
          * @name tint
          * @default (255, 255, 255)
-         * @memberOf me.Renderable#
+         * @memberof me.Renderable#
          * @example
          * // add a red tint to this renderable
          * this.tint.setColor(255, 128, 128);
@@ -272,10 +271,10 @@ class Renderable extends Rect {
         /**
          * The name of the renderable
          * @public
-         * @type {String}
+         * @type {string}
          * @name name
          * @default ""
-         * @memberOf me.Renderable
+         * @memberof me.Renderable
          */
         this.name = "";
 
@@ -284,7 +283,7 @@ class Renderable extends Rect {
          * @public
          * @type {me.ObservableVector3d}
          * @name pos
-         * @memberOf me.Renderable#
+         * @memberof me.Renderable#
          */
         if (this.pos instanceof ObservableVector3d) {
             this.pos.setMuted(x, y, 0).setCallback(this.updateBoundsPos, this);
@@ -294,10 +293,10 @@ class Renderable extends Rect {
 
         /**
          * when true the renderable will be redrawn during the next update cycle
-         * @type {Boolean}
+         * @type {boolean}
          * @name isDirty
          * @default false
-         * @memberOf me.Renderable#
+         * @memberof me.Renderable#
          */
         this.isDirty = false;
 
@@ -314,26 +313,33 @@ class Renderable extends Rect {
         this.setOpacity(1.0);
     }
 
+    /**
+     * Whether the renderable object is floating, or contained in a floating container
+     * @public
+     * @see me.Renderable#floating
+     * @readonly
+     * @type {boolean}
+     * @name isFloating
+     * @memberof me.Renderable
+     */
+    get isFloating() {
+        return this.floating === true || (typeof this.ancestor !== "undefined" && this.ancestor.floating === true);
+    }
+
     /**
      * Whether the renderable object is visible and within the viewport
      * @public
      * @readonly
-     * @type Boolean
+     * @type {boolean}
      * @default false
      * @name inViewport
-     * @memberOf me.Renderable
+     * @memberof me.Renderable
      */
 
-    /**
-     * @ignore
-     */
     get inViewport() {
         return this._inViewport;
     }
 
-    /**
-     * @ignore
-     */
     set inViewport(value) {
         if (this._inViewport !== value) {
             this._inViewport = value;
@@ -347,14 +353,11 @@ class Renderable extends Rect {
      * returns true if this renderable is flipped on the horizontal axis
      * @public
      * @see me.Renderable#flipX
-     * @type {Boolean}
+     * @type {boolean}
      * @name isFlippedX
-     * @memberOf me.Renderable
+     * @memberof me.Renderable
      */
 
-    /**
-     * @ignore
-     */
     get isFlippedX() {
         return this._flip.x === true;
     }
@@ -363,14 +366,11 @@ class Renderable extends Rect {
      * returns true if this renderable is flipped on the vertical axis
      * @public
      * @see me.Renderable#flipY
-     * @type {Boolean}
+     * @type {boolean}
      * @name isFlippedY
-     * @memberOf me.Renderable
+     * @memberof me.Renderable
      */
 
-    /**
-     * @ignore
-     */
     get isFlippedY() {
         return this._flip.y === true;
     }
@@ -378,9 +378,9 @@ class Renderable extends Rect {
     /**
      * returns the bounding box for this renderable
      * @name getBounds
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
-     * @return {me.Bounds} bounding box Rectangle object
+     * @returns {me.Bounds} bounding box Rectangle object
      */
     getBounds() {
         if (typeof this._bounds === "undefined") {
@@ -399,9 +399,9 @@ class Renderable extends Rect {
     /**
      * get the renderable alpha channel value<br>
      * @name getOpacity
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
-     * @return {Number} current opacity value between 0 and 1
+     * @returns {number} current opacity value between 0 and 1
      */
     getOpacity() {
         return this.alpha;
@@ -410,9 +410,9 @@ class Renderable extends Rect {
     /**
      * set the renderable alpha channel value<br>
      * @name setOpacity
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
-     * @param {Number} alpha opacity value between 0.0 and 1.0
+     * @param {number} alpha opacity value between 0.0 and 1.0
      */
     setOpacity(alpha) {
         if (typeof (alpha) === "number") {
@@ -429,10 +429,10 @@ class Renderable extends Rect {
      * flip the renderable on the horizontal axis (around the center of the renderable)
      * @see me.Matrix2d#scaleX
      * @name flipX
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
-     * @param {Boolean} [flip=true] `true` to flip this renderable.
-     * @return {me.Renderable} Reference to this object for method chaining
+     * @param {boolean} [flip=true] `true` to flip this renderable.
+     * @returns {me.Renderable} Reference to this object for method chaining
      */
     flipX(flip = true) {
         this._flip.x = !!flip;
@@ -444,10 +444,10 @@ class Renderable extends Rect {
      * flip the renderable on the vertical axis (around the center of the renderable)
      * @see me.Matrix2d#scaleY
      * @name flipY
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
-     * @param {Boolean} [flip=true] `true` to flip this renderable.
-     * @return {me.Renderable} Reference to this object for method chaining
+     * @param {boolean} [flip=true] `true` to flip this renderable.
+     * @returns {me.Renderable} Reference to this object for method chaining
      */
     flipY(flip = true) {
         this._flip.y = !!flip;
@@ -458,11 +458,11 @@ class Renderable extends Rect {
     /**
      * multiply the renderable currentTransform with the given matrix
      * @name transform
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @see me.Renderable#currentTransform
      * @function
-     * @param {me.Matrix2d} matrix the transformation matrix
-     * @return {me.Renderable} Reference to this object for method chaining
+     * @param {me.Matrix2d} m the transformation matrix
+     * @returns {me.Renderable} Reference to this object for method chaining
      */
     transform(m) {
         this.currentTransform.multiply(m);
@@ -475,10 +475,10 @@ class Renderable extends Rect {
     /**
      * return the angle to the specified target
      * @name angleTo
-     * @memberOf me.Renderable
+     * @memberof me.Renderable
      * @function
      * @param {me.Renderable|me.Vector2d|me.Vector3d} target
-     * @return {Number} angle in radians
+     * @returns {number} angle in radians
      */
     angleTo(target) {
         var a = this.getBounds();
@@ -499,10 +499,10 @@ class Renderable extends Rect {
     /**
      * return the distance to the specified target
      * @name distanceTo
-     * @memberOf me.Renderable
+     * @memberof me.Renderable
      * @function
      * @param {me.Renderable|me.Vector2d|me.Vector3d} target
-     * @return {Number} distance
+     * @returns {number} distance
      */
     distanceTo(target) {
         var a = this.getBounds();
@@ -523,10 +523,10 @@ class Renderable extends Rect {
     /**
      * Rotate this renderable towards the given target.
      * @name lookAt
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
      * @param {me.Renderable|me.Vector2d|me.Vector3d} target the renderable or position to look at
-     * @return {me.Renderable} Reference to this object for method chaining
+     * @returns {me.Renderable} Reference to this object for method chaining
      */
     lookAt(target) {
         var position;
@@ -547,15 +547,15 @@ class Renderable extends Rect {
     /**
      * Rotate this renderable by the specified angle (in radians).
      * @name rotate
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
-     * @param {Number} angle The angle to rotate (in radians)
+     * @param {number} angle The angle to rotate (in radians)
      * @param {me.Vector2d|me.ObservableVector2d} [v] an optional point to rotate around
-     * @return {me.Renderable} Reference to this object for method chaining
+     * @returns {me.Renderable} Reference to this object for method chaining
      */
-    rotate(angle) {
+    rotate(angle, v) {
         if (!isNaN(angle)) {
-            this.currentTransform.rotate(angle);
+            this.currentTransform.rotate(angle, v);
             //this.updateBoundsPos(this.pos.x, this.pos.y);
             this.isDirty = true;
         }
@@ -569,11 +569,11 @@ class Renderable extends Rect {
      * is an image, the image.width and image.height properties are unaltered but the currentTransform
      * member will be changed.
      * @name scale
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
-     * @param {Number} x a number representing the abscissa of the scaling vector.
-     * @param {Number} [y=x] a number representing the ordinate of the scaling vector.
-     * @return {me.Renderable} Reference to this object for method chaining
+     * @param {number} x a number representing the abscissa of the scaling vector.
+     * @param {number} [y=x] a number representing the ordinate of the scaling vector.
+     * @returns {me.Renderable} Reference to this object for method chaining
      */
     scale(x, y) {
         this.currentTransform.scale(x, y);
@@ -585,10 +585,10 @@ class Renderable extends Rect {
     /**
      * scale the renderable around his anchor point
      * @name scaleV
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
-     * @param {me.Vector2d} vector scaling vector
-     * @return {me.Renderable} Reference to this object for method chaining
+     * @param {me.Vector2d} v scaling vector
+     * @returns {me.Renderable} Reference to this object for method chaining
      */
     scaleV(v) {
         this.scale(v.x, v.y);
@@ -599,12 +599,12 @@ class Renderable extends Rect {
      * update function. <br>
      * automatically called by the game manager {@link me.game}
      * @name update
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
      * @protected
-     * @param {Number} dt time since the last update in milliseconds.
-     * @return false
-     **/
+     * @param {number} dt time since the last update in milliseconds.
+     * @returns {boolean} true if the renderable is dirty
+     */
     update(/* dt */) {
         return this.isDirty;
     }
@@ -613,9 +613,9 @@ class Renderable extends Rect {
      * 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() {
         super.updateBounds();
@@ -627,7 +627,7 @@ class Renderable extends Rect {
      * update the renderable's bounding rect (private)
      * @ignore
      * @name updateBoundsPos
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
      */
      updateBoundsPos(newX, newY) {
@@ -659,9 +659,9 @@ class Renderable extends Rect {
      /**
       * return the renderable absolute position in the game world
       * @name getAbsolutePosition
-      * @memberOf me.Renderable.prototype
+      * @memberof me.Renderable.prototype
       * @function
-      * @return {me.Vector2d}
+      * @returns {me.Vector2d}
       */
       getAbsolutePosition() {
           if (typeof this._absPos === "undefined") {
@@ -679,28 +679,29 @@ class Renderable extends Rect {
      * called when the anchor point value is changed
      * @private
      * @name onAnchorUpdate
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
+     * @param {number} x the new X value to be set for the anchor
+     * @param {number} y the new Y value to be set for the anchor
      */
-     onAnchorUpdate(newX, newY) {
+     onAnchorUpdate(x, y) {
          // since the callback is called before setting the new value
          // manually update the anchor point (required for updateBoundsPos)
-         this.anchorPoint.setMuted(newX, newY);
+         this.anchorPoint.setMuted(x, y);
          // then call updateBounds
          this.updateBoundsPos(this.pos.x, this.pos.y);
      }
 
-
     /**
      * prepare the rendering context before drawing
      * (apply defined transforms, anchor point). <br>
      * automatically called by the game manager {@link me.game}
      * @name preDraw
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
      * @protected
      * @param {me.CanvasRenderer|me.WebGLRenderer} renderer a renderer object
-     **/
+     */
     preDraw(renderer) {
         var bounds = this.getBounds();
         var ax = bounds.width * this.anchorPoint.x,
@@ -747,11 +748,11 @@ class Renderable extends Rect {
      * object draw. <br>
      * automatically called by the game manager {@link me.game}
      * @name draw
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
      * @protected
      * @param {me.CanvasRenderer|me.WebGLRenderer} renderer a renderer object
-     **/
+     */
     draw(/*renderer*/) {
         // empty one !
     }
@@ -760,11 +761,11 @@ class Renderable extends Rect {
      * restore the rendering context after drawing. <br>
      * automatically called by the game manager {@link me.game}
      * @name postDraw
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
      * @protected
      * @param {me.CanvasRenderer|me.WebGLRenderer} renderer a renderer object
-     **/
+     */
     postDraw(renderer) {
 
         // remove the previously applied tint
@@ -786,11 +787,11 @@ class Renderable extends Rect {
      * onCollision callback, triggered in case of collision,
      * when this renderable body is colliding with another one
      * @name onCollision
-     * @memberOf me.Renderable.prototype
+     * @memberof me.Renderable.prototype
      * @function
      * @param {me.collision.ResponseObject} response the collision response object
      * @param {me.Renderable} other the other renderable touching this one (a reference to response.a or response.b)
-     * @return {Boolean} true if the object should respond to the collision (its position and velocity will be corrected)
+     * @returns {boolean} true if the object should respond to the collision (its position and velocity will be corrected)
      * @example
      * // colision handler
      * onCollision(response) {
@@ -863,7 +864,7 @@ class Renderable extends Rect {
      * OnDestroy Notification function<br>
      * Called by engine before deleting the object
      * @name onDestroyEvent
-     * @memberOf me.Renderable
+     * @memberof me.Renderable
      * @function
      */
     onDestroyEvent() {