melonjs 15.2.1 → 15.4.0

package/dist/types/application/application.d.ts

@@ -8,35 +8,14 @@ export default class Application {
     /**
      * @param {number} width - The width of the canvas viewport
      * @param {number} height - The height of the canvas viewport
-     * @param {object} [options] - The optional video/renderer parameters.<br> (see Renderer(s) documentation for further specific options)
-     * @param {string|HTMLElement} [options.parent=document.body] - the DOM parent element to hold the canvas in the HTML file
-     * @param {number|Renderer} [options.renderer=AUTO] - renderer to use (CANVAS, WEBGL, AUTO), or a custom renderer class
-     * @param {number|string} [options.scale=1.0] - enable scaling of the canvas ('auto' for automatic scaling)
-     * @param {string} [options.scaleMethod="fit"] - screen scaling modes ('fit','fill-min','fill-max','flex','flex-width','flex-height','stretch')
-     * @param {boolean} [options.preferWebGL1=false] - if true the renderer will only use WebGL 1
-     * @param {boolean} [options.depthTest="sorting"] - ~Experimental~ the default method to sort object on the z axis in WebGL ("sorting", "z-buffer")
-     * @param {string} [options.powerPreference="default"] - a hint to the user agent indicating what configuration of GPU is suitable for the WebGL context ("default", "high-performance", "low-power"). To be noted that Safari and Chrome (since version 80) both default to "low-power" to save battery life and improve the user experience on these dual-GPU machines.
-     * @param {boolean} [options.transparent=false] - whether to allow transparent pixels in the front buffer (screen).
-     * @param {boolean} [options.antiAlias=false] - whether to enable or not video scaling interpolation
-     * @param {boolean} [options.consoleHeader=true] - whether to display melonJS version and basic device information in the console
+     * @param {Application.Settings} [options] - The optional parameters for the application and default renderer
      * @throws Will throw an exception if it fails to instantiate a renderer
      * @example
      * let my game = new Application(640, 480, {renderer: me.video.AUTO}) {
      *     ....
      * }
      */
-    constructor(width: number, height: number, options?: {
-        parent?: string | HTMLElement | undefined;
-        renderer?: number | Renderer;
-        scale?: string | number | undefined;
-        scaleMethod?: string | undefined;
-        preferWebGL1?: boolean | undefined;
-        depthTest?: boolean | undefined;
-        powerPreference?: string | undefined;
-        transparent?: boolean | undefined;
-        antiAlias?: boolean | undefined;
-        consoleHeader?: boolean | undefined;
-    } | undefined);
+    constructor(width: number, height: number, options?: any);
     /**
      * the parent HTML element holding the main canvas of this application
      * @type {HTMLElement}
@@ -81,9 +60,30 @@ export default class Application {
     isInitialized: boolean;
     /**
      * the given settings used when creating this application
-     * @type {Object}
+     * @type {object}
      */
-    settings: Object;
+    settings: object;
+    /**
+     * Specify whether to pause this app when losing focus
+     * @type {boolean}
+     * @default true
+     * @example
+     *  // keep the default game instance running even when loosing focus
+     *  me.game.pauseOnBlur = false;
+     */
+    pauseOnBlur: boolean;
+    /**
+     * Specify whether to unpause this app when gaining back focus
+     * @type {boolean}
+     * @default true
+     */
+    resumeOnFocus: boolean;
+    /**
+     * Specify whether to stop this app when losing focus
+     * @type {boolean}
+     * @default false
+     */
+    stopOnBlur: boolean;
     isDirty: boolean;
     isAlwaysDirty: boolean;
     frameCounter: number;
@@ -97,8 +97,11 @@ export default class Application {
     updateAverageDelta: number;
     /**
      * init the game instance (create a physic world, update starting time, etc..)
+     * @param {number} width - The width of the canvas viewport
+     * @param {number} height - The height of the canvas viewport
+     * @param {Application.Settings} [options] - The optional parameters for the application and default renderer
      */
-    init(width: any, height: any, options: any): void;
+    init(width: number, height: number, options?: any): void;
     /**
      * reset the game Object manager
      * destroy all current objects
@@ -128,7 +131,7 @@ export default class Application {
     updateFrameRate(): void;
     /**
      * Returns the parent HTML Element holding the main canvas of this application
-     * @returns {HTMLElement}
+     * @returns {HTMLElement} the parent HTML element
      */
     getParentElement(): HTMLElement;
     /**
@@ -138,14 +141,12 @@ export default class Application {
     /**
      * update all objects related to this game active scene/stage
      * @param {number} time - current timestamp as provided by the RAF callback
-     * @param {Stage} stage - the current stage
      */
-    update(time: number, stage: Stage): void;
+    update(time: number): void;
     /**
      * draw the active scene/stage associated to this game
-     * @param {Stage} stage - the current stage
      */
-    draw(stage: Stage): void;
+    draw(): void;
 }
 import CanvasRenderer from "./../video/canvas/canvas_renderer.js";
 import World from "./../physics/world.js";

package/dist/types/application/header.d.ts

@@ -1,5 +1,5 @@
 /**
  * display information
- * @param {Application} game - the game application instance calling this function
+ * @param {Application} app - the game application instance calling this function
  */
-export function consoleHeader(app: any): void;
+export function consoleHeader(app: Application): void;

package/dist/types/application/settings.d.ts

@@ -1,18 +1,82 @@
 export namespace defaultSettings {
-    const parent: undefined;
-    const renderer: number;
-    const autoScale: boolean;
-    const scale: number;
-    const scaleMethod: string;
-    const transparent: boolean;
-    const premultipliedAlpha: boolean;
-    const blendMode: string;
-    const antiAlias: boolean;
-    const failIfMajorPerformanceCaveat: boolean;
-    const subPixel: boolean;
-    const preferWebGL1: boolean;
-    const powerPreference: string;
-    const verbose: boolean;
-    const consoleHeader: boolean;
-    const legacy: boolean;
+    let parent: undefined;
+    let renderer: number;
+    let autoScale: boolean;
+    let scale: number;
+    let scaleMethod: string;
+    let scaleTarget: undefined;
+    let transparent: boolean;
+    let premultipliedAlpha: boolean;
+    let blendMode: string;
+    let antiAlias: boolean;
+    let failIfMajorPerformanceCaveat: boolean;
+    let subPixel: boolean;
+    let preferWebGL1: boolean;
+    let powerPreference: string;
+    let verbose: boolean;
+    let consoleHeader: boolean;
+    let legacy: boolean;
 }
+/**
+ * Application & Renderer Settings definition.
+ */
+export type Settings = {
+    /**
+     * - the DOM parent element to hold the canvas in the HTML file
+     */
+    parent?: string | HTMLElement | undefined;
+    /**
+     * - renderer to use (CANVAS, WEBGL, AUTO), or a custom renderer class
+     */
+    renderer?: number | Renderer;
+    /**
+     * - enable scaling of the canvas ('auto' for automatic scaling)
+     */
+    scale?: string | number | undefined;
+    /**
+     * - screen scaling modes : <br>
+     * - <i><b>`fit`</b></i> : Letterboxed; content is scaled to design aspect ratio <br>
+     * <center><img src="images/scale-fit.png"/></center><br>
+     * - <i><b>`fill-min`</b></i> : Canvas is resized to fit minimum design resolution; content is scaled to design aspect ratio <br>
+     * <center><img src="images/scale-fill-min.png"/></center><br>
+     * - <i><b>`fill-max`</b></i> : Canvas is resized to fit maximum design resolution; content is scaled to design aspect ratio <br>
+     * <center><img src="images/scale-fill-max.png"/></center><br>
+     * - <i><b>`flex`</b><</i> : Canvas width & height is resized to fit; content is scaled to design aspect ratio <br>
+     * <center><img src="images/scale-flex.png"/></center><br>
+     * - <i><b>`flex-width`</b></i> : Canvas width is resized to fit; content is scaled to design aspect ratio <br>
+     * <center><img src="images/scale-flex-width.png"/></center><br>
+     * - <i><b>`flex-height`</b></i> : Canvas height is resized to fit; content is scaled to design aspect ratio <br>
+     * <center><img src="images/scale-flex-height.png"/></center><br>
+     * - <i><b>`stretch`</b></i> : Canvas is resized to fit; content is scaled to screen aspect ratio <br>
+     * <center><img src="images/scale-stretch.png"/></center>
+     */
+    scaleMethod?: "flex" | "fill-min" | "fill-max" | "flex-width" | "flex-height" | "stretch" | "fit" | undefined;
+    /**
+     * - the HTML Element to be used as the reference target when using automatic scaling (by default melonJS will use the parent container of the div element containing the canvas)
+     */
+    scaleTarget?: string | HTMLElement | undefined;
+    /**
+     * - if true the renderer will only use WebGL 1
+     */
+    preferWebGL1?: boolean | undefined;
+    /**
+     * - ~Experimental~ the default method to sort object on the z axis in WebGL
+     */
+    depthTest?: "sorting" | "z-buffer" | undefined;
+    /**
+     * - a hint to the user agent indicating what configuration of GPU is suitable for the WebGL context. To be noted that Safari and Chrome (since version 80) both default to "low-power" to save battery life and improve the user experience on these dual-GPU machines.
+     */
+    powerPreference?: "default" | "high-performance" | "low-power" | undefined;
+    /**
+     * - whether to allow transparent pixels in the front buffer (screen).
+     */
+    transparent?: boolean | undefined;
+    /**
+     * - whether to enable or not video scaling interpolation
+     */
+    antiAlias?: boolean | undefined;
+    /**
+     * - whether to display melonJS version and basic device information in the console
+     */
+    consoleHeader?: boolean | undefined;
+};

package/dist/types/audio/audio.d.ts

@@ -1,14 +1,12 @@
 /**
  * Initialize and configure the audio support.<br>
- * melonJS supports a wide array of audio codecs that have varying browser support :
- * <i> ("mp3", "mpeg", opus", "ogg", "oga", "wav", "aac", "caf", "m4a", "m4b", "mp4", "weba", "webm", "dolby", "flac")</i>.<br>
  * For a maximum browser coverage the recommendation is to use at least two of them,
  * typically default to webm and then fallback to mp3 for the best balance of small filesize and high quality,
  * webm has nearly full browser coverage with a great combination of compression and quality, and mp3 will fallback gracefully for other browsers.
  * It is important to remember that melonJS selects the first compatible sound based on the list of extensions and given order passed here.
  * So if you want webm to be used before mp3, you need to put the audio format in that order.
  * @function audio.init
- * @param {string} [format="mp3"] - audio format to prioritize
+ * @param {"mp3"|"mpeg"|"opus"|"ogg"|"oga"|"wav"|"aac"|"caf"|"m4a"|"m4b"|"mp4"|"weba"|"webm"|"dolby"|"flac"} [format="mp3"] - audio format to prioritize
  * @returns {boolean} Indicates whether audio initialization was successful
  * @example
  * // initialize the "sound engine", giving "webm" as default desired audio format, and "mp3" as a fallback
@@ -17,14 +15,14 @@
  *     return;
  * }
  */
-export function init(format?: string | undefined): boolean;
+export function init(format?: "mp3" | "mpeg" | "opus" | "ogg" | "oga" | "wav" | "aac" | "caf" | "m4a" | "m4b" | "mp4" | "weba" | "webm" | "dolby" | "flac" | undefined): boolean;
 /**
  * check if the given audio format is supported
  * @function audio.hasFormat
- * @param {string} codec - audio format : "mp3", "mpeg", opus", "ogg", "oga", "wav", "aac", "caf", "m4a", "m4b", "mp4", "weba", "webm", "dolby", "flac"
+ * @param {"mp3"|"mpeg"|"opus"|"ogg"|"oga"|"wav"|"aac"|"caf"|"m4a"|"m4b"|"mp4"|"weba"|"webm"|"dolby"|"flac"} codec - the audio format to check for support
  * @returns {boolean} return true if the given audio format is supported
  */
-export function hasFormat(codec: string): boolean;
+export function hasFormat(codec: "mp3" | "mpeg" | "opus" | "ogg" | "oga" | "wav" | "aac" | "caf" | "m4a" | "m4b" | "mp4" | "weba" | "webm" | "dolby" | "flac"): boolean;
 /**
  * check if audio (HTML5 or WebAudio) is supported
  * @function audio.hasAudio

package/dist/types/camera/camera2d.d.ts

@@ -81,7 +81,7 @@ export default class Camera2d extends Renderable {
      */
     invCurrentTransform: Matrix2d;
     offset: Vector2d;
-    target: Vector2d | ObservableVector3d | null;
+    target: Vector2d | null;
     follow_axis: number;
     _shake: {
         intensity: number;
@@ -100,15 +100,15 @@ export default class Camera2d extends Renderable {
     /** @ignore */
     _updateProjectionMatrix(): void;
     /** @ignore */
-    _followH(target: any): number;
+    _followH(target: any): any;
     /** @ignore */
-    _followV(target: any): number;
+    _followV(target: any): any;
     /**
      * reset the camera position to specified coordinates
      * @name reset
      * @memberof Camera2d
-     * @param {number} [x=0]
-     * @param {number} [y=0]
+     * @param {number} [x=0] - initial position of the camera on the x axis
+     * @param {number} [y=0] - initial position of the camera on the y axis
      */
     reset(x?: number | undefined, y?: number | undefined): void;
     /**
@@ -167,8 +167,8 @@ export default class Camera2d extends Renderable {
      * @name move
      * @memberof Camera2d
      * @see Camera2d.focusOn
-     * @param {number} x
-     * @param {number} y
+     * @param {number} x - horizontal offset
+     * @param {number} y - vertical offset
      * @example
      * // Move the camera up by four pixels
      * me.game.viewport.move(0, -4);
@@ -245,17 +245,16 @@ export default class Camera2d extends Renderable {
      * @memberof Camera2d
      * @param {Renderable|Entity|Sprite|NineSliceSprite} obj - to be checked against
      * @param {boolean} [floating = obj.floating] - if visibility check should be done against screen coordinates
-     * @returns {boolean}
+     * @returns {boolean} true if within the viewport
      */
     isVisible(obj: Renderable | Entity | Sprite | NineSliceSprite, floating?: boolean | undefined): boolean;
     /**
      * convert the given "local" (screen) coordinates into world coordinates
      * @name localToWorld
      * @memberof Camera2d
-     * @param {number} x
-     * @param {number} y
-     * @param {number} [v] - an optional vector object where to set the
-     * converted value
+     * @param {number} x - the x coordinate of the local point to be converted
+     * @param {number} y - the y coordinate of the local point to be converted
+     * @param {number} [v] - an optional vector object where to set the converted value
      * @returns {Vector2d}
      */
     localToWorld(x: number, y: number, v?: number | undefined): Vector2d;
@@ -265,9 +264,8 @@ export default class Camera2d extends Renderable {
      * @memberof Camera2d
      * @param {number} x
      * @param {number} y
-     * @param {number} [v] - an optional vector object where to set the
-     * converted value
-     * @returns {Vector2d}
+     * @param {number} [v] - an optional vector object where to set the converted value
+     * @returns {Vector2d} a vector with the converted local coordinates
      */
     worldToLocal(x: number, y: number, v?: number | undefined): Vector2d;
     /**
@@ -285,5 +283,4 @@ import Renderable from "./../renderable/renderable.js";
 import Matrix3d from "./../math/matrix3.js";
 import Matrix2d from "./../math/matrix2.js";
 import Vector2d from "./../math/vector2.js";
-import ObservableVector3d from "./../math/observable_vector3.js";
 import Rect from "./../geometries/rectangle.js";

package/dist/types/entity/entity.d.ts

@@ -82,7 +82,6 @@ export default class Entity extends Renderable {
      * @ignore
      * @name onBodyUpdate
      * @memberof Entity
-     * @param {Body} body - the body whose bounds to update
      */
     onBodyUpdate(): void;
     preDraw(renderer: any): void;

package/dist/types/geometries/ellipse.d.ts

@@ -14,8 +14,6 @@ export default class Ellipse {
      * the center coordinates of the ellipse
      * @public
      * @type {Vector2d}
-     * @name pos
-     * @memberof Ellipse
      */
     public pos: Vector2d;
     /**
@@ -27,32 +25,24 @@ export default class Ellipse {
      * Maximum radius of the ellipse
      * @public
      * @type {number}
-     * @name radius
-     * @memberof Ellipse
      */
     public radius: number;
     /**
      * Pre-scaled radius vector for ellipse
      * @public
      * @type {Vector2d}
-     * @name radiusV
-     * @memberof Ellipse
      */
     public radiusV: Vector2d;
     /**
      * Radius squared, for pythagorean theorom
      * @public
      * @type {Vector2d}
-     * @name radiusSq
-     * @memberof Ellipse
      */
     public radiusSq: Vector2d;
     /**
      * x/y scaling ratio for ellipse
      * @public
      * @type {Vector2d}
-     * @name ratio
-     * @memberof Ellipse
      */
     public ratio: Vector2d;
     shapeType: string;
@@ -60,8 +50,6 @@ export default class Ellipse {
     onResetEvent(x: any, y: any, w: any, h: any): void;
     /**
      * set new value to the Ellipse shape
-     * @name setShape
-     * @memberof Ellipse
      * @param {number} x - the center x coordinate of the ellipse
      * @param {number} y - the center y coordinate of the ellipse
      * @param {number} w - width (diameter) of the ellipse
@@ -71,8 +59,6 @@ export default class Ellipse {
     setShape(x: number, y: number, w: number, h: number): Ellipse;
     /**
      * Rotate this Ellipse (counter-clockwise) by the specified angle (in radians).
-     * @name rotate
-     * @memberof Ellipse
      * @param {number} angle - The angle to rotate (in radians)
      * @param {Vector2d|ObservableVector2d} [v] - an optional point to rotate around
      * @returns {Ellipse} Reference to this object for method chaining
@@ -80,74 +66,56 @@ export default class Ellipse {
     rotate(angle: number, v?: Vector2d | ObservableVector2d): Ellipse;
     /**
      * Scale this Ellipse by the specified scalar.
-     * @name scale
-     * @memberof Ellipse
-     * @param {number} x
-     * @param {number} [y=x]
+     * @param {number} x - the scale factor along the x-axis
+     * @param {number} [y=x] - the scale factor along the y-axis
      * @returns {Ellipse} Reference to this object for method chaining
      */
     scale(x: number, y?: number | undefined): Ellipse;
     /**
      * Scale this Ellipse by the specified vector.
-     * @name scale
-     * @memberof Ellipse
      * @param {Vector2d} v
      * @returns {Ellipse} Reference to this object for method chaining
      */
     scaleV(v: Vector2d): Ellipse;
     /**
      * apply the given transformation matrix to this ellipse
-     * @name transform
-     * @memberof Ellipse
      * @param {Matrix2d} matrix - the transformation matrix
      * @returns {Polygon} Reference to this object for method chaining
      */
     transform(matrix: Matrix2d): Polygon;
     /**
      * translate the circle/ellipse by the specified offset
-     * @name translate
-     * @memberof Ellipse
-     * @method
-     * @param {number} x - x offset
-     * @param {number} y - y offset
-     * @returns {Ellipse} this ellipse
-     */
-    /**
-     * translate the circle/ellipse by the specified vector
-     * @name translate
-     * @memberof Ellipse
-     * @param {Vector2d} v - vector offset
+     * @param {number|Vector2d} x -  x coordinate or a vector point to translate by
+     * @param {number} [y] - y offset
      * @returns {Ellipse} this ellipse
+     * @example
+     * ellipse.translate(10, 10);
+     * // or
+     * ellipse.translate(myVector2d);
      */
     translate(...args: any[]): Ellipse;
     /**
      * check if this circle/ellipse contains the specified point
-     * @name contains
-     * @method
-     * @memberof Ellipse
-     * @param {Vector2d} point
-     * @returns {boolean} true if contains
-     */
-    /**
-     * check if this circle/ellipse contains the specified point
-     * @name contains
-     * @memberof Ellipse
-     * @param  {number} x -  x coordinate
-     * @param  {number} y -  y coordinate
+     * @param {number|Vector2d} x -  x coordinate or a vector point to check
+     * @param {number} [y] -  y coordinate
      * @returns {boolean} true if contains
+     * @example
+     * if (circle.contains(10, 10)) {
+     *   // do something
+     * }
+     * // or
+     * if (circle.contains(myVector2d)) {
+     *  // do something
+     * }
      */
     contains(...args: any[]): boolean;
     /**
      * returns the bounding box for this shape, the smallest Rectangle object completely containing this shape.
-     * @name getBounds
-     * @memberof Ellipse
      * @returns {Bounds} this shape bounding box Rectangle object
      */
     getBounds(): Bounds;
     /**
      * clone this Ellipse
-     * @name clone
-     * @memberof Ellipse
      * @returns {Ellipse} new Ellipse
      */
     clone(): Ellipse;

package/dist/types/geometries/path2d.d.ts

@@ -27,7 +27,7 @@ export default class Path2D {
     closePath(): void;
     /**
      * triangulate the shape defined by this path into an array of triangles
-     * @returns {Point[]}
+     * @returns {Point[]} an array of vertices representing the triangulated path or shape
      */
     triangulatePath(): Point[];
     /**

package/dist/types/geometries/point.d.ts

@@ -6,13 +6,13 @@ export default class Point {
     constructor(x?: number, y?: number);
     /**
      * the position of the point on the horizontal axis
-     * @type {Number}
+     * @type {number}
      * @default 0
      */
     x: number;
     /**
      * the position of the point on the vertical axis
-     * @type {Number}
+     * @type {number}
      * @default 0
      */
     y: number;
@@ -26,17 +26,9 @@ export default class Point {
      */
     set(x?: number, y?: number): Point;
     /**
-     * return true if the two points are the same
-     * @name equals
-     * @memberof Point
-     * @method
-     * @param {Point} point
-     * @returns {boolean}
-     */
-    /**
-     * return true if this point is equal to the given values
-     * @param {number} x
-     * @param {number} y
+     * return true if this point is equal to the given point
+     * @param {number|Point|Vector2d} x
+     * @param {number} [y]
      * @returns {boolean}
      */
     equals(...args: any[]): boolean;