phaser/wip/plugins/path/Path.js

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

/**
* A Phaser.Path contains all the functions need to create and manipulate a single Path object.
* A Path is a list of PathPoint objects connected by Hermite curves.
*
* @class Phaser.Path
* @constructor
* @param {Phaser.Game} game - A reference to the Phaser.Game instance.
* @param {number} [type=Phaser.Path.CoordinateSystems.WORLD] - The coordinate system used by the Path.
* @param {boolean} [loops=false] - Should this Path loop or not when a PathFollower reaches the end of it?
*/
Phaser.Path = function (game, type, loops) {

    if (type === undefined) { type = Phaser.Path.CoordinateSystems.WORLD; }
    if (loops === undefined) { loops = false; }

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

    /**
    * @property {number} coordinateSystem - The coordinate system used by the Path.
    */
    this.coordinateSystem = type;

    /**
    * @property {boolean} loops - Should this Path loop or not when a PathFollower reaches the end of it?
    */
    this.loops = loops;

    /**
    * @property {string} cacheKey - The key of the JSON file in the cache used to define this path.
    */
    this.cacheKey = '';

    /**
    * @property {string} key - The key of the object within the JSON data. Used if there are multiple paths per JSON file.
    */
    this.key = '';

    /*
    * @property {Phaser.PathPoint} name - The name of this path.
    */
    this.name = '';

    /*
     * @property {Phaser.PathPoint} type - The Phaser.Path.PathTypes of this path.
     */
    this.type = Phaser.Path.PathTypes.PATH;

    /*
    * @property {Array} branches - A list of branches this path has.
    */
    this.branches = [];

    /**
    * @property {array} _points - A private cache of the Points on this Path.
    * @private
    */
    this._points = [];

    /**
    * @property {Phaser.Point} _offset - Default offset for PathFollowers on this path instance.
    * @private
    */
    this._offset = new Phaser.Point();

    /*
    * @property {Phaser.PathPoint} _p1 - Used for internal calculations.
    * @private
    */
    this._p1 = new Phaser.PathPoint();

    /*
    * @property {Phaser.PathPoint} _p2 - Used for internal calculations.
    * @private
    */
    this._p2 = new Phaser.PathPoint();

    /*
    * @property {Phaser.PathPoint} origin - the origin of this path. Used mostly for BRANCH paths.
    * @private
    */
    this._origin = new Phaser.Point();

};

Phaser.Path.prototype.constructor = Phaser.Path;

Phaser.Path.PathTypes = {};
Phaser.Path.BranchTypes = {};
Phaser.Path.CoordinateSystems = {};

/**
* @constant
* @type {number}
*/
Phaser.Path.PathTypes.PATH = 0;

/**
* @constant
* @type {number}
*/
Phaser.Path.PathTypes.BRANCH = 1;

/**
* @constant
* @type {number}
*/
Phaser.Path.BranchTypes.ATTACHED = 0;

/**
* @constant
* @type {number}
*/
Phaser.Path.BranchTypes.JOINED = 1;

/**
* Points are relative to the World origin.
* @constant
* @type {number}
*/
Phaser.Path.CoordinateSystems.WORLD = 1;

/**
* Points are relative to the screen origin.
* @constant
* @type {number}
*/
Phaser.Path.CoordinateSystems.SCREEN = 2;

/**
* Points are relative to the first point.
* @constant
* @type {number}
*/
Phaser.Path.CoordinateSystems.OFFSET = 3;

