melonjs 10.6.1 → 10.8.0

package/src/particles/emitter.js

@@ -1,334 +1,81 @@
 import { createCanvas } from "./../video/video.js";
-import * as pool from "./../system/pooling.js";
-import Renderable from "./../renderable/renderable.js";
-import ParticleContainer from "./particlecontainer.js";
+import pool from "./../system/pooling.js";
+import ParticleEmitterSettings from "./settings.js";
 import { randomFloat } from "./../math/math.js";
+import Container from "./../renderable/container.js";
 
 
-
-// generate a default image for the particles
-var pixel = (function () {
-    var canvas = createCanvas(1, 1);
-    var context = canvas.getContext("2d");
-    context.fillStyle = "#fff";
-    context.fillRect(0, 0, 1, 1);
-    return canvas;
-})();
+// default texture used when no sprite is defined
+let defaultParticleTexture;
 
 /**
- * me.ParticleEmitterSettings contains the default settings for me.ParticleEmitter
  * @ignore
- * @class
- * @see ParticleEmitter
  */
-var ParticleEmitterSettings = {
-    /**
-     * Width of the particle spawn area.<br>
-     * @public
-     * @type {number}
-     * @name width
-     * @memberof ParticleEmitterSettings
-     * @default 0
-     */
-    width : 0,
-
-    /**
-     * Height of the particle spawn area
-     * @public
-     * @type {number}
-     * @name height
-     * @memberof ParticleEmitterSettings
-     * @default 0
-     */
-    height : 0,
-
-    /**
-     * Image used for particles
-     * @public
-     * @type {CanvasImageSource}
-     * @name image
-     * @memberof ParticleEmitterSettings
-     * @default 1x1 white pixel
-     * @see http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#canvasimagesource
-     */
-    image : pixel,
-
-    /**
-     * Total number of particles in the emitter
-     * @public
-     * @type {number}
-     * @name totalParticles
-     * @default 50
-     * @memberof ParticleEmitterSettings
-     */
-    totalParticles : 50,
-
-    /**
-     * Start angle for particle launch in Radians
-     * @public
-     * @type {number}
-     * @name angle
-     * @default Math.PI / 2
-     * @memberof ParticleEmitterSettings
-     */
-    angle : Math.PI / 2,
-
-    /**
-     * Variation in the start angle for particle launch in Radians
-     * @public
-     * @type {number}
-     * @name angleVariation
-     * @default 0
-     * @memberof ParticleEmitterSettings
-     */
-    angleVariation : 0,
-
-    /**
-     * Minimum time each particle lives once it is emitted in ms
-     * @public
-     * @type {number}
-     * @name minLife
-     * @default 1000
-     * @memberof ParticleEmitterSettings
-     */
-    minLife : 1000,
-
-    /**
-     * Maximum time each particle lives once it is emitted in ms
-     * @public
-     * @type {number}
-     * @name maxLife
-     * @default 3000
-     * @memberof ParticleEmitterSettings
-     */
-    maxLife : 3000,
-
-    /**
-     * Start speed of particles.<br>
-     * @public
-     * @type {number}
-     * @name speed
-     * @default 2
-     * @memberof ParticleEmitterSettings
-     */
-    speed : 2,
-
-    /**
-     * Variation in the start speed of particles
-     * @public
-     * @type {number}
-     * @name speedVariation
-     * @default 1
-     * @memberof ParticleEmitterSettings
-     */
-    speedVariation : 1,
-
-    /**
-     * Minimum start rotation for particles sprites in Radians
-     * @public
-     * @type {number}
-     * @name minRotation
-     * @default 0
-     * @memberof ParticleEmitterSettings
-     */
-    minRotation : 0,
-
-    /**
-     * Maximum start rotation for particles sprites in Radians
-     * @public
-     * @type {number}
-     * @name maxRotation
-     * @default 0
-     * @memberof ParticleEmitterSettings
-     */
-    maxRotation : 0,
-
-    /**
-     * Minimum start scale ratio for particles (1 = no scaling)
-     * @public
-     * @type {number}
-     * @name minStartScale
-     * @default 1
-     * @memberof ParticleEmitterSettings
-     */
-    minStartScale : 1,
-
-    /**
-     * Maximum start scale ratio for particles (1 = no scaling)
-     * @public
-     * @type {number}
-     * @name maxStartScale
-     * @default 1
-     * @memberof ParticleEmitterSettings
-     */
-    maxStartScale : 1,
-
-    /**
-     * Minimum end scale ratio for particles
-     * @public
-     * @type {number}
-     * @name minEndScale
-     * @default 0
-     * @memberof ParticleEmitterSettings
-     */
-    minEndScale : 0,
-
-    /**
-     * Maximum end scale ratio for particles
-     * @public
-     * @type {number}
-     * @name maxEndScale
-     * @default 0
-     * @memberof ParticleEmitterSettings
-     */
-    maxEndScale : 0,
-
-    /**
-     * Vertical force (Gravity) for each particle
-     * @public
-     * @type {number}
-     * @name gravity
-     * @default 0
-     * @memberof ParticleEmitterSettings
-     * @see game.world.gravity
-     */
-    gravity : 0,
-
-    /**
-     * Horizontal force (like a Wind) for each particle
-     * @public
-     * @type {number}
-     * @name wind
-     * @default 0
-     * @memberof ParticleEmitterSettings
-     */
-    wind : 0,
-
-    /**
-     * Update the rotation of particle in accordance the particle trajectory.<br>
-     * The particle sprite should aim at zero angle (draw from left to right).<br>
-     * Override the particle minRotation and maxRotation.<br>
-     * @public
-     * @type {boolean}
-     * @name followTrajectory
-     * @default false
-     * @memberof ParticleEmitterSettings
-     */
-    followTrajectory : false,
-
-    /**
-     * Enable the Texture Additive by canvas composite operation (lighter).<br>
-     * WARNING: Composite Operation may decreases performance!.<br>
-     * @public
-     * @type {boolean}
-     * @name textureAdditive
-     * @default false
-     * @memberof ParticleEmitterSettings
-     */
-    textureAdditive : false,
-
-    /**
-     * Update particles only in the viewport, remove it when out of viewport.<br>
-     * @public
-     * @type {boolean}
-     * @name onlyInViewport
-     * @default true
-     * @memberof ParticleEmitterSettings
-     */
-    onlyInViewport : true,
-
-    /**
-     * Render particles in screen space. <br>
-     * @public
-     * @type {boolean}
-     * @name floating
-     * @default false
-     * @memberof ParticleEmitterSettings
-     */
-    floating : false,
-
-    /**
-     * Maximum number of particles launched each time in this emitter (used only if emitter is Stream).<br>
-     * @public
-     * @type {number}
-     * @name maxParticles
-     * @default 10
-     * @memberof ParticleEmitterSettings
-     */
-    maxParticles : 10,
-
-    /**
-     * How often a particle is emitted in ms (used only if emitter is Stream).<br>
-     * Necessary that value is greater than zero.<br>
-     * @public
-     * @type {number}
-     * @name frequency
-     * @default 100
-     * @memberof ParticleEmitterSettings
-     */
-    frequency : 100,
-
-    /**
-     * Duration that the emitter releases particles in ms (used only if emitter is Stream).<br>
-     * After this period, the emitter stop the launch of particles.<br>
-     * @public
-     * @type {number}
-     * @name duration
-     * @default Infinity
-     * @memberof ParticleEmitterSettings
-     */
-    duration : Infinity,
-
-    /**
-     * Skip n frames after updating the particle system once. <br>
-     * This can be used to reduce the performance impact of emitters with many particles.<br>
-     * @public
-     * @type {number}
-     * @name framesToSkip
-     * @default 0
-     * @memberof ParticleEmitterSettings
-     */
-    framesToSkip : 0
+function createDefaultParticleTexture(w = 8, h = 8) {
+    if (typeof defaultParticleTexture === "undefined") {
+        defaultParticleTexture = createCanvas(w, h, true);
+        var context = defaultParticleTexture.getContext("2d");
+        context.fillStyle = "#fff";
+        context.fillRect(0, 0, w, h);
+    }
+    return defaultParticleTexture;
 };
 
 /**
+ * @classdesc
  * Particle Emitter Object.
- * @class
- * @augments Rect
- * @param {number} x x-position of the particle emitter
- * @param {number} y y-position of the particle emitter
- * @param {object} settings An object containing the settings for the particle emitter. See {@link ParticleEmitterSettings}
- * @example
- * // Create a basic emitter at position 100, 100
- * var emitter = new me.ParticleEmitter(100, 100);
- *
- * // Adjust the emitter properties
- * emitter.totalParticles = 200;
- * emitter.minLife = 1000;
- * emitter.maxLife = 3000;
- * emitter.z = 10;
- *
- * // Add the emitter to the game world
- * me.game.world.addChild(emitter);
- *
- * // Launch all particles one time and stop, like a explosion
- * emitter.burstParticles();
- *
- * // Launch constantly the particles, like a fountain
- * emitter.streamParticles();
- *
- * // At the end, remove emitter from the game world
- * // call this in onDestroyEvent function
- * me.game.world.removeChild(emitter);
+ * @augments Container
  */
-class ParticleEmitter extends Renderable {
-
-    /**
-     * @ignore
-     */
-    constructor(x, y, settings) {
+class ParticleEmitter extends Container {
+    /**
+     * @param {number} x x position of the particle emitter
+     * @param {number} y y position of the particle emitter
+     * @param {ParticleEmitterSettings} [settings=ParticleEmitterSettings] the settings for the particle emitter.
+     * @example
+     * // Create a particle emitter at position 100, 100
+     * var emitter = new ParticleEmitter(100, 100, {
+     *     width: 16,
+     *     height : 16,
+     *     tint: "#f00",
+     *     totalParticles: 32,
+     *     angle: 0,
+     *     angleVariation: 6.283185307179586,
+     *     maxLife: 5,
+     *     speed: 3
+     * });
+     *
+     * // Add the emitter to the game world
+     * me.game.world.addChild(emitter);
+     *
+     * // Launch all particles one time and stop, like a explosion
+     * emitter.burstParticles();
+     *
+     * // Launch constantly the particles, like a fountain
+     * emitter.streamParticles();
+     *
+     * // At the end, remove emitter from the game world
+     * // call this in onDestroyEvent function
+     * me.game.world.removeChild(emitter);
+     */
+    constructor(x, y, settings = {}) {
         // call the super constructor
-        super(x, y, Infinity, Infinity);
+        super(
+            x, y,
+            settings.width | 1,
+            settings.height | 1
+        );
+
+        /**
+         * the current (active) emitter settings
+         * @public
+         * @type {ParticleEmitterSettings}
+         * @name settings
+         * @memberof ParticleEmitter
+         */
+        this.settings = {};
+
+        // center the emitter around the given coordinates
+        this.centerOn(x, y);
 
         // Emitter is Stream, launch particles constantly
         /** @ignore */
@@ -354,169 +101,95 @@ class ParticleEmitter extends Renderable {
         // don't sort the particles by z-index
         this.autoSort = false;
 
-        this.container = new ParticleContainer(this);
+        // count the updates
+        this._updateCount = 0;
 
-        // Reset the emitter to defaults
-        this.reset(settings);
-    }
+        // internally store how much time was skipped when frames are skipped
+        this._dt = 0;
 
-    /**
-     * @ignore
-     */
-    get z() {
-        return this.container.pos.z;
-    }
+        //this.anchorPoint.set(0, 0);
 
-    /**
-     * @ignore
-     */
-    set z(value) {
-        this.container.pos.z = value;
+        // Reset the emitter to defaults
+        this.reset(settings);
     }
 
     /**
-     * Floating property for particles, value is forwarded to the particle container <br>
-     * @type {boolean}
-     * @name floating
-     * @memberof ParticleEmitter
+     * Reset the emitter with particle emitter settings.
+     * @param {ParticleEmitterSettings} settings [optional] object with emitter settings. See {@link ParticleEmitterSettings}
      */
-    get floating() {
-        return this.container.floating;
-    }
-
-    set floating(value) {
-        this.container.floating = value;
-    }
+    reset(settings = {}) {
+        Object.assign(this.settings, ParticleEmitterSettings, settings);
 
-    /**
-     * @ignore
-     */
-    onActivateEvent() {
-        this.ancestor.addChild(this.container);
-        this.container.pos.z = this.pos.z;
-        if (!this.ancestor.autoSort) {
-            this.ancestor.sort();
+        // Cache the image reference
+        if (typeof this.settings.image === "undefined") {
+            this.settings.image = createDefaultParticleTexture(settings.textureSize, settings.textureSize);
         }
-    }
 
-    /**
-     * @ignore
-     */
-    onDeactivateEvent() {
-        if (this.ancestor.hasChild(this.container)) {
-            this.ancestor.removeChildNow(this.container);
-        }
-    }
+        this.floating = this.settings.floating;
 
-    /**
-     * @ignore
-     */
-    destroy() {
-        this.reset();
+        this.isDirty = true;
     }
 
     /**
-     * returns a random point inside the bounds x axis of this emitter
-     * @name getRandomPointX
-     * @memberof ParticleEmitter
-     * @function
+     * returns a random point on the x axis within the bounds of this emitter
      * @returns {number}
      */
     getRandomPointX() {
-        return this.pos.x + randomFloat(0, this.width);
+        return randomFloat(0, this.getBounds().width);
     }
 
     /**
-     * returns a random point inside the bounds y axis of this emitter
-     * @name getRandomPointY
-     * @memberof ParticleEmitter
-     * @function
+     * returns a random point on the y axis within the bounds this emitter
      * @returns {number}
      */
     getRandomPointY() {
-        return this.pos.y + randomFloat(0, this.height);
-    }
-
-    /**
-     * Reset the emitter with default values.<br>
-     * @function
-     * @param {object} settings [optional] object with emitter settings. See {@link ParticleEmitterSettings}
-     * @name reset
-     * @memberof ParticleEmitter
-     */
-    reset(settings) {
-        // check if settings exists and create a dummy object if necessary
-        settings = settings || {};
-        var defaults = ParticleEmitterSettings;
-
-        var width = (typeof settings.width === "number") ? settings.width : defaults.width;
-        var height = (typeof settings.height === "number") ? settings.height : defaults.height;
-        this.resize(width, height);
-
-        Object.assign(this, defaults, settings);
-
-        // reset particle container values
-        this.container.reset();
+        return randomFloat(0, this.getBounds().height);
     }
 
     // Add count particles in the game world
     /** @ignore */
     addParticles(count) {
-        for (var i = 0; i < ~~count; i++) {
+        for (var i = 0; i < count; i++) {
             // Add particle to the container
-            var particle = pool.pull("Particle", this);
-            this.container.addChild(particle);
+            this.addChild(pool.pull("Particle", this), this.pos.z);
         }
+        this.isDirty = true;
     }
 
     /**
-     * Emitter is of type stream and is launching particles <br>
-     * @function
+     * Emitter is of type stream and is launching particles
      * @returns {boolean} Emitter is Stream and is launching particles
-     * @name isRunning
-     * @memberof ParticleEmitter
      */
     isRunning() {
         return this._enabled && this._stream;
     }
 
     /**
-     * Launch particles from emitter constantly <br>
-     * Particles example: Fountains
+     * Launch particles from emitter constantly (e.g. for stream)
      * @param {number} duration [optional] time that the emitter releases particles in ms
-     * @function
-     * @name streamParticles
-     * @memberof ParticleEmitter
      */
     streamParticles(duration) {
         this._enabled = true;
         this._stream = true;
-        this.frequency = Math.max(this.frequency, 1);
-        this._durationTimer = (typeof duration === "number") ? duration : this.duration;
+        this.settings.frequency = Math.max(1, this.settings.frequency);
+        this._durationTimer = (typeof duration === "number") ? duration : this.settings.duration;
     }
 
     /**
-     * Stop the emitter from generating new particles (used only if emitter is Stream) <br>
-     * @function
-     * @name stopStream
-     * @memberof ParticleEmitter
+     * Stop the emitter from generating new particles (used only if emitter is Stream)
      */
     stopStream() {
         this._enabled = false;
     }
 
     /**
-     * Launch all particles from emitter and stop <br>
-     * Particles example: Explosions <br>
+     * Launch all particles from emitter and stop (e.g. for explosion)
      * @param {number} total [optional] number of particles to launch
-     * @function
-     * @name burstParticles
-     * @memberof ParticleEmitter
      */
     burstParticles(total) {
         this._enabled = true;
         this._stream = false;
-        this.addParticles((typeof total === "number") ? total : this.totalParticles);
+        this.addParticles((typeof total === "number") ? total : this.settings.totalParticles);
         this._enabled = false;
     }
 
@@ -524,6 +197,22 @@ class ParticleEmitter extends Renderable {
      * @ignore
      */
     update(dt) {
+        // skip frames if necessary
+        if (++this._updateCount > this.settings.framesToSkip) {
+            this._updateCount = 0;
+        }
+        if (this._updateCount > 0) {
+            this._dt += dt;
+            return this.isDirty;
+        }
+
+        // apply skipped delta time
+        dt += this._dt;
+        this._dt = 0;
+
+        // Update particles
+        this.isDirty |= super.update(dt);
+
         // Launch new particles, if emitter is Stream
         if ((this._enabled) && (this._stream)) {
             // Check if the emitter has duration set
@@ -532,7 +221,7 @@ class ParticleEmitter extends Renderable {
 
                 if (this._durationTimer <= 0) {
                     this.stopStream();
-                    return false;
+                    return this.isDirty;
                 }
             }
 
@@ -540,21 +229,32 @@ class ParticleEmitter extends Renderable {
             this._frequencyTimer += dt;
 
             // Check for new particles launch
-            var particlesCount = this.container.children.length;
-            if ((particlesCount < this.totalParticles) && (this._frequencyTimer >= this.frequency)) {
-                if ((particlesCount + this.maxParticles) <= this.totalParticles) {
-                    this.addParticles(this.maxParticles);
+            var particlesCount = this.children.length;
+            if ((particlesCount < this.settings.totalParticles) && (this._frequencyTimer >= this.settings.frequency)) {
+                if ((particlesCount + this.settings.maxParticles) <= this.settings.totalParticles) {
+                    this.addParticles(this.settings.maxParticles);
                 }
                 else {
-                    this.addParticles(this.totalParticles - particlesCount);
+                    this.addParticles(this.settings.totalParticles - particlesCount);
                 }
-
                 this._frequencyTimer = 0;
+                this.isDirty = true;
             }
         }
-        return true;
+        return this.isDirty;
     }
 
+    /**
+     * Destroy function
+     * @ignore
+     */
+    destroy() {
+        // call the parent destroy method
+        super.destroy(arguments);
+        // clean emitter specific Properties
+        this.settings.image = undefined;
+        this.settings = undefined;
+    }
 };
 
-export { ParticleEmitterSettings, ParticleEmitter };
+export default ParticleEmitter;