PathFollower.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 PathFollower is a virtual entity that follows the Path.
* It is usually linked to a game object such as a Sprite and it will control either the
* position of that object, or its velocity if it is a physics object.
*
* Callbacks will be triggered when certain events happen as the follower moves.  These
* may be used to aid in the creation of complex behaviours for the game objects.
*
* @class Phaser.PathFollower
* @constructor
* @param {Phaser.Path} path - The Path object which this follower is created on.
* @param {Phaser.Sprite|object} follower - The game object which this follower controls. Requires public properties: `x`, `y` for position and `rotation` for angle control (if specified).
* @param {number} [speed=1] - The current speed of this follower in pixels per frame. This value is multiplied with the Path segment speed to give the final value used.
* @param {number} [angleOffset=null] - If `null` then the PathFollower won't rotate. Otherwise it will face in the paths direction plus this offset which is given in radians.
* @param {function} [callbackAtEnd] - A callback to be invoked when the follower reaches the end of a path.
* @param {number} [physicsAdjustTime=0] - If non-zero then the follower expects to control a physics object using "arcade.moveToObject" to control velocity.
*/
Phaser.PathFollower = function (path, follower, speed, rotationOffset, angularOffset, callbackAtEnd, physicsAdjustTime) {

    if (speed === undefined) { speed = 1; }
    if (rotationOffset === undefined) { rotationOffset = 0; }
    if (angularOffset === undefined) { angularOffset = { angle: 0, distance: 0 }; }
    if (physicsAdjustTime === undefined) { physicsAdjustTime = 0; }

    Phaser.EventTarget.call(this);

    this.path = path;

    this.follower = follower;

    this._turnOffset = rotationOffset;

    this.callbackAtEnd = callbackAtEnd;

    this.physicsAdjustTime = physicsAdjustTime;

    // offset is an x,y offset from the Path unique for this PathFollower, it is added to the Path's own offset to give a final location
    this.offset = new Phaser.Point(0, 0);

    if (typeof speed === 'object')
    {
        this.speed = Phaser.Utils.extend(true, Object.create(Phaser.PathFollower.Defaults.speed), speed);
    }
    else
    {
        this.speed = Object.create(Phaser.PathFollower.Defaults.speed);

        this.speed.min = speed;
        this.speed.max = speed;
    }

    // _angularOffset is an angular offset from the Path's tangent direction, using angle (radians) and distance (pixels)
    this._angularOffset = { angle: 0, distance: 0 };

    this.setAngularOffset(angularOffset.angle, angularOffset.distance);

    // branchCount is used when the follower passes a counted PathPoint (see the Mummy Path example)
    // it is set whenever this follower passes a counted PathPoint and the count is zero
    // it decrements each time the follower passes a counted PathPoint and the count is non-zero
    // when the count reaches zero it triggers EVENT_COUNT_FINISH
    // NOTE: if there are multiple counted PathPoints this will not work as expected as there is only one count variable per follower!
    this.branchCount = 0;

    this.branchPredicate = null;

    // distance along the current Path segment
    this._currentDistance = 0;

    // PathPoint index of the start of the current Path segment
    this._currentPoint = 0;

    // Hermite curve for the current Path segment
    this._currentCurve = this.path.getCurve(this._currentPoint);

    // initialise the _pathSpeed by taking the speed of the first point on this Path
    var pp = new Phaser.PathPoint();

    if (this.path.getPathPoint(0, pp))
    {
        this._pathSpeed = pp.speed;
    }

    // set up a virtualParticle if this is controlling a Physics body instead of a simple graphic object
    if (this.physicsAdjustTime !== 0)
    {
        this.virtualParticle = new Phaser.Point(pp.x, pp.y);
    }
    else
    {
        this.virtualParticle = null;
    }

    // default maximum gap permitted between a physics based follower and its virtual particle, in pixels
    this.maximumGap = 1000;

    // process the data for the first point on this Path
    this.path.processData(this, this._currentPoint, false);

    // initialise the pause time to zero for this follower
    this._pauseTime = 0;

    this._accelerationTime = 0;

    this.yoyo = false;

    if (!follower.events)
    {
        follower.events = {};
    }

    follower.events.onPathPointReached = new Phaser.Signal(); // "follower has reached a PathPoint on the path"
    follower.events.onPathBranchReached = new Phaser.Signal(); // "follower has reached a branch and must choose a direction" (stay on this path or changePath to the branch)

    /* TODO: */
    follower.events.onCountFinished = new Phaser.Signal(); // "follower passed a counted point the specified number of times" */
    follower.events.onPathStart = new Phaser.Signal(); // NOTE: not "follower started a path" but "follower moved backwards to the start of the path"
    follower.events.onPathYoyo = new Phaser.Signal(); // "follower moved to the end of the path" but NOT if the path is looped, that generates EVENT_PATH_LOOPED instead
    follower.events.onPathEnd = new Phaser.Signal(); // "follower moved to the end of the path" but NOT if the path is looped, that generates EVENT_PATH_LOOPED instead
    follower.events.onPathLoop = new Phaser.Signal(); // "follower reached the end of a looped path and has started at the beginning again"

    follower.followerPathName = this.path.name;

    Object.defineProperty(this.speed, 'avg', {
        get: function() {
            return (this.min + this.max) / 2;
        }
    });

};

