I was talking with Ido about memory usage in AS3, and we discovered a small weakness in the AVM’s garbage collector. If you use a functional style of programming with lots of anonymous or nested functions, here’s something to watch out for:

import flash.display.Sprite;
import flash.events.Event;

function foo():* {
    var sprite:Sprite = new Sprite();
    sprite.addEventListener(Event.ENTER_FRAME, tick);

    // this closure creates a reference to the outer scope, foo
    return function():void { }
}

function tick(event:Event):void {
    trace("tick");
}

var func:* = foo();
System.gc();
// sprite is never garbage collected, and continues to tick

sprite will not be garbage collected, even though it’s just a local variable of foo and no other references to it exist!

The issue is the anonymous function returned by foo. This closure creates a reference to the outer scope, foo. This is necessary so that you can access the outer variables from inside the nested function. For example, the inner function might have done sprite.x = 10.

Unfortunately, outer variables are still referenced and stay alive, even if you never use them inside the closure! In our case, the free variable sprite is still referenced by the closure even though it’s never used in the anonymous function. It remains ineligible for garbage collection. Notice that if we change the return to return 0, then sprite is collected and stops ticking.

Here are some tips to avoid this issue:

• Ensure that closures will be garbage collected by clearing references to them. If we eventually do func = null, then our closure is no longer reachable and will be collected, along with sprite.
• Avoid using nested functions and anonymous functions. Instead of using an anonymous inner function, we could move the function outside:

  function foo():*
  {
      return myFunc;
  }
  
  function myFunc():* { }
  

• Null out any local variables at the end of the outer function. We can set sprite = null at the end of the function since we won’t be using it any longer.

This isn’t a big issue, but it’s something to keep in mind if you’re juggling function references with chunky objects like BitmapData. Is it possible for a VM to be smart enough to reference only the objects that are actually needed, instead of pushing the entire outer scope? I’m not sure. I wonder if other VMs such as V8 handle this any better?

My buddies Shawn Tanner and Michael Swain have released Skincraft, an awesome skin creator for Minecraft. Check it out on Newgrounds:

Skincraft

I helped out with the 3D display of the Minecraft character, as well as the file sharing features of the Newgrounds API that allow people to upload their skins. I’ve been hard at work on the Newgrounds API for several months, and I think this is one of the best examples of it yet!

Tom was looking for some old school effects to use in The Room Tribute game, so I cooked up some pixel-style transitions. By creating a small BitmapData and scaling it to the entire stage, you can create many fun, chunky effects that even AS2 can handle. Now Flash can look like an ancient version of Windows…

Dithered Transitions

Click here to download the source (Flash 8+ FLA).

I don’t have many memories from when I was very young, but one sticks out clearly in my mind. My mom was shopping at the mall, with my brother and me in tow. As we walked past the Hills department store, a blast of electronic noise caught my ear. An arcade had opened in the mall, and like moths to flame, my brother and I stormed into it. To a kid, no experience is quite as visceral as walking into an arcade. And the first thing I saw was this:

The synthesized guitar, the booming drum samples, the giant showcase cabinet with the huge screen — Capcom’s Street Fighter II had an intoxicating attract mode, and immediately, I was mesmerized.

SFII is easily among the most influential video games of all time. Not only did it define the fighting game genre, it also brought on a whole new era of gaming. It signified the death of the “Golden Age” of arcade games that marked the ’80s. No longer were games about defeating the computer and getting a high score. Who cares how many dots you could eat? Man vs. machine wasn’t interesting anymore. The ultimate opponent is man itself.

Games were now a social event. How did you perform the special moves? Before the Internet era, word of mouth was the only way for these memes to spread. Quarters would line up on the arcade cabinet, each challenger attempting to dethrone the incumbent. Each player had a personality. You could play with honor. You could play cheap. You could have an ego. Your ego could be crushed. For one player, there’s a thrilling victory. For the other, agonizing defeat.

The game was wildly popular, and updates and sequels were plentiful. SF2 was ported to nearly every home console around, and new fighting games flooded the market. Within a decade, there were over a dozen games released in the Street Fighter series alone.

