melonjs 14.0.2 → 14.1.0

package/dist/melonjs.mjs/system/pooling.js

@@ -0,0 +1,209 @@
+/*!
+ * melonJS Game Engine - v14.1.0
+ * http://www.melonjs.org
+ * melonjs is licensed under the MIT License.
+ * http://www.opensource.org/licenses/mit-license
+ * @copyright (C) 2011 - 2022 Olivier Biot (AltByte Pte Ltd)
+ */
+/**
+ * @classdesc
+ * Object pooling - a technique that might speed up your game if used properly.<br>
+ * If some of your classes will be instantiated and removed a lot at a time, it is a
+ * good idea to add the class to this object pool. A separate pool for that class
+ * will be created, which will reuse objects of the class. That way they won't be instantiated
+ * each time you need a new one (slowing your game), but stored into that pool and taking one
+ * already instantiated when you need it.<br><br>
+ * This technique is also used by the engine to instantiate objects defined in the map,
+ * which means, that on level loading the engine will try to instantiate every object
+ * found in the map, based on the user defined name in each Object Properties<br>
+ * <img src="images/object_properties.png"/><br>
+ * @see {@link pool} the default global instance of ObjectPool
+ */
+class ObjectPool {
+
+    constructor() {
+        this.objectClass = {};
+        this.instance_counter = 0;
+    }
+
+    /**
+     * register an object to the pool. <br>
+     * Pooling must be set to true if more than one such objects will be created. <br>
+     * (Note: for an object to be poolable, it must implements a `onResetEvent` method)
+     * @param {string} className - as defined in the Name field of the Object Properties (in Tiled)
+     * @param {object} classObj - corresponding Class to be instantiated
+     * @param {boolean} [recycling=false] - enables object recycling for the specified class
+     * @example
+     * // implement CherryEntity
+     * class CherryEntity extends Spritesheet {
+     *    onResetEvent() {
+     *        // reset object mutable properties
+     *        this.lifeBar = 100;
+     *    }
+     * };
+     * // add our users defined entities in the object pool and enable object recycling
+     * me.pool.register("cherryentity", CherryEntity, 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");
+         }
+     }
+
+    /**
+     * Pull a new instance of the requested object (if added into the object pool)
+     * @param {string} name - as used in {@link pool.register}
+     * @param {object} [...arguments] - arguments to be passed when instantiating/reinitializing the object
+     * @returns {object} the instance of the requested object
+     * @example
+     * me.pool.register("bullet", BulletEntity, true);
+     * me.pool.register("enemy", EnemyEntity, true);
+     * // ...
+     * // when we need to manually create a new bullet:
+     * var bullet = me.pool.pull("bullet", x, y, direction);
+     * // ...
+     * // params aren't a fixed number
+     * // when we need new enemy we can add more params, that the object construct requires:
+     * var enemy = me.pool.pull("enemy", x, y, direction, speed, power, life);
+     * // ...
+     * // when we want to destroy existing object, the remove
+     * // function will ensure the object can then be reallocated later
+     * me.game.world.removeChild(enemy);
+     * me.game.world.removeChild(bullet);
+     */
+    pull(name) {
+        var args = new Array(arguments.length);
+        for (var i = 0; i < arguments.length; i++) {
+            args[i] = arguments[i];
+        }
+        var className = this.objectClass[name];
+        if (className) {
+            var proto = className["class"],
+                poolArray = className.pool,
+                obj;
+
+            if (poolArray && ((obj = poolArray.pop()))) {
+                // pull an existing instance from the pool
+                args.shift();
+                // call the object onResetEvent function if defined
+                if (typeof(obj.onResetEvent) === "function") {
+                    obj.onResetEvent.apply(obj, args);
+                }
+                this.instance_counter--;
+            }
+            else {
+                // create a new instance
+                args[0] = proto;
+                obj = new (proto.bind.apply(proto, args))();
+                if (poolArray) {
+                    obj.className = name;
+                }
+            }
+            return obj;
+        }
+        throw new Error("Cannot instantiate object of type '" + name + "'");
+    }
+
+    /**
+     * purge the object pool from any inactive object <br>
+     * Object pooling must be enabled for this function to work<br>
+     * note: this will trigger the garbage collector
+     */
+    purge() {
+        for (var className in this.objectClass) {
+            if (this.objectClass[className]) {
+                this.objectClass[className].pool = [];
+            }
+        }
+        this.instance_counter = 0;
+    }
+
+    /**
+     * Push back an object instance into the object pool <br>
+     * Object pooling for the object class must be enabled,
+     * and object must have been instantiated using {@link pool#pull},
+     * otherwise this function won't work
+     * @throws will throw an error if the object cannot be recycled
+     * @param {object} obj - instance to be recycled
+     * @param {boolean} [throwOnError=true] - throw an exception if the object cannot be recycled
+     * @returns {boolean} true if the object was successfully recycled in the object pool
+     */
+    push(obj, throwOnError = true) {
+        if (!this.poolable(obj)) {
+            if (throwOnError === true ) {
+                throw new Error("me.pool: object " + obj + " cannot be recycled");
+            } else {
+                return false;
+            }
+        }
+
+        // store back the object instance for later recycling
+        this.objectClass[obj.className].pool.push(obj);
+        this.instance_counter++;
+
+        return true;
+    }
+
+    /**
+     * Check if an object with the provided name is registered
+     * @param {string} name - of the registered object class
+     * @returns {boolean} true if the classname is registered
+     */
+    exists(name) {
+        return name in this.objectClass;
+    }
+
+    /**
+     * Check if an object is poolable
+     * (was properly registered with the recycling feature enable)
+     * @see register
+     * @param {object} obj - object to be checked
+     * @returns {boolean} true if the object is poolable
+     * @example
+     * if (!me.pool.poolable(myCherryEntity)) {
+     *     // object was not properly registered
+     * }
+     */
+    poolable(obj) {
+        var className = obj.className;
+        return (typeof className !== "undefined") &&
+                (typeof obj.onResetEvent === "function") &&
+                (className in this.objectClass) &&
+                (typeof this.objectClass[className].pool !== "undefined");
+
+    }
+
+    /**
+     * returns the amount of object instance currently in the pool
+     * @returns {number} amount of object instance
+     */
+    getInstanceCount() {
+        return this.instance_counter;
+    }
+}
+
+var pool = new ObjectPool();
+
+/**
+ * a default global ObjectPool instance
+ * @namespace pool
+ * @see ObjectPool
+ * @example
+ * // register our bullet object into the object pool
+ * pool.register("bullet", BulletEntity, true);
+ * // ...
+ * // when we need to manually create a new bullet:
+ * var bullet = pool.pull("bullet", x, y, direction, velocity);
+ * // ...
+ * // when we want to destroy existing object, the remove
+ * // function will ensure the object can then be reallocated later
+ * game.world.removeChild(bullet);
+ */
+var pool$1 = pool;
+
+export { pool$1 as default };

