sprite-anim
sprite-anim is a simple spritesheet animation engine.
Installation
npm install sprite-anim --save
Features
- 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
Browser compatibility
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
Use
Browserify
var SpriteAnim = require('sprite-anim');
AMD
require(['sprite-anim.js'], function(SpriteAnim){
});
Script tag
<script src="path/to/file/sprite-anim.js"></script>
<script>
// global variable SpriteAnim
</script>
Examples
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
Parsers
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 imagesframeSize
: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 framesframes
: an array of frames{x, y, index, width, height}
Example
var CustomParser = function(framesData){
this.numFrames = 0;
this.frames = [];
// populate frames and increment numFrames
};
Renderers
DOMRenderer
Render frame with a DOM element (background-position
).
Params
element
: DOM elementoptions
(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 elementsprite
: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
};
SpriteAnim
create instance
new SpriteAnim(parser, renderer, options)
options
(Object
)
frameRate
(Number
) Animation frame rate (default:60
)loop
(Boolean
) Iftrue
loop animation (default:false
)yoyo
(Boolean
) Iftrue
repeat from end when looping (default:false
)numFrames
(Boolean
) Force total framesmanualUpdate
(Boolean
) Iftrue
the animation will not update itself. (default:false
) You'll have to update it manually with an explicitonEnterFrame()
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