// events for PathFollower
Phaser.PathFollower.EVENT_REACHED_POINT = "event_reached_point";   // "follower has reached a PathPoint on the path"
Phaser.PathFollower.EVENT_BRANCH_CHOICE = "event_branch_choice";   // "follower has reached a branch and must choose a direction" (stay on this path or changePath to the branch)
Phaser.PathFollower.EVENT_COUNT_FINISH = "event_count_finish";     // "follower passed a counted point the specified number of times"
Phaser.PathFollower.EVENT_PATH_START = "event_path_start";         // NOTE: "a path started" but "follower moved backwards to the start of the path"
Phaser.PathFollower.EVENT_PATH_END = "event_path_end";             // "follower moved to the end of the path" but NOT if the path is looped, that generates EVENT_PATH_LOOPED instead
Phaser.PathFollower.EVENT_PATH_LOOPED = "event_path_looped";       // "follower reached the end of a looped path and has started at the beginning again"

// reduce dynamic object allocations by using this temporary Point wherever possible
Phaser.PathFollower.tempPoint = new Phaser.Point();

Phaser.PathFollower.Defaults = {
    speed: {
        min: 1,
        max: 1,
        theta: null,
        lambda: null,
        _target: null,
        _elapsed: 0,
        _current: null,
        _previous: null
    }
};

// remove all event listeners when this PathFollower is destroyed
Phaser.PathFollower.prototype.destroy = function () {

    this.follower.events.onPathPointReached.removeAll();
    this.follower.events.onPathBranchReached.removeAll();
    this.follower.events.onCountFinished.removeAll();
    this.follower.events.onPathStart.removeAll();
    this.follower.events.onPathEnd.removeAll();
    this.follower.events.onPathLoop.removeAll();

};

