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.

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.

How to make Facebook-AS3 API to actually work without going insane

Note that the last major change in the API was in April 2010 with the introduction of OAuth 2.0 in Facebook. At the time of this writing, version 1.6.1 is the current version of the API.

First, the setup for a web based project is a bit messy, since you need to register your Facebook app with a specific URL and put some code in the Html wrapper – for a full explanation read this post.

OAuth in AS3

Logging in a Facebook user with OAuth2 is simple enough if you use HTTP and JS. Issue a call with the AppID and permissions and it receive the access token in the JS callback function. Not so with the facebook-as3 API: you need to call Facebook.init() and then depending on the result call Facebook.login() to handle the login prompt.

Problem #1 - Facebook.init() returns (null, null)

The official documentation says Facebook.init will return a session on success and null on fail – however it actually returns only the session in the result, or null if you are not logged in. The second argument (fail object) is always null. Just this simple discovery had cost me a few days of hair pulling, so don’t rely on the docs. Yes, they are supposed to be updated frequently by Adobe but somehow this detail slipped out [facepalm].

Problem #2 –  Facebook.login() returns null regardless of actual login

Calling login right after Facebook.init() returns may not work as expected, and worse – results will vary depending on the browser and Flash player version (For me it works in Chrome and fails on IE8).

Don’t waste time on the official docs, since there is no mention of that there. It turns out that Flash player 10 imposes a security restriction (that may or may not be related to the browser) that will cause login to fail silently and return right away with null and lose connection with the login popup, which is very confusing since the API call to Facebook actually works in the browser, only not in your code [facepalm again].

My Solution

There is more than one solution to the authentication process, and it really depends on what you need. You could avoid the facebook-as3 library all together, as some developers on the forums suggested. There are no restrictions in HTTP/JS login, and it is painless. But what about the AS3 code?

After looking at a few samples, it appears that the simple solution would be to have a login button in your app, and require the user to click it to invoke the login popup. Simply put the Facebook.login call in the button handler function and it works perfectly.
However, you need to prevent subsequent calls to Facebook.login after a successful once, so make sure you hide or disable the button or face the consequences (I managed to crash IE8 with multiple login calls).  See sample code below:

	Facebook.init(APPID, onInit);
	...
 
	private function onInit(result:Object, fail:Object):void
	{
		btnLogin.visible = (result==null);
		if (result != null) {
			// We have a session
			trace("you are logged in");
		}
		else {
			trace("need to log in");
		}
	}
 
	// Login Button handler
	private function btnLogin_clickHandler(event:MouseEvent):void
	{
		Facebook.login(onLogin);
	}
 
	private function onLogin(result:Object, f:Object):void
	{
		if (result == null) trace("Access denied!!!");
		else {
			trace("Login complete.");
			btnLogin.enabled= false;
		}
	}

If anybody has a better solution I would love to hear.  Hopefully someone at Adobe will notice and modify the documentation to better reflect the reality, or even better – fix those issues inside the AS3 API so that it would be consistent with the HTTP/JS API.

Slow and heavy code is more apparent on a mobile platform – often the desktop hardware will compensate with a powerful CPU and plenty of memory so you might not even notice that your application or game is lagging. 

Intro: The Runtime

Every game or application makes use of two major resources: CPU and memory. How you use them will determine how it will run: hogging the CPU or memory will result in a slow or choppy run, and in some cases may crash the app. The following are a couple of things every decent Flash developer should understand about the Flash player and AIR runtime. By the way, every time you read ‘Flash Player’ here it refers to the AIR runtime as well.

Flash is a JIT environment (JIT= Just In Time) and uses a VM (Virtual Machine) dubbed AVM2. The Flash player uses a familiar model of frame cycles – a loop were each frame is processed and then rendered to the screen in sequence. Running on a single thread, the frame execution model divides the frame time slice into two distinct sections, one for user code execution and one for rendering content to screen (we ignore the green part for simplicity). The player tries to balance the two, in a model that is often referred to as the elastic racetrack.

