Spritesheet.js

A library to use spritesheet based animations in the HTML5 canvas. Spritesheets are images that contain all the assets needed to render one (or many) 2D animations on the screen, and are comonly used in (but not limited to) videogames. This library is a fork of the one developed for one of my games (Paradux, for the Imagine Cup), so some features are quite particular and they won't be needed in most of the common usage cases. Despite that, the library pretends to be generic enough to be used in almost any web/game/app that uses spritesheets, and be platform and device independent (that is the reason why some features, as rotation, were not initially considered).

Demos

Example 1: a quick example that renders a dog in the beach.

Example 2: put on your 3d glasses to enjoy the anaglyph effect.

Example 3: learn about using the zIndex to create depth (press Space to move the cards).

Example 4: the dog example, now with static objects and 'code frames'.

Example 5: see how to use different render modes to adapt to the screen size.

Main concepts

There are four levels to consider when designing a spritesheet:

For example, when animating a person walking, there could be two states: "Idle" and "Walking". Each state could be formed by several layers: "Body", "Arms", "Legs", and some layers could be reused in both states. Each layer could have several frames with the sucessive steps of the animation. Finally, the spritesheet should contain all of them, plus a reference to "someone_walking.png".

Writing the spritesheet with XML

A XML file can describe one or multiple spritesheets and has the following structure:

<spritesheets>
 <spritesheet name="Something" src="path/something.png">
    <states>
      <state name="State1">
        <layer name="Layer1"></layer>
        ...
      </state>
      ...
    </states>
    <layers>
       <layer name="Layer1" x="0" y="0">
        <frame name="Frame1"></frame>
        ...
      </layer>
      ...
    </layers>
    <frames>
      <frame name="Frame1" x="0" y="0" w="100" h="50" t="30"></frame>
      ...
    </frames>
  </spritesheet>
  ...
</spritesheets>

You can test the animations in the viewer.

Using the library

To start using the library follow this steps:

  1. Include the .js file in your .html file.

    <script src="spritesheet.js"></script>
  2. Instantiate the library. If you want to draw on several canvases, you will need a different instance for each one.

    var canvasAnimation = new Spritesheet();
  3. Set up the library specifying a canvas and the frames per second.

    canvasAnimation.setUp(document.getElementById("canvas"), 30);
  4. Choose a buffer size (the default is 1366x768).

    canvasAnimation.setBufferSize(800, 600);
  5. Load one or several XML files with your spritesheets

    canvasAnimation.asyncload("spritesheets.xml", callback_load);
  6. Once the XML files have been loaded (you should use the callback to wait until that has happened), you can create objects that instantiate a spritesheet. Keep track of the ids generated to modify those objects.

    var object_id = canvasAnimation.addObject("Spritesheet", "State", 0, 0, 0, false, false);
  7. Set the camera position if needed.

    canvasAnimation.setCamera(-650, 0);
  8. You can modify the objects using their id, like in these examples.

    canvasAnimation.setState(object_id, "SomeState");
    canvasAnimation.setX(object_id, 50);
    canvasAnimation.moveX(20);

FAQ

Examples

Check out examples/example1.html to see a quick example that shows various features, and you should also read examples/spritesheets.xml to see the spritesheet structure.

Check out examples/example2.html to see how to use custom render modes.

Check out examples/example3.html to see how to use the Zindex to make '3d' animations.

Check out examples/example4.html to see when to use static objects and how to use custom 'code frames'.

Check out examples/example5.html to see the preloaded render modes in action.

Thanks to Silvia Barbero for allowing me to use her dog sprite!

If you have used Spritesheet.js in a project, or you have just made a nice demo, you can ask to be featured in this section!

Known bugs

There are no known bugs, if you find one please report it! (or even better, fix it yourself and submit a pull request)

Roadmap

These features will be added to the library:

These feaures are being considered:

If you have ideas for more features, or want to help implementing some of those mentioned here, pull requests are welcome!