Particle Engine - Counters

/*:
 * @plugindesc v1.01 Extension, that comes with an assortment of counters to be used for the particle engine.
 * @author Iavra
 *
 * Changelog:
 * - 1.01: Renamed the "Steady" counter to "Interval" and added randomization options.
 *
 * @help
 * When setting an emitter's counter, you can specify one of the classes contained in this plugin, like this:
 *
 * emitter.setCounter(new IAVRA.PARTICLE.C.Blast(10));
 *
 * The example creates a Blast counter, which will create a certain number of particles, when the emitter starts and
 * no particles during runtime.
 *
 * The following counters are contained in the IAVRA.PARTICLE.C / IAVRA.PARTICLE.COUNTER namespace:
 *
 * Blast(count)                      Creates a number of particles, when the emitter starts and none during runtime.
 *                                   Can be overloaded, by supplying an array instead, which contains the range used
 *                                   to calculate a random number of particles.
 * Trigger(count)                    Creates a number of particles, whenever its "trigger" function is called. Can be
 *                                   overloaded, by supplying an array instead, which contains the range used to
 *                                   calculate a random number of particles.
 * Interval(count, interval)         Creates the given number of particles in a given interval, in frames. Both
 *                                   parameters can be overloaded by supplying an array, instead, which contains the
 *                                   range used to generate random numbers.
 * Variable(countVar, intervalVar)   Creates a number of particles at a variable rate, both of which are defined by the
 *                                   given variables.
 * Switch(counter, switchId)         Wraps another counter object and surpresses it, if the given switch is set to OFF.
 */

