https://github.com/manuelodelain/sprite-anim
Simple spritesheet animation engine.
https://github.com/manuelodelain/sprite-anim
animation spritesheet
Last synced: 9 months ago
JSON representation
Simple spritesheet animation engine.
- Host: GitHub
- URL: https://github.com/manuelodelain/sprite-anim
- Owner: manuelodelain
- License: mit
- Created: 2015-06-01T15:04:33.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2021-04-18T17:35:07.000Z (about 5 years ago)
- Last Synced: 2025-03-17T11:21:36.682Z (over 1 year ago)
- Topics: animation, spritesheet
- Language: JavaScript
- Homepage: http://manuelodelain.github.io/sprite-anim/
- Size: 2.17 MB
- Stars: 18
- Watchers: 3
- Forks: 4
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 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](https://github.com/es-shims/es5-shim) for EcmaScript 5 methods compatibility.
## Documentation
### Use
#### Browserify
```
var SpriteAnim = require('sprite-anim');
````
#### AMD
```
require(['sprite-anim.js'], function(SpriteAnim){
});
````
#### Script tag
```
// global variable SpriteAnim
````
### 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 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
};
```
### Renderers
#### 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
};
```
### SpriteAnim
#### 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