API Docs for:
Show:

File: animation\Components.js


/**
 A component class which holds animations and logic recquired to play them.
 @class Animation
 @constructor
 */
function Animation(){
    this._animations = {};
    this._currentAnimation = null;
    this._currentFrame = 0;
    this._currentFrameTime = 0;
    this._priority = Number.NEGATIVE_INFINITY;
    this._rate = 1;
    this._finishedCallback = null;
    this._callbackData = null;
}

Animation.prototype = {
    constructor : Animation,
    _componentIdentifier : 0,
    
    /**
     Registers a new animation. Overwrites previously registered animations with the same name.
     @method add
     @param handle {AssetHandle} The animation asset handle.
     @param name {String} Name of the animation. From now on, the animation will be referenced by this name within this component.
     */
    add : function(handle, name){
        this._animations[name] = handle;
    },
    
    /**
     Removes a registered animation.
     @method remove
     @param name {String} Name of the animation.
     */
    remove : function(name){
        this._animations[name] = null;
    },
    
    /**
     Retrieves a registered animation.
     @method get
     @param name {String} Name of the animation.
     @return {AssetHandle|null|undefined} Handle to the animation asset that was registered with the given name. If the animation wasn't registered, the function will return null or undefined.
     */
    get : function(name){
        return this._animations[name];
    },
    
    /**
     Checks whether an animation with the given name was registered.
     @method has
     @param name {String} Name of the animation.
     @return {Boolean}
     */
    has : function(name){
        return Boolean(this._animations[name]);
    },
    
    /**
     Schedules playing of an animation. The new animation will be played if there's no animation currently playing or if the priority of the new animation is at least as high as the one currently playing. If the animation being played is the same as the currently playing animation, then only the rate, priority and callbacks will be set.
     @method play
     @param name {String} Name of the animation.
     @param [priority] {Number} The animation's priority. A greater number signifies greater priority. If the priority is smaller than the priority of the currently playing animation, the new animation will not be played. If not provided, defaults to Number.NEGATIVE_INFINITY.
     @param [rate] {Number} Rate at which the new animation should be played. A rate of 0.5 means that the animation will play twice as fast as specified in the asset file, while a rate of 2 means that it'll play two times slower. If this value is not provided or is less than or equal to 0, then the rate will default to 1.
     @param [finishedCallback] {Function} A function to be called when the animation finishes playing. The callback will not be called for looping animations (obviously) and animations that get overwritten by playing other animations before they can finish.
     @param [callbackData] User specified data for the callback.
     */
    play : function(name, priority, rate, finishedCallback, callbackData){
        //Set the default values for the optional parameters.
        priority = (priority !== undefined) ? priority : Number.NEGATIVE_INFINITY;
        rate = (rate > 0) ? rate : 1;
        
        var animation = this._animations[name];
        
        if(animation && (!this._currentAnimation || priority >= this._priority)){
            //If the new animation is the same as the currently playing animation,
            //then only set a new priority, rate and callback.
            if(this._currentAnimation !== animation){
                this._currentAnimation = animation;
                this._currentFrame = 0;
                this._currentFrameTime = 0;
            }
            
            this._priority = priority;
            this._rate = rate;
            this._finishedCallback = finishedCallback;
            this._callbackData = callbackData;
        }
    }
};