package/dist/melonjs.mjs/system/save.js

@@ -0,0 +1,157 @@
+/*!
+ * melonJS Game Engine - v14.1.0
+ * http://www.melonjs.org
+ * melonjs is licensed under the MIT License.
+ * http://www.opensource.org/licenses/mit-license
+ * @copyright (C) 2011 - 2022 Olivier Biot (AltByte Pte Ltd)
+ */
+import { on, BOOT } from './event.js';
+
+/**
+ * allow to access and manage the device localStorage
+ * @example
+ * // Initialize "score" and "lives" with default values
+ * // This loads the properties from localStorage if they exist, else it sets the given defaults
+ * me.save.add({ score : 0, lives : 3 });
+ *
+ * // Print all
+ * // On first load, this prints { score : 0, lives : 3 }
+ * // On further reloads, it prints { score : 31337, lives : 3, complexObject : ... }
+ * // Because the following changes will be saved to localStorage
+ * console.log(JSON.stringify(me.save));
+ *
+ * // Save score
+ * me.save.score = 31337;
+ *
+ * // Also supports complex objects thanks to the JSON backend
+ * me.save.add({ complexObject : {} })
+ * me.save.complexObject = { a : "b", c : [ 1, 2, 3, "d" ], e : { f : [{}] } };
+ *
+ * // WARNING: Do not set any child properties of complex objects directly!
+ * // Changes made that way will not save. Always set the entire object value at once.
+ * // If you cannot live with this limitation, there's a workaround:
+ * me.save.complexObject.c.push("foo"); // Modify a child property
+ * me.save.complexObject = me.save.complexObject; // Save the entire object!
+ *
+ * // Remove "lives" from localStorage
+ * me.save.remove("lives");
+ * @namespace save
+ */
+
+// Variable to hold the object data
+var data = {};
+
+let hasLocalStorage = false;
+
+try {
+    // true if localStorage is supported
+    hasLocalStorage = typeof globalThis !== "undefined" && typeof globalThis.localStorage !== "undefined";
+} catch (e) {
+    // the above generates an exception when cookies are blocked
+    hasLocalStorage = false;
+}
+
+/**
+ * a function to check if the given key is a reserved word
+ * @ignore
+ */
+function isReserved(key) {
+    return (key === "add" || key === "remove");
+}
+
+
+// Initialize me.save on Boot event
+on(BOOT, () => {
+    // Load previous data if local Storage is supported
+    if (hasLocalStorage === true) {
+        var me_save_content = globalThis.localStorage.getItem("me.save");
+
+        if (typeof me_save_content === "string" && me_save_content.length > 0) {
+            var keys = JSON.parse(me_save_content) || [];
+            keys.forEach((key) => {
+                data[key] = JSON.parse(globalThis.localStorage.getItem("me.save." + key));
+            });
+        }
+    }
+});
+
+var save = {
+
+    /**
+     * Add new keys to localStorage and set them to the given default values if they do not exist
+     * @name add
+     * @memberof save
+     * @param {object} props - key and corresponding values
+     * @example
+     * // Initialize "score" and "lives" with default values
+     * me.save.add({ score : 0, lives : 3 });
+     * // get or set the value through me.save
+     * me.save.score = 1000;
+     */
+    add(props) {
+        var obj = save;
+
+        Object.keys(props).forEach((key) => {
+            if (isReserved(key)) {
+                return;
+            }
+
+            (function (prop) {
+                Object.defineProperty(obj, prop, {
+                    configurable : true,
+                    enumerable : true,
+                    /**
+                     * @ignore
+                     */
+                    get () {
+                        return data[prop];
+                    },
+                    /**
+                     * @ignore
+                     */
+                    set (value) {
+                        data[prop] = value;
+                        if (hasLocalStorage === true) {
+                            globalThis.localStorage.setItem("me.save." + prop, JSON.stringify(value));
+                        }
+                    }
+                });
+            })(key);
+
+            // Set default value for key
+            if (!(key in data)) {
+                obj[key] = props[key];
+            }
+        });
+
+        // Save keys
+        if (hasLocalStorage === true) {
+            globalThis.localStorage.setItem("me.save", JSON.stringify(Object.keys(data)));
+        }
+    },
+
+    /**
+     * Remove a key from localStorage
+     * @name remove
+     * @memberof save
+     * @param {string} key - key to be removed
+     * @example
+     * // Remove the "score" key from localStorage
+     * me.save.remove("score");
+     */
+    remove (key) {
+        if (!isReserved(key)) {
+            if (typeof data[key] !== "undefined") {
+                delete data[key];
+                if (hasLocalStorage === true) {
+                    globalThis.localStorage.removeItem("me.save." + key);
+                    globalThis.localStorage.setItem("me.save", JSON.stringify(Object.keys(data)));
+                }
+            }
+        }
+    }
+};
+
+var save$1 = save;
+
+export { save$1 as default };

