First Frame Export Demystified

I wrote this a couple of weeks back and just never got around to posting it. This post represents the fruit of many hours banging my head on the desk trying to figure out what was going wrong. Hopefully it will save you some brain cells.

First of all, let’s cover some basic definitions.

Export. This is the action of marking a symbol in the library as “Export for AS.” The main reason you would want to do this is if you plan to attach the symbol to the stage at run time using attachMovie. This would also cover using methods like createObject and createClassObject, as these are wrappers for attachMovie.

Attach. This is the action of telling Flash to take a symbol from the library and placing it on stage, or within an already existing movie clip, at run time. In order to attach a symbol, it needs to exist in the library, and needs to have a linkage name. You use the linkage name in the attachMovie method, to tell Flash what movie to attach.

Symbol. Mainly I am talking about movie clips here, although other types of items can be exported. And when I say movie clips, I am including subclasses of movie clips, which include any and all components.

Exporting Basics.

All right. Let’s take a simple example. You make a graphic, or import a bitmap, turn it into a movie clip, tell it to export and give it a linkage name. By default, it will export prior to the first frame being played. This is cool, because it means the symbol will be included in the swf, and available to attach as soon as your movie actually starts.

There are some drawbacks though. First of all, it will be included in your movie whether it is ever used or not. Say you make some movie clips for testing purposes during development, and in the final release, they are not used, but you leave them in the fla. If they are exported first frame, they will be included in your swf. Extra file size.

Another drawback is that because they are exported prior to the first frame, they kill any kind of preloader you might have going on. If your exported symbols are large, the movie’s gonna seem to hang before it starts. Your preloader starts on frame one, but by the time Flash gets there, everything is already loaded.

OK. So we turn off “Export on First Frame”. Problem solved, right? Nope. Now we go in the exact opposite direction. The symbol will not be included in the swf at all, unless it appears on the timeline somewhere, like any other unexported symbol.

If you just uncheck the first frame option and put some code in the movie to attach the symbol, it won’t happen, because the symbol isn’t there to attach. Flash does not analyze all your code and say, “Ah, here, he is attaching symbol x. We better make sure that goes along in the swf.” Actually, that’d be pretty much impossible because you could be dynamically deciding what to attach at run time, perhaps based on user input. So Flash relies on you to tell it what to include in the file.

Unfortunately, there is no “Export on Frame X” functionality. The only way to force Flash to include a symbol which is not exported on the first frame is to place it on stage somewhere in the movie at author time. So, you make a key frame some ways into the movie (say frame 5 for example), and place any exported items on it. Now, since they aren’t coming in until frame 5, your preloader on frame one works just fine.

Your preloader should just loop between frames 1 and 2, or just stop the timeline and perform an onEnterFrame function. You can use it to compare getBytesLoaded() with getBytesTotal() or _framesloaded and _totalframes. When those two are equal, your entire movie has loaded, and all your symbols are ready to be attached. You should now jump to some other frame, beyond frame 5, and start the main movie. You don’t ever want the playhead to touch frame 5. It’s just there to force your symbols to load.

Components.

OK, so the above is nothing groundbreaking. People have been doing that exact thing forever, or at least since the release of Flash MX, which gave us the first frame option (everything always exported first frame in Flash 5). Where the real fun comes in is in building components.

As I said before, components are basically movie clips, with a few extra features. When you build a component and get it all working the way it’s supposed to, you export it as a swc file. A swc file is basically a zip file containing a swf and a few other things. This gets added to the components panel and you can drag it into a new movie.

The contained swf is the component you will see on stage in your compiled movie. It’s also the live preview you see on stage during development. The important thing to realize is that it is a swf which is just like any other swf that you might publish directly. In other words, it follows all the same export rules described above, including the first drawback I mentioned.

To remind you: any symbol exported first frame will be included in the swf, whether it is used or not. This means that any symbol that is exported first frame in the fla where you are creating your component will be included in the swc!

Example: You have an fla you are using to develop a component. While testing it, you drag a few UIComponents on stage ? maybe some buttons, text inputs or areas, etc. These are not part of the component you are building, you are just using them to interact with the component to make sure it is working. OK, you get it working perfectly and you export it. Well, it is exporting a swf inside the swc. If those UIComponents are set for first frame export (which they are by default), they will go along for the trip into your swc!

Try it out. Create a simple component and export the swc. Look at the file size. Now drag a few UIComponents onto the stage and delete them ? just so they end up in the library. Re-export and check the size again. If you have ASV, you can decompile the swf inside the swc and you’ll see them sitting there.

Now, that itself wouldn’t be the end of the world. Yeah, it bloats your components unnecessarily, but it won’t really hurt anything. Coming up is the real killer.

Instead of just a single component, let’s say you’re making a suite of components. As they may share many of the same assets, and they are of the same family, it makes sense to develop all of them in the same fla.

Say you have five components, A, B, C, D and E. Each one is itself a movie clip. And let’s say you leave them all as export first frame. You get them all working and export each one. Think about what’s happening. Each component swc is going to contain every element that is set to export first frame in the fla. In other words, each component is going to carry with it a copy of all the other components! Yuck.

But it’s worse than just yuck. This situation can actually break your components. Generally what happens is you make a new movie and drag one of your new components into it. All is fine. Drag in another one that was created in the same fla. Wham. All goes to hell. I’m not sure precisely what happens, but I think it sets up some sort of weird demonic feedback loop or something. Some kind of conflict between the multiple versions of symbols or something. In fact, it doesn’t always happen, but it will eventually.

There are a couple of solutions: One is to develop each component in its own fla, and ensure that at export time there is no extra symbol in the fla. But, as mentioned above, it is useful to develop several components in the same fla. Say you have a skin element that is used across all of your components. If you have five different flas, and you update that skin, you have to update it in all five flas. So the much better solution is to make sure that nothing, absolutely nothing in the fla is set to export on first frame.

I’ve set up a command that makes this very easily. Just name it “No First Frame.jsfl” and pop it in your commands folder:

items = fl.getDocumentDOM().library.items;

numItems = items.length;

for(var i=0; i

When you run it, it will make sure nothing in your library is set to export first frame.
An interesting point is that the resulting component, when dragged into a new movie, will be set to export first frame. It seems that is the default for any and all components in the component panel, despite how they are published.
Exporting Classes
(Some of the basic concepts here were gleaned from Colin Moock's Essential ActionScript 2.0)
To continue on from the first section, another thing that may mess up your preloader is the classes that are included in your movie, including the classes used in components. Like symbols, all classes in a movie are set to be included in the movie before the first frame. Generally, your classes are going to wind up much smaller than your symbols, but they could get large enough that you might want to preload them as well.
The first thing you need to do is the equivalent of unchecking first frame export for a symbol. In your fla, go to publish settings and click on ActionScript 2.0 Settings?
In the field "Export frame for classes", type in a number other than 1. This will make your classes be included on that frame, rather than the first frame. Their size will be included in your preloader if you are using getBytesLoaded/Total.
The important thing to remember here is that you can't do anything class-based until the frame after the classes load. So don't include any class-based stuff in your preloader, don't include any components on the first frame. More importantly, ensure that your classes are exported prior to the frame in which you have included your symbols on the timeline.
Currently my timelines look like this:
Frame 1: Preloader (when loaded, gotoAndStop frame 30)

Frame 10: Classes export

Frame 20: Components/Symbols placed on stage to force export

Frame 30: Code to start movie.
Of course, you could just do this on frames 1, 2, 3 and 4, but spreading them out allows me to put some visible labels on the layers. I made this into a template, so it is easy to start any application with this setup.