Basic Sprite Sheet

Updated On: April 9, 2013

Sprite Sheet Component

A Sprite Sheet component is used for dividing, caching, and holding the individual frames of a sprite sheet image. This component is always used with a Sprite Sheet Renderer and it requires a divider to split up the sprite sheet image into individual frames. The Sprite Sheet Renderer pulls each frame from this sprite sheet base on the current value of its spriteIndex property. In GameBuilder Studio all of this is wired up for you automatically whenever you add a sprite sheet asset or swf asset with animations to the scene.

%STEP_TITLE%

Code Sample

var entity : IEntity = PBE.allocateEntity();

//Load a TexturePacker JSON-Array data file of coordinates
var sheetDivider : TexturePackerDivider = new TexturePackerDivider();
sheetDivider.jsonResource = PBE.resourceManager.load("assets/imagesheet_data.json") as JSONResource;

//Create a sprite sheet of the image atlas to be divided up
//This component caches and stores each frames data. to save memory
var sheet : SpriteSheetComponent = new SpriteSheetComponent();
sheet.filename = "assets/imagesheet.png";
sheet.divider = sheetDivider;

entity.addComponent(sheet, "SpriteSheet");

var sheetRenderer : SpriteSheetRenderer = new SpriteSheetRenderer();
sheetRenderer.spriteSheet = sheet;

entity.addComponent(sheetRenderer, "SpriteSheetRenderer");

Cell Count Divider

//Divide up a sheet based on a row, column count
var sheetDivider : CellCountDivider = new CellCountDivider();
sheetDivider.xCount = 10; //10 Columns
sheetDivider.yCount = 2; // 2 Rows

//Grab the image region based on frame Index
var regionByIndex : Rectangle = sheetDivider.getFrameArea(1);

The cell count divider will take the amount of cells from left to right and top to bottom and divide the sprite sheet image up evenly based on that count. This requries each frame to be evenly sized and placed in rows and columns for this divider to work.

Fixed Size Divider

//Divide up a sheet based on a fixed width and height
var sheetDivider : FixedSizeDivider = new FixedSizeDivider();
sheetDivider.width = 50;
sheetDivider.height = 50;
sheetDivider.horizontalSpacing = 5;
sheetDivider.verticalSpacing = 0;

//Grab the image region based on frame Index
var regionByIndex : Rectangle = sheetDivider.getFrameArea(1);

This divider will split up the sprite sheet image based on fixed width and height cell size from left to right of the entire sprite sheet image. With this divider you can also add padding to the calculation.

Texture Packer Divider

//Load a TexturePacker JSON-Array data file of coordinates
var sheetDivider : TexturePackerDivider = new TexturePackerDivider();
sheetDivider.jsonResource = PBE.resourceManager.load("assets/imagesheet_data.json") as JSONResource;

//Grab the torso image region
var region : Rectangle = sheetDivider.getFrameByName("torso");
//OR
//Grab the image region based on frame Index
var regionByIndex : Rectangle = sheetDivider.getFrameArea(1);

This is the only divider that can be used independent of a Sprite Sheet component. It loads the JSON-Array data from Texture Packer and stores a list of frame region data objects by index or by file name (without the file extension).

**Note: Keep in mind that dividers are not cached by themselves. Only when used with a Sprite Sheet component.

Releasing Cache

var spritesheet : SpriteSheetComponent = new SpriteSheetComponent();
//Setting false will not override the internal reference counter to 
//perform an immediate flush of the sprite sheet cache.
spritesheet.releaseCache(false);

You can manually release the cache of a sprite sheet by calling the above method. This is necessary to flush the store frames if there are changes to a sprite sheet during runtime with the cache property set to true. This is not done automatically because it can trigger the garbage collector which has a negative impact on runtime performance (FPS).

Follow Us For Updates