Canvas-sprite NPM

canvas-sprite

Render sprite animation with canvas

demo: https://codesandbox.io/s/red-dawn-m706x

Why?

Because why not ?

Even simple sprite sheet animation can be done with pure CSS, but:

the animation looks "shaking" on Android device when the element is using repsonsive unit in some case.
the animation looks "flashing" on iOS device when the sprite image's dimension is too large.

Install!

npm i -S canvas-sprite

or you can include dist/main.js with a <script /> tag, it exposes CanvasSprite to global

Usage!

Simple Case

import CanvasSprite from 'canvas-sprite';

var cs = CanvasSprite({
  canvas: document.getElementById('canvas'),
  imageUrl: './sprite.png',
  frames: 25,
  fps: 12,
  loop: true,
  onLoop: function (count) {
    console.log('have looped', count, 'times');
  },
  onEnd: function () {
    console.log('end');
  }
});

// call destroy when the canvas element is removed from DOM
cs.destroy();

Cache Management

If an url string is passed to options.imageUrl, the library has to fetch the image from the URL before display the animation, and when the image is too large, it may take too long to fetching it, this will be the case when trying to switch sprite sheet on the same canvas element. So we can pass a loaded Image to options.imageUrl to get a seamlessly switching.

import CanvasSprite, { loadImage } from 'canvas-sprite';

let cs = null;
function createAnim(image) {
  cs.destroy();
  cs = CanvasSprite({
    canvas: document.getElementById('canvas'),
    imageUrl: image,
    frames: 25,
    fps: 12,
    loop: true
  });
}

// prepare image cache
let cache = [];
Promise.all([
  loadImage('./sprite_sheet_1.png'),
  loadImage('./sprite_sheet_2.png')
])
  .then(imgs => {
    cache = imgs;
    console.log('cache is ready');
  })
  .then(() => {
    createAnim(cache[0]);
    // some time later...
    setTimeout(() => {
      createAnim(cache[1]);
    }, 10 * 1000);
  });

API!

options:

canvas (HTMLCanvasElement): the canvas we want to render the sprite, required
imageUrl (String|Image): the sprite image url or image element, required
frames (Number): the number of sprite frames, required
fps (Number): frames rendered per second, required
loop (Boolean): should sprite animation loop, default to true
onEnd (Function): function invoked when animation ends if options.loop is false
onLoop (Function): function invoked every time aniamtion loops if options.loop is true

instance methods:

play(): play animation, can be called after pause/stop
pause(): pause animation, stay in curren frame
stop(): stop animation, reset to first frame
destroy(): destroy animation, should be called when canvas element is removed(unmounted) from DOM, in case of memory leak

static methods: