How to structure and set up a Flash project without using the Flash IDE

When I first entered the world of open source Flash development, I was completely lost. How do I get off the ground? Which files go where, and how do I get the whole thing to compile? How do the different parts (.as files, swfmill .xml files and so on) fit together? In fact, I wasn’t even sure whether I could start a project from scratch without using the Flash IDE (which I don’t have). I was close to giving up, but somehow I pulled through and got something working. If you feel as lost as I did when I started out, this tutorial should help you to see a bit clearer. At the same time, I will show you a working file system layout for organizing a project.

Disclaimer: I have myself just got started with open source Flash development and want to help other people who attempt to get into that, but I’m far from an expert, so take everything I say with a grain of salt. Think of everything written here as “IMHO“, “from what I’ve found out” and “how it seems to work”.

Before we get started, make sure you have swfmill and MTASC installed and added to your path. Of course you will need a text editor; I personally use SE|PY ActionScript Editor for my Flash needs, but of course you can use whatever strikes your fancy. I am using Windows, but this article should be equally helpful for users on other systems.

Some experience with object oriented programming is assumed.

Before we start any coding (of which we won’t be seeing too much in this article anyway, so don’t hold your breath), let’s spend a minute thinking about how we want to layout the project filesystem-wise. I have found the following layout to work well:

Now we get down to the details of our source files and what makes them work together. I have created a simple project application which I will use for demonstration purposes; also, I’ll provide a download link to the entire project at the end of the article. But now, let’s dive in head first with the ActionScript code.

Our simple skeleton project contains only a single .as source file called Application.as. Here is how it looks:

class Application extends MovieClip {
	var mytf:TextField;
	
	function Application() {
	}
	
	function onLoad() {
		createTextField("mytf", 2, 10, 75, 100, 20);
		mytf = this["mytf"];
		mytf.text = "Hello, world!";
	}
}

Very basic stuff really, though don’t panic if you don’t understand everything right now. I’ll try to explain what we are doing here, even though this is not primarily an introduction to ActionScript.

Flash contains a MovieClip class, which all visual objects like forms, buttons, sprites and so on should be derived from. It’s good practice to make one application class as we have done here and contain all other objects within this class; this Application class will function as the root of our application, as the name implies.

If you have any experience with OOP, you won’t have much trouble noting that Application has one instance variable called mytf which is of type TextField (another built-in Flash class), and its constructor Application() does nothing.

There is one other method called onLoad() which we’re overriding from the base MovieClip class. This will be called when the clip is placed “on stage”, so to speak, and gives it an opportunity to set itself up for viewing. Your first instinct would probably be to put this stuff into the constructor, and so thought I, but I found out the hard way that some stuff like drawing or attaching other clips doesn’t work well in the constructor, so we will be using the onLoad() method for such purposes. You can still set up instance variables or create objects within the constructor, but as a rule of thumb everything that’s concerned with the appearance of the clip should go into onLoad(). At least that’s what I found.

So what does this particular onLoad() method do? Quite simply, it calls createTextField(), which is a method of the MovieClip class, so this only works because we extend MovieClip. If we hadn’t extended that class, we would have to call _root.createTextField(); _root refers to the MovieClip at the root of the document hierarchy. Our application instance is in fact an immediate child of _root. The arguments of the method specify, in order: an instance name for the text field; the depth (which you can think of as the z-index of the object, the higher, the farther on top; note that this must be unique for every object you create!); x coordinate; y coordinate; width; height.

By the way, since we have spent so much time talking about this method call: the official ActionScript 2.0 reference can be found at http://livedocs.macromedia.com/flash/mx2004/main_7_2/wwhelp/wwhimpl/js/html/wwhelp.htm?href=Part_ASLR.html, a very helpful resource (though layout and navigation are debatable).

But further in the text: the method now gets the freshly created text field by accessing its own list of children with array syntax and assigns it to the instance variable mytf. Finally, we set the text field’s content to the ubiquitous “Hello, world!”. (Well, what did you expect for a first project?)

Next comes the XML input file for swfmill, which pulls together all the resources we need for our final SWF file. If you don’t know how to use swfmill, an excellent introduction can be found at http://iterative.org/swfmill/doc/using-swfmill.html. But on to the file, app.xml:

<?xml version="1.0" encoding="utf-8" ?>
<movie width="400" height="300" framerate="12">
  <background color="#f0f8ff"/>
  <clip import="build/classes.swf" />
  
  <frame>
    <library>
      <clip id="app" class="Application" />
      <clip id="image" import="lib/test.png" />
    </library>
  
    <place id="app" name="myApp" depth="0" />
    <place id="image" name="myImage" x="5" y="5" depth="1" />
  </frame>
</movie>

If you’ve read the document linked to above, most of this should be self-explanatory. We set up a movie with a certain width, height and frame rate and set its background color. Next we import the file build/classes.swf which contains our compiled AS code. (We’ll get to the details of how this file gets created in a moment.)

Then we set up the only frame in the movie by first defining its library; it contains definitions for our application movie clip (note the class= attribute, this is where the magic happens as this links the clip to our class definition) as well as an external image file. Finally we place two objects on stage: our application object as well as one instance of the image imported above. Again, note the important depth= attributes; remember to set these uniquely or stuff will break. Also, every instance of a clip needs a unique name attribute; this corresponds to the first argument of the createTextField() method we’ve seen above.

Now we put it all together by compiling everything into one SWF file with these commands in build.bat:

mtasc -swf build/classes.swf -header 1:1:24 Application.as
swfmill simple app.xml build/app.swf

The first line compiles our Application.as source file into build/classes.swf. The -header argument is needed to create a new SWF file from scratch as opposed to updating an old one; in this case, we create a movie with a width and height of 1 and a frame rate of 24, but this doesn’t really matter as this file contains only our code, not the final movie. Just provide any numbers to make MTASC happy.

The second line compiles app.xml into the final output file, build/app.swf. Remember that we pulled in build/classes.swf in the XML file: that is how the compiled code gets put together with the other data.

And that’s all there is to it (okay, okay, it wasn’t all that short after all...); run the build script and view your output file. Ugly? You bet. Useless? As hell. But what’s more important, it works, and we can now start coding and get to the really interesting stuff. But that’s for a later tutorial. In the meanwhile, feel free to download the sample project and play around with it.

If this tutorial has helped you or there are things left unclear, please feel free to mail me at chofreither (at) gmail (dot) com.

— Clemens Hofreither 2005/09/04 11:33