Posted in ActionScript

More then two years ago I wrote a guide on how to use TextMate for developing ActionScript 3.0 projects using the free Adobe Flex SDK. It is the most popular blog post on my site until today. As with many other step-by-step tutorials, it has become outdated though. The good news is that it has become much easier to setup TextMate for AS3. Here’s the new way of doing it:

1. If you don’t already own it, download and install the trial version of TextMate from the Macromates website. If you are new to TextMate have a look at the online manual to familiarize yourself with the basic functions of the editor.

2. Download the free Flex SDK from the Adobe Open Source website. The latest stable and tested version at the time of writing is Flex SDK 4 Release. Move the extracted folder into your Developer/SDKs folder. If those two folders don’t exist yet, create them at the root of your harddrive.

3. Download Simon Gregory’s ActionScript 3 bundle for TextMate from GitHub. Unzip the downloaded file. Rename the folder to ActionScript 3.tmbundle and double-click it. TextMate will install the bundle and add it to the Bundle Menu.

4. Now let’s set up a new ActionScript project in TextMate. Select File→New Project from the menu, create a new folder for your project in the Finder and drag it in the TextMate Project Drawer. Click somewhere in the Project Drawer so that the new folder is not selected. Then click on the info button located in the bottom of the Project Drawer. Add two shell variables so that the ActionScript Bundle knows where to look for your files:

TM_FLEX_FILE_SPECS    src/Main.as
TM_FLEX_OUTPUT        bin/Main.swf

5. For compilation we want to use the faster Flex Compiler Shell (fcsh) instead of the default mxmlc compiler. To enable it go to TextMate→Preferences→Advanced→Shell Variables and add a new global variable:

TM_FLEX_USE_FCSH    true

6. Let’s write a simple “Hello World” application. Create two new folders named bin and src in your project directory. Then create a new file in the src folder and name it Main.as. It should look something like this:

package
{        
    import flash.display.Sprite;
    import flash.text.TextField;

    [SWF( backgroundColor='0xFFFFFF', frameRate='30', width='200', height='200')]

    public class Main extends Sprite
    {
        private var textField: TextField;

        public function Main()
        {
            textField = new TextField();
            textField.text = "Hello World.";

            addChild(textField);
        }        
    }
}

7. Make sure that ActionScript 3 is selected in the language dropdown menu and then save your project from the file menu. Press Apple+B to compile the main class. This will open the terminal and start up the Flex Compiler Shell. You will find the generated Main.swf in the bin folder.

8. Open the Main.swf with the Flash Player. If you have not installed it yet, you can find it in your Flex SDK installation under runtimes/player/10/mac/Flash Player.app.zip.

In our AS3-only game projects we always ran into the same issues regarding the sound assets. Often we wanted to try out a new sound or adjust the volume of a sound in the context of the actual game to see if it would fit in. This would require our sound designer Martin to send me the new sound file, or tell me “please make this sound +5% louder”. I would do the change, recompile the SWF and send it back to him. To achive a good result we would have to do this cycle a couple of times, which was very time-consuming and unsatisfing for both of us.

So I decided to write a little sound helper class called SoundControl to make things easier and more straightforward. Here’s how it works:

1. An XML config file is used to store all properties (id, file, volume, pan, startTime and loops) for the sound assets. This makes it easy to do changes directly, like trying out another sound or adjusting the volume. The startTime which is measured in milliseconds is especially important if you want to loop a mp3 file, since they always have a small gap at the beginning. You can measure this gap in any visual audio editor (such as Audacity or Adobe Soundbooth) and use the length of the gap as the startTime to loop the sound gaplessly.

<soundConfig embedSounds="false">
    <sound>
        <id>HelloWorld</id>
        <file>../assets/mp3/HelloWorld.mp3</file>
        <volume>0.5</volume>
        <pan>0</pan>
        <startTime>0</startTime>
        <loops>10000</loops>
    </sound>
</soundConfig>

2. You can choose between embedding the sounds in your SWF or to load them dynamically by setting the embedSounds property in the soundConfig tag. When embedding the sounds, you need to add the assets to the EmbeddedSounds class. Make sure to name the class for each asset the same as the id in the XML.

package de.pixelate.pelikan.sound
{    
    public class EmbeddedSounds
    {
        [Embed(source="../../../../assets/mp3/HelloWorld.mp3")] public static var HelloWorld: Class;
    }    
}

3. The SoundControl class enables you to play the sounds defined in the XML. Create an instance of the SoundControl class and add an event listener that will be called once the XML and all sound assets are loaded.

var soundControl: SoundControl = new SoundControl();
soundControl.addEventListener(Event.INIT, onSoundControlInit);

4. While developing you usually want to dynamically load the XML file, so you can quickly do changes and try out different sounds without recompiling the SWF.

soundControl.loadXMLConfig("xml/soundConfig.xml");

5. For production you might want to compile the XML into your SWF, so you can also pass a XML object to the SoundControl instance instead:

soundControl.setXMLConfig(xml);

6. Both commands will preload the sounds that are specified in the XML and dispatch Event.INIT from the SoundControl instance. Once your event handler is called you can play any sound by its id specified in the XML.