// update this PathFollower and move the attached graphic or physics object
// @return: false if this PathFollower should be removed from the Path's list of followers
Phaser.PathFollower.prototype.update = function () {

    // exit immediately if _pauseTime is non-zero and it's not that time yet
    if (this._pauseTime != 0)
    {
        if (game.time.now < this._pauseTime)
        {
            return true;
        }

        this._pauseTime = 0;

        if (this.follower.animations !== undefined)
        {
            // Phaser.AnimationManager doesn't check for a currentAnim before trying to set it's paused value, so I have to do it here
            if (this.follower.animations.currentAnim)
            {
                this.follower.animations.paused = false;
            }
        }
    }

    // if the follower is a physics object following a virtual particle
    var waitForFollower = false;

    if (this.physicsAdjustTime && this.virtualParticle)
    {
        // if the distance is too great, make the virtual particle wait for the follower to catch up
        if (game.physics.arcade.distanceBetween(this.follower, this.virtualParticle) >= this.maximumGap)
        {
            waitForFollower = true;
        }
    }

    // advance along the path unless we're waiting for the follower to catch up
    if (!waitForFollower)
    {
        this._currentDistance += this._calculateDistance();
    }

    // are we moving forwards or backwards?
    var direction = (this.speed.avg * this._pathSpeed) >= 0 ? 1 : -1;

    // while we're past either end of the current curve
    while ((direction == 1 && this._currentDistance >= this._currentCurve.length) || (direction == -1 && this._currentDistance < 0))
    {
        var memCurveLength = this._currentCurve.length;

        // backwards...
        if (direction == -1)
        {
            var branchTaken = false;

            // passed a point going backwards, process the data for it
            var point = this.path.processData(this, this._currentPoint, true);
            this.follower.events.onPathPointReached.dispatch(this.follower, point);
            this.takeBranchIfAvailable();
            this._currentPoint--;

            // reached the start of the path moving backwards
            if (this._currentPoint < 0)
            {
                if (this.path.loops)
                {
                    this.follower.events.onPathLoop.dispatch(point);
                    this._currentPoint = this.path.numPoints() - 1;
                }
                else
                {
                    if (!this.yoyo)
                    {
                        this.follower.events.onPathEnd.dispatch();        
                    }
                    else
                    {
                        this.follower.events.onPathYoyo.dispatch();
                        var speed = {min: this.speed.min, max: this.speed.max};
                        this.speed.min = -speed.max;
                        this.speed.max = -speed.min;
                        this._currentPoint = 0;
                        this._currentCurve = this.path.getCurve(this._currentPoint);
                        this._currentDistance = 0;
                        return true;
                    }
                }
            }

            if (!branchTaken)
            {
                // get the curve for this new point
                this._currentCurve = this.path.getCurve(this._currentPoint);

                // there isn't one, take a branch if there's one attached here
                if (!this._currentCurve)
                {
                    return this.takeBranchIfAvailable();
                }

                // move backwards to the end of the previous curve in the path
                this._currentDistance += this._currentCurve.length;
            }
        }
        else        // forwards...
        {
            this._currentPoint++;
            
            // reached the end of the path moving forwards
            if (this.path.atEnd(this._currentPoint))
            {
                if (this.path.loops)
                {
                    // the path loops
                    this.follower.events.onPathLoop.dispatch();
                    this._currentPoint = 0;
                }
                else
                {
                    // if the path doesn't loop
                    if (!this.takeBranchIfAvailable())
                    {
                        if (!this.yoyo)
                        {
                            this.follower.events.onPathEnd.dispatch();        
                        }
                        else
                        {
                            this.follower.events.onPathYoyo.dispatch();
                            var speed = {min: this.speed.min, max: this.speed.max};
                            this.speed.min = -speed.max;
                            this.speed.max = -speed.min;
                            this._currentPoint = this.path.length - 2;
                            this._currentCurve = this.path.getCurve(this._currentPoint);
                            this._currentDistance = this._currentCurve.length;
                            return true;
                        }
                    }
                }
            }

            // passed a point going forwards, process the data for the next one
            point = this.path.processData(this, this._currentPoint, false);

            this.follower.events.onPathPointReached.dispatch(this.follower, point);
            
            this.takeBranchIfAvailable();

            // move forwards to the start of the next curve in the path
            this._currentDistance -= memCurveLength;

            // get the curve for this new point
            this._currentCurve = this.path.getCurve(this._currentPoint);

            // there isn't one, take a branch if there's one attached here
            if (!this._currentCurve)
            {
                return this.takeBranchIfAvailable();
            }
        }

        // update the path speed while we have a reference to the PathPoint handy
        this._pathSpeed = point.speed;
    }

    return this.setPosition();

};

Phaser.PathFollower.prototype._calculateDistance = function () {

    if (this.speed.min === this.speed.max)
    {
        return game.time.elapsed * this.speed.avg * this._pathSpeed;
    }
    else
    {
        this.speed._elapsed += game.time.elapsed;
        this.speed._current = this.speed.current || this.speed.avg;

        if (this.speed._elapsed >= this.speed.theta)
        {
            this.speed._current = this.speed._target;
            this.speed._target = null;
            this.speed._elapsed = 0;
        }

        if (!this.speed._target )
        {
            var min = Phaser.Math.clamp(this.speed._current - (this.speed._current * this.speed.lambda), this.speed.min, this.speed.max);
            var max = Phaser.Math.clamp(this.speed._current + (this.speed._current * this.speed.lambda), this.speed.min, this.speed.max);

            this.speed._target = game.rnd.realInRange(min, max);
        }

        var step = Phaser.Math.smoothstep(this.speed._elapsed,0,this.speed.theta);
        
        return Phaser.Math.linear(this.speed._current, this.speed._target, step) * this._pathSpeed;;
    }

};

