Spritesheet Tools

Matt Karl edited this page May 14, 2015 · 4 revisions

Spritesheet or texture atlases are a good way to compress complex art, instead of keeping it as vector art, where it could be performance heavy and a large amount of JavaScript. SpringRoll supports several ways of using spritesheets or texture atlases to your advantage. Note: EaselJS has SpriteSheet and Sprite classes - we made alternatives to these because of the strictness of the sprite layout required by the SpriteSheet class. The best tool we have found for generating spritesheets from separate images we have found is TexturePacker - just use the JSON Hash format, with trimming but no rotation.


springroll.easeljs.TextureAtlas is a class that represents a spritesheet. Creating one from an image and a config object (or an array of each) is simple. This class is located in the EaselJS Animation module;

// include the class
var TextureAtlas = include('springroll.easeljs.TextureAtlas');

//JSON data, from TexturePacker's JSON Hash format or Flash's JSON format, for example
var myJSON;

//The spritesheet image
var myImage;

// Create a new texture atlas from a loaded image and json object
var singleAtlas = new TextureAtlas(myImage, myJSON);

// if you have animations split into multiple atlases
var multiAtlas = new TextureAtlas([myImage, myImage2], [myJSON, myJSON2]);

// gets a Texture object
var texture = singleAtlas.getFrame("appleTree");

// gets array of Textures: 'appleEat_0000' -> 'appleEat_0005'
var textureList = singleAtlas.getFrames("appleEat_#", 0, 5);


springroll.easeljs.BitmapMovieClip is a DisplayObject with a similar API to createjs.MovieClip created from a TextureAtlas and a config object describing how to reassemble the movie clip. This class is located in the EaselJS Animation module;

// Include the classes
var TextureAtlas = include('springroll.easeljs.TextureAtlas');
var BitmapMovieClip = include('springroll.easeljs.BitmapMovieClip');

// Create a new texture atlas
var atlas = new TextureAtlas(myAtlasImage, myAtlasJSON);

// Create the bitmap movieclip pass in the atlas and the clip
// initialization data, this include things like FPS, frame labels, etc
var clip = new BitmapMovieClip(atlas, myClipJSON);

There's a convenient JSFL script to export all the data you need for a BitmapMovieClip directly from Flash. In the tools folder of SpringRoll, you will find Export BitmapMovieClip.jsfl. Running this will export each MovieClip you have selected in the library. The script will first ask what scale the MovieClip should be scaled to (using a scale of 0.5 results in a half sized spritesheet that is restored to normal size when reassembled at runtime). The script will then save the configuration JSON for the BitmapMovieClip, followed by the spritesheet for the BitmapMovieClip.


springroll.easeljs.BitmapUtils has additional static functions for easy use of spritesheets. This class is located in the EaselJS Utilities module;

loadSpriteSheet is a function designed to place a DisplayObject prototype in the global 'lib' object that is used by the code exported from Flash with Canvas documents. After a JavaScript asset file has been loaded (or without one), call this function to create or replace an entry for each sprite in the spritesheet. This allows you to combine images used in a Canvas Flash document into one spritesheet.

//JSON data, from TexturePacker's JSON Hash format or Flash's JSON format, for example
var myJSON;

//The spritesheet image
var myImage;

var BitmapUtils = include('springroll.easeljs.BitmapUtils');
BitmapUtils.loadSpriteSheet(myJSON.frames, myImage);

bitmapFromTexture is similar to loadSpriteSheet, except that it creates a single DisplayObject from a Texture from TextureAtlas, instead of creating an entry in the global 'lib' dictionary.



Another JSFL script that may be useful is Export Frame Labels.jsfl. Also located in the tools folder of SpringRoll, it exports a PNG sequence of the current timeline, but only frames with frame labels. Each image is named after the frame label. It is suggested that you create a document where you use this to export the root timeline of the document.