sprite-anim

sprite-anim is a simple spritesheet animation engine.

$3

npm install sprite-anim --save

$3

- common API (play / pause / stop / gotoAndPlay / gotoAndStop / dispose)
- initialize frames with data (JSONArrayParser), automatically with dimensions (SimpleParser) or your own custom parser
- works with DOM elements (DOMRenderer), canvas element (CanvasRenderer), off-screen canvas (OffScreenCanvasRenderer) or your own custom renderer
- optimized for multiple animations (one requestAnimationFrame for all instances)
- single animation with multiple spritesheets support

$3

IE 6+ with DOM element, IE 9+ with DOM and canvas element.
If you need to support IE 8- use es5-shim for EcmaScript 5 methods compatibility.

Documentation

$3

#### Browserify
``
var SpriteAnim = require('sprite-anim');
``

#### AMD
`
require(['sprite-anim.js'], function(SpriteAnim){
});
``

#### Script tag
`


``

$3

#### DOM element with spritesheet and frame dimensions

`
var element = document.getElementById('anim');
var renderer = new SpriteAnim.DOMRenderer(element);
var parser = new SpriteAnim.SimpleParser({width: 1410, height: 3960}, {width: 470, height: 120});
var anim = new SpriteAnim(parser, renderer, {frameRate: 25});

anim.play();
`

#### Canvas element with frames data

`
var img = new Image();

img.addEventListener('load', function(){
var element = document.getElementById('anim');
var renderer = new SpriteAnim.CanvasRenderer(element, img);
var parser = new SpriteAnim.JSONArrayParser(framesData); // framesData is your JSON data
var anim = new SpriteAnim(parser, renderer, {frameRate: 25});

anim.play();
});

img.src = 'images/anim.png';// your spritesheet image
`

$3

#### SimpleParser
Initialize frames directly with spritesheet image dimensions and frame dimensions.

##### Params
- sprite: Object {width: Number, height: Number} || HTMLImageElement (loaded image) || Array Objects with width/height values or loaded images
- frameSize: Object {width: Number, height: Number}

#### JSONArrayParser
Initialize frames with an Array of frames data, following the TexturePacker JSONArray output.

##### Params
- data: Object
- scaleFactor (optional): Number

#### Custom parser
You can implement your own parser.

A parser must have these properties :
- numFrames: number of frames
- frames: an array of frames {x, y, index, width, height}

##### Example
`
var CustomParser = function(framesData){
this.numFrames = 0;
this.frames = [];

// populate frames and increment numFrames
};
`




$3

#### DOMRenderer
Render frame with a DOM element (background-position).

##### Params
- element: DOM element
- options (optional): Object
- scaleFactor: Number
- sprite: HTMLImageElement loaded image || Array loaded images (multiple spritesheets).
Auto set background image/size.

#### CanvasRenderer
Render frame with a canvas element (drawImage).

##### Params
- canvas: canvas element
- sprite: HTMLImageElement loaded spritesheet image || || Array loaded spritesheet images (multiple spritesheets)
- options (Object):
- clearFrame (Boolean): clear frame on render

#### Custom renderer
You can implement your own renderer.

A renderer must have a render method with a parameter frame.
There is an optionnal parameter animation which is the SpriteAnim instance.
The frame param is an object with properties {x, y, index, width, height}.

##### Example
`
var CustomRenderer = function(){
};

CustomRenderer.prototype.render = function(frame, animation){
// draw the frame
};
`

$3


#### create instance
new SpriteAnim(parser, renderer, options)

##### options (Object)
- frameRate (Number)
Animation frame rate (default: 60)
- loop (Boolean)
If true loop animation (default: false)
- yoyo (Boolean)
If true repeat from end when looping (default: false)
- numFrames (Boolean)
Force total frames
- manualUpdate (Boolean)
If true the animation will not update itself. (default: false)
You'll have to update it manually with an explicit onEnterFrame() call on a custom render loop.


#### properties

##### x (Number)
Horizontal position from the top left corner of the container. (default: 0)

##### y (Number)
Vertical position from the top left corner of the container. (default: 0)

##### alpha (Number)
Alpha value of the animation. A value between 0 and 1. Currently only supported on canvas mode. (default: 1)

##### loop (Boolean)
If true loop animation (default: false)

##### yoyo (Boolean)
If true repeat from end when looping (default: false)


##### frameRate (Number)
Animation frame rate

##### numFrames (Number)
Total frames

##### currentFrame (Number)
Current frame index

##### isPlaying (Boolean)
true if the animation is playing

##### reversed (Boolean)
true if the animation is playing reversed

##### complete (Boolean)
true if the animation is complete


#### methods

##### play()
Play animation

##### pause()
Pause animation

##### stop()
Pause and reset animation (frame index = 0)

##### gotoAndPlay(frameIndex)
Go to a frame index and play animation

##### gotoAndStop(frameIndex)
Go to a frame index and pause animation

##### onEnterFrame(timeStamp)
Called internally each frame.
If you add the manualUpdate option and call this method directly in a external render loop you have to pass a timeStamp argument (from the requestAnimationFrame callback).

##### renderFrame()
Render the current frame

##### dispose()
Dispose SpriteAnim instance


#### events

##### complete
Dispatched when animation ended

##### enterFrame`
Dispatched on each frame