melonjs 15.2.1 → 15.4.0

package/README.md

@@ -31,7 +31,7 @@ Compatibility
 
 Graphics
 - 2D sprite-based graphic engine
-- Fast WebGL 1 & 2 renderer for desktop and mobile devices with fallback to Canvas rendering
+- [Blazing Fast](https://melonjs.discourse.group/t/melonjs-benchmark/48/4) WebGL renderer for desktop and mobile devices with fallback to Canvas rendering
 - High DPI resolution & Canvas advanced auto scaling
 - Sprite with 9-slice scaling option, and animation management
 - built-in effects such as tinting and masking

package/dist/melonjs.mjs/_virtual/_commonjsHelpers.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license

package/dist/melonjs.mjs/_virtual/earcut.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license

package/dist/melonjs.mjs/_virtual/howler.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license

package/dist/melonjs.mjs/_virtual/index.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license

package/dist/melonjs.mjs/application/application.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
@@ -8,7 +8,7 @@
 import { autoDetectRenderer } from '../video/utils/autodetect.js';
 import CanvasRenderer from '../video/canvas/canvas_renderer.js';
 import { getElement, platform, enableSwipe } from '../system/device.js';
-import { on, emit, GAME_AFTER_UPDATE, GAME_BEFORE_DRAW, GAME_AFTER_DRAW, WINDOW_ONRESIZE, WINDOW_ONORIENTATION_CHANGE, GAME_INIT, GAME_RESET, GAME_BEFORE_UPDATE, GAME_UPDATE } from '../system/event.js';
+import { on, emit, STATE_CHANGE, STATE_RESTART, STATE_RESUME, STAGE_RESET, GAME_AFTER_UPDATE, GAME_BEFORE_DRAW, GAME_AFTER_DRAW, WINDOW_ONRESIZE, WINDOW_ONORIENTATION_CHANGE, GAME_INIT, TICK, BLUR, FOCUS, GAME_RESET, GAME_BEFORE_UPDATE, GAME_UPDATE } from '../system/event.js';
 import { getUriFragment } from '../utils/utils.js';
 import timer from '../system/timer.js';
 import state from '../state/state.js';
@@ -24,21 +24,11 @@ import { WEBGL, CANVAS, AUTO } from '../const.js';
  * An Application is responsible for updating (each frame) all the related object status and draw them.
  * @see game
  */
- class Application {
+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}) {
@@ -98,10 +88,34 @@ import { WEBGL, CANVAS, AUTO } from '../const.js';
 
         /**
          * the given settings used when creating this application
-         * @type {Object}
+         * @type {object}
          */
         this.settings = undefined;
 
+        /**
+         * 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;
+         */
+        this.pauseOnBlur = true;
+
+        /**
+         * Specify whether to unpause this app when gaining back focus
+         * @type {boolean}
+         * @default true
+         */
+        this.resumeOnFocus = true;
+
+        /**
+         * Specify whether to stop this app when losing focus
+         * @type {boolean}
+         * @default false
+         */
+        this.stopOnBlur = false;
+
         // to know when we have to refresh the display
         this.isDirty = true;
 
@@ -133,6 +147,9 @@ import { WEBGL, CANVAS, AUTO } from '../const.js';
 
     /**
      * 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, height, options) {
 
@@ -173,6 +190,12 @@ import { WEBGL, CANVAS, AUTO } from '../const.js';
         this.settings.zoomX = width * this.settings.scale;
         this.settings.zoomY = height * this.settings.scale;
 
+        // identify parent element and/or the html target for resizing
+        this.parentElement = getElement(this.settings.parent);
+        if (typeof this.settings.scaleTarget !== "undefined" ) {
+            this.settings.scaleTarget = getElement(this.settings.scaleTarget);
+        }
+
         if (typeof this.settings.renderer === "number") {
             switch (this.settings.renderer) {
                 case AUTO:
@@ -194,7 +217,6 @@ import { WEBGL, CANVAS, AUTO } from '../const.js';
         on(WINDOW_ONORIENTATION_CHANGE, () => onresize(this), this);
 
         // add our canvas (default to document.body if settings.parent is undefined)
-        this.parentElement = getElement(this.settings.parent);
         this.parentElement.appendChild(this.renderer.getCanvas());
 
         // Mobile browser hacks
@@ -233,6 +255,37 @@ import { WEBGL, CANVAS, AUTO } from '../const.js';
         this.isInitialized = true;
 
         emit(GAME_INIT, this);
+        on(STATE_CHANGE, this.repaint, this);
+        on(STATE_RESTART, this.repaint, this);
+        on(STATE_RESUME, this.repaint, this);
+        on(STAGE_RESET, this.reset, this);
+        on(TICK, (time) => {
+            // update all game objects
+            this.update(time);
+            // render all game objects
+            this.draw();
+        }, this);
+
+
+        // on blur event, pause the current
+        on(BLUR, () => {
+            if (this.stopOnBlur === true) {
+                state.stop(true);
+            }
+            if (this.pauseOnBlur === true) {
+                state.pause(true);
+            }
+        });
+
+        // on focus event, restart or resume the current
+        on(FOCUS, () => {
+            if (this.stopOnBlur === true) {
+                state.restart(true);
+            }
+            if (this.resumeOnFocus === true) {
+                state.resume(true);
+            }
+        });
     }
 
     /**
@@ -297,7 +350,7 @@ import { WEBGL, CANVAS, AUTO } from '../const.js';
 
     /**
      * Returns the parent HTML Element holding the main canvas of this application
-     * @returns {HTMLElement}
+     * @returns {HTMLElement} the parent HTML element
      */
     getParentElement() {
         return this.parentElement;
@@ -313,9 +366,8 @@ import { WEBGL, CANVAS, AUTO } from '../const.js';
     /**
      * 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, stage) {
+    update(time) {
         // handle frame skipping if required
         if ((++this.frameCounter % this.frameRate) === 0) {
             // reset the frame counter
@@ -339,7 +391,8 @@ import { WEBGL, CANVAS, AUTO } from '../const.js';
                 }
 
                 // update all objects (and pass the elapsed time since last frame)
-                this.isDirty = stage.update(this.updateDelta) || this.isDirty;
+                this.isDirty = this.world.update(this.updateDelta);
+                this.isDirty = state.current().update(this.updateDelta) || this.isDirty;
 
                 this.lastUpdate = globalThis.performance.now();
                 this.updateAverageDelta = this.lastUpdate - this.lastUpdateStart;
@@ -358,9 +411,8 @@ import { WEBGL, CANVAS, AUTO } from '../const.js';
 
     /**
      * draw the active scene/stage associated to this game
-     * @param {Stage} stage - the current stage
      */
-    draw(stage) {
+    draw() {
         if (this.renderer.isContextValid === true && (this.isDirty || this.isAlwaysDirty)) {
             // publish notification
             emit(GAME_BEFORE_DRAW, globalThis.performance.now());
@@ -369,7 +421,7 @@ import { WEBGL, CANVAS, AUTO } from '../const.js';
             this.renderer.clear();
 
             // render the stage
-            stage.draw(this.renderer);
+            state.current().draw(this.renderer, this.world);
 
             // set back to flag
             this.isDirty = false;

package/dist/melonjs.mjs/application/header.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
@@ -9,7 +9,7 @@ import { devicePixelRatio, platform, getScreenOrientation, language, hasWebAudio
 
 /**
  * display information
- * @param {Application} game - the game application instance calling this function
+ * @param {Application} app - the game application instance calling this function
  */
 function consoleHeader(app) {
     let renderType = app.renderer.type;

package/dist/melonjs.mjs/application/resize.js

@@ -1,11 +1,11 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
  * @copyright (C) 2011 - 2023 Olivier Biot (AltByte Pte Ltd)
  */
-import { getParentBounds, devicePixelRatio } from '../system/device.js';
+import { getElementBounds, getParentBounds, devicePixelRatio } from '../system/device.js';
 
 /**
  * scale the "displayed" canvas by the given scalar.
@@ -49,7 +49,8 @@ function scale(game, x, y) {
 function onresize(game) {
     let renderer = game.renderer;
     let settings = renderer.settings;
-    let scaleX = 1, scaleY = 1;
+    let scaleX = settings.scale, scaleY = settings.scale;
+    let nodeBounds;
 
     if (settings.autoScale) {
 
@@ -63,8 +64,13 @@ function onresize(game) {
             canvasMaxHeight = parseInt(style.maxHeight, 10) || Infinity;
         }
 
-        // get the maximum canvas size within the parent div containing the canvas container
-        let nodeBounds = getParentBounds(game.getParentElement());
+        if (typeof game.settings.scaleTarget !== "undefined") {
+            // get the bounds of the given scale target
+            nodeBounds = getElementBounds(game.settings.scaleTarget);
+        } else {
+            // get the maximum canvas size within the parent div containing the canvas container
+            nodeBounds = getParentBounds(game.getParentElement());
+        }
 
         let _max_width = Math.min(canvasMaxWidth, nodeBounds.width);
         let _max_height = Math.min(canvasMaxHeight, nodeBounds.height);
@@ -109,13 +115,9 @@ function onresize(game) {
                 scaleX = scaleY = _max_height / settings.height;
             }
         }
-
-        // adjust scaling ratio based on the new scaling ratio
-        scale(game, scaleX, scaleY);
-    } else {
-        // adjust scaling ratio based on the given settings
-        scale(game, settings.scale, settings.scale);
     }
+    // adjust scaling ratio
+    scale(game, scaleX, scaleY);
 }
 
 export { onresize };

package/dist/melonjs.mjs/application/settings.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
@@ -12,6 +12,7 @@ const defaultSettings = {
     autoScale : false,
     scale : 1.0,
     scaleMethod : "manual",
+    scaleTarget : undefined,
     transparent : false,
     premultipliedAlpha: true,
     blendMode : "normal",
@@ -25,4 +26,39 @@ const defaultSettings = {
     legacy : false
 };
 
+/**
+ * Application & Renderer Settings definition.
+ * @typedef {object} Settings
+ * @property {string|HTMLElement} [parent=document.body] - the DOM parent element to hold the canvas in the HTML file
+ * @property {number|Renderer} [renderer=AUTO] - renderer to use (CANVAS, WEBGL, AUTO), or a custom renderer class
+ * @property {number|string} [scale=1.0] - enable scaling of the canvas ('auto' for automatic scaling)
+ * @property {"fit"|"fill-min"|"fill-max"|"flex"|"flex-width"|"flex-height"|"stretch"} [scaleMethod="fit"] - 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>
+ * @property {string|HTMLElement} [scaleTarget] - 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)
+ * @property {boolean} [preferWebGL1=false] - if true the renderer will only use WebGL 1
+ * @property {"sorting"|"z-buffer"} [depthTest="sorting"] - ~Experimental~ the default method to sort object on the z axis in WebGL
+ * @property {("default"|"high-performance"|"low-power")} [powerPreference="default"] - 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.
+ * @property {boolean} [transparent=false] - whether to allow transparent pixels in the front buffer (screen).
+ * @property {boolean} [antiAlias=false] - whether to enable or not video scaling interpolation
+ * @property {boolean} [consoleHeader=true] - whether to display melonJS version and basic device information in the console
+ * @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 {Compositor} [options.compositor] - a custom compositor class (WebGL only)
+ * @see Application
+ * @memberof Application
+ */
+
 export { defaultSettings };

package/dist/melonjs.mjs/audio/audio.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
@@ -75,15 +75,13 @@ let stopOnAudioError = true;
 
 /**
  * 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
@@ -92,7 +90,7 @@ let stopOnAudioError = true;
  *     return;
  * }
  */
- function init(format = "mp3") {
+function init(format = "mp3") {
     // convert it into an array
     audioExts = format.split(",");
 
@@ -102,7 +100,7 @@ let stopOnAudioError = true;
 /**
  * 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
  */
 function hasFormat(codec) {

package/dist/melonjs.mjs/camera/camera2d.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
@@ -29,7 +29,7 @@ let targetV = new Vector2d();
  * a 2D orthographic camera
  * @augments Renderable
  */
- class Camera2d extends Renderable {
+class Camera2d extends Renderable {
     /**
      * @param {number} minX - start x offset
      * @param {number} minY - start y offset
@@ -213,8 +213,8 @@ let targetV = new Vector2d();
      * 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 = 0, y = 0) {
         // reset the initial camera position to 0,0
@@ -371,8 +371,8 @@ let targetV = new Vector2d();
      * @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);
@@ -593,7 +593,7 @@ let targetV = new Vector2d();
      * @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, floating = obj.floating) {
         if (floating === true || obj.floating === true) {
@@ -609,10 +609,9 @@ let targetV = new Vector2d();
      * 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, y, v) {
@@ -631,9 +630,8 @@ let targetV = new Vector2d();
      * @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, y, v) {
         // TODO memoization for one set of coords (multitouch)

package/dist/melonjs.mjs/const.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license

package/dist/melonjs.mjs/entity/entity.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - v15.2.1
+ * melonJS Game Engine - v15.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
@@ -16,7 +16,7 @@ import Body from '../physics/body.js';
  * @augments Renderable
  * @see Renderable
  */
- class Entity extends Renderable {
+class Entity extends Renderable {
     /**
      * @param {number} x - the x coordinates of the entity object
      * @param {number} y - the y coordinates of the entity object
@@ -186,7 +186,7 @@ import Body from '../physics/body.js';
         }
 
         if (absolute === true) {
-            var absPos = this.getAbsolutePosition();
+            let absPos = this.getAbsolutePosition();
             bounds.centerOn(absPos.x + bounds.x + bounds.width / 2,  absPos.y + bounds.y + bounds.height / 2);
         }
 
@@ -198,7 +198,6 @@ import Body from '../physics/body.js';
      * @ignore
      * @name onBodyUpdate
      * @memberof Entity
-     * @param {Body} body - the body whose bounds to update
      */
     onBodyUpdate() {
         this.updateBounds();