I found that most of the tutorials on sprite sheets are for the Cocos2D engine (in Objective-C for iOS). Here I will show a practical and convenient way to animate sprite sheets in AS3, making the game perform well on both Flash in browser and AIR mobile.

There are a few off the shelf engines that use variations of spritesheets, among them Starling (Flash 11 only) and Flixel. These may be perfect for certain type of projects, but I decided to write my own classes to minimize the dependency on 3rd party code.

Demo

Click image to see the demo

Download the full demo code from BitBucket here.

The Tools

You would need a code IDE (FlashDevelop, FDT or Flash Builder) and an image tool that can pack textures. I use the popular TexturePacker, in my opinion the best texture tool for developers. If anyone knows anything better, please comment.

Preparing the assets

The animated sprite is created by the artist  with their animation package of choice. This is a sequence of images that form the animation frames.  In this case (and most others) all frames are the same size.

Open TexturePacker and import the individual images into the projects. Select json as the data format, check ‘Allow free sizes’ and make sure ‘Allow rotation’ is not checked. Publish the texture to the output folder. The setting I use can be seen here.

There are many different options with TexturePacker, that are out of scope of this article. For more in depth look, check out Chris Fletcher’s tutorial here.

Once published, you end up with a large PNG file – the texture sheet, and a json file to go with it.

Reading the texure with the AnimTextureSheet class

I created the AnimTextureSheet class to encapsulate a texture sheet and its data. After loading your animation assets, you get a BitmapData from the sheet PNG and a string from the json file. After decoding the json string, the function populateFrameArray serialize the frame data into an array which is then passed into the  newly created AnimTextureSheet.

	var seqRaw:Object = JSON.decode( sheetData );
	var animData:Array= [];
	populateFrameArray(animData, seqRaw.frames);
 
	// Sort
	animData.sortOn("id");
 
	// Create and initialize the tile sheet
	var tileSheet:AnimTextureSheet= new AnimTextureSheet();
	tileSheet.init(texture, animData);

Once initialized, the tille sheet is ready to go, and the  drawFrame() method can be called to blit a frame into a destination bitmap buffer.

UPDATE
When compiling with Flash Player 11 (or Flex 4.6) there is a build error due to the new native JSON parser:
Can not resolve a multiname reference unambiguously. JSON [..]
To resolve the problem, simply change the first line to read:
var seqRaw:Object =  com.adobe.serialization.json.JSON.decode( sheetData );

Play it

To actually display the animation,  we need a display object to hold the bitmap. For that purpose I created the AnimSprite class, that is based on flash.display.Bitmap. This class in only for convenience - you can create your own – it demonstrates the possible use cases for an animated sprite.

	private function createAnim():AnimSprite
	{
		var anim:AnimSprite = new AnimSprite();
 
		anim.initialize(_texSheet);
		anim.addSequence("all", arFrames, 16);
 
		anim.play("all");
		return anim;
	}
 
	// Call on enter frame event
	protected function onFrameUpdate(event:Event):void
	{
		if (pause){
			return;
		}
		for (var i:int = 0; i < arSprites.length; i++) 	{
			AnimSprite(arSprites[i]).updateAnimation();
		}
 
	}

The above code shows how AnimSprite is actually used.

1. instantiate the AnimSprite
2. initialize it with  a tile sheet
3. add one or more sequences (indexed frames) with an individual frame rate
4. add it to the stage.

To play it:

1. Call play() to start playing a sequence
2. call updateAnimation() on every frame

How it works

AnimSprite uses partial blitting technique to animate. It uses the bitmapData as a frame buffer that holds the frame image that gets displayed. On every update, the updateAnimation()  function checks if the animation frame need to advance, and if so calls advanceFrame() – that sets the dirty flag when the current frame index is changed.  The the following method is then used to draw the frame:

	protected function drawFrameInternal():void
	{
		dirty = false;
 
		bitmapData.fillRect(bitmapData.rect, 0);
		mAnimSheet.drawFrame(curIndex, bitmapData);
	}

Check out the code for more details on the AnimSprite class.

That’s pretty much it. Let me know if you find any bugs or problems.

This article is cross posted on #AltDevBlogADay. See my other articles published on #AltDevBlogADay here.

