JacksonDunstan.com

Adobe adds new features to every new version of Flash Player. To use these features, you have to compile your SWF correctly. Unfortunately, setting up your build environment and passing the right options to the compiler can be a bit tricky. Today’s article attempts to clear up the confusion so you can take advantage of the latest Flash Player features.

I won’t be covering the myriad IDEs for Flash, but instead the one tool they all use behind the scenes: the Flex SDK. Specifically, the MXMLC command-line tool to produce SWFs and the COMPC command-line tool to produce SWCs. The basic usage is trivial!

mxmlc MyApp.as

Now say you want to take advantage of a shiny new feature like Stage3D. You’re read the API docs, so you go ahead and write some code and recompile with the command above. Surprisingly, you face an error like this one:

/path/to/MyApp.as(8): col: 10 Error: Access of possibly undefined property stage3Ds through a reference with static type flash.display:Stage.
 
			stage.stage3Ds[0].requestContext3D("auto", "baseline");

Wait, why doesn’t the compiler know about Stage3D? Hasn’t Flash Player 11 been out for a year? Didn’t you just download the latest Flex SDK from Adobe? You did, but the compiler needs a little help to support a “new” version of Flash Player.

To begin, you need to add an option to the command line telling the compiler which version of Flash Player you’re compiling for:

mxmlc MyApp.as -target-player=11.4.0

Now you’ll get a different error when you compile:

/path/to/flex_sdk/frameworks/flex-config.xml(56): Error: unable to open 'libs/player/11.4/playerglobal.swc'
 
      </external-library-path>

This error is a bit cryptic, but it reveals a bit about what’s going on with this command line option. You see, all that is happening when you specify the -target-player option is that you’re telling the compiler to link against a specific SWC with the Flash Player API in it. This API changes each time a new version of Flash Player is released, usually to add new classes, functions, and parameters. The error message above is saying that the compiler searched for that SWC (playerglobal.swc) and couldn’t find it. So you need to download the Flash Player 11.4 playerglobal.swc and put it here:

/path/to/flex_sdk/frameworks/libs/player/11.4

You will need to create that directory if it doesn’t exist and, for you readers in the future, swap out “11.4” for “11.5”, “12.0”, or whatever version Adobe has released. Let’s look at my tiny app:

package
{
        import flash.display.Sprite;
        public class MyApp extends Sprite
        {
                public function MyApp()
                {
                        stage.stage3Ds[0].requestContext3D("auto");
                }
        }
}

All it does is try to use the most basic function of Stage3D and when I run it with Flash Player 11.4 I get this uncaught exception:

ReferenceError: Error #1069: Property stage3Ds not found on flash.display.Stage and there is no default value.
	at MyApp()

What gives? Didn’t we target the correct version of Flash Player? Well, only partially. You see, the only effect of the -target-player option is to specify the playerglobal.swc to link against. As it turns out, each SWF has a version number inside it that Flash Player uses to determine which Flash Player API that you’re allowed to use at runtime. So we need to recompile with yet-another option:

mxmlc MyApp.as -target-player=11.4.0 -swf-version=17

17 might seem like a strange version number since Flash Player is only on version 11.4, but this number is an integer that gets bumped with each “minor” version release of Flash Player. Here’s a table of the SWF versions that are currently available:

If you recompile now your code should run as expected. To recap, here are the three steps you need to do in order to target a specific version of Flash Player:

1. Get the appropriate playerglobal.swc
2. Pass -target-player=X.Y.Z to MXMLC or COMPC
3. Pass -swf-version=A.B to MXMLC or COMPC

One thing to keep in mind is that, once you’ve targeted a specific version of Flash Player with the above steps, users with previous versions of Flash Player won’t be able to use your SWF. You should handle this gracefully, perhaps with JavaScript detection and a message on the web page informing the user to upgrade. Users with future versions of Flash Player will, of course, still be able to use the SWF.

Hopefully this clears up some of the confusion that happens when you want to take advantage of Flash’s new features. If you have any questions, feel free to post a comment!