melonjs 15.2.1 → 15.4.0

package/src/state/state.js

@@ -2,7 +2,6 @@ import { pauseTrack, resumeTrack } from "./../audio/audio.js";
 import * as fctUtil from "./../utils/function.js";
 import * as event from "./../system/event.js";
 import { game } from "../index.js";
-import * as device from "./../system/device.js";
 import Stage from "./../state/stage.js";
 import DefaultLoadingScreen from "./../loader/loadingscreen.js";
 
@@ -72,11 +71,7 @@ function _pauseRunLoop() {
  * @ignore
  */
 function _renderFrame(time) {
-    let stage = _stages[_state].stage;
-    // update all game objects
-    game.update(time, stage);
-    // render all game objects
-    game.draw(stage);
+    event.emit(event.TICK, time);
     // schedule the next frame update
     if (_animFrameId !== -1) {
         _animFrameId = globalThis.requestAnimationFrame(_renderFrame);
@@ -125,9 +120,6 @@ function _switchState(state) {
         if (_onSwitchComplete) {
             _onSwitchComplete();
         }
-
-        // force repaint
-        game.repaint();
     }
 }
 
@@ -141,54 +133,6 @@ event.on(event.BOOT, () => {
     event.on(event.VIDEO_INIT, () => {
         state.change(state.DEFAULT, true);
     });
-
-    if (typeof globalThis.addEventListener === "function") {
-        // set pause/stop action on losing focus
-        globalThis.addEventListener("blur", () => {
-            if (device.stopOnBlur) {
-                state.stop(true);
-            }
-            if (device.pauseOnBlur) {
-                state.pause(true);
-            }
-        }, false);
-        // set restart/resume action on gaining focus
-        globalThis.addEventListener("focus", () => {
-            if (device.stopOnBlur) {
-                state.restart(true);
-            }
-            if (device.resumeOnFocus) {
-                state.resume(true);
-            }
-            // force focus if autofocus is on
-            if (device.autoFocus) {
-                device.focus();
-            }
-        }, false);
-    }
-
-    if (typeof globalThis.document !== "undefined") {
-        if (typeof globalThis.document.addEventListener === "function") {
-            // register on the visibilitychange event if supported
-            globalThis.document.addEventListener("visibilitychange", () => {
-                if (globalThis.document.visibilityState === "visible") {
-                    if (device.stopOnBlur) {
-                        state.restart(true);
-                    }
-                    if (device.resumeOnFocus) {
-                        state.resume(true);
-                    }
-                } else {
-                    if (device.stopOnBlur) {
-                        state.stop(true);
-                    }
-                    if (device.pauseOnBlur) {
-                        state.pause(true);
-                    }
-                }
-            }, false );
-        }
-    }
 });
 
 /**
@@ -273,7 +217,7 @@ let state = {
      * default state ID for the default Stage
      * (the default stage is the one running as soon as melonJS is started)
      * @constant
-     * @name SETTINGS
+     * @name DEFAULT
      * @memberof state
      */
     DEFAULT : 9,
@@ -361,9 +305,6 @@ let state = {
             // calculate the elpased time
             _pauseTime = globalThis.performance.now() - _pauseTime;
 
-            // force repaint
-            game.repaint();
-
             // publish the restart notification
             event.emit(event.STATE_RESTART, _pauseTime);
         }

package/src/system/device.js

@@ -1,5 +1,6 @@
 import { getParent } from "./../video/video.js";
 import save from "./save.js";
+import * as event from "./../system/event.js";
 import { prefixed } from "./../utils/agent.js";
 import { DOMContentLoaded } from "./dom.js";
 import * as device_platform from "./platform.js"; // export * as name1 from …; // ECMAScript® 2020
@@ -45,6 +46,7 @@ function hasOffscreenCanvas() {
 
 /**
  * used by [un]watchAccelerometer()
+ * @ignore
  */
 function onDeviceMotion(e) {
     // Accelerometer information
@@ -55,6 +57,7 @@ function onDeviceMotion(e) {
 
 /**
  * used by [un]watchDeviceOrientation()
+ * @ignore
  */
 export function onDeviceRotate(e) {
     gamma = e.gamma;
@@ -347,6 +350,8 @@ export let alpha = 0;
  * Specify whether to pause the game when losing focus
  * @name pauseOnBlur
  * @memberof device
+ * @deprecated since 15.4.0
+ * @see Application.pauseOnBlur
  * @type {boolean}
  * @public
  * @default true
@@ -357,6 +362,8 @@ export let pauseOnBlur = true;
  * Specify whether to unpause the game when gaining focus
  * @name resumeOnFocus
  * @memberof device
+ * @deprecated since 15.4.0
+ * @see Application.resumeOnFocus
  * @type {boolean}
  * @public
  * @default true
@@ -364,25 +371,27 @@ export let pauseOnBlur = true;
 export let resumeOnFocus = true;
 
 /**
- * Specify whether to automatically bring the window to the front
- * @name autoFocus
+ * Specify whether to stop the game when losing focus or not.
+ * The engine restarts on focus if this is enabled.
+ * @name stopOnBlur
  * @memberof device
+ * @deprecated since 15.4.0
+ * @see Application.stopOnBlur
  * @type {boolean}
  * @public
- * @default true
+ * @default false
  */
-export let autoFocus = true;
+export let stopOnBlur = false;
 
 /**
- * Specify whether to stop the game when losing focus or not.
- * The engine restarts on focus if this is enabled.
- * @name stopOnBlur
+ * Specify whether to automatically bring the window to the front
+ * @name autoFocus
  * @memberof device
  * @type {boolean}
  * @public
- * @default false
+ * @default true
  */
-export let stopOnBlur = false;
+export let autoFocus = true;
 
 /**
 * specify a function to execute when the Device is fully loaded and ready
@@ -430,6 +439,38 @@ export let stopOnBlur = false;
 * });
 */
 export function onReady(fn) {
+    // register on blur/focus and visibility event handlers
+    if (typeof globalThis.addEventListener === "function") {
+        // set pause/stop action on losing focus
+        globalThis.addEventListener("blur", () => {
+            event.emit(event.BLUR);
+        }, false);
+        // set restart/resume action on gaining focus
+        globalThis.addEventListener("focus", () => {
+            event.emit(event.FOCUS);
+            // force focus if autofocus is on
+            if (autoFocus === true) {
+                focus();
+            }
+        }, false);
+    }
+    if (typeof globalThis.document !== "undefined") {
+        if (typeof globalThis.document.addEventListener === "function") {
+            // register on the visibilitychange event if supported
+            globalThis.document.addEventListener("visibilitychange", () => {
+                if (globalThis.document.visibilityState === "visible") {
+                    event.emit(event.FOCUS);
+                    // force focus if autofocus is on
+                    if (autoFocus === true) {
+                        focus();
+                    }
+                } else {
+                    event.emit(event.BLUR);
+                }
+            }, false );
+        }
+    }
+    // call the supplied function
     DOMContentLoaded(fn);
 }
 

package/src/system/event.js

@@ -30,6 +30,39 @@ export const DOM_READY = "dom_ready";
  */
 export const BOOT = "me.boot";
 
+/**
+ * event generated when the system update the engine and the renderer by one step
+ * @public
+ * @constant
+ * @type {string}
+ * @name TICK
+ * @memberof event
+ * @see event.on
+ */
+export const TICK = "me.tick";
+
+/**
+ * event generated when the main browser or window is losing focus
+ * @public
+ * @constant
+ * @type {string}
+ * @name BLUR
+ * @memberof event
+ * @see event.on
+ */
+export const BLUR = "me.blur";
+
+/**
+ * event generated when the main browser or window is gaining back focus
+ * @public
+ * @constant
+ * @type {string}
+ * @name FOCUS
+ * @memberof event
+ * @see event.on
+ */
+export const FOCUS = "me.focus";
+
 /**
  * event when the game is paused <br>
  * Data passed : none <br>
@@ -89,6 +122,17 @@ export const STATE_RESTART = "me.state.onRestart";
  */
 export const STATE_CHANGE = "me.state.onChange";
 
+/**
+ * event for when a stage is resetted
+ * @public
+ * @constant
+ * @type {string}
+ * @name STAGE_RESET
+ * @memberof event
+ * @see event.on
+*/
+export const STAGE_RESET = "me.stage.onReset";
+
 /**
  * event for when the video is initialized<br>
  * Data passed : none <br>

package/src/system/platform.js

@@ -1,21 +1,21 @@
- /**
-  * The device platform type
-  * @namespace platform
-  * @memberof device
-  * @property {string} ua the user agent string for the current device
-  * @property {boolean} iOS `true` if the device is an iOS platform
-  * @property {boolean} android `true` if the device is an Android platform
-  * @property {boolean} android2 `true` if the device is an Android 2.x platform
-  * @property {boolean} linux `true` if the device is a Linux platform
-  * @property {boolean} chromeOS `true` if the device is running on ChromeOS.
-  * @property {boolean} wp `true` if the device is a Windows Phone platform
-  * @property {boolean} BlackBerry`true` if the device is a BlackBerry platform
-  * @property {boolean} Kindle`true` if the device is a Kindle platform
-  * @property {boolean} ejecta `true` if running under Ejecta
-  * @property {boolean} isWeixin `true` if running under Wechat
-  * @property {boolean} nodeJS `true` if running under node.js
-  * @property {boolean} isMobile `true` if a mobile device
-  */
+/**
+* The device platform type
+* @namespace platform
+* @memberof device
+* @property {string} ua the user agent string for the current device
+* @property {boolean} iOS `true` if the device is an iOS platform
+* @property {boolean} android `true` if the device is an Android platform
+* @property {boolean} android2 `true` if the device is an Android 2.x platform
+* @property {boolean} linux `true` if the device is a Linux platform
+* @property {boolean} chromeOS `true` if the device is running on ChromeOS.
+* @property {boolean} wp `true` if the device is a Windows Phone platform
+* @property {boolean} BlackBerry`true` if the device is a BlackBerry platform
+* @property {boolean} Kindle`true` if the device is a Kindle platform
+* @property {boolean} ejecta `true` if running under Ejecta
+* @property {boolean} isWeixin `true` if running under Wechat
+* @property {boolean} nodeJS `true` if running under node.js
+* @property {boolean} isMobile `true` if a mobile device
+*/
 
 export const ua = typeof globalThis.navigator !== "undefined" ? globalThis.navigator.userAgent : "";
 export const iOS = /iPhone|iPad|iPod/i.test(ua);

package/src/system/pooling.js

@@ -38,15 +38,15 @@ class ObjectPool {
      * me.pool.register("cherrysprite", Cherry, true);
      */
     register(className, classObj, recycling = false) {
-         if (typeof (classObj) !== "undefined") {
-             this.objectClass[className] = {
-                 "class" : classObj,
-                 "pool" : (recycling ? [] : undefined)
-             };
-         } else {
-             throw new Error("Cannot register object '" + className + "', invalid class");
-         }
-     }
+        if (typeof (classObj) !== "undefined") {
+            this.objectClass[className] = {
+                "class" : classObj,
+                "pool" : (recycling ? [] : undefined)
+            };
+        } else {
+            throw new Error("Cannot register object '" + className + "', invalid class");
+        }
+    }
 
     /**
      * Pull a new instance of the requested object (if added into the object pool)

package/src/tweens/tween.js

@@ -23,7 +23,7 @@ import { Interpolation } from "./interpolation.js";
  * author lechecacharro<br>
  * author Josh Faul / http://jocafa.com/
  */
- export default class Tween {
+export default class Tween {
 
     /**
      * @param {object} object - object on which to apply the tween

package/src/utils/function.js

@@ -23,8 +23,7 @@ export function defer(func, thisArg, ...args) {
 }
 
 /**
- * returns a function that, when invoked will only be triggered at most
- * once during a given window of time
+ * returns a function that, when invoked will only be triggered at most once during a given window of time
  * @public
  * @memberof utils.function
  * @name throttle

package/src/video/canvas/canvas_renderer.js

@@ -12,18 +12,9 @@ import * as event from "./../../system/event.js";
  * a canvas renderer object
  * @augments Renderer
  */
- export default class CanvasRenderer extends Renderer {
-    /**
-     * @param {object} options - The renderer parameters
-     * @param {number} options.width - The width of the canvas without scaling
-     * @param {number} options.height - The height of the canvas without scaling
-     * @param {HTMLCanvasElement} [options.canvas] - The html canvas to draw to on screen
-     * @param {boolean} [options.antiAlias=false] - Whether to enable anti-aliasing
-     * @param {boolean} [options.transparent=false] - Whether to enable transparency on the canvas (performance hit when enabled)
-     * @param {boolean} [options.subPixel=false] - Whether to enable subpixel renderering (performance hit when enabled)
-     * @param {boolean} [options.textureSeamFix=true] - enable the texture seam fix when rendering Tile when antiAlias is off for the canvasRenderer
-     * @param {number} [options.zoomX=width] - The actual width of the canvas with scaling applied
-     * @param {number} [options.zoomY=height] - The actual height of the canvas with scaling applied
+export default class CanvasRenderer extends Renderer {
+    /**
+     * @param {Application.Settings} [options] - optional parameters for the renderer
      */
     constructor(options) {
         // parent constructor
@@ -536,11 +527,7 @@ import * as event from "./../../system/event.js";
     setColor(color) {
         let context = this.getContext();
         context.strokeStyle =
-        context.fillStyle = (
-            color instanceof Color ?
-            color.toRGBA() :
-            color
-        );
+        context.fillStyle = (color instanceof Color ? color.toRGBA() : color);
     }
 
     /**

package/src/video/renderer.js

@@ -18,22 +18,9 @@ import Point from "../geometries/point.js";
  * @classdesc
  * a base renderer object
  */
- export default class Renderer {
+export default class Renderer {
     /**
-     * @param {object} options - The renderer parameters
-     * @param {number} options.width - The width of the canvas without scaling
-     * @param {number} options.height - The height of the canvas without scaling
-     * @param {HTMLCanvasElement} [options.canvas] - The html canvas to draw to on screen
-     * @param {boolean} [options.antiAlias=false] - Whether to enable anti-aliasing, use false (default) for a pixelated effect.
-     * @param {boolean} [options.failIfMajorPerformanceCaveat=true] - If true, the renderer will switch to CANVAS mode if the performances of a WebGL context would be dramatically lower than that of a native application making equivalent OpenGL calls.
-     * @param {boolean} [options.transparent=false] - Whether to enable transparency on the canvas
-     * @param {boolean} [options.premultipliedAlpha=true] - in WebGL, whether the renderer will assume that colors have premultiplied alpha when canvas transparency is enabled
-     * @param {boolean} [options.blendMode="normal"] - the default blend mode to use ("normal", "multiply")
-     * @param {boolean} [options.depthBuffer="sorting"] - ~Experimental~ the default method to sort object on the z axis in WebGL ("sorting", "z-buffer")
-     * @param {boolean} [options.subPixel=false] - Whether to enable subpixel rendering (performance hit when enabled)
-     * @param {boolean} [options.verbose=false] - Enable the verbose mode that provides additional details as to what the renderer is doing
-     * @param {number} [options.zoomX=width] - The actual width of the canvas with scaling applied
-     * @param {number} [options.zoomY=height] - The actual height of the canvas with scaling applied
+     * @param {Application.Settings} [options] - optional parameters for the renderer
      */
     constructor(options) {
         /**
@@ -46,7 +33,7 @@ import Point from "../geometries/point.js";
         /**
          * the requested video size ratio
          * @public
-         * @type {Number}
+         * @type {number}
          */
         this.designRatio = this.settings.width / this.settings.height;
 
@@ -203,7 +190,7 @@ import Point from "../geometries/point.js";
         }
 
         let _context = canvas.getContext("2d", {
-                "alpha" : transparent
+            "alpha" : transparent
         });
 
         if (!_context.canvas) {
@@ -419,10 +406,10 @@ import Point from "../geometries/point.js";
 
     /**
      * creates a Blob object representing the last rendered frame
-     * @param {Object} [options] - An object with the following properties:
-     * @param {String} [options.type="image/png"] - A string indicating the image format
-     * @param {Number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
-     * @return {Promise} A Promise returning a Blob object representing the last rendered frame
+     * @param {object} [options] - An object with the following properties:
+     * @param {string} [options.type="image/png"] - A string indicating the image format
+     * @param {number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
+     * @returns {Promise} A Promise returning a Blob object representing the last rendered frame
      * @example
      * renderer.convertToBlob().then((blob) => console.log(blob));
      */
@@ -439,10 +426,10 @@ import Point from "../geometries/point.js";
     /**
      * creates an ImageBitmap object of the last frame rendered
      * (not supported by standard Canvas)
-     * @param {Object} [options] - An object with the following properties:
-     * @param {String} [options.type="image/png"] - A string indicating the image format
-     * @param {Number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
-     * @return {Promise} A Promise returning an ImageBitmap.
+     * @param {object} [options] - An object with the following properties:
+     * @param {string} [options.type="image/png"] - A string indicating the image format
+     * @param {number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
+     * @returns {Promise} A Promise returning an ImageBitmap.
      * @example
      * renderer.transferToImageBitmap().then((image) => console.log(image));
      */
@@ -460,10 +447,10 @@ import Point from "../geometries/point.js";
 
     /**
      * returns a data URL containing a representation of the last frame rendered
-     * @param {Object} [options] - An object with the following properties:
-     * @param {String} [options.type="image/png"] - A string indicating the image format
-     * @param {Number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
-     * @return {Promise} A Promise returning a string containing the requested data URL.
+     * @param {object} [options] - An object with the following properties:
+     * @param {string} [options.type="image/png"] - A string indicating the image format
+     * @param {number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
+     * @returns {Promise} A Promise returning a string containing the requested data URL.
      * @example
      * renderer.toDataURL().then((dataURL) => console.log(dataURL));
      */

package/src/video/texture/atlas.js

@@ -10,18 +10,18 @@ import { ETA } from "./../../math/math.js";
  * @ignore
  */
 export function createAtlas(width, height, name = "default", repeat = "no-repeat") {
-   return {
-       "meta" : {
-           "app" : "melonJS",
-           "size" : { "w" : width, "h" : height },
-           "repeat" : repeat,
-           "image" : "default"
-       },
-       "frames" : [{
-           "filename" : name,
-           "frame" : { "x" : 0, "y" : 0, "w" : width, "h" : height }
-       }]
-   };
+    return {
+        "meta" : {
+            "app" : "melonJS",
+            "size" : { "w" : width, "h" : height },
+            "repeat" : repeat,
+            "image" : "default"
+        },
+        "frames" : [{
+            "filename" : name,
+            "frame" : { "x" : 0, "y" : 0, "w" : width, "h" : height }
+        }]
+    };
 }
 
 /**

package/src/video/texture/canvas_texture.js

@@ -62,7 +62,7 @@ class CanvasTexture {
 
     /**
      * enable/disable image smoothing (scaling interpolation)
-     * @param {boolean} [enable=false]
+     * @param {boolean} [enable=false] - whether to enable or not image smoothing (scaling interpolation)
      */
     setAntiAlias(enable = false) {
         let canvas = this.canvas;
@@ -105,7 +105,7 @@ class CanvasTexture {
      * @param {number} y - The y-axis coordinate of the top-left corner of the rectangle from which the ImageData will be extracted
      * @param {number} width - The width of the rectangle from which the ImageData will be extracted. Positive values are to the right, and negative to the left
      * @param {number} height - The height of the rectangle from which the ImageData will be extracted. Positive values are down, and negative are up
-     * @return {ImageData} The ImageData extracted from this CanvasTexture.
+     * @returns {ImageData} The ImageData extracted from this CanvasTexture.
      */
     getImageData(x, y, width, height) {
         // clamp values
@@ -119,10 +119,10 @@ class CanvasTexture {
 
     /**
      * creates a Blob object representing the image contained in this canvas texture
-     * @param {Object} [options] - An object with the following properties:
-     * @param {String} [options.type="image/png"] - A string indicating the image format
-     * @param {Number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
-     * @return {Promise} A Promise returning a Blob object representing the image contained in this canvas texture
+     * @param {object} [options] - An object with the following properties:
+     * @param {string} [options.type="image/png"] - A string indicating the image format
+     * @param {number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
+     * @returns {Promise} A Promise returning a Blob object representing the image contained in this canvas texture
      * @example
      * canvasTexture.convertToBlob().then((blob) => console.log(blob));
      */
@@ -140,10 +140,10 @@ class CanvasTexture {
 
     /**
      * creates an ImageBitmap object from the most recently rendered image of this canvas texture
-     * @param {Object} [options] - An object with the following properties:
-     * @param {String} [options.type="image/png"] - A string indicating the image format
-     * @param {Number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
-     * @return {Promise} A Promise returning an ImageBitmap.
+     * @param {object} [options] - An object with the following properties:
+     * @param {string} [options.type="image/png"] - A string indicating the image format
+     * @param {number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
+     * @returns {Promise} A Promise returning an ImageBitmap.
      * @example
      * canvasTexture.transferToImageBitmap().then((bitmap) => console.log(bitmap));
      */
@@ -164,10 +164,10 @@ class CanvasTexture {
     /**
      * returns a data URL containing a representation of the most recently rendered image of this canvas texture
      * (not supported by OffscreenCanvas)
-     * @param {Object} [options] - An object with the following properties:
-     * @param {String} [options.type="image/png"] - A string indicating the image format
-     * @param {Number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
-     * @return {Promise} A Promise returning a string containing the requested data URL.
+     * @param {object} [options] - An object with the following properties:
+     * @param {string} [options.type="image/png"] - A string indicating the image format
+     * @param {number} [options.quality] - A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
+     * @returns {Promise} A Promise returning a string containing the requested data URL.
      * @example
      * renderer.toDataURL().then((dataURL) => console.log(dataURL));
      */