Phaser.Path.prototype = {

    /**
    * Initialize a Path based on the given coordinate system.
    *
    * @method Phaser.Path#create
    * @param {number|string} coordinateSystem - The Phaser.Path.CoordinateSystems type to use.
    * @param {boolean} [loops=false] - Should this Path loop or not when a PathFollower reaches the end of it?
    * @return {Phaser.Path} This Path object.
    */
    create: function (coordinateSystem, loops) {

        if (loops === undefined) { loops = false; }

        switch (coordinateSystem)
        {
            default:
                this.coordinateSystem = Phaser.Path.CoordinateSystems.WORLD;
                break;

            case 2:
            case 'SCREEN_COORDINATES':
                this.coordinateSystem = Phaser.Path.CoordinateSystems.SCREEN;
                break;

            case 3:
            case 'OFFSET_COORDINATES':
                this.coordinateSystem = Phaser.Path.CoordinateSystems.OFFSET;
                break;
        }

        this.loops = loops;

        this._points = [];

        return this;

    },

    /**
    * Clone this Path object. It clones the origin and points data.
    *
    * @method Phaser.Path#clone
    * @return {Phaser.Path} The cloned Path.
    */
    clone: function () {

        var clone = new Phaser.Path(this.coordinateSystem, this.loops);

        this.origin.clone(clone.origin);

        this.points.forEach(function(p) {
            clone._points.push(p.clone());
        });

        return clone;

    },

    /**
    * Creates a new PathPoint object, relative to the path origin, and adds it to this path.
    *
    * @method Phaser.Path#addPathPoint
    * @param {number} [x=0] - The x position of the PathPoint.
    * @param {number} [y=0] - The y position of the PathPoint.
    * @param {number} [vx=0] - The vx tangent vector value of the PathPoint.
    * @param {number} [vy=0] - The vy tangent vector value of the PathPoint.
    * @param {number} [speed=1] - The speed value of the PathPoint.
    * @param {number} [data={}] - The data object
    * @param {number} [index=null] - The index of the new path point. If not given, will add point to end of point list.
    * @return {Phaser.PathPoint} The PathPoint object that was created.
    */
    addPathPoint: function (x, y, vx, vy, speed, data, index) {

        if (x === undefined) { x = 0; }
        if (y === undefined) { y = 0; }
        if (vx === undefined) { vx = 0; }
        if (vy === undefined) { vy = 0; }

        var pp = new Phaser.PathPoint(x - this.origin.x, y - this.origin.y, vx, vy, speed, data);

        if (index !== null && index !== undefined)
        {
            this._points.splice(index, 0, pp);
        }
        else
        {
            this._points.push(pp);
        }

        return pp;

    },

    /**
    * Remove a PathPoint from this paths point list.
    *
    * @method Phaser.Path#removePathPoint
    * @param {number} [index] - The index of the PathPoint to remove.
    * @return {Phaser.PathPoint} The removed PathPoint object.
    */
    removePathPoint: function (index) {

        var p = this.getPathPointReference(index);

        if (p)
        {
            this._points.splice(index, 1);
        }

        return p;

    },

    /**
    * Set a PathPoint objects position and tangent vector.
    *
    * @method Phaser.Path#setPathPoint
    * @param {number} index - The index of the PathPoint in this paths point list.
    * @param {number} x - The x coordinate of the PathPoint.
    * @param {number} y - The y coordinate of the PathPoint.
    * @param {number} [vx] - The x coordinate of the tangent vector to create the curve from.
    * @param {number} [vy] - The y coordinate of the tangent vector to create the curve from.
    * @return {Phaser.PathPoint} A reference to the PathPoint object that was updated.
    */
    setPathPoint: function (index, x, y, vx, vy) {

        var p = this.getPathPointReference(index);

        if (p)
        {
            p.setTo(x, y, vx, vy);
        }

        return p;

    },

    /**
    * Translate all points in a path by the given point.
    *
    * @method Phaser.Path#translatePoints
    * @param {Phaser.Point|object} point - A Phaser.Point, or a Point-like Object with public `x` and `y` properties, that will be used to modify all points in this paths point list.
    * @return {Phaser.Path} This Path object.
    */
    translatePoints: function (point) {

        this._points.forEach(function(pnt) {
            pnt.x += point.x;
            pnt.y += point.y;
        });

        return this;

    },

    /**
    * Set the Path level offset which will affect all of this paths PathFollowers.
    *
    * @method Phaser.Path#setOffset
    * @param {number} x - The x offset.
    * @param {number} y - The y offset.
    * @return {Phaser.Path} This Path object.
    */
    setOffset: function (x, y) {

        this._offset.x = x;
        this._offset.y = y;

        return this;

    },

    /**
    * Get a point on the the current Path curve.
    *
    * @method Phaser.Path#getPointOnThisCurve
    * @param {Phaser.Hermite} curve - A Phaser.Hermite curve object.
    * @param {number} [t=0 .. 1.0] - The distance on the curve to get the point from. Where 0 is the start of the curve, and 1 is the end.
    * @return {Phaser.Point} A point containing the x and y values at the specified distance (t) value in the curve.
    */
    getPointOnThisCurve: function (curve, t) {

        if (!curve)
        {
            return null;
        }

        var pnt = curve.getPoint(t);

        pnt.x += this._offset.x;
        pnt.y += this._offset.y;

        return pnt;

    },

    /**
    * Gets the points on the curve representing the end points of the line segments that make up the curve.
    *
    * @method Phaser.Path#getControlPointsOnThisCurve
    * @param {Phaser.Hermite} curve - A Phaser.Hermite curve.
    * @return {array} An array of points representing the end points of 10 line segments that make up the curve.
    */
    getControlPointsOnThisCurve: function (curve) {

        var pnts = Phaser.ArrayUtils.numberArrayStep(0, 1.1, 0.1).map(function(num) {
            return this.getPointOnThisCurve(curve, num);
        }, this);

        return pnts;

    },

    /**
    * Get a PathPoint from this path. Automatically handles path looping.
    * 
    * The values from the PathPoint are copied into the given PathPoint object, which must
    * be a reference to a pre-existing PathPoint, as it's not returned by this method.
    *
    * @method Phaser.Path#getPathPoint
    * @param {number} index - The index of the point in this path to get.
    * @param {Phaser.PathPoint} point - A PathPoint object into which the found point object is cloned.
    * @return {boolean} false if the index is past the end of the path and it doesn't loop, otherwise true.
    */
    getPathPoint: function (index, point) {

        var i = this.loops ? index % this._points.length : index;

        //  If index is in the points list range
        if (this._points.length > i)
        {
            point.copy(this._points[i]);

            switch (this.coordinateSystem)
            {
                case Phaser.Path.CoordinateSystems.SCREEN:

                    point.x -= this.game.camera.x;
                    point.y -= this.game.camera.y;
                    break;

                case Phaser.Path.CoordinateSystems.OFFSET:

                    point.x += this.origin.x;
                    point.y += this.origin.y;
                    break;
            }

            return true;
        }
        else
        {
            //  The path doesn't loop and the index is out of range, so fail
            return false;
        }

    },

    /**
    * Get a reference to a PathPoint from this Path, handle path looping.
    * 
    * NOTE: because this is a PathPoint reference, it does not take into account the coordinateSystem selected, it will be WORLD, or OFFSET unmodified
    *
    * @method Phaser.Path#getPathPointReference
    * @param {number} index - The index of the point in this path to get.
    * @return {Phaser.PathPoint} A reference to the PathPoint object in this Path, or null if index is out of range.
    */
    getPathPointReference: function (index) {

        var i = this.loops ? index % this._points.length : index;

        //  If index is in the points list range
        if (this._points.length > i)
        {
            return this._points[i];
        }

        //  The path doesn't loop and the index is out of range, fail
        return null;

    },

    /**
    * Get the curve from the given point index to the next.
    * 
    * If the curve has been created previously, use that definition again, otherwise calculate it now.
    *
    * @method Phaser.Path#getCurve
    * @param {number} [index=0] - The index of the point in this path to get the curve from.
    * @return {Phaser.Hermite} A new Hermite object representing the curve starting at the 'index' path point.
    */
    getCurve: function (index) {

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

        //  Beginning of the curve
        if (!this.getPathPoint(index, this._p1))
        {
            return null;
        }

        //  Has this curve been calculated already?
        if (this._p1.curve)
        {
            return this._p1.curve;
        }

        //  End of the curve
        if (!this.getPathPoint(index + 1, this._p2))
        {
            if (!this._p1.branchPath)
            {
                return null;
            }

            //  We joined another Path
            var newPath = this._p1.branchPath;
            var joinIndex = this._p1.branchPointIndex;

            if (!newPath.getPathPoint(joinIndex + 1, this._p2))
            {
                return null;
            }
        }

        //  Create and return the new Hermite object
        this._p1.curve = new Phaser.Hermite(this._p1.x, this._p1.y, this._p2.x, this._p2.y, this._p1.vx, this._p1.vy, this._p2.vx, this._p2.vy);

        this.curvePointIndex = index;

        return this._p1.curve;

    },

    /**
    * Find the first matching PathPoint in this path.
    * It works by taking the given PathPoint object, and then iterating through all points
    * in this Path until it finds one with the same values, then returns the index to it.
    *
    * @method Phaser.Path#pointIndex
    * @param {Phaser.PathPoint} pathPoint - The PathPoint object that will have its values compared to all the points in this Path.
    * @return {number} The index of the PathPoint in this Path if an equal match is found, or -1 if no match is found.
    */
    pointIndex: function (pathPoint) {

        var l = this._points.length;

        for (var i = 0; i < l; i++)
        {
            if (this.coordinateSystem === Phaser.Path.CoordinateSystems.OFFSET && i !== 0)
            {
                if (pathPoint.equals(this._points[i], this._points[0].x, this._points[0].y))
                {
                    return i;
                }
            }
            else
            {
                if (pathPoint.equals(this._points[i]))
                {
                    return i;
                }
            }
        }

        return -1;

    },

    /**
    * Is the given PathPoint index the end of this path?
    *
    * @method Phaser.Path#atEnd
    * @param {number} index - The index of the PathPoint to test.
    * @return {boolean} true if index is the last point in this path.
    */
    atEnd: function (index) {

        //  If the path loops, the end of the path is the end of the last curve
        if (this.loops)
        {
            return (index === this._points.length);
        }

        //  If the path doesn't loop, the end of the path is the last point on it
        return (index === this._points.length - 1);

    },

    /**
    * The total number of PathPoints in this Path.
    * 
    * @method Phaser.Path#numPoints
    * return {number} The total number of PathPoints in this Path.
    */
    numPoints: function () {

        return this._points.length;

    },

    /*
    *  DATA PROCESSING
    */

    /**
    * Process the data associated with a point on this Path.
    * Used by Phaser.PathFollower objects as they pass each control point.
    * 
    * @method Phaser.Path#processData
    * @param {Phaser.PathFollower} follower - The PathFollower that is processing the data.
    * @param {number} pathPointIndex - The index of the path point to process.
    * @param {boolean} reversing - Whether or not the follower is traversing the path in reverse.
    * @return {Phaser.PathPoint} The PathPoint that has been processed.
    */
    processData: function (follower, pathPointIndex, reversing) {

        if (this.getPathPoint(pathPointIndex, this._p1))
        {
            //  If there is a branch that can be taken from this point, 
            //  trigger an event to decide whether to take it or stay on the current path.
            //  Branches are forwards facing so they are ignored when the follower is reversing.
            if (this._p1.branchPath && !reversing)
            {
                follower.dispatchEvent({
                    type: Phaser.PathFollower.EVENT_BRANCH_CHOICE,
                    target: follower,
                    data: this._p1.clone()
                });
            }

            //  If there is information in the data member of this point
            if (this._p1.data && this._p1.data.type)
            {
                switch (this._p1.data.type)
                {
                    case Phaser.PathPoint.DATA_PAUSE:

                        follower.pause(this._p1.data.value);
                        break;

                    case Phaser.PathPoint.DATA_COUNTER:

                        // first time past, set the count
                        if (follower.branchCount === 0)
                        {
                            follower.branchCount = this._p1.data.value;
                        }
                        else
                        {
                            //  After that decrease the count
                            follower.branchCount--;

                            if (follower.branchCount <= 0)
                            {
                                follower.branchCount = 0;

                                //  Trigger event when counter expires
                                follower.dispatchEvent({
                                    type: Phaser.PathFollower.EVENT_COUNT_FINISH,
                                    target: follower,
                                    data: this._p1.clone()
                                });
                            }
                        }
                        break;
                }
            }

            //  Trigger event when passing any point on the path
            follower.dispatchEvent({
                type: Phaser.PathFollower.EVENT_REACHED_POINT,
                target: follower,
                data: this._p1.clone()
            });
        }

        return this._p1;

    },

    /**
    * If your Path has 3 points or more, this will walk through it and auto-smooth them out.
    * Note: It ignores branches.
    *
    * @method Phaser.Path#smooth
    * @return {Phaser.Path} This Path object.
    */
    smooth: function () {

        if (this._points.length === 0)
        {
            return this;
        }

        var i;
        var thisPoint;
        var p1;
        var p2;
        var dx;
        var dy;

        for (i = 1; i < this._points.length - 1; i++)
        {
            thisPoint = this.getPathPointReference(i);

            p1 = this.getPathPointReference(i - 1);
            p2 = this.getPathPointReference(i + 1);

            dx = p2.x - p1.x;
            dy = p2.y - p1.y;

            thisPoint.setTangent(dx, dy);
        }

        if (this.loops)
        {
            i = this._points.length - 1;

            thisPoint = this.getPathPointReference(i);

            p1 = this.getPathPointReference(i - 1);
            p2 = this.getPathPointReference(0);

            dx = p2.x - p1.x;
            dy = p2.y - p1.y;

            thisPoint.setTangent(dx, dy);

            i = 0;

            thisPoint = this.getPathPointReference(i);

            p1 = this.getPathPointReference(this._points.length - 1);
            p2 = this.getPathPointReference(1);

            dx = p2.x - p1.x;
            dy = p2.y - p1.y;

            thisPoint.setTangent(dx, dy);
        }

        return this;

    },

    /**
    * Draw the path on given canvas context. Used for debugging.
    * 
    * @method Phaser.Path#debug
    * @param {CanvasContext2D} ctx - The canvas context to draw the path on.
    * @param {boolean} [active=false] - Whether or not to highlight the active segments of this Path or not.
    * @return {Phaser.Path} This Path object.
    */
    debug: function (ctx, active) {

        var lineColor = '#333333';

        if (active)
        {
            lineColor = '#ffff00';
        }

        if (this._points.length === 0)
        {
            return this;
        }

        this._p1.setTo(0, 0);

        //  Draw the lines

        var lastPoint = this._points.length;

        if (!this.loops)
        {
            lastPoint--;
        }

        var p = new Phaser.PathPoint();

        for (var i = 0; i < lastPoint; i++)
        {
            var curve = this.getCurve(i);

            this.getPathPoint(i, p);

            ctx.lineWidth = 2;
            ctx.strokeStyle = 'rgb(100, 0, 250)';

            ctx.save();

            //  Control Points
            var controlPoints = this.getControlPointsOnThisCurve(curve);

            //  Draw lines
            ctx.beginPath();

            controlPoints.forEach(function(pnt, index) {

                if (!!pnt)
                {
                    if (index === 0)
                    {
                        ctx.moveTo(pnt.x, pnt.y);
                    }
                    else
                    {
                        ctx.lineTo(pnt.x, pnt.y);
                    }
                }

            });

            ctx.stroke();
            ctx.closePath();

            if (p.active)
            {
                ctx.fillStyle = '#ffffff';
                ctx.strokeStyle = '#333333';
                ctx.lineWidth = 1;

                //  Copy control points to the point object
                this.getPathPointReference(i).controlPoints = controlPoints;

                controlPoints.forEach(function(pnt) {

                    ctx.beginPath();

                    ctx.arc(pnt.x, pnt.y, 3, 0, Math.PI * 2);
                    ctx.fill();
                    ctx.stroke();

                    ctx.closePath();

                });
            }

            ctx.restore();
        }
        
        return this;

    },

    /**
    * Serializes this Path into a JSON object and returns it.
    * 
    * @methods Phaser.Path#toJSON
    * @return {Object} A JSON object representing this Path.
    */
    toJSON: function () {

        return {
            name: this.name,
            id: this.id,
            type: this.type,
            coordinateSystem: this.coordinateSystem,
            loops: this.loops,
            speed: 1,
            pointList: this._points.map(function(p) {
                return p.toJSON();
            }),
        };

    }

};

/**
* @property {Array} - The list of PathPoints that make up this path.
* @readonly
*/
Object.defineProperty(Phaser.Path.prototype, 'points', {

    get: function () {

        return this._points;

    }

});

/**
* @property {number} - The number of points in this path.
* @readonly
*/
Object.defineProperty(Phaser.Path.prototype, 'length', {

    get: function () {

        return this._points.length;

    }

});

/**
* @property {Phaser.Point} - The origin of the path.
*/
Object.defineProperty(Phaser.Path.prototype, 'origin', {

    get: function() {

        return this._origin;

    },

    set: function (val) {

        this._origin.setTo(val.x, val.y);

    }

});