Each new game brought a new system to map out. Strategies would evolve, and an entire nomenclature was developed to discuss the games. Chess masters talk about discovered checks and knight forks; Street Fighters talk about tick throws and option selects. Communities grew, and rivalries flared. Eventually, nations would battle.

I’ve played the Street Fighter series for most of my life, but I was just a Kumbaya guitarist playing a scant few chords. Only in recent years have I gone in depth with the games, jumping deep down the rabbit hole and trying to get better. I regularly get together with a small group of dedicated players to go a few rounds. We’ll have fun, we’ll talk tactics, we’ll talk smack — all in an effort push the bar higher. Even in the most trivial pursuits, improvement is fulfilling.

Happy birthday, Street Fighter II.

If you’ve ever tried to add mouse wheel support to a Flash web app, it’s likely you’ve run into this problem: Scrolling the mouse wheel will scroll the web page, regardless of any mouse wheel listeners or code you have inside the Flash. There seems to be no way to easily prevent the web page from scrolling. Here’s an example.

This is a regression from AS2. In AS2, adding a mouse wheel listener would prevent the web page from scrolling. Not so in AS3. Even preventDefault doesn’t seem to help.

Currently, the best solution is to disable the mouse wheel in the browser using JavaScript such as with Liam O’Donnell’s MouseWheelTrap. Unfortunately, this solution only works if you have script access on the page that contains your Flash. In some cases, you don’t have control over where your SWF is hosted. It’d be nice if there was a Flash-side solution.

There is a little workaround that prevents the page from scrolling. If the mouse is over a TextField, and the TextField has more text than it can display, the mouse wheel will scroll the TextField, not scroll the web page! We can use this to our advantage by placing a TextField over the entire stage. Fill it with a ton of blank lines, prevent it from scrolling so it never reaches the top or bottom, and now it prevents the web page from scrolling. Here is the workaround in action.

stage.addEventListener(MouseEvent.MOUSE_WHEEL, onMouseWheel);

// fill textfield with empty lines
const NUM_LINES:uint = 1000;
var dummyText:String = "";
for(var i:uint = 0; i < NUM_LINES; i++) {
	dummyText += "\n";
}
textField.text = dummyText;
// initially scroll to middle of text, so that we can scroll in both directions
textField.scrollV = NUM_LINES/2;

function onMouseWheel(event:MouseEvent):void {
	clip.y -= event.delta;
	// prevent TextField text from scrolling,
	// so that we can scroll indefinitely
	event.preventDefault();
}

This solution has a huge problem, though. Try clicking on the blue square in the first example, and then again in the second example with the workaround. Since a TextField is covering the stage, it will steal all of your MouseEvents, including clicks and rollovers. All of your buttons and mouse events will stop working! This might be OK in some cases where you don’t need full mouse functionality, such as a game that only checks mouseX and mouseY. But is there any way to use this workaround while still maintaining other mouse functionality?

The answer is probably not. I’ve tried all sorts of crazy schemes, such as:

• setting to TextField’s width and height to 0 and making it follow the mouse,
• listening for MouseOver events on the stage and adding the TextField as a child of the object the mouse is over,
• fiddling with the TextField.mouseEnabled in ENTER_FRAME or RENDER handlers,
• redispatching MouseEvents captured by the TextField to the clips that should have received them (!)

Most of these failed to maintain normal mouse control while always preventing the web page from scrolling. The last option seemed to be successful, but that’s an awful lot of messy work just to use a mouse wheel, and who knows if it causes any other problems!

Ideally, simply calling mouseEvent.preventDefault() should prevent the web page from scrolling. It looks like this is already a feature request on Adobe’s bug database, so if this has been bothering you as well, you should vote for it to encourage Adobe to fix this issue.

Cheers to Tyler Glaiel for turning me on to this problem.

Edit – May 04, 2011

Dennis Kolyako created a clever workaround that captures the mouse wheel by loading an AS2 movie inside the AS3 movie, allowing us to get the desired AS2 mouse functionality. This seems to be the best solution, so be sure to check it out. Thanks to Gaen for pointing it out!

Everyone has been buzzing about Molehill, the new low-level 3D API that will be available in Flash Player 11. This API finally gives Flash developers the GPU acceleration that they’ve been waiting for. It’s a wrapper over OpenGL/DirectX, giving you a nice interface with a OpenGL ES 2.0 featureset. That’s right, all the Z-buffered triangles and shaders your heart desires.

Julia set rendered in Flash Player Incubator

Adobe released a public beta of Flash Player 11, so I grabbed it and tried to get my Pixel Bender Julia set plotter running in the player. Unfortunately, Adobe hasn’t yet released the latest Pixel Bender Toolkit, which you would use to compile shaders in Adobe’s shader format for use with Molehill. But then HxSL appeared, from the brilliant Nicolas Cannasse — a shader compiler released before Adobe’s official tools!

I did a quick port of the Julia set code to HxSL, and then went through and hand-optimized the assembly output. The Molehill API is still a beta, so there are some hiccups. Branches and loops aren’t available in shaders yet. HxSL currently unrolls your loops, duplicating your code. Even a small loop can only be unrolled so much before you hit the shader instruction limit — you can only have a max of 256 instructions per shader. I took a gander at Adobe’s assembler, AGALMiniAssembler, and noticed there were flow control instructions such as rep, ife, and ifg. Sadly, these aren’t yet working. You’ll get an “unimplemented” error if you try to use them. Hopefully these are implemented before release.

So right now, I’m stuck with a Julia set renderer that can only chug for a handful of iterations. If or when the flow control instructions are implemented, this shader can be optimized, and many more cool shaders could be created.

For now, check it out action or download the source! This demo requires that you have the Flash Player Incubator beta installed.

The Flash Player makes a decent effort to be forward-compatible. When you run an Flash Player 10 targeted SWF in Flash Player 9, it’ll run fine until you start using Flash Player 10 specific features. At best, the code will just fail silently or pop up an error dialog. But at worst, the file will fail to play at all! Here are some examples of features that will cause errors if the user is running an old version:

• 3D transformations.
• The Vector class.
• Dynamic audio using SampleDataEvent.
• Global error handling.
• Multitouch and accelerometer events.

Even seemingly innocuous code can cause problems, such as Event.ADDED_TO_STAGE—it was first added in Flash Player 9 Revision 1! Therefore, it’s very important to check that the user has the Flash Player version that we expect. Otherwise, you may get some nasty reviews stating that your game refuses to work.

You can check the player version using Capabilities.version. Here’s a helpful function to check that the user has the version we require. For example, calling isFlashVersion(10,1) will return true if the user is running Flash Player version 10.1 or greater.

function isFlashVersion(major:uint, minor:uint = 0, build:uint = 0, internalBuild:uint = 0):Boolean
{
    var version:Array = flash.system.Capabilities.version.split(" ")[1].split(",");
    var requiredVersion:Array = arguments;

    for (var i:uint = 0; i < requiredVersion.length; i++)
        version[i] = uint(version[i]);

    for (i = 0; i < requiredVersion.length; i++)
    {
        if (version[i] > requiredVersion[i])
            return true;
        if (version[i] < requiredVersion[i])
            return false;
    }
    return true;
}

It’s best to do a version check in your preloader before any offending code can run. Unfortunately, some features like Vector will cause Flash Player 9 to error out immediately if they are referenced anywhere on the main timeline. Therefore, the preloader should instantiate the application class indirectly, like so:

// instatiate class Game without directly referencing it
var GameClass:Class = Class( flash.utils.getDefinitionByName("Game") );
var game:Sprite = new GameClass();

This will allow your preloader to run regardless of the other content in your SWF. Now your preloader can check whether the Flash Player is the version that your SWF requires. If not, you can display a message directing the user to the Flash Player download page. This can help ensure that your Flash content reaches as many people as possible.

Memory management is tricky when working with a garbage collector. Throw in a complex display list hierarchy with lots of event handlers, and it’s definitely a challenge! It’s very easy to overlook some hidden object reference, causing objects to not be marked as garbage. Soon your memory usage is spiraling out of control! This has lead many developers such as Grant Skinner and Ted Patrick to suggest always setting useWeakReference to true when you call addEventListener.

This is indeed a good idea and can be a helpful failsafe, but I think that it fails to emphasize another important action: Always remove your event listeners. I fear that many developers may be given a false sense of security by always using weakly referenced listeners, so I’ve tried to create a clear description of how event listeners create references and how to clean them up. This assumes you have an idea of how Flash’s mark-sweep garbage collector works. If not, check out Grant’s excellent AS3 Resource Management articles, which are a must read for any Flash developer.

Event listeners and references

Let’s look at the creation of a simple event listener:

dispatcher.addEventListener(Event.COMPLETE, listener.handlerMethod);

Here we can see the two objects involved in event handling: the dispatcher and the listener. Note that they could refer to the same object. They could also be omitted, in which case they implicitly refer to “this” (i.e., the object running that line of code).

addEventListener creates a reference from the dispatcher to the listener. The reference is needed to call the handler function when the event fires. This means that listener can not be garbage collected until it is removed from the dispatcher, or until dispatcher is also eligible for garbage collection.

(a) The root holds a reference to an event dispatcher. Because the listener is still reachable in the object graph, it can not be garbage collected until (b) the listener is removed using removeEventListener, or (c) the references to the dispatcher itself are cleared, allowing for both items to be collected.

Listeners do not prevent a dispatcher from being garbage collected. References are one way, not bidirectional. If we cleared all references to dispatcher, it would have no references pointing to it. It would be eligible for garbage collection, regardless of whether we removed the listener.

(a) The root contains an object that is listening to a dispatcher. Even though someone is still listening, (b) the dispatcher is unreachable and is eligible for garbage collection, assuming no other references to the dispatcher exist.

useWeakReference

Let’s look at how useWeakReference affects things. Weak references are not traversed during mark-sweep garbage collection. Therefore, weak references will allow your listener objects to be garbage collected in certain situations where they otherwise would not. Let’s consider the common example of a Player class that would watch for key presses:

public class Player extends MovieClip {
	public function initPlayer():void {
		stage.addEventListener(KeyboardEvent.KEY_DOWN, onKeyDown);
	}

	public function onKeyDown(e:Event):void { /* ... */ }
}

Imagine that our player dies, and we want him to be cleaned up. However, the event listener creates a reference from the stage to the player. The stage is the topmost display object and is always accessible. Therefore, when the mark-sweep process runs, this event listener allows the garbage collector to hop from the stage to our player object, even if we’ve cleared all other references and removed it from the display list. Our player object will never be collected and will sit around wasting memory! But what if we set useWeakReference to true?

		stage.addEventListener(KeyboardEvent.KEY_DOWN, onKeyDown, false, 0, true);

Now, despite our listener, the garbage collector can not travel from the stage to our player object. The player will be marked as unreachable and eligible for collection. Weak references helped us out here.

(a) The player is visible on the stage, listening for keyboard presses. If the player dies and we remove him from the stage, (b) the event listener will prevent his garbage collection. (c) Using a weakly referenced listener will allow the player to be garbage collected, even if we forget to remove the listener.

However, let’s consider a different example. Imagine a shooting game where an enemy is killed when clicked by the user:

public class Game extends MovieClip {
	private var enemy:Enemy;
	public function Game() {
		enemy = new Enemy();
		addChild(enemy);
		enemy.addEventListener(MouseEvent.MOUSE_DOWN, onEnemyClicked, false, 0, true);
	}

	public function onEnemyClicked(event:Event):void
	{
		removeChild(enemy);	 // kill the enemy
		enemy = null;
	}
}

In this example, the enemy is the dispatcher, creating a reference from the enemy to the root game object. It doesn’t matter if we use a weak reference here. After our enemy dies, when the garbage collector runs, it can’t hop from the root to the enemy. The reference is in the opposite direction, from enemy to root! Therefore, the enemy doesn’t get marked and will be eligible for garbage collection, even though someone is still listening to it.

(a) The root has many references to an enemy, and is listening for an event from the enemy. When the enemy dies and is removed from the display list, (b) the enemy is unreachable and is eligible for garbage collection, even if we don't use a weak reference or remove the listener.

useWeakReference only has an effect when the listener object has a shorter lifetime than the dispatcher. Usually this happens when a “child” object is listening for events from a “parent” object. In our first example, the player was a transient child object listening to the long-lived global stage. This is the minority case—more often, an object will listen to events from child objects or itself.

Unfortunately, all of this talk misses an even bigger problem. Regardless of any use of weak references, an object may continue to dispatch and listen to events until it gets garbage collected. Since the garbage collector runs at some indeterminate point in the future (possibly never), this could take quite a while! In our first case, the stage will continue to throw KEY_DOWN events, triggering a response inside the player, even though he’s dead! For events like KEY_DOWN and ENTER_FRAME, this is a source for many subtle bugs and performance problems. We really need to remove our listeners manually!

Clean up after yourself

All of the above pitfalls are avoided if we follow a simple rule: Regardless of whether or not you use weak references, at the end of an object’s lifetime, always remove any listeners that it created. If you clear your listeners when you’re done with them, then you will both prevent your events from firing when an object is “dead”, and you will ensure that listeners are not preventing garbage collection of your objects!

Here’s a good checklist to follow when you are done with an object:

1. Remove it from the display list.
2. If it’s a MovieClip, tell it to stop().
3. Remove any event listeners that the object has created.
4. Clear any references in parent objects by setting them to null.

Implementing a dispose method on your objects makes it easy to manage your cleanup duties. Here’s some sample code illustrating these concepts:

package
{
	import flash.display.MovieClip;
	public class Game extends MovieClip
	{
		public var player:Player;

		public function Game()
		{
			player = new Player();	// creates a reference from Game to Player
			addChild(player);		// creates both a reference from Game to Player and vice versa
			player.initPlayer();	// more references created here (see below)

		}

		// all player die someday!
		public function killPlayer():void
		{
			removeChild(player);	// clear the two references created by the display list
			player.dispose();		// tell player to clear its own references and event listeners
			player = null;		// finally, get rid of the direct variable reference
		}
	}
}

package
{
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.KeyboardEvent;

	public class Player extends MovieClip
	{
		public function initPlayer():void {
			// creates a reference from the stage to player
			stage.addEventListener(KeyboardEvent.KEY_DOWN, onKeyDown);

			// creates a self-reference from player to player
			addEventListener(Event.ENTER_FRAME, onEnterFrame);
		}

		private function onKeyDown(event:Event):void	{ /* ... */ }
		private function onEnterFrame(event:Event):void	{ /* ... */ }

		public function dispose():void
		{
			// clean up after ourself!
			stop();
			stage.removeEventListener(KeyboardEvent.KEY_DOWN, onKeyDown);
			removeEventListener(Event.ENTER_FRAME, onEnterFrame);
		}
	}
}

This project was originally posted on my Newgrounds.com blog on December 4, 2008.

Near the end of 2008, Adobe released Alchemy, a toolset to cross-compile C++ into ActionScript libraries. Naturally, the first thing that popped into my mind was to try to port Doom!

Doom running in Flash

This port is based on the vanilla Doom source code for Linux. A few months later, I added Heretic and Hexen support using the original DOS source of Heretic and Hexen. These sources were released by id Software and Raven Software under the GPL. The (messy) code for my port is also released under the GPL, available on GitHub.

These type of reverse-engineering projects are always fun. It’s a blast to look through the source of an ancient game! And it’s truly an experience when the game suddenly springs to life after a late-night hacking session. It was such a trip when I first saw “R_Init: Init DOOM refresh daemon” in my Flash output window…

If I were to start again, I’d probably base it on a more modern source port like PrBoom. That way I’d gain many of the bug fixes and cool features that these ports have solved years ago!

This port did manage to win FHM’s 2009 Web Game Awards! The amount of work I did to port such an awesome game was negligible, so I decided to donate the prize to charity. Go open source!

I had the pleasure of giving a talk on ActionScript 3.0 game programming at Flash Camp Philadelphia 2009. I spoke about how games are built, the pros and cons of the standard game inheritance hierarchy, and a few alternatives to it. I also talked about some techniques such as:

• Game loop timing using getTimer()
• Decoupling game logic and animation from Flash Player’s frame rate
• Rolling your own display list for benefits such as depth sorting
• Using the Flex Builder profiler to optimize your game

A lot of these techniques are used by the newer game frameworks such as Flixel, FlashPunk, and PushButton Engine, so it’s good to have an understanding of what’s going on behind the scenes.

This talk was given on November 7, 2009 at Philadelphia University. You can download the slides and some sample code here!