phaser/src/tween/Tween.js

/**
* @author       Richard Davey <rich@photonstorm.com>
* @copyright    2014 Photon Storm Ltd.
* @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
*/

/**
* Create a new Tween.
*
* @class Phaser.Tween
* @constructor
* @param {object} target - The Target object that will be affected by this tween.
* @param {Phaser.Game} game - Current game instance.
* @param {Phaser.TweenManager} manager - The TweenManager responsible for looking after this Tween.
*/
Phaser.Tween = function (target, game, manager) {

    /**
    * @property {Phaser.Game} game - A reference to the currently running Game.
    */
    this.game = game;

    /**
    * @property {object} target - Reference to the target object.
    */
    this.target = target;

    /**
    * @property {object} parent - Reference to the parent tween if part of a chained tween.
    */
    this.parent = null;

    /**
    * @property {Phaser.TweenManager} manager - Reference to the TweenManager.
    */
    this.manager = manager;

    this.timeline = [];

    /**
    * @property {number} duration - The duration of the tween in ms.
    * @readOnly
    * @default
    */
    this.duration = 1000;

    /**
    * @property {number} percent - A value between 0 and 1 that represents how far through the duration this tween is.
    * @readOnly
    */
    this.percent = 0;

    /**
    * @property {number} repeatCounter - If the Tween is set to repeat this contains the current repeat count.
    */
    this.repeatCounter = 0;

    /**
    * @property {boolean} yoyo - True if the Tween is set to yoyo, otherwise false.
    * @default
    */
    this.yoyo = false;

    /**
    * @property {boolean} inReverse - When a Tween is yoyoing this value holds if it's currently playing forwards (false) or in reverse (true).
    * @default
    */
    this.inReverse = false;

    /**
    * @property {number} _delay - Private delay counter.
    * @private
    * @default
    */
    this._delay = 0;

    /**
    * @property {number} startTime - The time the Tween started or null if it hasn't yet started.
    */
    this.startTime = null;

    /**
    * @property {boolean} _onStartCallbackFired - Private flag.
    * @private
    * @default
    */
    this._onStartCallbackFired = false;

    /**
    * @property {function} _onUpdateCallback - An onUpdate callback.
    * @private
    * @default null
    */
    this._onUpdateCallback = null;

    /**
    * @property {object} _onUpdateCallbackContext - The context in which to call the onUpdate callback.
    * @private
    * @default null
    */
    this._onUpdateCallbackContext = null;

    /**
    * @property {boolean} _paused - Is this Tween paused or not?
    * @private
    * @default
    */
    this._paused = false;

    /**
    * @property {number} _pausedTime - Private pause timer.
    * @private
    * @default
    */
    this._pausedTime = 0;

    /**
    * @property {boolean} _codePaused - Was the Tween paused by code or by Game focus loss?
    * @private
    */
    this._codePaused = false;

    /**
    * @property {boolean} pendingDelete - True if this Tween is ready to be deleted by the TweenManager.
    * @default
    */
    this.pendingDelete = false;

    /**
    * @property {Phaser.Signal} onStart - The onStart event is fired when the Tween begins.
    */
    this.onStart = new Phaser.Signal();

    /**
    * @property {Phaser.Signal} onLoop - The onLoop event is fired if the Tween loops.
    */
    this.onLoop = new Phaser.Signal();

    /**
    * @property {Phaser.Signal} onComplete - The onComplete event is fired when the Tween completes. Does not fire if the Tween is set to loop.
    */
    this.onComplete = new Phaser.Signal();

    /**
    * @property {boolean} isRunning - If the tween is running this is set to true, otherwise false. Tweens that are in a delayed state or waiting to start are considered as being running.
    * @default
    */
    this.isRunning = false;

    this.current = 0;

};