package/dist/melonjs.mjs/system/timer.js

@@ -0,0 +1,286 @@
+/*!
+ * melonJS Game Engine - v14.1.0
+ * http://www.melonjs.org
+ * melonjs is licensed under the MIT License.
+ * http://www.opensource.org/licenses/mit-license
+ * @copyright (C) 2011 - 2022 Olivier Biot (AltByte Pte Ltd)
+ */
+import utils from '../utils/utils.js';
+import { on, GAME_BEFORE_UPDATE, BOOT, STATE_RESUME, STATE_RESTART, STATE_CHANGE } from './event.js';
+import state from '../state/state.js';
+import { clamp } from '../math/math.js';
+
+/**
+ * @classdesc
+ * a Timer class to manage timing related function (FPS, Game Tick, Time...)
+ * @see {@link timer} the default global timer instance
+ */
+class Timer {
+
+    constructor() {
+        /**
+         * Last game tick value. <br>
+         * Use this value to scale velocities during frame drops due to slow hardware or when setting an FPS limit.
+         * This feature is disabled by default (Enable interpolation to use it).
+         * @public
+         * @see interpolation
+         * @See maxfps
+         * @type {number}
+         * @name tick
+         */
+        this.tick = 1.0;
+
+        /**
+         * Last measured fps rate.<br>
+         * This feature is disabled by default, unless the debugPanel is enabled/visible.
+         * @public
+         * @type {number}
+         * @name fps
+         */
+        this.fps = 0;
+
+        /**
+         * Set the maximum target display frame per second
+         * @public
+         * @see tick
+         * @type {number}
+         * @default 60
+         */
+        this.maxfps = 60;
+
+        /**
+         * Enable/disable frame interpolation
+         * @see tick
+         * @type {boolean}
+         * @default false
+         */
+        this.interpolation = false;
+
+        //hold element to display fps
+        this.framecount = 0;
+        this.framedelta = 0;
+
+        /* fps count stuff */
+        this.last = 0;
+        this.now = 0;
+        this.delta = 0;
+        // for timeout/interval update
+        this.step =0;
+        this.minstep = 0;
+
+        // list of defined timer function
+        this.timers = [];
+        this.timerId = 0;
+
+        // Initialize mtimer on Boot event
+        on(BOOT, () => {
+            // reset variables to initial state
+            this.reset();
+            this.now = this.last = 0;
+            // register to the game before update event
+            on(GAME_BEFORE_UPDATE, this.update.bind(this));
+        });
+
+        // reset timer
+        on(STATE_RESUME, () => {
+            this.reset();
+        });
+        on(STATE_RESTART, () => {
+            this.reset();
+        });
+        on(STATE_CHANGE, () => {
+            this.reset();
+        });
+    }
+
+
+    /**
+     * reset time (e.g. usefull in case of pause)
+     * @ignore
+     */
+    reset() {
+        // set to "now"
+        this.last = this.now = globalThis.performance.now();
+        this.delta = 0;
+        // reset delta counting variables
+        this.framedelta = 0;
+        this.framecount = 0;
+        this.step = Math.ceil(1000 / this.maxfps); // ROUND IT ?
+        // define some step with some margin
+        this.minstep = (1000 / this.maxfps) * 1.25; // IS IT NECESSARY?\
+    }
+
+    /**
+     * Calls a function once after a specified delay. See me.timer.setInterval to repeativly call a function.
+     * @param {Function} fn - the function you want to execute after delay milliseconds.
+     * @param {number} delay - the number of milliseconds (thousandths of a second) that the function call should be delayed by.
+     * @param {boolean} [pauseable=true] - respects the pause state of the engine.
+     * @param {...*} args - optional parameters which are passed through to the function specified by fn once the timer expires.
+     * @returns {number} The numerical ID of the timer, which can be used later with me.timer.clearTimeout().
+     * @example
+     * // set a timer to call "myFunction" after 1000ms
+     * me.timer.setTimeout(myFunction, 1000);
+     * // set a timer to call "myFunction" after 1000ms (respecting the pause state) and passing param1 and param2
+     * me.timer.setTimeout(myFunction, 1000, true, param1, param2);
+     */
+    setTimeout(fn, delay, pauseable, ...args) {
+        this.timers.push({
+            fn : fn,
+            delay : delay,
+            elapsed : 0,
+            repeat : false,
+            timerId : ++this.timerId,
+            pauseable : pauseable === true || true,
+            args : args
+        });
+        return this.timerId;
+    }
+
+    /**
+     * Calls a function continously at the specified interval.  See setTimeout to call function a single time.
+     * @param {Function} fn - the function to execute
+     * @param {number} delay - the number of milliseconds (thousandths of a second) on how often to execute the function
+     * @param {boolean} [pauseable=true] - respects the pause state of the engine.
+     * @param {...*} args - optional parameters which are passed through to the function specified by fn once the timer expires.
+     * @returns {number} The numerical ID of the timer, which can be used later with me.timer.clearInterval().
+     * @example
+     * // set a timer to call "myFunction" every 1000ms
+     * me.timer.setInterval(myFunction, 1000);
+     * // set a timer to call "myFunction" every 1000ms (respecting the pause state) and passing param1 and param2
+     * me.timer.setInterval(myFunction, 1000, true, param1, param2);
+     */
+    setInterval(fn, delay, pauseable, ...args) {
+        this.timers.push({
+            fn : fn,
+            delay : delay,
+            elapsed : 0,
+            repeat : true,
+            timerId : ++this.timerId,
+            pauseable : pauseable === true || true,
+            args : args
+        });
+        return this.timerId;
+    }
+
+    /**
+     * Clears the delay set by me.timer.setTimeout().
+     * @param {number} timeoutID - ID of the timeout to be cleared
+     */
+    clearTimeout(timeoutID) {
+        utils.function.defer(this.clearTimer.bind(this), this, timeoutID);
+    }
+
+    /**
+     * Clears the Interval set by me.timer.setInterval().
+     * @param {number} intervalID - ID of the interval to be cleared
+     */
+    clearInterval(intervalID) {
+        utils.function.defer(this.clearTimer.bind(this), this, intervalID);
+    }
+
+    /**
+     * Return the current timestamp in milliseconds <br>
+     * since the game has started or since linux epoch (based on browser support for High Resolution Timer)
+     * @returns {number}
+     */
+    getTime() {
+        return this.now;
+    }
+
+    /**
+     * Return elapsed time in milliseconds since the last update
+     * @returns {number}
+     */
+    getDelta() {
+        return this.delta;
+    }
+
+    /**
+     * compute the actual frame time and fps rate
+     * @ignore
+     */
+    countFPS() {
+        this.framecount++;
+        this.framedelta += this.delta;
+        if (this.framecount % 10 === 0) {
+            this.fps = clamp(Math.round((1000 * this.framecount) / this.framedelta), 0, this.maxfps);
+            this.framedelta = 0;
+            this.framecount = 0;
+        }
+    }
+
+    /**
+     * update
+     * @ignore
+     */
+    update(time) {
+        this.last = this.now;
+        this.now = time;
+        this.delta = (this.now - this.last);
+
+        // fix for negative timestamp returned by wechat or chrome on startup
+        if (this.delta < 0) {
+            this.delta = 0;
+        }
+
+        // get the game tick
+        this.tick = (this.delta > this.minstep && this.interpolation) ? this.delta / this.step : 1;
+
+        this.updateTimers();
+    }
+
+    /**
+     * clear Timers
+     * @ignore
+     */
+    clearTimer(timerId) {
+        for (var i = 0, len = this.timers.length; i < len; i++) {
+            if (this.timers[i].timerId === timerId) {
+                this.timers.splice(i, 1);
+                break;
+            }
+        }
+    }
+
+
+    /**
+     * update timers
+     * @ignore
+     */
+    updateTimers() {
+        for (var i = 0, len = this.timers.length; i < len; i++) {
+            var _timer = this.timers[i];
+            if (!(_timer.pauseable && state.isPaused())) {
+                _timer.elapsed += this.delta;
+            }
+            if (_timer.elapsed >= _timer.delay) {
+                _timer.fn.apply(null, _timer.args);
+                if (_timer.repeat === true) {
+                    _timer.elapsed -= _timer.delay;
+                } else {
+                    this.clearTimeout(_timer.timerId);
+                }
+            }
+        }
+    }
+}
+
+const timer = new Timer();
+
+/**
+ * the default global Timer instance
+ * @namespace timer
+ * @see Timer
+ * @example
+ * // set a timer to call "myFunction" after 1000ms
+ * timer.setTimeout(myFunction, 1000);
+ * // set a timer to call "myFunction" after 1000ms (respecting the pause state) and passing param1 and param2
+ * timer.setTimeout(myFunction, 1000, true, param1, param2);
+ * // set a timer to call "myFunction" every 1000ms
+ * timer.setInterval(myFunction, 1000);
+ * // set a timer to call "myFunction" every 1000ms (respecting the pause state) and passing param1 and param2
+ * timer.setInterval(myFunction, 1000, true, param1, param2);
+ */
+var timer$1 = timer;
+
+export { timer$1 as default };