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

===== Introduction =====

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".

===== Preliminaries =====

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 [[SEPY]] 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.

===== File system layout =====

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:

^ Path ^ Remark ^
| ''/'' | Project root directory.|
| ''/*.as'' | The logic is contained in ActionScript 2.0 classes, each of which is contained in its own file with a filename of ''[Classname].as''. |
| ''/app.xml'' | The XML input file to [[Swfmill]] which imports assets and links our classes into the SWF. Of course you can name it however you like, this is just an example. |
| ''/build.bat'' | I am lazy and use a simple batch file to build my project. For a larger project, you would probably be well advised to use a more sophisticated approach such as one using [[flashant]], but I like to KISS as long as it works. |
| ''/lib/'' | This subfolder will contain all data files to be imported into the main SWF: images, sounds, fonts, other SWF files and so on. Obviously you can further split this up into more nested subfolders for different media types, if desired.|
| ''/build/'' | The build subfolder will contain all ouput files created by our build script. |
| ''/build/classes.swf'' | We will let [[MTASC]] create this intermediate file which contains all our compiled ActionScript classes without any media.|
| ''/build/app.swf'' | This is the final output file, the product of all your sweat and hard work: the created Flash movie.|
| ''/build/index.html'' | This is not strictly necessary, but I like to create an HTML file which embeds the Flash movie for more convenient viewing inside a browser. |


===== The files in detail =====

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.

==== The ActionScript code ====

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

<code actionscript>
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!";
	}
}</code>

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?)

==== The Swfmill XML input ====

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'':

<code 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>
</code>

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.

==== The build script ====

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

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

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.

===== Conclusion =====

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 [[http://eriatarka.byethost.com/flash/downloads/skeleton.zip|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.

 --- //[[eriatarka|Clemens Hofreither]] 2005/09/04 11:33//