Phaser.Tween.prototype = {

    /**
    * Sets this tween to be a `to` tween on the properties given. A `to` tween starts at the current value and tweens to the destination value given.
    * For example a Sprite with an `x` coordinate of 100 could be tweened to `x` 200 by giving a properties object of `{ x: 200 }`.
    *
    * @method Phaser.Tween#to
    * @param {object} properties - The properties you want to tween, such as `Sprite.x` or `Sound.volume`. Given as a JavaScript object.
    * @param {number} [duration=1000] - Duration of this tween in ms.
    * @param {function} [ease=null] - Easing function. If not set it will default to Phaser.Easing.Default, which is Phaser.Easing.Linear.None by default but can be over-ridden at will.
    * @param {boolean} [autoStart=false] - Whether this tween will start automatically or not.
    * @param {number} [delay=0] - Delay before this tween will start, defaults to 0 (no delay). Value given is in ms.
    * @param {number} [repeat=0] - Should the tween automatically restart once complete? If you want it to run forever set as -1. This ignores any chained tweens.
    * @param {boolean} [yoyo=false] - A tween that yoyos will reverse itself and play backwards automatically. A yoyo'd tween doesn't fire the Tween.onComplete event, so listen for Tween.onLoop instead.
    * @return {Phaser.Tween} This Tween object.
    */
    to: function (properties, duration, ease, autoStart, delay, repeat, yoyo) {

        if (typeof duration === 'undefined') { duration = 1000; }
        if (typeof ease === 'undefined') { ease = this.easingFunction; }
        if (typeof autoStart === 'undefined') { autoStart = false; }
        if (typeof delay === 'undefined') { delay = 0; }
        if (typeof repeat === 'undefined') { repeat = 0; }
        if (typeof yoyo === 'undefined') { yoyo = false; }

        if (yoyo && repeat === 0)
        {
            repeat = 1;
        }

        this.timeline.push(new Phaser.TweenData(this).to(properties, duration, ease, autoStart, delay, repeat, yoyo));

        if (autoStart)
        {
            return this.start();
        }
        else
        {
            return this;
        }

    },

    /**
    * Sets this tween to be a `from` tween on the properties given. A `from` tween starts at the given value and tweens to the current values.
    * For example a Sprite with an `x` coordinate of 100 could be tweened from `x: 200` by giving a properties object of `{ x: 200 }`.
    *
    * @method Phaser.Tween#from
    * @param {object} properties - Properties you want to tween from.
    * @param {number} [duration=1000] - Duration of this tween in ms.
    * @param {function} [ease=null] - Easing function. If not set it will default to Phaser.Easing.Linear.None.
    * @param {boolean} [autoStart=false] - Whether this tween will start automatically or not.
    * @param {number} [delay=0] - Delay before this tween will start, defaults to 0 (no delay). Value given is in ms.
    * @param {number} [repeat=0] - Should the tween automatically restart once complete? If you want it to run forever set as Number.MAX_VALUE. This ignores any chained tweens.
    * @param {boolean} [yoyo=false] - A tween that yoyos will reverse itself and play backwards automatically. A yoyo'd tween doesn't fire the Tween.onComplete event, so listen for Tween.onLoop instead.
    * @return {Phaser.Tween} This Tween object.
    */
    from: function(properties, duration, ease, autoStart, delay, repeat, yoyo) {

        if (typeof duration === 'undefined') { duration = 1000; }
        if (typeof ease === 'undefined') { ease = this.easingFunction; }
        if (typeof autoStart === 'undefined') { autoStart = false; }
        if (typeof delay === 'undefined') { delay = 0; }
        if (typeof repeat === 'undefined') { repeat = 0; }
        if (typeof yoyo === 'undefined') { yoyo = false; }

        if (yoyo && repeat === 0)
        {
            repeat = 1;
        }

        this.timeline.push(new Phaser.TweenData(this).from(properties, duration, ease, autoStart, delay, repeat, yoyo));

        if (autoStart)
        {
            return this.start();
        }
        else
        {
            return this;
        }

    },

    /**
    * Starts the tween running. Can also be called by the autoStart parameter of `Tween.to.`
    * This sets the Tween.isRunning property to true and fires the onStartCallback if one is defined.
    * If the Tween has a delay set then nothing will start tweening until that delay has expired.
    *
    * @method Phaser.Tween#start
    * @param {number} [index=0] - If this Tween contains chained child tweens you can specify which one to start from. The default is zero, i.e. the first tween created.
    * @return {Phaser.Tween} This tween. Useful for method chaining.
    */
    start: function (index) {

        if (this.game === null || this.target === null || this.timeline.length === 0)
        {
            return this;
        }

        if (typeof index === 'undefined') { index = 0; }

        this.manager.add(this);

        this.isRunning = true;

        this._onStartCallbackFired = false;

        // this.startTime = this.game.time.time + this._delay;

        if (index < 0 || index > this.timeline.length - 1)
        {
            index = 0;
        }

        this.current = index;

        this.timeline[this.current].start();

        return this;

    },

    /**
    * Stops the tween if running and removes it from the TweenManager.
    * If called directly and there are any `onComplete` callbacks or events they are not dispatched.
    * Any chained or child tweens will be ignored.
    *
    * @method Phaser.Tween#stop
    * @return {Phaser.Tween} This tween. Useful for method chaining.
    */
    stop: function () {

        this.isRunning = false;

        this._onUpdateCallback = null;
        this._onStartCallbackFired = false;

        this.manager.remove(this);

        return this;

    },

    /**
    * Sets a delay time in ms before this tween will start.
    * The delay is invoked as soon as you call `Tween.start`.
    *
    * @method Phaser.Tween#delay
    * @param {number} time - The amount of time in ms that the Tween should wait until it begins, once `Tween.start` is called.
    * @return {Phaser.Tween} This tween. Useful for method chaining.
    */
    delay: function (time) {

        this._delay = time;

        return this;

    },

    /**
    * Sets the number of times this Tween will repeat.
    * If you have chained tweens this value sets the number of times *all* of the children will repeat before this Tween ends.
    *
    * @method Phaser.Tween#repeat
    * @param {number} total - How many times to repeat. Set to zero to remove an active repeat. Set to -1 to repeat forever.
    * @return {Phaser.Tween} This tween. Useful for method chaining.
    */
    repeat: function (total) {

        this.repeatCounter = total;

        return this;

    },

    /**
    * A Tween that has yoyo set to true will run through from its starting values to its end values and then play back in reverse from end to start.
    * Used in combination with repeat you can create endless loops.
    * If you have chained tweens this value sets the number of times *all* of the children
    *
    * @method Phaser.Tween#yoyo
    * @param {boolean} yoyo - Set to true to yoyo this tween.
    * @return {Phaser.Tween} This tween. Useful for method chaining.
    */
    yoyo: function(yoyo) {

        this.yoyo = yoyo;

        if (yoyo && this.repeatCounter === 0)
        {
            this.repeatCounter = 1;
        }

        return this;

    },

    /**
    * Set easing function this tween will use, i.e. Phaser.Easing.Linear.None.
    *
    * @method Phaser.Tween#easing
    * @param {function} easing - The easing function this tween will use, i.e. Phaser.Easing.Linear.None.
    * @return {Phaser.Tween} This tween. Useful for method chaining.
    */
    easing: function (easing) {

        this.easingFunction = easing;
        return this;

    },

    /**
    * Set interpolation function the tween will use, by default it uses Phaser.Math.linearInterpolation.
    * Also available: Phaser.Math.bezierInterpolation and Phaser.Math.catmullRomInterpolation.
    *
    * @method Phaser.Tween#interpolation
    * @param {function} interpolation - The interpolation function to use (Phaser.Math.linearInterpolation by default)
    * @return {Phaser.Tween} This tween. Useful for method chaining.
    */
    interpolation: function (interpolation) {

        this.interpolationFunction = interpolation;
        return this;

    },

    /**
    * You can chain tweens together by passing a reference to the chain function. This enables one tween to call another on completion.
    * You can pass as many tweens as you like to this function, they will each be chained in sequence.
    *
    * @method Phaser.Tween#chain
    * @return {Phaser.Tween} This tween. Useful for method chaining.
    */
    chain: function () {

        this.chainedTweens = arguments;
        return this;

    },

    /**
    * Loop a chain of tweens
    *
    * Usage:
    * game.add.tween(p).to({ x: 700 }, 1000, Phaser.Easing.Linear.None, true)
    * .to({ y: 300 }, 1000, Phaser.Easing.Linear.None)
    * .to({ x: 0 }, 1000, Phaser.Easing.Linear.None)
    * .to({ y: 0 }, 1000, Phaser.Easing.Linear.None)
    * .loop();
    * @method Phaser.Tween#loop
    * @param {boolean} [value=true] - If true this tween and any chained tweens will loop once they reach the end. Set to false to remove an active loop.
    * @return {Phaser.Tween} This tween. Useful for method chaining.
    */
    loop: function(value) {

        if (typeof value === 'undefined') { value = true; }

        this._loop = true;

        return this;

    },

    /**
    * Sets a callback to be fired each time this tween updates.
    *
    * @method Phaser.Tween#onUpdateCallback
    * @param {function} callback - The callback to invoke each time this tween is updated.
    * @param {object} callbackContext - The context in which to call the onUpdate callback.
    * @return {Phaser.Tween} This tween. Useful for method chaining.
    */
    onUpdateCallback: function (callback, callbackContext) {

        this._onUpdateCallback = callback;
        this._onUpdateCallbackContext = callbackContext;

        return this;

    },

    /**
    * Pauses the tween.
    *
    * @method Phaser.Tween#pause
    */
    pause: function () {

        this._codePaused = true;
        this._paused = true;
        this._pausedTime = this.game.time.now;

    },

    /**
    * This is called by the core Game loop. Do not call it directly, instead use Tween.pause.
    * @method Phaser.Tween#_pause
    * @private
    */
    _pause: function () {

        if (!this._codePaused)
        {
            this._paused = true;
            this._pausedTime = this.game.time.now;
        }

    },

    /**
    * Resumes a paused tween.
    *
    * @method Phaser.Tween#resume
    */
    resume: function () {

        if (this._paused)
        {
            this._paused = false;
            this._codePaused = false;

            this.startTime += (this.game.time.now - this._pausedTime);
        }

    },

    /**
    * This is called by the core Game loop. Do not call it directly, instead use Tween.pause.
    * @method Phaser.Tween#_resume
    * @private
    */
    _resume: function () {

        if (this._codePaused)
        {
            return;
        }
        else
        {
            this.startTime += this.game.time.pauseDuration;
            this._paused = false;
        }

    },

    /**
    * Core tween update function called by the TweenManager. Does not need to be invoked directly.
    *
    * @method Phaser.Tween#update
    * @param {number} time - A timestamp passed in by the TweenManager.
    * @return {boolean} false if the tween and all chained tweens have completed and should be deleted from the manager, otherwise true (still active).
    */
    update: function (time) {

        if (this.pendingDelete)
        {
            return false;
        }

        // if (this._paused || time < this.startTime)
        if (this._paused)
        {
            return true;
        }

        if (this._onStartCallbackFired === false)
        {
            this.onStart.dispatch(this.target);
            this._onStartCallbackFired = true;
        }
 
        var status = this.timeline[this.current].update(time);

        if (status === Phaser.TweenData.PENDING)
        {
            return true;
        }
        else if (status === Phaser.TweenData.RUNNING)
        {
            if (this._onUpdateCallback !== null)
            {
                this._onUpdateCallback.call(this._onUpdateCallbackContext, this, this.timeline[this.current].value, this.timeline[this.current]);
            }

            //  In case the update callback modifies this tween
            return this.isRunning;
        }
        else if (status === Phaser.TweenData.LOOPED)
        {
            this.onLoop.dispatch(this.target, this.timeline[this.current]);
            return true;
        }
        else if (status === Phaser.TweenData.COMPLETE)
        {
            if (this.current < this.timeline.length - 1)
            {
                this.current++;
                this.timeline[this.current].start();
                return true;
            }
            else
            {
                //  No more tweens in the chain
                this.isRunning = false;
                this.onComplete.dispatch(this.target, this.timeline[this.current]);
                return false;
            }

        }

    },

    /**
    * This will generate an array populated with the tweened object values from start to end.
    * It works by running the tween simulation at the given frame rate based on the values set-up in Tween.to and similar functions.
    * It ignores delay and repeat counts and any chained tweens. Just one play through of tween data is returned, including yoyo if set.
    *
    * @method Phaser.Tween#generateData
    * @param {number} [frameRate=60] - The speed in frames per second that the data should be generated at. The higher the value, the larger the array it creates.
    * @param {array} [data] - If given the generated data will be appended to this array, otherwise a new array will be returned.
    * @return {array} An array of tweened values.
    */
    generateData: function (frameRate, data) {

        if (this.game === null || this.target === null)
        {
            return null;
        }

        this.startTime = 0;

        for (var property in this._valuesEnd)
        {
            // Check if an Array was provided as property value
            if (Array.isArray(this._valuesEnd[property]))
            {
                if (this._valuesEnd[property].length === 0)
                {
                    continue;
                }

                // create a local copy of the Array with the start value at the front
                this._valuesEnd[property] = [this.target[property]].concat(this._valuesEnd[property]);
            }

            this._valuesStart[property] = this.target[property];

            if (!Array.isArray(this._valuesStart[property]))
            {
                this._valuesStart[property] *= 1.0; // Ensures we're using numbers, not strings
            }

            this._valuesStartRepeat[property] = this._valuesStart[property] || 0;
        }

        //  Simulate the tween. We will run for frameRate * (this.duration / 1000) (ms)
        var time = 0;
        var total = Math.floor(frameRate * (this.duration / 1000));
        var tick = this.duration / total;

        var output = [];

        while (total--)
        {
            var property;

            var percent = (time - this.startTime) / this.duration;
            percent = percent > 1 ? 1 : percent;

            var value = this.easingFunction(percent);
            var blob = {};

            for (property in this._valuesEnd)
            {
                var start = this._valuesStart[property] || 0;
                var end = this._valuesEnd[property];

                if (end instanceof Array)
                {
                    blob[property] = this.interpolationFunction(end, value);
                }
                else
                {
                    if (typeof end === 'string')
                    {
                        //  Parses relative end values with start as base (e.g.: +10, -3)
                        end = start + parseFloat(end, 10);
                    }
                    else if (typeof end === 'number')
                    {
                        //  Protect against non numeric properties.
                        blob[property] = start + (end - start) * value;
                    }
                }
            }

            output.push(blob);

            time += tick;
        }

        var blob = {};

        for (property in this._valuesEnd)
        {
            blob[property] = this._valuesEnd[property];
        }

        output.push(blob);

        if (this.yoyo)
        {
            var reversed = output.slice();
            reversed.reverse();
            output = output.concat(reversed);
        }

        if (typeof data !== 'undefined')
        {
            data = data.concat(output);

            return data;
        }
        else
        {
            return output;
        }

    }

};

Phaser.Tween.prototype.constructor = Phaser.Tween;