melonjs 14.2.0 → 14.4.0

package/src/application/application.js

@@ -1,8 +1,15 @@
-import { renderer } from "./../video/video.js";
+import { autoDetectRenderer } from "../video/utils/autodetect.js";
+import CanvasRenderer from "./../video/canvas/canvas_renderer.js";
+import * as device from "./../system/device.js";
 import * as event from "./../system/event.js";
+import utils from "./../utils/utils.js";
 import timer from "./../system/timer.js";
 import state from "./../state/state.js";
 import World from "./../physics/world.js";
+import { onresize } from "./resize.js";
+import { defaultSettings } from "./settings.js";
+import { consoleHeader } from "./header.js";
+import { CANVAS, WEBGL, AUTO } from "../const.js";
 
 /**
  * @classdesc
@@ -11,7 +18,26 @@ import World from "./../physics/world.js";
  * @see game
  */
  export default class Application {
-    constructor() {
+    /**
+     * @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 {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
+     * @throws Will throw an exception if it fails to instantiate a renderer
+     * @example
+     * var my game = new Application(640, 480, {renderer: me.video.AUTO}) {
+     *     ....
+     * }
+     */
+    constructor(width, height, options) {
 
         /**
          * the parent HTML element holding the main canvas of this application
@@ -19,6 +45,12 @@ import World from "./../physics/world.js";
          */
         this.parentElement = undefined;
 
+        /**
+         * a reference to the active Canvas or WebGL active renderer renderer
+         * @type {CanvasRenderer|WebGLRenderer}
+         */
+        this.renderer = undefined;
+
         /**
          * the active stage "default" camera
          * @type {Camera2d}
@@ -64,6 +96,12 @@ import World from "./../physics/world.js";
          */
         this.isInitialized = false;
 
+        /**
+         * the given settings used when creating this application
+         * @type {Object}
+         */
+        this.settings = undefined;
+
         // to know when we have to refresh the display
         this.isDirty = true;
 
@@ -85,18 +123,111 @@ import World from "./../physics/world.js";
         this.updateDelta = 0;
         this.lastUpdateStart = null;
         this.updateAverageDelta = 0;
+
+        // when using the default game application, legacy is set to true
+        // and init is called through the legacy video.init() call
+        if (options.legacy !== true) {
+            this.init(width, height, options);
+        }
     }
 
     /**
      * init the game instance (create a physic world, update starting time, etc..)
      */
-    init() {
+    init(width, height, options) {
+
+        this.settings = Object.assign(defaultSettings, options || {});
+
+        // sanitize potential given parameters
+        this.settings.width = width;
+        this.settings.height = height;
+        this.settings.transparent = !!(this.settings.transparent);
+        this.settings.antiAlias = !!(this.settings.antiAlias);
+        this.settings.failIfMajorPerformanceCaveat = !!(this.settings.failIfMajorPerformanceCaveat);
+        this.settings.subPixel = !!(this.settings.subPixel);
+        this.settings.verbose = !!(this.settings.verbose);
+        if (this.settings.scaleMethod.search(/^(fill-(min|max)|fit|flex(-(width|height))?|stretch)$/) !== -1) {
+            this.settings.autoScale = (this.settings.scale === "auto") || true;
+        } else {
+            // default scaling method
+            this.settings.scaleMethod = "fit";
+            this.settings.autoScale = (this.settings.scale === "auto") || false;
+        }
+
+        // override renderer settings if &webgl or &canvas is defined in the URL
+        var uriFragment = utils.getUriFragment();
+        if (uriFragment.webgl === true || uriFragment.webgl1 === true || uriFragment.webgl2 === true) {
+            this.settings.renderer = WEBGL;
+            if (uriFragment.webgl1 === true) {
+                this.settings.preferWebGL1 = true;
+            }
+        } else if (uriFragment.canvas === true) {
+            this.settings.renderer = CANVAS;
+        }
+
+        // normalize scale
+        this.settings.scale = (this.settings.autoScale) ? 1.0 : (+this.settings.scale || 1.0);
+
+        // default scaled size value
+        this.settings.zoomX = width * this.settings.scale;
+        this.settings.zoomY = height * this.settings.scale;
+
+        if (typeof this.settings.renderer === "number") {
+            switch (this.settings.renderer) {
+                case AUTO:
+                case WEBGL:
+                    this.renderer = autoDetectRenderer(this.settings);
+                    break;
+                default:
+                    this.renderer = new CanvasRenderer(this.settings);
+                    break;
+            }
+        } else {
+            var CustomRenderer = this.settings.renderer;
+            // a renderer class
+            this.renderer = new CustomRenderer(this.settings);
+        }
+
+        // register to the channel
+        event.on(event.WINDOW_ONRESIZE, () => { onresize(this); }, this);
+        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
+        if (device.platform.isMobile) {
+            // Prevent the webview from moving on a swipe
+            device.enableSwipe(false);
+        }
+
+        // trigger an initial resize();
+        onresize(this);
+
+        // add an observer to detect when the dom tree is modified
+        if ("MutationObserver" in globalThis) {
+            // Create an observer instance linked to the callback function
+            var observer = new MutationObserver(onresize.bind(this, this));
+
+            // Start observing the target node for configured mutations
+            observer.observe(this.parentElement, {
+                attributes: false, childList: true, subtree: true
+            });
+        }
+
+        if (this.settings.consoleHeader !== false) {
+            consoleHeader(this);
+        }
+
         // create a new physic world
         this.world = new World();
         // set the reference to this application instance
         this.world.app = this;
         this.lastUpdate = globalThis.performance.now();
+
         this.isInitialized = true;
+
         event.emit(event.GAME_INIT, this);
     }
 
@@ -213,21 +344,21 @@ import World from "./../physics/world.js";
      * @param {Stage} stage - the current stage
      */
     draw(stage) {
-        if (renderer.isContextValid === true && (this.isDirty || this.isAlwaysDirty)) {
+        if (this.renderer.isContextValid === true && (this.isDirty || this.isAlwaysDirty)) {
             // publish notification
             event.emit(event.GAME_BEFORE_DRAW, globalThis.performance.now());
 
             // prepare renderer to draw a new frame
-            renderer.clear();
+            this.renderer.clear();
 
             // render the stage
-            stage.draw(renderer);
+            stage.draw(this.renderer);
 
             // set back to flag
             this.isDirty = false;
 
             // flush/render our frame
-            renderer.flush();
+            this.renderer.flush();
 
             // publish notification
             event.emit(event.GAME_AFTER_DRAW, globalThis.performance.now());

package/src/application/header.js

@@ -0,0 +1,25 @@
+import * as device from "../system/device";
+
+/**
+ * display information
+ * @param {Application} game - the game application instance calling this function
+ */
+export function consoleHeader(app) {
+    var renderType = app.renderer.type;
+    var gpu_renderer = (typeof app.renderer.GPURenderer === "string") ? " (" + app.renderer.GPURenderer + ")" : "";
+    var audioType = device.hasWebAudio ? "Web Audio" : "HTML5 Audio";
+
+    // output video information in the console
+    console.log(
+        renderType + " renderer" + gpu_renderer + " | " +
+        audioType + " | " +
+        "pixel ratio " + device.devicePixelRatio + " | " +
+        (device.platform.nodeJS ? "node.js" : device.platform.isMobile ? "mobile" : "desktop") + " | " +
+        device.getScreenOrientation() + " | " +
+        device.language
+    );
+
+    console.log( "resolution: " + "requested " + app.settings.width + "x" + app.settings.height +
+        ", got " + app.renderer.getWidth() + "x" + app.renderer.getHeight()
+    );
+}

package/src/{video/utils → application}/resize.js

@@ -1,14 +1,16 @@
-import * as device from "./../../system/device.js";
-import game from "./../../game.js";
+import * as device from "./../system/device";
 
 /**
  * scale the "displayed" canvas by the given scalar.
  * this will modify the size of canvas element directly.
  * Only use this if you are not using the automatic scaling feature.
+ * @private
+ * @param {Application} game - the game application instance triggering the resize
  * @param {number} x - x scaling multiplier
  * @param {number} y - y scaling multiplier
  */
-function scale(renderer, x, y) {
+function scale(game, x, y) {
+    var renderer = game.renderer;
     var canvas = renderer.getCanvas();
     var context = renderer.getContext();
     var settings = renderer.settings;
@@ -34,8 +36,11 @@ function scale(renderer, x, y) {
 
 /**
  * callback for window resize event
+ * @private
+ * @param {Application} game - the game application instance triggering the resize
  */
-export function onresize(renderer) {
+export function onresize(game) {
+    var renderer = game.renderer;
     var settings = renderer.settings;
     var scaleX = 1, scaleY = 1;
 
@@ -99,9 +104,9 @@ export function onresize(renderer) {
         }
 
         // adjust scaling ratio based on the new scaling ratio
-        scale(renderer, scaleX, scaleY);
+        scale(game, scaleX, scaleY);
     } else {
         // adjust scaling ratio based on the given settings
-        scale(renderer, settings.scale, settings.scale);
+        scale(game, settings.scale, settings.scale);
     }
 }

package/src/application/settings.js

@@ -0,0 +1,19 @@
+// default settings
+export const defaultSettings = {
+    parent : undefined,
+    renderer : 2, // AUTO
+    autoScale : false,
+    scale : 1.0,
+    scaleMethod : "manual",
+    transparent : false,
+    premultipliedAlpha: true,
+    blendMode : "normal",
+    antiAlias : false,
+    failIfMajorPerformanceCaveat : true,
+    subPixel : false,
+    preferWebGL1 : false,
+    powerPreference : "default",
+    verbose : false,
+    consoleHeader : true,
+    legacy : false
+};

package/src/camera/camera2d.js

@@ -10,7 +10,7 @@ import * as event from "./../system/event.js";
 import pool from "./../system/pooling.js";
 import Renderable from "./../renderable/renderable.js";
 import {clamp, toBeCloseTo} from "./../math/math.js";
-import game from "./../game.js";
+import { game } from "../index.js";
 
 
 // some ref shortcut

package/src/const.js

@@ -0,0 +1,23 @@
+/**
+ * constant to select the HTML5 Canvas renderer
+ * @type {number}
+ * @static
+ * @see Application
+ */
+export const CANVAS = 0;
+
+/**
+ * constant to select select the WebGL renderer
+ * @type {number}
+ * @static
+ * @see Application
+ */
+export const WEBGL = 1;
+
+/**
+ * constant to auto-select the renderer (Attempt WebGL first, with fallback to Canvas)
+ * @static
+ * @type (number)
+ * @see Application
+ */
+export const AUTO = 2;

package/src/index.js

@@ -1,24 +1,6 @@
 // ES5/ES6 polyfills
 import "./polyfill/index.js";
 
-// utility classes
-import * as audio from "./audio/audio.js";
-import collision from "./physics/collision.js";
-import * as event from "./system/event.js";
-import * as device from "./system/device.js";
-import game from "./game.js";
-import loader from "./loader/loader.js";
-import * as Math from "./math/math.js";
-import utils from "./utils/utils.js";
-import * as input from "./input/input.js";
-import { plugin, plugins } from "./plugin/plugin.js";
-import * as video from "./video/video.js";
-import save from "./system/save.js";
-import timer from "./system/timer.js";
-import pool from "./system/pooling.js";
-import state from "./state/state.js";
-import level from "./level/level.js";
-
 // class definition
 import Color from "./math/color.js";
 import Vector2d from "./math/vector2.js";
@@ -45,9 +27,6 @@ import CanvasRenderer from "./video/canvas/canvas_renderer.js";
 import CanvasTexture from "./video/texture/canvas_texture.js";
 import { TextureAtlas } from "./video/texture/atlas.js";
 import Renderable from "./renderable/renderable.js";
-import Text from "./text/text.js";
-import BitmapText from "./text/bitmaptext.js";
-import BitmapTextData from "./text/bitmaptextdata.js";
 import ColorLayer from "./renderable/colorlayer.js";
 import ImageLayer from "./renderable/imagelayer.js";
 import Sprite from "./renderable/sprite.js";
@@ -58,6 +37,9 @@ import UISpriteElement from "./renderable/ui/uispriteelement.js";
 import Collectable from "./renderable/collectable.js";
 import Trigger from "./renderable/trigger.js";
 import Light2d from "./renderable/light2d.js";
+import Text from "./text/text.js";
+import BitmapText from "./text/bitmaptext.js";
+import BitmapTextData from "./text/bitmaptextdata.js";
 import { Draggable, DropTarget } from "./renderable/dragndrop.js";
 import TMXRenderer from "./level/tiled/renderer/TMXRenderer.js";
 import TMXOrthogonalRenderer from "./level/tiled/renderer/TMXOrthogonalRenderer.js";
@@ -78,6 +60,24 @@ import ParticleEmitterSettings from "./particles/settings.js";
 import ParticleEmitter from "./particles/emitter.js";
 import Particle from "./particles/particle.js";
 import Entity from "./entity/entity.js";
+import Application from "./application/application.js";
+
+// utility classes
+import * as audio from "./audio/audio.js";
+import collision from "./physics/collision.js";
+import * as event from "./system/event.js";
+import * as device from "./system/device.js";
+import loader from "./loader/loader.js";
+import * as Math from "./math/math.js";
+import utils from "./utils/utils.js";
+import * as input from "./input/input.js";
+import { plugin, plugins } from "./plugin/plugin.js";
+import * as video from "./video/video.js";
+import save from "./system/save.js";
+import timer from "./system/timer.js";
+import pool from "./system/pooling.js";
+import state from "./state/state.js";
+import level from "./level/level.js";
 
 
 /**
@@ -95,7 +95,6 @@ export {
     collision,
     device,
     event,
-    game,
     loader,
     level,
     input,
@@ -169,12 +168,15 @@ export {
     ParticleEmitter,
     ParticleEmitterSettings,
     Particle,
-    Entity
+    Entity,
+    Application
 };
 
 // Backward compatibility for deprecated method or properties
 export * from "./lang/deprecated.js";
 
+// export all public constants
+export * from "./const.js";
 
 /**
  * a flag indicating that melonJS is fully initialized
@@ -192,6 +194,14 @@ export var initialized = false;
  */
 export var skipAutoInit = false;
 
+/*
+ * game is a default instance of a melonJS Application and represents your current game,
+ * it contains all the objects, tilemap layers, current viewport, collision map, etc...<br>
+ * @namespace game
+ * @see Application
+ */
+export const game = new Application(0, 0, {legacy:true});
+
 /**
  * initialize the melonJS library.
  * this is automatically called unless me.skipAutoInit is set to true,
@@ -206,6 +216,9 @@ export function boot() {
         return;
     }
 
+    // output melonJS version in the console
+    console.log("melonJS 2 (v" + version + ") | http://melonjs.org" );
+
     // register all built-ins objects into the object pool
     pool.register("me.Entity", Entity);
     pool.register("me.Collectable", Collectable);

package/src/input/pointer.js

@@ -1,6 +1,6 @@
 import Vector2d from "./../math/vector2.js";
 import Bounds from "./../physics/bounds.js";
-import game from "./../game.js";
+import { game } from "../index.js";
 import { globalToLocal } from "./input.js";
 import { locked } from "./pointerevent.js";
 

package/src/input/pointerevent.js

@@ -9,7 +9,7 @@ import pool from "./../system/pooling.js";
 import * as device from "./../system/device.js";
 import Pointer from "./pointer.js";
 import Rect from "./../geometries/rectangle.js";
-import game from "./../game.js";
+import { game } from "../index.js";
 
 /**
  * A pool of `Pointer` objects to cache pointer/touch event coordinates.

package/src/lang/console.js

@@ -0,0 +1,36 @@
+
+/**
+ * display a deprecation warning in the console
+ * @param {string} deprecated - deprecated class,function or property name
+ * @param {string} replacement - the replacement class, function, or property name
+ * @param {string} version - the version since when the lass,function or property is deprecated
+ */
+export function warning(deprecated, replacement, version) {
+    var msg = "melonJS: %s is deprecated since version %s, please use %s";
+    var stack = new Error().stack;
+
+    if (console.groupCollapsed) {
+        console.groupCollapsed(
+            "%c" + msg,
+            "font-weight:normal;color:yellow;",
+            deprecated,
+            version,
+            replacement
+        );
+    } else {
+        console.warn(
+            msg,
+            deprecated,
+            version,
+            replacement
+        );
+    }
+
+    if (typeof stack !== "undefined") {
+        console.warn(stack);
+    }
+
+    if (console.groupCollapsed) {
+        console.groupEnd();
+    }
+}

package/src/lang/deprecated.js

@@ -2,47 +2,12 @@ import { TextureAtlas } from "./../video/texture/atlas.js";
 import Renderer from "./../video/renderer.js";
 import { Draggable, DropTarget } from "./../renderable/dragndrop.js";
 import UISpriteElement from "./../renderable/ui/uispriteelement.js";
+import { warning } from "./console.js";
+
 /*
  * placeholder for all deprecated classes and corresponding alias for backward compatibility
  */
 
-/**
- * display a deprecation warning in the console
- * @ignore
- * @param {string} deprecated - deprecated class,function or property name
- * @param {string} replacement - the replacement class, function, or property name
- * @param {string} version - the version since when the lass,function or property is deprecated
- */
-export function warning(deprecated, replacement, version) {
-    var msg = "melonJS: %s is deprecated since version %s, please use %s";
-    var stack = new Error().stack;
-
-    if (console.groupCollapsed) {
-        console.groupCollapsed(
-            "%c" + msg,
-            "font-weight:normal;color:yellow;",
-            deprecated,
-            version,
-            replacement
-        );
-    } else {
-        console.warn(
-            msg,
-            deprecated,
-            version,
-            replacement
-        );
-    }
-
-    if (typeof stack !== "undefined") {
-        console.warn(stack);
-    }
-
-    if (console.groupCollapsed) {
-        console.groupEnd();
-    }
-}
-
 /**
  * Alias of {@link TextureAtlas}
  * @public

package/src/level/level.js

@@ -2,7 +2,7 @@ import utils from "./../utils/utils.js";
 import * as event from "./../system/event.js";
 import state from "./../state/state.js";
 import loader from "./../loader/loader.js";
-import game from "./../game.js";
+import { game } from "../index.js";
 import TMXTileMap from "./tiled/TMXTileMap.js";
 
 

package/src/level/tiled/TMXGroup.js

@@ -15,66 +15,45 @@ export default class TMXGroup {
 
         /**
          * group name
-         * @public
          * @type {string}
-         * @name name
-         * @memberof TMXGroup
          */
         this.name = data.name;
 
         /**
          * group width
-         * @public
          * @type {number}
-         * @name width
-         * @memberof TMXGroup
          */
         this.width = data.width || 0;
 
         /**
          * group height
-         * @public
          * @type {number}
-         * @name height
-         * @memberof TMXGroup
          */
         this.height = data.height || 0;
 
         /**
          * tint color
-         * @public
          * @type {string}
-         * @name tintcolor
-         * @memberof TMXGroup
          */
         this.tintcolor = data.tintcolor;
 
 
         /**
          * the group class
-         * @public
          * @type {string}
-         * @name class
-         * @memberof TMXGroup
          */
         this.class = data.class;
 
         /**
          * group z order
-         * @public
          * @type {number}
-         * @name z
-         * @memberof TMXGroup
          */
         this.z = z;
 
         /**
          * group objects list definition
          * @see TMXObject
-         * @public
          * @type {object[]}
-         * @name name
-         * @memberof TMXGroup
          */
         this.objects = [];