AS3 Conditional compilation or #ifdef in Flash

A few days ago I came across the method of conditional compiling in Flash. If you're from a C or a C++ background, you'll probably be familiar with the #define and #ifdef directives. They're most common in a multi-platform engine and usually found deep in the math or render code. They can be highly useful and let you develop specific code depending on how the variables are set up. Up until recently, I didn't think it was possible to do this through Flash.

How does it work?

Basically, you code as normal and when you want something to be conditionally compiled, you wrap it in compile blocks like so:

CONFIG::debug
{
	// your code here
}

FlashDevelop has 3 constants by default (what doesn't it have by default?): CONFIG::debug, CONFIG::release, and CONFIG::timeStamp. debug is defined as true when we're in the Debug configuration (see the dropdown on the top toolbar), release is defined as true when in the Release configuration, and timeStamp we don't care about here. If you want to define your own, you can by simply adding a define line to the Compiler Options of your project:

The syntax is:

-define+=DS::debug,true

Where DS::debug is the variable you want to define (DS can be any namespace (DS is the name of my engine), and debug can be any name), followed by an AS3-valid literal const (true, false, 0.1, "Damian")

If you're using the Flash IDE, you can add it by going through the File > Publication Parameters, hit the Parameters button beside ActionScript 3.0 on the Flash tab, then add your constant in the Configure Constants tab. As you can see, Flash defines a CONFIG::FLASH_AUTHORING for you if you need to target it specifically for something. Also, my Flash IDE is in French; one of the side effects of living in France.

Example time!

I've put together a simple project to show how this works (download it here or from below). It has 2 classes: a Main class and a Ball class. The Ball class is just a simple class that draws a circle and has a getter/setter for it's colour. The Main class uses the amazing AS3 Game Object Editor to edit the colour of the ball in real-time. Obviously I don't want to ship the object editor with this wonderful piece of flashery, so by using conditional compilation, the code for the Main class becomes:

package 
{
	import com.divillysausages.gameobjeditor.Editor;
	import flash.display.Sprite;
	import flash.events.Event;
	
	public class Main extends Sprite 
	{
		private var m_ball:Ball = null;
		
		CONFIG::debug
		{
			// we define the editor variable in a conditional block as well, as
			// otherwise, it'll still be included when we compile. The import
			// we can ignore as Flash strips out all imports that aren't used
			// in the project
			private var m_editor:Editor = null;
		}
		
		public function Main():void 
		{			
			// create our editor
			CONFIG::debug
			{
				// this is using the AS3 Game Object Editor
				// https://bitbucket.org/divillysausages/as3-game-object-editor
				this.m_editor = new Editor( this.stage );
				this.m_editor.registerClass( Ball );
				this.m_editor.visible = true;
			}
			
			// create and add our ball
			this.m_ball = new Ball;
			this.addChild( this.m_ball );
		}
		
	}
	
}

Running the SWF in debug mode gives us the following results:

Switching over to release mode, we compile and the AS3 Game Object Editor is no longer there:

My face :|

So far, no big shakes, so why not just use a Boolean to do all this for us? Because conditional compiling has one enormous benefit: if the condition is false, the code is removed from the SWF. Compiling in Debug mode (i.e. where CONFIG::debug is true) will yield us a SWF comprised of a number of classes:

That's a lot of extra crap. Switching to Release mode (i.e. where CONFIG::debug is false so the Editor never gets created) gives us a SWF like this:

See the amazing benefit yet?

What can I do with all this?

Practically, this is incredibly useful if you're making something like a game. Level editors, cheat codes, the ability to skip levels, test functions, change scores, change properties etc, can all be enabled during Debug mode. Then, when you switch over to Release mode to release your game, all of that is magically removed. There's no need to remember to disable everything when you're finished: in the Release SWF, it simply doesn't exist. There's no worry that somebody might discover the cheat codes you added for testing and destroy your game; they don't exist any more. Want to make sure that someone can't set a property for an object (say, by hacking the SWF)? Conditional compile out the contents of the setter.

If you've ever tried to make money from your game, you'll know all about implementing 100 different versions of Ad serving, highscore tables, event tracking, site-locked content and other paraphernalia. There's no need to keep 15 different projects with all the different changes. Conditional compile it and not only is it a simple recompile to make your changes, but other versions don't include the different libraries that you're using. For example, Kongregate don't show Mochi ads, so why should that SWF include the lib? If you want to connect to the Kong chat, why should the other SWFs need that code in there?

DS::kong
{
	// do some kongregate related stuff
}
DS::mochi
{
	// do some mochi related stuff
}

Troubleshooting

One thing to keep in mind if you don't want debug or cheat classes in your final SWF is to also conditionally compile the variable declaration. If your class is something like:

package 
{
	import com.divillysausages.gameobjeditor.Editor;
	import flash.display.Sprite;
	
	public class Main extends Sprite 
	{		
		private var m_editor:Editor = null;
		
		public function Main():void 
		{
			CONFIG::debug
			{
				// create the editor
				this.m_editor = new Editor( this.stage );
				...
			}
		}
		
	}
	
}

Then the editor classes will still be compiled, as the variable declaration for m_editor is bringing them in. Change the declaration line to:

CONFIG::debug
{
	private var m_editor:Editor = null;
}

And you'll be fine. You can ignore the import statement, as Flash strips out all imports that aren't used in the file.