Mapping Objects and Assets

Before actually making the first level, we need to create a manifest of all game objects. These can be anything from background elements, pick-ups or characters. Most are represented by static bitmaps or sprites-sheets where the game object is displayed using a single asset.

The idea is to map a logical game object (class) to a physical asset (bitmap or simple shape). For simplicity, we assume the size of the asset defines the bounding box of the logical game object. Each entry in the manifest will pair the class name with the asset file name, and a class ID. Its recommended to use some kind of naming convention with prefixes etc.

Building the Basic Level

Next we create a level template. This is a project with an empty level that would serve as a base for all future levels. Create a new Flash project (fla) and import all your assets into the library and save the file.

Flash keeps library objects either as the source assets or movie-clips, with the latter used as a container for a display object that can be manipulated.
For each of the source assets, create a movieclip for it (using F8), and name it to match the class id in the manifest. Save the file and start dragging objects to the stage. You can define a layer for graphic elements that are not exported and place there references, guides and bitmaps from the mock up. Make sure to have a rectangle that represents the screen bounds.Use the first level as template for the rest, reusing the same library objects.

Exporting the Level

The flash project file (fla) is how a levels is saved. This would be an intermediate file that will only be used to modify the level on design time. To actually use it in the game, we need to export the level data to a format that can be loaded at runtime.

Export the level data means we serialize it to XML, which will contain entries for all instances of game objects, each with is metadata (like class name, position, rotation and size). For that, we make use of JSFL – the JavaScript Flash API that’s included with the Flash IDE.

The following JSFL script creates an XML file and saves it in the current folder. To run, use Commands -> ‘Run Command’ and then point to the script file (should be saved with jsfl extension). After the first run, the script name will appear under the ‘Commands’ menu for quick access.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

//==========================================
//
// Export all stage instances to xml
 
	var doc = fl.getDocumentDOM();
	doc.selectAll();
 
	var sel = fl.getDocumentDOM().selection;
	var myXml = "\r\n"
 
	var iLen = sel.length;
	for (var i = 0; i < iLen; i++) {
		var s = sel[i];
		if (s.instanceType != "symbol") continue;
		myXml += "    <child type='" + s.libraryItem.name + "'";
		myXml += " x='" + s.x + "' y='" + s.y + "'";
		myXml += " rotation='" + s.rotation+ "'";
		myXml += "/>\n";
	}
 
	doc.selectNone();
        myXml += "</level>";
 
	flash.outputPanel.clear();
	flash.trace(myXml);
	var exportFileName = doc.pathURI.replace(/%20/g, " ").replace(doc.name,
                                doc.name.replace(/\.fla$/, "") + ".xml"); 
 
	flash.outputPanel.save(exportFileName);
	flash.trace("File saved to " + exportFileName);

Here is a sample of the resulting file:

A major advantage of this export is the ability to easily customize the XML data by changing the script to add different properties for each entry (lines 15-18).

Loading the Level

1. Read list of game objects from XML into an array.
2. Iterate on the array. For each item:
   1. Pass the class name to a factory method to create a new instance of the object.
   2. Locate the asset (resource) associated with the object, by looking it up on the object manifest map.
   3. Call the init function on the newly created instance, to populate it with the asset and metadata.
   4. Place the object on stage
3. End

Your mileage may vary, but that should do the trick. Here I assume all game entity classes are based on one base class, and make use of polymorphism to construct and populate them.

Round Trip and Edit Cycle

As mentioned before, the level is also saved as a native ‘fla’ file, as intermediate, so it can be loaded and exported at any later time. The most effective way to edit a level is by instant round tripping between the game (preview) and the editor. Round tripping is the process of moving from runtime back to design in order to edit or modify the level data.

Round Tripping

With a build of the game ready to run and the export script in place, this is made possible.Typically, the designer will have the level editor still open after exporting the data. Running the game will load the data and serve as a preview. If the game runs on a browser its only a matter of refreshing it to reload new data. Now all that is left to do is follow the sequence:  Edit –  Export –  Preview, rinse and repeat.

Taking control of the Content