soundControl.playSound("MySound");

That’s it! You can download the source code (licensed under MIT) at github.

While working on our upcoming game Mr. Bounce I was searching for a way to compile debug and release builds from the same source in AS3. Our game project includes things like an internal level editor and cheat keys that we need for developing and testing the game, but should not go in the release version of the game.

I stumpled across something called Conditional Compilation on Ryan Taylor’s Blog – a new feature of the Flex 3 SDK. It allows you to define constants (Booleans, Strings, Numbers or expressions) at compile time, which are globally accessible within the source of your application.

You can define your constants on the command-line with mxmlc, in a Flex Ant Task or using a configuration file. See Adobe’s documentation for more information on this.

For our game we defined the debug and release constants in the flex_config.xml file that is located in the Flex 3 SDK folder inside the frameworks folder. Both constants are Booleans using the CONFIG namespace.

<compiler>
   <!-- (other compile options...) -->
   <define> 
      <name>CONFIG::debug</name> 
      <value>true</value>
   </define>
   <define>
      <name>CONFIG::release</name> 
      <value>false</value>
   </define> 
</compiler>

Now we can check for the debug and release constants in the source code and execute the correct code for the target build:

private function init():void
{
   CONFIG::debug
   {
      // Only init the level editor for the debug build
      initEditor();
   }

   initGame();
}

We could also specify alternative versions of a function for the different builds:

CONFIG::debug
private function init():void
{
   initEditor();
   initGame();
}

CONFIG::release
private function init():void
{
   initGame();
}

I recently started using Alcon for logging and debugging AS3 projects. It uses LocalConnection to send your trace calls from the included Debug class to the Alcon console, so it is not dependent on the Flash or Flex IDE. It has some nice features that make it very handy including the ability to display both the current frame rate and memory usage. Another plus: It works on Mac as well.

UPDATE: This guide is outdated. Please read the new guide on how to setup TextMate for AS3 projects instead.

When developing Flash games I use a fairly uncommon combination of development tools which I’d like to share here. I’ll give an overview on how to setup the OS X editor TextMate for developing ActionScript 3.0 projects using the free Adobe Flex SDK. If you are new to Flash development and working on a Mac this might be a good alternative to buying Flash Professional 9 or Flex Builder since TextMate is available for a convenient price of €39. Setting everything up can be a little bit tricky and requires a number of steps so I try to be as clear as possible. Let’s go …

1. Download and install the 30 Day Trial of TextMate from the Macromates website. If you are new to TextMate please take a look at the online manual to familiarize yourself with the basic functions of the editor.

2. Download the free Flex SDK from the Adobe website. Move the extracted folder into your Developer/SDKs folder.

3. Make sure that you have Subversion installed. If you don’t you can download an easy-to-install package of Subversion from the homepage of Martin Ott.

4. Get the latest ActionScript 3 bundle for TextMate using Subversion. To do this, open the Terminal application, copy the following script into the Terminal and execute it by pressing return.

mkdir -p /Library/Application\ Support/TextMate/Bundles
cd /Library/Application\ Support/TextMate/Bundles
export LC_CTYPE=en_US.UTF-8
svn co http://macromates.com/svn/Bundles/trunk/Review/Bundles/ActionScript%203.tmbundle/
osascript -e 'tell app "TextMate" to reload bundles'

Now the ActionScript 3 Bundle should show up in the TextMate Bundle menu.

5. Download and install the Flex Compiler Shell—it compiles much faster than the standard mxmlc compiler by keeping everything in memory.

6. To use the Flex Compiler Shell from TextMate we also need to download and install the terminal application iTerm.

7. Now let’s set up a new ActionScript project in TextMate. Select File→New Project from the menu, create a new folder for your project in the Finder and drag it in the TextMate Project Drawer. Click on the info button located in the bottom of the Project Drawer. Add two shell variables so that the ActionScript Bundle knows where to look for your files:

TM_FLEX_FILE_SPECS    src/Main.as
TM_FLEX_OUTPUT        deploy/Main.swf

We also need to let TextMate know where the Flex SDK is located. Go to TextMate→Preferences→Advanced→Shell Variables and add a new global variable:

TM_FLEX_PATH    Developer/SDKs/Your Flex SDK Folder

8. You are still with me? Great. Let’s finally write a simple “Hello World” application. Create two new folders named deploy and src in your project directory. Then create a new file in the src folder and name it Main.as. It should look something like this:

package
{        
    import flash.display.Sprite;
    import flash.text.TextField;

    [SWF( backgroundColor='0xFFFFFF', frameRate='30', width='200', height='200')]

    public class Main extends Sprite
    {
        private var textField: TextField;

        public function Main()
        {
            textField = new TextField();
            textField.text = "Hello World.";

            addChild(textField);
        }        
    }
}

10. We are almost done! Make sure that ActionScript 3 is selected in the language dropdown menu. Press Shift+Command+B and select Build (fcsh) to compile the main class. This will open iTerm and start up the Flex Compiler Shell. You will find the generated Main.swf in the deploy folder. That’s it.