melonjs 10.3.0 → 10.5.1

package/src/physics/body.js

@@ -11,46 +11,41 @@ import { world } from "./../game.js";
 
 
 /**
+ * @classdesc
  * a Generic Physic Body Object with some physic properties and behavior functionality, to as a member of a Renderable.
- * @class Body
- * @memberof me
- * @param {me.Renderable} ancestor the parent object this body is attached to
- * @param {me.Rect|me.Rect[]|me.Polygon|me.Polygon[]|me.Line|me.Line[]|me.Ellipse|me.Ellipse[]|me.Bounds|me.Bounds[]|object} [shapes] a initial shape, list of shapes, or JSON object defining the body
- * @param {Function} [onBodyUpdate] callback for when the body is updated (e.g. add/remove shapes)
  */
 class Body {
-
-    constructor(parent, shapes, onBodyUpdate) {
+    /**
+     * @param {Renderable} ancestor the parent object this body is attached to
+     * @param {Rect|Rect[]|Polygon|Polygon[]|Line|Line[]|Ellipse|Ellipse[]|Bounds|Bounds[]|object} [shapes] a initial shape, list of shapes, or JSON object defining the body
+     * @param {Function} [onBodyUpdate] callback for when the body is updated (e.g. add/remove shapes)
+     */
+    constructor(ancestor, shapes, onBodyUpdate) {
 
         /**
          * a reference to the parent object that contains this body,
          * or undefined if it has not been added to one.
          * @public
-         * @type {me.Renderable}
+         * @type {Renderable}
          * @default undefined
-         * @name me.Body#ancestor
          */
-        this.ancestor = parent;
+        this.ancestor = ancestor;
 
-        /**
-         * The AABB bounds box reprensenting this body
-         * @public
-         * @type {me.Bounds}
-         * @name bounds
-         * @memberof me.Body
-         */
         if (typeof this.bounds === "undefined") {
+            /**
+             * The AABB bounds box reprensenting this body
+             * @public
+             * @type {Bounds}
+             */
             this.bounds = new Bounds();
         }
 
-        /**
-         * The collision shapes of the body
-         * @ignore
-         * @type {me.Polygon[]|me.Line[]|me.Ellipse[]}
-         * @name shapes
-         * @memberof me.Body
-         */
         if (typeof this.shapes === "undefined") {
+            /**
+             * The collision shapes of the body
+             * @ignore
+             * @type {Polygon[]|Line[]|Ellipse[]}
+             */
             this.shapes = [];
         }
 
@@ -59,10 +54,8 @@ class Body {
          * (by default will collide with all entities)
          * @ignore
          * @type {number}
-         * @default me.collision.types.ALL_OBJECT
-         * @name collisionMask
-         * @see me.collision.types
-         * @memberof me.Body
+         * @default collision.types.ALL_OBJECT
+         * @see collision.types
          */
         this.collisionMask = collision.types.ALL_OBJECT;
 
@@ -70,10 +63,8 @@ class Body {
          * define the collision type of the body for collision filtering
          * @public
          * @type {number}
-         * @default me.collision.types.ENEMY_OBJECT
-         * @name collisionType
-         * @see me.collision.types
-         * @memberof me.Body
+         * @default collision.types.ENEMY_OBJECT
+         * @see collision.types
          * @example
          * // set the body collision type
          * myEntity.body.collisionType = me.collision.types.PLAYER_OBJECT;
@@ -83,10 +74,8 @@ class Body {
         /**
          * body velocity
          * @public
-         * @type {me.Vector2d}
+         * @type {Vector2d}
          * @default <0,0>
-         * @name vel
-         * @memberof me.Body
          */
         if (typeof this.vel === "undefined") {
             this.vel = new Vector2d();
@@ -97,11 +86,9 @@ class Body {
          * body force or acceleration (automatically) applied to the body.
          * when defining a force, user should also define a max velocity
          * @public
-         * @type {me.Vector2d}
+         * @type {Vector2d}
          * @default <0,0>
-         * @name force
-         * @see me.Body.setMaxVelocity
-         * @memberof me.Body
+         * @see Body.setMaxVelocity
          * @example
          * // define a default maximum acceleration, initial force and friction
          * this.body.force.set(0, 0);
@@ -128,10 +115,8 @@ class Body {
         /**
          * body friction
          * @public
-         * @type {me.Vector2d}
+         * @type {Vector2d}
          * @default <0,0>
-         * @name friction
-         * @memberof me.Body
          */
         if (typeof this.friction === "undefined") {
             this.friction = new Vector2d();
@@ -144,8 +129,6 @@ class Body {
          * @public
          * @type {number}
          * @default 0
-         * @name bounce
-         * @memberof me.Body
          */
         this.bounce = 0;
 
@@ -154,18 +137,14 @@ class Body {
          * @public
          * @type {number}
          * @default 1
-         * @name mass
-         * @memberof me.Body
          */
         this.mass = 1;
 
         /**
          * max velocity (to limit body velocity)
          * @public
-         * @type {me.Vector2d}
+         * @type {Vector2d}
          * @default <490,490>
-         * @name maxVel
-         * @memberof me.Body
          */
         if (typeof this.maxVel === "undefined") {
             this.maxVel = new Vector2d();
@@ -175,13 +154,12 @@ class Body {
 
 
         /**
-         * either this body is a static body or not
+         * Either this body is a static body or not.
+         * A static body is completely fixed and can never change position or angle.
          * @readonly
          * @public
          * @type {boolean}
          * @default false
-         * @name isStatic
-         * @memberof me.Body
          */
         this.isStatic = false;
 
@@ -189,22 +167,18 @@ class Body {
         /**
          * The degree to which this body is affected by the world gravity
          * @public
-         * @see me.World.gravity
+         * @see World.gravity
          * @type {number}
          * @default 1.0
-         * @name gravityScale
-         * @memberof me.Body
          */
         this.gravityScale = 1.0;
 
         /**
          * If true this body won't be affected by the world gravity
          * @public
-         * @see me.World.gravity
+         * @see World.gravity
          * @type {boolean}
          * @default false
-         * @name ignoreGravity
-         * @memberof me.Body
          */
         this.ignoreGravity = false;
 
@@ -216,8 +190,6 @@ class Body {
          * @public
          * @type {boolean}
          * @default false
-         * @name falling
-         * @memberof me.Body
          */
         this.falling = false;
 
@@ -228,8 +200,6 @@ class Body {
          * @public
          * @type {boolean}
          * @default false
-         * @name jumping
-         * @memberof me.Body
          */
         this.jumping = false;
 
@@ -258,10 +228,6 @@ class Body {
     /**
      * set the body as a static body
      * static body do not move automatically and do not check againt collision with others
-     * @name setStatic
-     * @memberof me.Body
-     * @public
-     * @function
      * @param {boolean} [isStatic=true]
      */
     setStatic(isStatic = true) {
@@ -271,11 +237,7 @@ class Body {
     /**
      * add a collision shape to this body <br>
      * (note: me.Rect objects will be converted to me.Polygon before being added)
-     * @name addShape
-     * @memberof me.Body
-     * @public
-     * @function
-     * @param {me.Rect|me.Polygon|me.Line|me.Ellipse|me.Bounds|object} shape a shape or JSON object
+     * @param {Rect|Polygon|Line|Ellipse|Bounds|object} shape a shape or JSON object
      * @returns {number} the shape array length
      * @example
      * // add a rectangle shape
@@ -325,11 +287,7 @@ class Body {
 
     /**
      * set the body vertices to the given one
-     * @name setVertices
-     * @memberof me.Body
-     * @public
-     * @function
-     * @param {me.Vector2d[]} vertices an array of me.Vector2d points defining a convex hull
+     * @param {Vector2d[]} vertices an array of me.Vector2d points defining a convex hull
      * @param {number} [index=0] the shape object for which to set the vertices
      * @param {boolean} [clear=true] either to reset the body definition before adding the new vertices
      */
@@ -352,11 +310,7 @@ class Body {
 
     /**
      * add the given vertices to the body shape
-     * @name addVertices
-     * @memberof me.Body
-     * @public
-     * @function
-     * @param {me.Vector2d[]} vertices an array of me.Vector2d points defining a convex hull
+     * @param {Vector2d[]} vertices an array of me.Vector2d points defining a convex hull
      * @param {number} [index=0] the shape object for which to set the vertices
      */
     addVertices(vertices, index = 0) {
@@ -366,10 +320,6 @@ class Body {
     /**
      * add collision mesh based on a JSON object
      * (this will also apply any physic properties defined in the given JSON file)
-     * @name fromJSON
-     * @memberof me.Body
-     * @public
-     * @function
      * @param {object} json a JSON object as exported from a Physics Editor tool
      * @param {string} [id] an optional shape identifier within the given the json object
      * @see https://www.codeandweb.com/physicseditor
@@ -410,12 +360,8 @@ class Body {
 
     /**
      * return the collision shape at the given index
-     * @name getShape
-     * @memberof me.Body
-     * @public
-     * @function
      * @param {number} [index=0] the shape object at the specified index
-     * @returns {me.Polygon|me.Line|me.Ellipse} shape a shape object if defined
+     * @returns {Polygon|Line|Ellipse} shape a shape object if defined
      */
     getShape(index) {
         return this.shapes[index || 0];
@@ -423,10 +369,8 @@ class Body {
 
     /**
      * returns the AABB bounding box for this body
-     * @name getBounds
-     * @memberof me.Body
      * @function
-     * @returns {me.Bounds} bounding box Rectangle object
+     * @returns {Bounds} bounding box Rectangle object
      */
     getBounds() {
         return this.bounds;
@@ -434,11 +378,7 @@ class Body {
 
     /**
      * remove the specified shape from the body shape list
-     * @name removeShape
-     * @memberof me.Body
-     * @public
-     * @function
-     * @param {me.Polygon|me.Line|me.Ellipse} shape a shape object
+     * @param {Polygon|Line|Ellipse} shape a shape object
      * @returns {number} the shape array length
      */
     removeShape(shape) {
@@ -456,10 +396,6 @@ class Body {
 
     /**
      * remove the shape at the given index from the body shape list
-     * @name removeShapeAt
-     * @memberof me.Body
-     * @public
-     * @function
      * @param {number} index the shape object at the specified index
      * @returns {number} the shape array length
      */
@@ -471,12 +407,8 @@ class Body {
      * By default all entities are able to collide with all other entities, <br>
      * but it's also possible to specify 'collision filters' to provide a finer <br>
      * control over which entities can collide with each other.
-     * @name setCollisionMask
-     * @memberof me.Body
-     * @public
-     * @function
-     * @see me.collision.types
-     * @param {number} [bitmask = me.collision.types.ALL_OBJECT] the collision mask
+     * @see collision.types
+     * @param {number} [bitmask = collision.types.ALL_OBJECT] the collision mask
      * @example
      * // filter collision detection with collision shapes, enemies and collectables
      * myEntity.body.setCollisionMask(me.collision.types.WORLD_SHAPE | me.collision.types.ENEMY_OBJECT | me.collision.types.COLLECTABLE_OBJECT);
@@ -490,11 +422,7 @@ class Body {
 
     /**
      * define the collision type of the body for collision filtering
-     * @name setCollisionType
-     * @memberof me.Body
-     * @public
-     * @function
-     * @see me.collision.types
+     * @see collision.types
      * @param {number} type the collision type
      * @example
      * // set the body collision type
@@ -512,11 +440,7 @@ class Body {
 
     /**
      * the built-in function to solve the collision response
-     * @protected
-     * @name respondToCollision
-     * @memberof me.Body
-     * @function
-     * @param {me.collision.ResponseObject} response the collision response object
+     * @param {object} response the collision response object (see {@link collision.ResponseObject})
      */
     respondToCollision(response) {
         // the overlap vector
@@ -553,9 +477,6 @@ class Body {
      *    - The current element being processed in the array <br>
      *    - The index of element in the array. <br>
      *    - The array forEach() was called upon. <br>
-     * @name forEach
-     * @memberof me.Body.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.
      * @example
@@ -590,18 +511,12 @@ class Body {
 
     /**
      * Returns true if the any of the shape composing the body contains the given point.
-     * @name contains
-     * @memberof me.Body
-     * @function
-     * @param  {me.Vector2d} point
+     * @param {Vector2d} point
      * @returns {boolean} true if contains
      */
 
     /**
      * Returns true if the any of the shape composing the body contains the given point.
-     * @name contains
-     * @memberof me.Body
-     * @function
      * @param  {number} x x coordinate
      * @param  {number} y y coordinate
      * @returns {boolean} true if contains
@@ -633,12 +548,9 @@ class Body {
     /**
      * Rotate this body (counter-clockwise) by the specified angle (in radians).
      * Unless specified the body will be rotated around its center point
-     * @name rotate
-     * @memberof me.Body
-     * @function
      * @param {number} angle The angle to rotate (in radians)
-     * @param {me.Vector2d|me.ObservableVector2d} [v=me.Body.getBounds().center] an optional point to rotate around
-     * @returns {me.Body} Reference to this object for method chaining
+     * @param {Vector2d|ObservableVector2d} [v=Body.getBounds().center] an optional point to rotate around
+     * @returns {Body} Reference to this object for method chaining
      */
     rotate(angle, v = this.getBounds().center) {
         this.bounds.clear();
@@ -660,9 +572,6 @@ class Body {
 
     /**
      * cap the body velocity (body.maxVel property) to the specified value<br>
-     * @name setMaxVelocity
-     * @memberof me.Body
-     * @function
      * @param {number} x max velocity on x axis
      * @param {number} y max velocity on y axis
      * @protected
@@ -674,9 +583,6 @@ class Body {
 
     /**
      * set the body default friction
-     * @name setFriction
-     * @memberof me.Body
-     * @function
      * @param {number} x horizontal friction
      * @param {number} y vertical friction
      * @protected
@@ -760,10 +666,7 @@ class Body {
      * property is set to true and Body.jumping is set to !Body.falling.
      *
      * At this time a call to Body.Update does not call the onBodyUpdate callback that is listed in the constructor arguments.
-     * @name update
-     * @ignore
-     * @memberof me.Body
-     * @function
+     * @protected
      * @param {number} dt time since the last update in milliseconds.
      * @returns {boolean} true if resulting velocity is different than 0
      */