A better approach would be start working on tools and tools integration even before writing any code. Working on a 2D game like platformer or a side scroller, one of the first things you need is a decent level editor and to setup a content pipeline for game level data.
One possible solution would be to roll your own full featured editor. This would require a substantial amount of time and resources, and divert the focus for the game to tools. In my experience, this is not very practical if your goal is to get going quickly and work on the actual game.A much quicker solution would be to leverage existing editing tools to create the game levels.
One such tool is the Flash IDE (Flash CS4/CS5) – it has powerful editing features and is very easy to use. In a recent game project I managed to save time by using it to build my own levels. Since Flash is commonly used to build levels for nearly a decade, many developers found ways to customize it to their needs.

Here is my take on the issue of Stage3D/Molehill. While reading related tweets and posts, I notice a few misconceptions about Molehill – and this is something I’d like to address here.

Dude, where is my Display List?

Right from the start I felt something doesn’t feel right. If all the demos are using engines like Away3D, what’s in it for ‘plain’ flash games? Apparently, Molehill (and Flash 11) does not include GPU hardware acceleration for the Display List.

First of all a note about architecture. Flash uses a retained mode rendering model, through its Display List. It means we don’t actually draw, we place display objects on the display list (and the stage) – the rest is done by the Flash player, where the drawing actually takes place on every frame.

In contrast, Moelhill API  is a thin wrapper for OpenGL  (or Direct3D in some cases) that provides low level drawing of 3D geometry and textures, including programmable shaders. It exists outside of the flash stage, almost as a standalone system. It is not designed to support, or implement drawing of display objects.

While not without its problems, the flash display list is the core feature of Flash: a simple and easy to use scene graph that gets processed and rendered on every frame. Its what makes Flash Flash: you would not want to imagine building any games or applications without it.

Catching up to current technologies

This year we started seeing GPU hardware acceleration in JavaScript/CSS, although not on all browsers. Browser have rendering engines that can accelerate primitive drawing for vectors and font when rasterizing them to canvas. I would expect no less from the flash player.
The days when non-accelerated Display List was sufficient for developers are over. Here is what Ben Garney, a flash game heavyweight, says on his blog:

[...] I use the display list for lots of things, just like any Flash developer. It’s a useful, flexible, and powerful tool.

But when I have specific, performance oriented needs, I ditch it in favor of something I can control completely. That’s why I always use a raster pipeline – drawing all my own pixels – for my game rendering. Using BitmapData.copyPixels has a consistent, reliable cost, whereas the cost of drawing a DisplayObject hierarchy, either on stage or via draw(), is highly variable and difficult to predict in terms of both memory and CPU consumption. [...]

So developers like Ben Garney are opting to write their own renderers in order to gain better performance, but that is not an ideal long term solution. A much better one would be to utilize both multi-threading and GPU hardware acceleration for the standard flash Display List.

Hello 1993

For me, this is Deja vu all over again. It brings memories of the early 90s, were all we had was raw OpenGL or DirectX, and programming 3D was considered a black magic, some sort of witchcraft. We had to use special bitmap fonts and skimp on UI features for games, because everything was done in low-level, with no component libraries to speak of.
A lot has changed since then, both in technologies and standards. Are we are expected to use the low level Molehill or use a Molehill based 3D engine for any plain old 2D project?

1993 Ford Mustang

Bringing GPU acceleration to a small subset of flash applications just won’t cut it. Casual games that make a large part of Flash projects, need fast performing 2D display as well as complex UI. Forcing developers to shoehorn Molehill into any 2D project is just wrong. It’s not a good solution and would push more Flash developers to jump ship and look for alternatives.

GPU Acceleration for All

Don’t get me wrong: I am a 3D enthusiast myself, and did a lot of 3D programming on different games way before I started using Flash – and 3D API in flash is better than none. I simply don’t like the idea of having to choose between hardware acceleration or the Display List and not both of them together.

The next logical step for Adobe would be to build GPU hardware acceleration into the Flash Display List, so that the bottleneck of scene rendering would be removed. Yes, it carries some risks since Flash would become dependent on display driver vendors to run consistently on different platforms, but surely this can be resolved by partnering with nVidia and AMD. If done correctly, any existing AS3 code would be accelerated without any changes.