Objects in memory are garbage collected, and there is very little control on when and how fast an object would be collected and released. Memory allocation and release are costly operations and best be batched together in few blocks  rather than  small objects. Also keep in mind that large single object fragment less than multiple small objects.

Now without further ado, on to  list.

10. Bad code, in general

Bad code is typically the root cause of performance problems. Simply put, if its not architected and designed to be efficient it will not be efficient. A few scenarios come to mind:

• Coding a large system piece by piece without ever considering the big picture.
• Leaving old legacy code intact long after the business requirements have changed. Again, lack of design before coding.
• Coders are pressured to meet deadlines under a tight schedule and abandon any practices, in hope of getting the job done faster – this usually has the opposite effect.

9. Using Flex when its not needed

If you choose to use Flex over pure AS3, there better be a very good reason for it. Simply because you need a few labels and a couple of buttons in your app is not reason enough. There is a huge overhead involved with the Flex component framework, both in memory and CPU usage. Treat Flex as a necessary evil and avoid it if possible – there are plenty of alternate UI component frameworks that are lighter, like MinimalComps or Reflex, to name a few. In many cases its easier to implement few UI control yourself, based on supplied graphic assets.

8. Abusing MXML in Flex Apps

If despite the above you are using Flex, try to minimize the use of MXML, and use it n high level components only. MXML markup generates code on build time, and often coders are not aware that they can actually write it themselves better.

A typical way coders abuse MXML is by nesting boxes and groups only to create a layout, each with conditional properties (left/right/top/bottom). This will code unnecessary bloated code and hog CPU cycles on every redraw, since the layout need to be recalculated across all those nested groups.

The same goes for data binding – using binding when you can simply assign a value is a sure way to overload the app, particularly when its used on dozens of fields.

7. Misusing the MVC pattern

While a good programmer knows how to use patterns, a great programmer knows when to avoid them. Bending a component so that is uses MVC is wrong if the pattern is not needed.

Take a simple widget as an example: one could separate the code into a view class with 4-10 lines of code, a mediator class with all the functionality and throw in a few command classes, each to activate a specific function on the mediator. Almost all classes will require injection and you’ll end up with 4-6 different classes.  Now, just to wire them up is more effort than the entire widget – this is over engineering:  producing pieces of code that are overly complicated where simplicity is needed.

So for small widgets and controls, opt for the simple one class combo with a few public functions, and write it with as few lines as humanly possible. Simplicity is the key, and MVC should be left for top-level components in more complex cases.

6. Not using a Tweener

Tweeners are the secret weapon of flash coders. When you need animation sequencing or delayed calls, its best to use  a tweener.  I use TweenMax and its delayedCall() method to make delayed calls with ease and zero overhead, but any other tweener will do just as good.

Speaking of performance, a tweener is almost guaranteed to work faster than any half-baked solution you cooked up when you didn’t have the time to design properly. It has its own internal timer so you never have to use one yourself.

5. Using Timers

When people ask me what is the best way to use timers, my answer is simple: don’t use them – ever.

Besides the fact that timers are inaccurate and not very easy to use, they have a certain overhead that can add up and cripple the performance of your game. Timers hook into the Flash Player environment and calculates time on each frame,  using CPU cycles on every frame per each timer that is created. These will quickly add up to slow down the app - the more timer instances linger in the system, the more you can expect slow and choppy gameplay or unresponsive UI.

As an aternative, use a tweener or simply use the ENTER_FRAME event on the stage so it would be triggered on every frame.

Just one word of warning: enter frame is a system event – to minimize impact, use it sparsely.  If you are writing a game, it’s best to use it just for one object (your main game class) and have a single centralized enter frame handler make all the subsequent calls to game objects.

4. Memory Allocation and Release

As already mentioned, allocating memory is a costly operation.Whenever you use ‘new’ to create an object, it triggers a bunch of low-level functions inside the AIR runtime/Flash player, such as heap allocation, garbage collection and buffer locking.  Its important to avoid creating and destroying objects frequently or inside the game loop. Either create them ahead of time or use Object Pooling to avoid the performance hit.

