melonjs 15.2.1 → 15.4.0

package/dist/types/video/webgl/compositors/quad_compositor.d.ts

@@ -28,7 +28,6 @@ export default class QuadCompositor extends Compositor {
     /**
      * delete the given WebGL texture
      * @param {WebGLTexture} [texture] - a WebGL texture to delete
-     * @param {number} [unit] - Texture unit to delete
      */
     deleteTexture2D(texture?: WebGLTexture | undefined): void;
     /**

package/dist/types/video/webgl/utils/precision.d.ts

@@ -7,7 +7,7 @@ export function setPrecision(src: any, precision: any): any;
 /**
  * return the highest precision format supported by this device for GL Shaders
  * @ignore
- * @param {WebGLRenderingContext} gl
+ * @param {WebGLRenderingContext} gl - the current WebGL context
  * @returns {boolean} "lowp", "mediump", or "highp"
  */
 export function getMaxShaderPrecision(gl: WebGLRenderingContext): boolean;

package/dist/types/video/webgl/webgl_renderer.d.ts

@@ -4,39 +4,6 @@
  * @augments Renderer
  */
 export default class WebGLRenderer 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.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.subPixel=false] - Whether to enable subpixel renderering (performance hit when enabled)
-     * @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 {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 class that implements the compositor API for sprite rendering
-     */
-    constructor(options: {
-        width: number;
-        height: number;
-        canvas?: HTMLCanvasElement | undefined;
-        antiAlias?: boolean | undefined;
-        failIfMajorPerformanceCaveat?: boolean | undefined;
-        transparent?: boolean | undefined;
-        premultipliedAlpha?: boolean | undefined;
-        subPixel?: boolean | undefined;
-        preferWebGL1?: boolean | undefined;
-        depthTest?: boolean | undefined;
-        powerPreference?: string | undefined;
-        zoomX?: number | undefined;
-        zoomY?: number | undefined;
-        compositor?: any;
-    });
     /**
      * The WebGL version used by this renderer (1 or 2)
      * @type {number}
@@ -112,21 +79,21 @@ export default class WebGLRenderer extends Renderer {
      * @type {Map<WebGLCompositor>}
      */
     compositors: Map<WebGLCompositor, any>;
-    depthTest: boolean | undefined;
+    depthTest: any;
     customShader: any;
     cache: TextureCache;
     /**
      * add a new compositor to this renderer
      * @param {Compositor} compositor - a compositor instance
-     * @param {String} name - a name uniquely identifying this compositor
-     * @param {Boolean} [activate=false] - true if the given compositor should be set as the active one
+     * @param {string} name - a name uniquely identifying this compositor
+     * @param {boolean} [activate=false] - true if the given compositor should be set as the active one
      */
     addCompositor(compositor: Compositor, name?: string, activate?: boolean | undefined): void;
     /**
      * set the active compositor for this renderer
-     * @param {String} name - a compositor name
+     * @param {string} name - a compositor name
      * @param {GLShader} [shader] - an optional shader program to be used, instead of the default one, when activating the compositor
-     * @return {Compositor} an instance to the current active compositor
+     * @returns {Compositor} an instance to the current active compositor
      */
     setCompositor(name?: string, shader?: any): Compositor;
     /**
@@ -137,7 +104,7 @@ export default class WebGLRenderer extends Renderer {
      * Create a pattern with the specified repetition
      * @param {HTMLImageElement|SVGImageElement|HTMLVideoElement|HTMLCanvasElement|ImageBitmap|OffscreenCanvas|VideoFrame} image - Source image to be used as the pattern's image
      * @param {string} repeat - Define how the pattern should be repeated
-     * @returns {TextureAtlas}
+     * @returns {TextureAtlas} the patterned texture created
      * @see ImageLayer#repeat
      * @example
      * let tileable   = renderer.createPattern(image, "repeat");
@@ -148,7 +115,7 @@ export default class WebGLRenderer extends Renderer {
     createPattern(image: HTMLImageElement | SVGImageElement | HTMLVideoElement | HTMLCanvasElement | ImageBitmap | OffscreenCanvas | VideoFrame, repeat: string): TextureAtlas;
     /**
      * set/change the current projection matrix (WebGL only)
-     * @param {Matrix3d} matrix
+     * @param {Matrix3d} matrix - the new projection matrix
      */
     setProjection(matrix: Matrix3d): void;
     /**
@@ -196,25 +163,25 @@ export default class WebGLRenderer extends Renderer {
     /**
      * Draw a pattern within the given rectangle.
      * @param {TextureAtlas} pattern - Pattern object
-     * @param {number} x
-     * @param {number} y
-     * @param {number} width
-     * @param {number} height
+     * @param {number} x - x position where to draw the pattern
+     * @param {number} y - y position where to draw the pattern
+     * @param {number} width - width of the pattern
+     * @param {number} height - height of the pattern
      * @see WebGLRenderer#createPattern
      */
     drawPattern(pattern: TextureAtlas, x: number, y: number, width: number, height: number): void;
     /**
      * Returns the WebGL Context object of the given canvas element
-     * @param {HTMLCanvasElement} canvas
+     * @param {HTMLCanvasElement} canvas - the canvas element
      * @param {boolean} [transparent=false] - use true to enable transparency
      * @param {boolean} [depth=false] - use true to enable depth buffer testing
-     * @returns {WebGLRenderingContext}
+     * @returns {WebGLRenderingContext} the WebGL Context object
      */
     getContextGL(canvas: HTMLCanvasElement, transparent?: boolean | undefined, depth?: boolean | undefined): WebGLRenderingContext;
     /**
      * Returns the WebGLContext instance for the renderer
      * return a reference to the system 2d Context
-     * @returns {WebGLRenderingContext}
+     * @returns {WebGLRenderingContext} the current WebGL context
      */
     getContext(): WebGLRenderingContext;
     /**
@@ -230,10 +197,9 @@ export default class WebGLRenderer extends Renderer {
      * <img src="images/screen-blendmode.png" width="510"/> <br>
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation
      * @param {string} [mode="normal"] - blend mode : "normal", "multiply", "lighter", "additive", "screen"
-     * @param {WebGLRenderingContext} [gl]
+     * @param {WebGLRenderingContext} [gl] - a WebGL context
      */
     setBlendMode(mode?: string | undefined, gl?: WebGLRenderingContext | undefined): void;
-    currentBlendMode: any;
     /**
      * restores the canvas context
      */
@@ -249,8 +215,8 @@ export default class WebGLRenderer extends Renderer {
     rotate(angle: number): void;
     /**
      * scales the uniform matrix
-     * @param {number} x
-     * @param {number} y
+     * @param {number} x - x-axis scale
+     * @param {number} y - y-axis scale
      */
     scale(x: number, y: number): void;
     /**
@@ -283,18 +249,18 @@ export default class WebGLRenderer extends Renderer {
      * Stroke an arc at the specified coordinates with given radius, start and end points
      * @param {number} x - arc center point x-axis
      * @param {number} y - arc center point y-axis
-     * @param {number} radius
+     * @param {number} radius - arc radius
      * @param {number} start - start angle in radians
      * @param {number} end - end angle in radians
      * @param {boolean} [antiClockwise=false] - draw arc anti-clockwise
-     * @param {boolean} [fill=false]
+     * @param {boolean} [fill=false] - also fill the shape with the current color if true
      */
     strokeArc(x: number, y: number, radius: number, start: number, end: number, antiClockwise?: boolean | undefined, fill?: boolean | undefined): void;
     /**
      * Fill an arc at the specified coordinates with given radius, start and end points
      * @param {number} x - arc center point x-axis
      * @param {number} y - arc center point y-axis
-     * @param {number} radius
+     * @param {number} radius - arc radius
      * @param {number} start - start angle in radians
      * @param {number} end - end angle in radians
      * @param {boolean} [antiClockwise=false] - draw arc anti-clockwise
@@ -346,52 +312,50 @@ export default class WebGLRenderer extends Renderer {
     fillPolygon(poly: Polygon): void;
     /**
      * Draw a stroke rectangle at the specified coordinates
-     * @param {number} x
-     * @param {number} y
-     * @param {number} width
-     * @param {number} height
+     * @param {number} x - x axis of the coordinate for the rectangle starting point.
+     * @param {number} y - y axis of the coordinate for the rectangle starting point.
+     * @param {number} width - The rectangle's width.
+     * @param {number} height - The rectangle's height.
      * @param {boolean} [fill=false] - also fill the shape with the current color if true
      */
     strokeRect(x: number, y: number, width: number, height: number, fill?: boolean | undefined): void;
     /**
      * Draw a filled rectangle at the specified coordinates
-     * @param {number} x
-     * @param {number} y
-     * @param {number} width
-     * @param {number} height
+     * @param {number} x - x axis of the coordinate for the rectangle starting point.
+     * @param {number} y - y axis of the coordinate for the rectangle starting point.
+     * @param {number} width - The rectangle's width.
+     * @param {number} height - The rectangle's height.
      */
     fillRect(x: number, y: number, width: number, height: number): void;
     /**
      * Stroke a rounded rectangle at the specified coordinates
-     * @param {number} x
-     * @param {number} y
-     * @param {number} width
-     * @param {number} height
-     * @param {number} radius
+     * @param {number} x - x axis of the coordinate for the rounded rectangle starting point.
+     * @param {number} y - y axis of the coordinate for the rounded rectangle starting point.
+     * @param {number} width - The rounded rectangle's width.
+     * @param {number} height - The rounded rectangle's height.
+     * @param {number} radius - The rounded corner's radius.
      * @param {boolean} [fill=false] - also fill the shape with the current color if true
      */
     strokeRoundRect(x: number, y: number, width: number, height: number, radius: number, fill?: boolean | undefined): void;
     /**
      * Draw a rounded filled rectangle at the specified coordinates
-     * @param {number} x
-     * @param {number} y
-     * @param {number} width
-     * @param {number} height
-     * @param {number} radius
+     * @param {number} x - x axis of the coordinate for the rounded rectangle starting point.
+     * @param {number} y - y axis of the coordinate for the rounded rectangle starting point.
+     * @param {number} width - The rounded rectangle's width.
+     * @param {number} height - The rounded rectangle's height.
+     * @param {number} radius - The rounded corner's radius.
      */
     fillRoundRect(x: number, y: number, width: number, height: number, radius: number): void;
     /**
      * Stroke a Point at the specified coordinates
-     * @param {number} x
-     * @param {number} y
+     * @param {number} x - x axis of the coordinate for the point.
+     * @param {number} y - y axis of the coordinate for the point.
      */
     strokePoint(x: number, y: number): void;
     /**
      * Draw a a point at the specified coordinates
-     * @param {number} x
-     * @param {number} y
-     * @param {number} width
-     * @param {number} height
+     * @param {number} x - x axis of the coordinate for the point.
+     * @param {number} y - y axis of the coordinate for the point.
      */
     fillPoint(x: number, y: number): void;
     /**
@@ -407,8 +371,8 @@ export default class WebGLRenderer extends Renderer {
     transform(mat2d: Matrix2d): void;
     /**
      * Translates the uniform matrix by the given coordinates
-     * @param {number} x
-     * @param {number} y
+     * @param {number} x - x axis of the coordinate for the translation.
+     * @param {number} y - y axis of the coordinate for the translation.
      */
     translate(x: number, y: number): void;
     /**
@@ -417,10 +381,10 @@ export default class WebGLRenderer extends Renderer {
      * You can however save the current region using the save(),
      * and restore it (with the restore() method) any time in the future.
      * (<u>this is an experimental feature !</u>)
-     * @param {number} x
-     * @param {number} y
-     * @param {number} width
-     * @param {number} height
+     * @param {number} x - x axis of the coordinate for the upper-left corner of the rectangle to start clipping from.
+     * @param {number} y - y axis of the coordinate for the upper-left corner of the rectangle to start clipping from.
+     * @param {number} width - the width of the rectangle to start clipping from.
+     * @param {number} height - the height of the rectangle to start clipping from.
      */
     clipRect(x: number, y: number, width: number, height: number): void;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melonjs",
-  "version": "15.2.1",
+  "version": "15.4.0",
   "description": "melonJS Game Engine",
   "homepage": "http://www.melonjs.org/",
   "type": "module",
@@ -53,37 +53,37 @@
   ],
   "dependencies": {
     "@teppeis/multimaps": "^3.0.0",
-    "core-js": "^3.30.2",
+    "core-js": "^3.31.0",
     "earcut": "2.2.4",
     "eventemitter3": "^5.0.1",
     "howler": "2.2.3"
   },
   "devDependencies": {
-    "@babel/eslint-parser": "^7.21.8",
-    "@babel/plugin-syntax-import-assertions": "^7.20.0",
-    "@fastify/static": "^6.10.1",
+    "@babel/eslint-parser": "^7.22.5",
+    "@babel/plugin-syntax-import-assertions": "^7.22.5",
+    "@fastify/static": "^6.10.2",
     "@melonjs/webdoc-theme": "^1.1.1",
-    "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-commonjs": "^25.0.2",
     "@rollup/plugin-image": "^3.0.2",
-    "@rollup/plugin-node-resolve": "^15.0.2",
+    "@rollup/plugin-node-resolve": "^15.1.0",
     "@rollup/plugin-replace": "^5.0.2",
     "@webdoc/cli": "^2.2.0",
-    "chromedriver": "^113.0.0",
+    "chromedriver": "^114.0.2",
     "cross-env": "^7.0.3",
     "del-cli": "^5.0.0",
-    "eslint": "^8.40.0",
-    "eslint-plugin-jsdoc": "^44.2.3",
+    "eslint": "^8.43.0",
+    "eslint-plugin-jsdoc": "^46.2.6",
     "expect": "^29.5.0",
     "expect-mocha-image-snapshot": "^3.0.13",
-    "fastify": "^4.17.0",
+    "fastify": "^4.18.0",
     "mocha": "^10.2.0",
     "npm-self-link": "^1.1.7",
-    "puppeteer": "^20.2.0",
-    "rollup": "^3.21.7",
+    "puppeteer": "^20.7.3",
+    "rollup": "^3.25.1",
     "rollup-plugin-bundle-size": "^1.0.3",
     "rollup-plugin-string": "^3.0.0",
-    "terser": "^5.17.3",
-    "typescript": "^5.0.4"
+    "terser": "^5.18.1",
+    "typescript": "^5.1.3"
   },
   "scripts": {
     "build": "npm run lint && rollup -c --silent",

package/src/application/application.js

@@ -17,21 +17,11 @@ import { CANVAS, WEBGL, AUTO } from "../const.js";
  * An Application is responsible for updating (each frame) all the related object status and draw them.
  * @see game
  */
- export default class Application {
+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}) {
@@ -91,10 +81,34 @@ import { CANVAS, WEBGL, 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;
 
@@ -126,6 +140,9 @@ import { CANVAS, WEBGL, 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) {
 
@@ -166,6 +183,12 @@ import { CANVAS, WEBGL, 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 = device.getElement(this.settings.parent);
+        if (typeof this.settings.scaleTarget !== "undefined" ) {
+            this.settings.scaleTarget = device.getElement(this.settings.scaleTarget);
+        }
+
         if (typeof this.settings.renderer === "number") {
             switch (this.settings.renderer) {
                 case AUTO:
@@ -187,7 +210,6 @@ import { CANVAS, WEBGL, AUTO } from "../const.js";
         event.on(event.WINDOW_ONORIENTATION_CHANGE, () => onresize(this), this);
 
         // add our canvas (default to document.body if settings.parent is undefined)
-        this.parentElement = device.getElement(this.settings.parent);
         this.parentElement.appendChild(this.renderer.getCanvas());
 
         // Mobile browser hacks
@@ -226,6 +248,37 @@ import { CANVAS, WEBGL, AUTO } from "../const.js";
         this.isInitialized = true;
 
         event.emit(event.GAME_INIT, this);
+        event.on(event.STATE_CHANGE, this.repaint, this);
+        event.on(event.STATE_RESTART, this.repaint, this);
+        event.on(event.STATE_RESUME, this.repaint, this);
+        event.on(event.STAGE_RESET, this.reset, this);
+        event.on(event.TICK, (time) => {
+            // update all game objects
+            this.update(time);
+            // render all game objects
+            this.draw();
+        }, this);
+
+
+        // on blur event, pause the current
+        event.on(event.BLUR, () => {
+            if (this.stopOnBlur === true) {
+                state.stop(true);
+            }
+            if (this.pauseOnBlur === true) {
+                state.pause(true);
+            }
+        });
+
+        // on focus event, restart or resume the current
+        event.on(event.FOCUS, () => {
+            if (this.stopOnBlur === true) {
+                state.restart(true);
+            }
+            if (this.resumeOnFocus === true) {
+                state.resume(true);
+            }
+        });
     }
 
     /**
@@ -290,7 +343,7 @@ import { CANVAS, WEBGL, 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;
@@ -306,9 +359,8 @@ import { CANVAS, WEBGL, 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
@@ -332,7 +384,8 @@ import { CANVAS, WEBGL, 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;
@@ -351,9 +404,8 @@ import { CANVAS, WEBGL, 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
             event.emit(event.GAME_BEFORE_DRAW, globalThis.performance.now());
@@ -362,7 +414,7 @@ import { CANVAS, WEBGL, 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/src/application/header.js

@@ -2,7 +2,7 @@ import * as device from "../system/device";
 
 /**
  * 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) {
     let renderType = app.renderer.type;

package/src/application/resize.js

@@ -42,7 +42,8 @@ function scale(game, x, y) {
 export 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) {
 
@@ -56,8 +57,13 @@ export function onresize(game) {
             canvasMaxHeight = parseInt(style.maxHeight, 10) || Infinity;
         }
 
-        // get the maximum canvas size within the parent div containing the canvas container
-        let nodeBounds = device.getParentBounds(game.getParentElement());
+        if (typeof game.settings.scaleTarget !== "undefined") {
+            // get the bounds of the given scale target
+            nodeBounds = device.getElementBounds(game.settings.scaleTarget);
+        } else {
+            // get the maximum canvas size within the parent div containing the canvas container
+            nodeBounds = device.getParentBounds(game.getParentElement());
+        }
 
         let _max_width = Math.min(canvasMaxWidth, nodeBounds.width);
         let _max_height = Math.min(canvasMaxHeight, nodeBounds.height);
@@ -102,11 +108,7 @@ export 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);
 }

package/src/application/settings.js

@@ -5,6 +5,7 @@ export const defaultSettings = {
     autoScale : false,
     scale : 1.0,
     scaleMethod : "manual",
+    scaleTarget : undefined,
     transparent : false,
     premultipliedAlpha: true,
     blendMode : "normal",
@@ -17,3 +18,38 @@ export const defaultSettings = {
     consoleHeader : true,
     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
+ */

package/src/audio/audio.js

@@ -76,15 +76,13 @@ export 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
@@ -93,7 +91,7 @@ export let stopOnAudioError = true;
  *     return;
  * }
  */
- export function init(format = "mp3") {
+export function init(format = "mp3") {
     // convert it into an array
     audioExts = format.split(",");
 
@@ -103,7 +101,7 @@ export 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
  */
 export function hasFormat(codec) {