(function($, undefined) {
    "use strict";

    if(!$.PARTICLE) { throw new Error("This plugin depends on 'Iavra Particle - Core'."); }

    /**
     * Extends a given object with all properties from another given object. Mainly used to simplify subclassing.
     * @param {Object} base - Base object to be extended.
     * @param {Object} extend - Object containing the properties to be appended to the given base object.
     * @returns {Object} The base object, after it has been extended.
     */
    var _extend = function(base, extend) {
        for(var key in extend) { base[key] = extend[key]; }
        return base;
    };

    /**
     * Returns a random floating point number between the given minimum (inclusive) and maximum (exclusive).
     * @param {number} min - Minimum number to be generated (inclusive).
     * @param {number} max - Maximum number to be generated (exclusive).
     * @returns {number} A random number between the given minimum and maximum numbers.
     */
    var _random = function(min, max) {
        return min + (max - min) * Math.random();
    };

    //=============================================================================
    // IAVRA.PARTICLE.COUNTER
    //=============================================================================

    $.PARTICLE.COUNTER = $.PARTICLE.C = {
        Blast: function(count) { this._initialize(count); },
        Trigger: function(count) { this._initialize(count); },
        Interval: function(count, interval) { this._initialize(count, interval); },
        Variable: function(countVar, intervalVar) { this._initialize(countVar, intervalVar); },
        Switch: function(counter, switchId) { this._initialize(counter, switchId); }
    };

    //=============================================================================
    // IAVRA.PARTICLE.COUNTER.Blast
    //=============================================================================

    /**
     * A Blast counter creates a given number of particles, when the emitter starts and won't create new particles
     * afterwards.
     */
    $.PARTICLE.COUNTER.Blast.prototype = _extend(Object.create($.PARTICLE.Counter.prototype), {

        /**
         * Initializes the counter. Takes the number of particles to create as a parameter and can be overloaded, by
         * passing an array instead of a number.
         * @param {(number|number[])} count - Number of particles to create. If this is an array, its first and second
         * element are used as the lower and upper bound to calculate a random number.
         */
        _initialize: function(count) {
            if(Array.isArray(count)) {
                this._min = count[0];
                this._max = count[1];
            } else {
                this._min = this._max = count;
            }
        },

        /**
         * Gets called, when the emitter is started. Can specify any number of particles to be created at this point.
         * @param {IAVRA.PARTICLE.Emitter} emitter - The enclosing emitter instance.
         * @returns {number} Either the given count or a random number between the given minimum and maximum.
         */
        start: function(emitter) {
            return (this._min === this.max) ? this._min : _random(this._min, this._max);
        }

    });

    //=============================================================================
    // IAVRA.PARTICLE.COUNTER.Trigger
    //=============================================================================

    /**
     * A Trigger counter creates a given number of particles, whenever its "trigger" function is called.
     */
    $.PARTICLE.COUNTER.Trigger.prototype = _extend(Object.create($.PARTICLE.Counter.prototype), {

        /**
         * Initializes the counter. Takes the number of particles to create as a parameter and can be overloaded, by
         * passing an array instead of a number.
         * @param {(number|number[])} count - Number of particles to create. If this is an array, its first and second
         * element are used as the lower and upper bound to calculate a random number.
         */
        _initialize: function(count) {
            if(Array.isArray(count)) {
                this._min = count[0];
                this._max = count[1];
            } else {
                this._min = this._max = count;
            }
            this._trigger = false;
        },

        /**
         * Gets called, whenever the emitter updates. Can specify any number of particles to be created at this point.
         * @param {IAVRA.PARTICLE.Emitter} emitter - The enclosing emitter instance.
         * @returns {number|undefined} If this counter has been triggered, returns either the given count or a random
         * number between the given minimum and maximum. If not, will return undefined, which gets interpreted as 0.
         */
        update: function(emitter) {
            if(this._trigger) {
                this._trigger = false;
                return (this._min === this.max) ? this._min : _random(this._min, this._max);
            }
        },

        /**
         * Instructs the counter to create particles the next time its "update" function is called.
         */
        trigger: function() {
            this._trigger = true;
        }

    });

    //=============================================================================
    // IAVRA.PARTICLE.COUNTER.Interval
    //=============================================================================

    /**
     * An Interval counter permanently creates a number of particles via the given parameters.
     */
    $.PARTICLE.COUNTER.Interval.prototype = _extend(Object.create($.PARTICLE.Counter.prototype), {

        /**
         * Initializes the counter. Takes the number of particles to create and the emission interval as parameters.
         * @param {(number|number[])} count - Number of particles to create during each interval. If this is an array,
         * its first and second element are used as the lower and upper bound to calculate a random number.
         * @param {(number|number[])} interval - How often new particles should be created, in frames. If this is an
         * array, its first and second element are used as the lower and upper bound to calculate a random number.
         */
        _initialize: function(count, interval) {
            if(Array.isArray(count)) {
                this._minCount = count[0];
                this._maxCount = count[1];
            } else {
                this._minCount = this._maxCount = count;
            }
            if(Array.isArray(interval)) {
                this._minInt = interval[0];
                this._maxInt = interval[1];
            } else {
                this._minInt = this._maxInt = interval;
            }
            this._initTimer();
        },

        /**
         * Sets the timer to a random number between the given minimum and maximum interval.
         */
        _initTimer: function() {
            this._timer = (this._minInt === this.maxInt) ? this._minInt : _random(this._minInt, this._maxInt);
        },

        /**
         * Gets called, whenever the emitter updates. Can specify any number of particles to be created at this point.
         * @param {IAVRA.PARTICLE.Emitter} emitter - The enclosing emitter instance.
         * @returns {number|undefined} If the internal timer has reached the given interval, returns the given number
         * of particles. If not, will return undefined, which gets interpreted as 0.
         */
        update: function(emitter) {
            if(--this._timer <= 0) {
                this._initTimer();
                return (this._minCount === this.maxCount) ? this._minCount : _random(this._minCount, this._maxCount);
            }
        }

    });

    //=============================================================================
    // IAVRA.PARTICLE.COUNTER.Variable
    //=============================================================================

    /**
     * A Variable counter creates particles depending on the values stored in the given variables.
     */
    $.PARTICLE.COUNTER.Variable.prototype = _extend(Object.create($.PARTICLE.Counter.prototype), {

        /**
         * Initializes the counter. Takes the variable ids used to determine, how many particles should be created and
         * in which interval.
         * @param {number} countVar - Id of the variable, that contains the number of particles to create.
         * @param {number} intervalVar - Id of the variable containing the emission rate.
         */
        _initialize: function(countVar, intervalVar) {
            this._countVar = countVar;
            this._intervalVar = intervalVar;
            this._timer = 0;
        },

        /**
         * Gets called, whenever the emitter updates. Can specify any number of particles to be created at this point.
         * @param {IAVRA.PARTICLE.Emitter} emitter - The enclosing emitter instance.
         * @returns {number|undefined} If the internal timer has reached the interval stored in the given variable,
         * returns the number of particles defined in the other given variable. If not, will return undefined, which
         * gets interpreted as 0.
         */
        update: function(emitter) {
            if(++this._timer >= $gameVariables.value(this._intervalVar)) {
                this._timer = 0;
                return $gameVariables.value(this._countVar);
            }
        }

    });

    //=============================================================================
    // IAVRA.PARTICLE.COUNTER.Switch
    //=============================================================================

    /**
     * A Switch counter serves as a wrapper for another counter object, which will only be called, if the given switch
     * is set to true.
     */
    $.PARTICLE.COUNTER.Switch.prototype = _extend(Object.create($.PARTICLE.Counter.prototype), {

        /**
         * Initializes the counter. Takes the counter object to wrap and the switch id used to determine, whether it
         * should emit or not.
         * @param {IAVRA.PARTICLE.Counter} counter - Counter instance to be wrapped.
         * @param {number} switchId - Id of the switch, that controls the wrapped counter's emission rate.
         */
        _initialize: function(counter, switchId) {
            this._counter = counter;
            this._switchId = switchId;
        },

        /**
         * Gets called, when the emitter is started. Can specify any number of particles to be created at this point.
         * @param {IAVRA.PARTICLE.Emitter} emitter - The enclosing emitter instance.
         * @returns {number|undefined} The wrapped counter's result, if the given switch is set to true. If not, will
         * return undefined, which gets interpreted as 0.
         */
        start: function(emitter) {
            if($gameSwitches.value(this._switchId)) { return this._counter.start(emitter); }
            this._counter.start(emitter);
        },

        /**
         * Gets called, whenever the emitter updates. Can specify any number of particles to be created at this point.
         * @param {IAVRA.PARTICLE.Emitter} emitter - The enclosing emitter instance.
         * @returns {number|undefined} The wrapped counter's result, if the given switch is set to true. If not, will
         * return undefined, which gets interpreted as 0.
         */
        update: function(emitter) {
            if($gameSwitches.value(this._switchId)) { return this._counter.update(emitter); }
        }

    });

})(this.IAVRA || (this.IAVRA = {}));