// move the attached graphic or physics object to match this PathFollower
// @return: false if this PathFollower should be removed from the Path's list of followers
Phaser.PathFollower.prototype.setPosition = function () {

    // if the follower object has been destroyed, kill this too
    if (!this.follower)
    {
        return false;
    }

    this._currentCurve.getPointWithDistance(this._currentDistance, Phaser.PathFollower.tempPoint);

    var ox = this.offset.x;
    var oy = this.offset.y;

    if (this._angularOffset.distance != 0)
    {
        var angle = (this.follower.rotation + this._angularOffset.angle);
        ox += Math.cos(angle) * this._angularOffset.distance;
        oy += Math.sin(angle) * this._angularOffset.distance;
    }

    if (this.physicsAdjustTime)
    {
        // move the virtual particle along the path
        this.virtualParticle.x = Phaser.PathFollower.tempPoint.x + ox;
        this.virtualParticle.y = Phaser.PathFollower.tempPoint.y + oy;

        // move the physics body towards the virtual particle
        if (this.follower.body)
        {
            game.physics.arcade.moveToObject(this.follower, this.virtualParticle, 100, this.physicsAdjustTime);
        }
    }
    else
    {
        // move the follower along the path by directly adjusting it's x,y coordinates
        this.follower.x = Phaser.PathFollower.tempPoint.x + ox;
        this.follower.y = Phaser.PathFollower.tempPoint.y + oy;
    }

    // if this follower should turn to follow the path, and it has a rotation member
    if (this._turnOffset !== undefined && this.follower.rotation !== undefined)
    {
        // turn to follow the path with a fixed offset of _turnOffset
        this.follower.rotation = this._currentCurve.getAngleWithDistance(this._currentDistance) + this._turnOffset;
    }

    return true;

};

// if we've reached the end of a path or a branch, take any branch that is available rather than die
// @return: true if successful, false if no branch is available
Phaser.PathFollower.prototype.takeBranchIfAvailable = function () {

    var p = new Phaser.PathPoint();

    if (this.path.getPathPoint(this._currentPoint, p))
    {
        // kill this follower if there isn't a branch for us to take
        if (!p.branchPath || !this.branchPredicate || !this.branchPredicate(p, this.path))
        {
            return false;
        }

        // changePath calls back to redo this function, exit after calling it
        
        this.changePath(p.branchPath, p.branchPointIndex);

        return true;    
    }

    return false;

};

// follow a different path
Phaser.PathFollower.prototype.changePath = function (branchPath, branchPointIndex) {

    // change to the new path
    this.path = branchPath;

    // get the speed of the new path
    this._pathSpeed = this.path.getPathPointReference(0).speed;

    // set my position on the new path
    this._currentPoint = branchPointIndex;

    // update the curve if we've moved past a Path point
    this._currentCurve = this.path.getCurve(this._currentPoint);

    // we've finished the path
    if (!this._currentCurve)
    {
        return this.takeBranchIfAvailable();
    }

    // move me to the correct position on the new curve
    this.setPosition();

};

// change this follower's x,y offset values
Phaser.PathFollower.prototype.setOffset = function (x, y) {

    // remove any prior offset from the follower's position
    this.follower.x -= this.offset.x;
    this.follower.y -= this.offset.y;

    // set the new offset for this PathFollower
    this.offset.x = x;
    this.offset.y = y;

    // add the offset into the follower's position straight away
    this.follower.x += this.offset.x;
    this.follower.y += this.offset.y;

};

// set this follower's angular offset values
Phaser.PathFollower.prototype.setAngularOffset = function (angle, distance) {

    this._angularOffset.angle = angle;
    this._angularOffset.distance = distance;

};

// cause this follower to pause for 'delay' milliseconds
Phaser.PathFollower.prototype.pause = function (delay) {

    this._pauseTime = game.time.now + delay;

    if (this.follower.animations !== undefined)
    {
        if (this.follower.animations.currentAnim)
        {
            this.follower.animations.paused = true;
        }
    }

};

Object.defineProperty(Phaser.PathFollower.prototype, 'paused', {

    get: function() {
        return !!this._pauseTime;
    },

    set: function(val) {
        if(!!val) {
            this.pause(Number.MAX_VALUE);
        } else {
            this._pauseTime = game.time.now - 1;
        }
    },

    enumerable: true,
    configurable: true

});