Regarding garbage collection, stick to the basics: don’t leave any references behind (especially class members) and clean up your classes so they get picked up. Frequently calling System.gc() (in AIR only) is not a good idea since it will be invoked anyway by the player, and may cause an overhead.

Pay special attention to anyscronous objects like loaders: you need to call loader.unloadAndStop() to release the loaded content.

3. Overloaded display list

The Flash Player use a deferred rendering model based on a scene graph, or a display list. This means that instead of issuing draw calls, we place display objects on the stage and the rest is done internally in the player runtime environment.On every render cycle, it traverses through the display list hierarchy top to bottom and draws every object in its place. While the implementation is internal to the player, the time it takes to draw one frame depends on the size and complexity of the display list.

One way to reduce render time is to minimize the amount of display objects – by removing any hidden or unnecessary objects. In a game you might want to keep references to the game objects and remove them from the display list when they are off-screen. Also make sure that removed object are actually disposed, by removing any references and event listeners and stopping movie clips and sounds, otherwise they will keep using CPU cycles on every frame.

2. Drawing API and Vector Rendering

Rendering in the Flash player consists mainly of rasterization and compositing, and both could form a potential bottleneck.

In compositing, alpha blending and filters are applied. Keep these under tight lid, specially filters can be extremely CPU intensive. One way to optimize filters is to compose them off screen on by drawing the filtered object into a bitmap, and then use the bitmap in place of the original object.

Rasterization is the process of drawing all vector shapes and fonts into pixels (in a bitmap). This is where the old ‘Bitmap vs Vector’ debate take place – a trade-off between memory and CPU usage exists. While vector shapes take little space they are slow to rasterize and put a toll on the CPU on every redraw. Bitmaps, on the other hand, take more space up-front but they skip the rasterization on redraw so drawing is much faster.

Bitmaps also allow for baking in post processing effects and skip the run-time filters. Since a large portion of the frame rendering is spent on rasterizing vector shapes, we can try to rasterize some elements ahead of time using off screen blitting.

Some game engines like Flixel and PushButton offer bitmap only rendering, where all display objects are rasterized in advance and then blitted to a central bitmap buffer which is the only object on the display list. With this technique rendering is faster in magnitudes, but it has its own limitations.

Also for some platforms (Mobile devices and TV), AIR has built in GPU acceleration for bitmap rendering – Many developers prefer bitmaps for this reason alone.

1. Using Events

There is no easy way to say this – the Flash event/listener model is one of the weak points in the runtime environment. It’s slow, messy, and requires extra boilerplate code to achieve the trivial. Most Flash coders tolerate it, but you don’t have to – I’ll show a few good alternatives.

So what exactly is wrong with native flash events?

Every time dispatchEvent() is called it makes a copy (or a clone) of the event object. When this happens inside the game loop you get lots of small memory allocations every frame – a sure way to cause a performance hit. From my days writing console games in C++ I was taught to avoid this scenario, and this applies in magnitudes in a JITed environment like AIR or Flash player.

Here’s a partial list of problems in flash event model:

• Custom events require new classes
• You must allocate new objects for each dispatch – a costly operation
• Registering for an event via addEventListener leaves a reference to the listener object that keeps it from being released automatically.
• It does not compare well to modern event models, such as C# events.

In short, this model is slow, heavy and inefficient. Since we are after high performance and efficient memory usage, I would strongly suggest considering an alternative. This is only true for custom events – on display objects you may still need to use Flash events for mouse, keyboard or enter frame – but you can keep these to a minimum.

A solid alternative to events are AS3 Signals,  an open source library by Robert Penner. I use them is all my projects and games. For more about signals check out this post from Flash guru Peter Elst.

Conclusion

Writing fast and efficient code in Flash and AIR requires some attention and planning, to avoid common pitfalls. Keeping the display list light and avoid costly operations inside the update loop is key to a smooth and solid performance.