I have a domain, webspace… there is no good reason beyond lazyness to not host my own blog but forward to wordpress.com. Finally I found the time and bravery to make the move! I hope everything still works. In the days to come I’ll explore the new customization options that I now have.

Thanks to Barry from GameCharts.com for the nudge!

This post is a little advanced and you should be allready familiar with embedding and dynamically loading resources in Flash.

The Challenge

The content creators create assets file by file and save them to a folder structure. Thanks to the magics of version control systems (SVN in our case) these ever growing amount of assets is synced between all collaborators. But someone has to make sure everything is available at runtime when the application needs it.

To embedd all resources using the [Embed] tag in the game’s source code would cause several problems: The size of the SWF would be huge as all assets that are potentially needed would have to be included. Each embedded resource has to be added when you build your project so compile times would explode. And as we’re using FlashBuilder we would have to write some lines of code for each embedd asset. But who’s going to maintain that? Gamedesigners and artists change, add and delete files to the repository but they don’t have the means (and inclination) to edit source code, so who’s keeping it synced?
A contrary approach is to put all resource files on server and load them at run time. But different types of resources require different code to load, if you require many resources at once you have to open one connection for each resource (adding a lot of overhead) and you have to keep track of multiple loaders. Lastly many resource files are compressed efficiently when embedded into a SWF and it’s sad to miss out on that kind of optimization.

Our Solution

So we’ve decided to setup an asset pipeline that converts our assets into a format that is more optimized to the needs of the runtime environment. Such a system is a common thing in “real” game development but unusual for flash game development – maybe because traditionally Flash applications are authored in an IDE that has build in functionality for asset management.

Flash Builder doesn’t have anything like that but luckily it’s based on Eclipse, a software development environment with an extensible plugin system. One plugin (part of the “Eclipse Java Development Tools”) adds support for “Apache Ant” build scripts to Flash Builder. Ant is a tool for automating software build processes. What to build with it? SWF’s that contain only assets as embedded resources, get uploaded to the server alongside our game SWF and when resource are needed the appropriate resource-packs are loaded at runtime to make the embedded assets available to Flash.

But our Ant script does a lot more then just invoke a compiler to build some AS3 files. It also generates these files on the fly. So the manual work required to embedd all our assets into some dozens of resource packs reduces to clicking a button.

The Details

So, what happens when we click?

1. The Script will go to the root directory where our assets are stored and browse the subdirectories recursively. Finally when a directory is reached that contains files a resource pack is created.
2. To do that we first generate create a temporary AS3 source file. We just concatenate templates that contain a mix of actual source code and temporary portions of text, marked with @-symbols, that are replaced by the Ant script when it builds the source file.First we include the header…

   package @PACKAGE@
   {
     import flash.display.Sprite;
     public class @PACK_NAME@ extends Sprite
     {
   

   …then we add souce code for each asset in the folder based on it’s file extension…

     [Embed(source="@ASSET_PATH@/@ASSET_NAME@.@ASSET_EXTENSION@", mimeType="image/png", compression="true", quality="@IMAGE_COMPRESSION@")]
     public static var @ASSET_NAME@:Class;
   

   …finally we add a footer to close the class and package declartion.

     }
   }

3. Now we kindly ask the mxmlc compiler to compile the generated class into a SWF. The Flex SDK contains Ant tasks for that purpose so it’s pretty easy to invoke the mxmlc compiler from an Ant script.
   

   
     false
   

4. We also copy a manifest XML that describes game objects and links them with certain embedded Resources in the ResourcePacks we generated.
   A gameobject’s definition might look like this:There’s one special manifest that tells our application what other manifests to load and where to look for the resource packs. When a player starts the game this main manifest is loaded. Now that we know what resourcepacks and manifests exists on the server we can ask the ResourceManager to load them when neaded.

5. The manifests and the compiled SWFs are uploaded to the server.

I can has Resources, please?

To get the assets when you need them you have to add code to your main application that will load the resourcepacks and manifests and extract the required resources. Our ResourceManager turned out rather complex but at its core it’s pretty straight-forward. This is how you’d load a XML-based manifest file.

private function loadManifest (url:String):void
{
  var xmlLoader:URLLoader = new URLLoader();
  xmlLoader.addEventListener(Event.COMPLETE, onManifestLoaded);
  xmlLoader.load(new URLRequest(url));
}
private function onManifestLoaded(e:Event):void
{
  var xml:XML = new XML(e.target.data);
  app.processManifest(xml);
}

And provided you know the URL to the resource pack an asset can be retrieved like this:

private function loadAssets(url:String):void
{
var loader:Loader = new Loader();
loaders[url] = loader;
loader.contentLoaderInfo.addEventListener(Event.INIT, onLoaded);
resourcesToLoad[url] = loader;
loader.load(new URLRequest(url));
}

When the loader completes it contains the class that we generated and compiled with our Ant script. We can look for the embedded resources if we know their name. To access a specific image asset you’d do this:

var resourcePack:Class = loader.contentLoaderInfo.applicationDomain.getDefinition(resourcePackClassName) as Class;
var resource:Class = resourcePack[imageName];
var bitmapData:BitmapData = (new resource() as Bitmap).bitmapData;

Final Words

I do realize that (unlike ours) many Flash applications need to be deployable as a single SWF that contains all the code and assets. Also, in smaller projects the effort of setting up system like ours might be bigger then just embedding the assets manually. But for us Ant has made deployment much easier and it allows the coders and artists to work on the same project mostly independ from each other.

I’d be curios to learn how other developers manage the assets in their projects! Feel free to comment!

To get it working I had to answer three questions:

1. How do the properties a, b, c, d, tx and ty map to the coefficients of the matrix?

2. How to use the matrix to transform a Point?

The Matrix class provides two methods to transform a point.

• deltaTransformPoint transforms a point without applying the translation.

x' = a * x + c * y;
y' = b * x + d * y;

• transformPoint transforms a point including the translation.

x' = a * x + c * y + tx;
y' = b * x + d * y + ty;

If you know the mapping of coefficients and a bit of computer graphics that’s the expected behavior. To be able to multiply a 2D vector with a 3D matrix you introduce an extra 1 as 3rd component. Then perform a matrix multiplication. That way the transformation is added to x and y after the rotation/sheering is done.

3. How to setup the matrix to get the desired transformation?

If none of the provided methods fits your need (like in my case) you can set the correct values for the coefficients directly. That’s easier then it sounds. Look at the basis vectors of your source coordinate system and imagine (or calculate) how they look like after the transformation. Assign coefficients a the x and b the y value of the transformed x-axis. Assign the x and y value of the transformed y-axis to c and d.
If you need it you can set tx and ty to move the transformed points relative to the new origin.

And why do I blog about math, now?

Adobe managed to have a incorrect illustration of the layout of the coefficients in the german doc (english docs happen to be correct!) and the inscrutable description of the transformPoint and deltaTransformPoint methods lacked the specifics I needed. Let’s hope this post and the power of google will help those, that seek the same kind of knowledge!

I loosely followed a paper Particle-based Viscoelastic Fluid Simulation to implement a sandbox application that simulates and renders a small blob of fluid and allows you to tinker with various parameters. Click the image below and give it a try!

The fluid is represented as a set of ~400 particles that interact with their neighbours and such seem to form a coherent entity.

For rendering I use an oldschool approach: Each particle is represented as a metaball. For a given pixel the force function of every metaball is evaluated, summed up and the final sum is compared with a threshold value to decide whether the pixel is inside or outside of the fluid.

To be able to do that in realtime I precalculate the values that a forcefunction yields for pixels within a relevant range of the particles center as a Bitmap.

These tiny images (about 40×40 pixels) are rendered at the position of the particle with additive blendmode.

Now I can decide with a single lookup in the resulting Bitmap if a pixel belongs to the surface or not. That evaluation step is done by a pixel bender shader and instead of just working with a boolean state (inside or outside) I sample a gradient based on the accumulated force value.

This approach allows me to achieve a variety of styles in the visual appearance of the simulated fluid by just using different gradients.

This technique would unfold it’s real potential if you could use hardware acceleration to accumulate the field functions because that’s a bottle neck in the current implementation.

Not sure if that stuff has any practical relevance, anyway. But the SWF is only 32kb big so people that are into demos (32k, 64k) could maybe make something fancy out of it. Here’s the source code released under the MIT license.

At the 14th December 2009 I created a thread in the Flixel forums with a mission statement:

The setup is classic: a hero in a dungeon full of treasure, traps and NPC of questionable attitude. The twist is that I’m limiting the player’s view to what his avatar is seeing. Top-down-ego-perspective so to speak. I hope it’s making exploring the dungeon more interesting and the enemies more scary if you don’t see all the stuff long before it becomes relevant/dangerous.

I used that thread to post ideas and prototypes and it became a major source of feedback and motivation spread over 6 pages. I love the Flixel community!

Meanwhile some Flixel games had been sponsored and the developers where kind enough to share figures with me and introduce me to the concept. So there actually was a market for flash games created by hobbyists? That intrigued me – I was curious to learn how that business worked and what my own game would be worth to sponsors.

There was a website dedicated to bring sponsors and developers together: Flash Game License. To help my game stick out I commissioned a portrait of the protagonist that I wanted to turn into an eye-catching thumbnail fit to communicate the essence of the game in one glimpse. Finding an artist, directing the process and finally receiving an awesome result was great. It felt like the best investment I’ve made in a long time! In the FGL Icon Hotness ranking my thumbnail was soon among the top 30 of over 2000 icons.

Now I had multiple reasons to finish the project. Many people knew about it and expected results, I had invested a little money and a lot of time (worth 4-6 weeks of fulltime work) and if all went well I would be able to reap some substantial reward (in cash and exposure) by finishing it.

In August I was more or less done and quite happy with the game. I watched friends playing through the whole thing. There were a few minor issues and when I had them fixed I felt it was time to find a sponsor.

Finding a Sponsor

I uploaded to FGL at 14th August 2010. Developers could immediately play and review the game but it had to be approved by the site admins before sponsors would be able to see it. I made a couple of minor fixes while impatiently waiting to get approved. Luckily after a couple of days I realized that reuploading the game was repeatedly putting me at the end of the approval-queue.

The game got approved at the 19th August with a developer rating of 8 out of 10 points. Pretty cool. Now I was sitting there, pressing F5, waiting for bids.

I’ve heard that many developers didn’t rely on FGL alone but also emailed sponsors directly. I resolved to do that, too. Researched lists of sponsors. But in the end I wrote only 3 mails – to the portals that I personally used and liked. Armorgames, Kongregate, Newgrounds. Without having to lie I told them that I’d be proud to have Rune Hunt bear their logo. Armor Games replied to my mail and viewed the game but didn’t place a bid. Not yet.

Instead I received the first 5 bids from 4 different sponsors all on the 20th of August. The best bid offered was 2000$ for a primary license. A great start!

A day later I uploaded a new SWF including reviewed dialogue. (Thanks to Hectate and zyxstand from the Flixel forums!) It has also been the first version that included a sitelock and measures to make decompilation a little more difficult. I should have done that right from the beginning but the protection method offered by FGL didn’t work for me and at that point I didn’t realize how important proper protection is to sponsors: If the game leaks without their branding they are skrewed.

2 days later a new sponsor offered 3000$ for an exclusive license with no adds allowed. I marked the 2000$ primary as “Best Bid” and promptly received an increased bid. In the note I was told that his bid was now obviously better then any other. I didn’t get a reply on my questions regarding details of the offer, though. The reputation of the sponsor wasn’t good. I hoped for an alternative.

Meanwhile I had created and uploaded a trailer for the game. And so I wrote a PM to one of the other sponsors that had placed a bid, telling him about the trailer, the reviewed texts and all the other changes hoping for a new bid. I got a friendly reply the other day and it was the beginning of at least a dozen PMs we exchanged over the following weeks. The sponsor was worried about the 3 days without protection (this was when I realized my error) and he made an offer reflecting that: A primary license including a performance plan. So, now I had an alternative. And I really liked the sponsor. If the game did good I’d receive about 3000$ for a primary license. I had hoped for more money but then, what did I know?

At the 13th of September I enabled Last Call which basically means “I’m going to decide on a bid soon!”. The 3 days went by with no new bids. I was a little disappointed and couldn’t really decide which bid to chose. And I totally didn’t expect what happened next. After Last Call had ended I got 2 new bids from sponsors that hadn’t yet taken part in the bidding. And a message from a 3rd one who asked me to wait so he could conferr with his partner before maybe placing a bid, too. The bids where clear improvements to what was offered previously. One of them was from Armor Games.

The sponsor offering the performance deal made a new bid: In addition to a 2000$ I would get up to 6000$ bonus based on the number of plays (all sources combined) within two months.  With 3 million plays that would be 8k + CPMstar + sitelocks.

Of course I had no idea how good my game would do and betting on the amount of plays I’d get really troubled me but the bid was best. I told Daniel from Armor Games as much. To my horror they made a new bid, with a performance plan! Complicated because only plays on the sponsor’s portal counted but the eCPM were rather huge. I had no means to compare the bids, I was confused and that’s exactly what I told both of them.

Both made offers stripped of any performance plan. I asked for simple deals and that’s what I got: exclusive license offers. This is where a little bid war started. I was amazed – when Last Call had run out I allready expected to get less then 4k$ total (adds & sitelocks included) now I was offered more then twice that amount as upfront cash.

In the end the other sponsor who’d been worried of my game leaking told me that he could not increase his bid any higher. He gave two very valid reasons and for both of them I was responsible.

1. he was concerned because he had found my game being unprotected for the first couple of days and that’s clearly a stupid mistake from my part.
2. he didn’t expect to be able to outbid Armorgames in the end anyway. Another stupid mistake from my part. I shouldn’t have told him who the other sponsor was but we had exchanged so many upfront & friendly mails that I just forgot that some information are better not shared.

Two serious errors on my part and there has been a 3rd: I didn’t give the 3rd sponsor who had placed a recent bid enough time to react. I was under the impression that I was supposed to decide fast because of the Last Call period being over. So I was telling them about my plans to accept a bid now and that theirs wasn’t quite on parr with the top bids. I waited 24 hours, saw that they had logged in but didn’t reply to my PM and accepted Armor Game’s bid. Later I learned that they were still debating to increase their previous bid by another 2000$ when I terminated the bidding process.

But despite these things I’m happy: I received more money then I had hoped for. Working with Daniel proved to be a pleasure. 5 days later we brought the game online. He required a couple of changes that I didn’t expect (like adding a walkthrough) but in the end I was very happy with how the branding integrated with the game. I received the payment only minutes after the game has gone online. And because he wanted to use paypal and they take a huge fee from the seller he added another 250$ to compensate.

If you plan on selling a flash game through FGL I hope you can learn from how things went for me. I tried to keep exact numbers and names private where possible.

Hungry eyes watch from the shadows. The flickering light of a butterfly is all that keeps them at bay. Run for your live – and sanity!

Finally, after almost a year of working on it, I have finished Rune Hunt!

Well, technically it’s been finished a couple of weeks ago. But I tried to find a portal that would sponsor the game. The basic idea of sponsorship is that you include links and logos of a flash game portal in your game before you spread it. The branding means traffic for the sponsor and that traffic is what they essentially pay you for. The other great thing besides money is that the sponsoring portal has an interest in getting your game played and will help spreading it – for example by featuring it on the front page. So you get money, exposure and retain full creative control. Cool stuff!

So in the last weeks I’ve spend quite a while on flashgamelicense.com and learned a great deal about how the market around free flash games works. The website is basically an agent that brings developers and sponsors together. Sponsors can bid on your games, after a while you pick the best offer and pay a comission to FGL. The process of trying to license my own game was nerve-wrecking but fun and in the end pretty successful. Huge thanks to ArmorGames for the generous sponsorship!

But enough of that for now. Go and play the game allready!

A member of the Flash Player Engineering team the new player replied to my inquiry about known performance issues:

General actionscript performance is not any slower in 10.1 than 10.0 from our testing, it must be something particular in your code which exhibits the problem. Do you have a reproducable test code or a url you can point us at?

So I tried to isolate and reproduce my problems. It seems that my problems are caused by a Memory Leak in the Drawing API. I wrote a simple test application to illustrate the issue and hopefully find a work-around.

//... there`s a buffer as rendertarget and a flare
private var _flare:BitmapData = null;
private var _buffer:BitmapData = null;

//each frame I render the flare 100 times into the buffer 
for(var i:int = 0; i < 100; i++)
    _buffer.draw(_flare, null, null, BlendMode.ADD);

In the 10.0 player there is no memory fluctuation caused by this code. But in the 10.1 player each draw-call allocates new memory. The total memory is increasing linearily until the garbage collector kicks in. This of course effects the performance.

In all browsers and on all systems that I tested the memory leak was present in the new player – but the way the garbage collector handled it varied so the graph isn’t always as clear. You can test it for yourself. And here’s the source for the test application.

My guess at what happens: BitmapData.draw() method accepts IBitmapDrawable an interface that is implemented by all DisplayObjects and BitmapData objects. If you pass a BitmapData object however it seems like memory gets allocated based on the size of the render target. This memory is not reused or instantly freed but has to be collected by the garbage collector.

Knowing this there’s a neat workaround: If you wrap the BitmapData in a Bitmap before you draw it you can avoid the bugged code and the memory keeps steady!

//wrap _flare in a Bitmap (do this only once!)
_flareBmp = new Bitmap(_flare);

//now instead of _flare render _flareBmp
for(var i:int = 0; i < 100; i++)
    _buffer.draw(_flareBmp, null, null, BlendMode.ADD);

Drawbacks of loading on demand

• different types of resources require different code to load.
• there’s a gap between a resource beeing requested and the time it actually becomes available.
• if you require multiple resources at once (loading the next level data) you have to open one connection for each resource which means a tremendous overhead.
• if you’re loading multiple resources you have to keep track of multiple loaders to know your overall progress
• when a resource fails to load you have to detect and handle it.

Drawbacks of embedding

• Code and Data are not decoupled: When the assets change you have to change and recompile your code.
• Workflow issues: How can content creators (artists, level designers) test their work ingame?
• Transcoding a resource into a flash compatible format is taking time and so for large applications build times explode.
• It’s likely that more data is pre-loaded than is actually required in a users session. The long initial load time might become a barrier for users and it certainly wastes bandwidth.

Alternatives

The general approach to overcome these limitations is to decouple your data from your logic but preprocess and package the data into a Flash compatible format so it becomes trivial to join logic and data when needed.

Option #1 – Statically linked SWCs

If you don’t need loading on demand you can create a SWC file containing the resources and link it with your main application. The effect is the same as if you’d have embedded all the files directly but by splitting resources into multiple projects you keep your build times fast. Projectes are re-compiled seperately and only when needed.

It’s also nice that you can create the SWCs with more artist friendly tools like the Flash IDE. This provides additional benefits like build-in conversion of Sounds from WAV format to flash compatible MP3 encoding. I get back to that later.

To link a SWC in Flex/Flash Builder you select Project->Properties and click the “Add SWC” button in the ActionScript Build Path category to select and add the SWC containing the resources.

Now the resources are available at compile time by their class-names just like if you embedded them using the Embed-Tag.

For example in the “sounds.swc” I have  a number of embedded asset classes for sound effects. They have names like “firefly_flee” or “music_title_screen” and extend the Sound class. To play “firefly_flee” I just have to instantiate it and call the play() method:

var sound:Sound = new firefly_flee();
sound.play();

Option #2 – Dynamically load and link SWFs

In Option #1 you still have to recompile your main appliciation whenever a resource pack has changed and every linked resource will get pre-loaded whether you’ll need it or not. Alternatively you can package the resources in a SWF instead of a SWC and load it on demand. To load a SWF use a Loader class.

function load():void
{
    var loader:Loader = new Loader();
    loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onLoaded);
    var urlReq:URLRequest = new URLRequest("sounds.swf");
    loader.load(urlReq);
}

When onLoaded is called the SWF has been loaded including all the embedded Resources. But how to access them? The SWF contains a specifically named class for each resource. You might know their names but since the classes weren’t present at compile time you couldn’t write any code using them. So before you can use the resource class to create an instance of the resource we have to retrieve that class by its name.

public function onLoaded(event:Event):void
{
    var info:LoaderInfo = event.currentTarget as LoaderInfo;
    var soundClass:Class = info.applicationDomain.getDefinition("firefly_flee") as Class;
    var sound:Sound = new sndClass;
    sound.play();
}

An ApplicationDomain is a container for AS3 definitions and if not specified otherwise each loader will create it’s own applicationDomain where it adds all the definitions that are part of the loaded SWF. Of course you wouldn’t want to play a sound right in an event handler. Instead just load the SWF once and then store a pointer to the applicationDomain and call getDefinition on it whenever you need a class.

Now a smart question to ask would be: Why do I have to load the classes into a new ApplicationDomain and keep a pointer to it? Can’t I just add all the definitions to where my other classes are stored?

Yes you can. Just provide a LoaderContext when requesting to load the SWF and in that LoaderContext you can specify in what AppDomain you want the definitions to end up.

loader.load(urlReq, new LoaderContext(false, ApplicationDomain.currentDomain));

Now whenever you want to reference a resource you can get the resource class  by calling getDefinition on the ApplicationDomain.currentDomain.

But a word of caution: You have to make sure that there are no naming collisions. Classes that allready exist in the currentDomain will not be replaced by a definition of the same name in the newly loaded SWF. And classes once added the main SWFs AppDomain can’t be removed. If you want to be able to unload dynamically loaded resources you have to keep them in different AppDomains.

If you want to learn more about Application Domains read this excellent post.

Options #3 – Use Flex Modules

Last option combines the benefits of both: Using Modules. The basic idea is that you know all the classes at compile time so you can code against them but then you don’t link them into your main SWF but into seperate SWFs that get loaded dynamically on demand or when you request it using the ModuleManager singleton. The drawback? This technology is part of the Flex framework and Flex applications are typically bigger then pure ActionScript applications. But if you are going with Flex anyone check it out!

Creating Resource Projects

While you can create resource projects in Flash Builder the Flash IDE is a better suited for that. Adding resources to the Library using drag & drop and getting a preview is handy.
Right click -> Linkage... and you can mark that file to be exported for ActionScript.

The class name can be edited to your liking. To generate a SWF just publish the file. If you want to generate a SWC for static linking with your main application check the Export SCW option in the Publish Settings Dialog.

The main reason for using the Flash IDE however is that it allows you to embedd files that would otherwise not be embeddable.

Most notably: Flash will encode WAV files as Mp3 for you. Details like encoding quality can be specified in the Publish Settings Dialog. But in any case Flash will create “loopable” Mp3′s that don’t suffer from the infamous gaps at the start and finish of the sound.

Another neat features: When you embedd images you can chose to JPEG-compress them and even specify the quality. Even PNGs with trancparency can have their RGB channels JPEG compressed which can reduce the memory-footprint considerably.

A completely different approach to genereating resource packs is to use some custom automated process. For example you could write a Level-Editor in a langauge like C# but export the levels as a ready-to-load SWF file by generating appropriate source files and feeding them to the Flex commandline compiler.

It’s easy to pickup ActionScript3 with a programming background in C++,/C# or Java as the languages shares the same concepts and similar syntax. So, why learn about stages and timelines, keyframes and whatnot when you can write your games like you always did? Well… almost. There are concepts in Flash that require some getting used to. Resources is one of them.

There are two fundamental different ways to get your resources loaded.

One is to embedd all the potentially needed data into your SWF file. This increases the initial loading time but once the application has fully loaded all resources are instantly available, too.

The second option is to send a lean application and load individual resources on demand. This is will reduce the initial load but making things less convenient for the coder and user.

Loading Resources on Demand

Loading individual resources when they are needed is similar to what you’d do in most local applications only that a request takes a lot longer to return the result because the data is on a server and not your local harddisk. Pausing the application while waiting for the result isn’t an option so instead you make the request and then register an event-listener to get notified when the resource has been loaded. Flash provides two classes for this task called Loader and URLLoader.

function load():void
{
    var loader:Loader = new Loader();
    loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onLoaded);
    var urlReq:URLRequest = new URLRequest(myimage.jpg);
    loader.load(urlReq);
}

function onLoadComplete(event:Event):void
{
    var myimage:Bitmap = event.target.content as Bitmap;
}

The Loader can be used for images and SWF files only. To to load binary data like XML or TXT files you use the URLLoader class instead. You access the resource using the data property instead of one named content and you usually have to do use some other classes to interpret the raw binary data. For example to load an XML file you have to pass the data as a constructor parameter to a newly created XML instances.

function load():void
{
    var loader:URLLoader = new URLLoader();
    loader.addEventListener(Event.COMPLETE, onLoaded);
    var urlReq:URLRequest = new URLRequest(myxml.xml);
    loader.load(urlReq);
}

function onLoadComplete(event:Event):void
{
    var myxml:XML= new XML(event.target.data);
}

So we see that depending on the type of resource you have to use different loading mechanisms. There is no general approach – sometimes classes even provide integrated loading. For example to load an MP3 (the only sound format natively supported) you use the load function of the Sound class which is special in the way that it allows you to start playback before the resource has fully loaded. (Streaming)

function load():void
{
    var sound:Sound = new Sound();
    var urlReq:URLRequest = new URLRequest(mysound.mp3);
    sound.load(urlReq);
    sound.play();
}

The above examples show that while it is possible to load individual resources on demand there is not one generalized approach to do so. This can make it quite difficult to integrate for large applications.

Embedding Resources

Another option is to embedd all potentially required resources directly into your SWF file. To do so you must use the [Embed] metadata tag before a variable definition of type Class. As a parameter of the [Embed] tag you specify a resource location. When your sourcecode is compiled a new class is added that represents the embedded resource and the class-variable right below the embed tag will point to it. This variable can then be used to instantiate copies of the resource.

	[Embed(source="data/music.mp3")]
	private var music_sound:Class;

	function playMusic():void
	{
		var sound:Sound = new music_Sound();
		sound.play();
	}

If you don’t provide an absolute path to the resource (starting with a drive-letter) Flex matches the path to at least 3 directories: the projects root, the source directory and the directory of the file containing the embed tag. You can not use URLs to resources.

Once a resource is located it gets transcoded and added to the SWF as a full featured AS3 class. These generated classes are called embedded asset classes and inherit from the well known base classes classes.
For example a JEPG will end up as a descendant of the Bitmap class. The only difference to the ordinary Bitmap class is that when you instantiate the embedded asset class (with the new keyword) you get a Bitmap that preinitialized with the embedded JPEG.

What kind of class is generated to represent a resource depends on file extensions.

• JPEGs, GIFs and PNGs -> Bitmap
• Mp3s -> Sound
• SVG -> Sprite
• SWF -> MovieClip
• TTF -> Font

Note: for Fonts you need to specify an additional parameter fontFamily to be able to use it by name like any other font.

Sometimes you’ll want to embedd resources that are haven a unsupported file extension. In this case you have to specify explicitly how to transcode the file. Usually an unsupported file extension means that the file format is one that isn’t in the list above so your best option is to encode it as binary data. To do so set the mime-type parameter to ‘application/octet-stream’.

The embedded asset class created for binary data descends from the ByteArray class. So you can embedd *any* file in flash but for some you get only a very lowlevel representation. But with a bit of luck there are higher level classes available to handle it with. Remeber the example about loading an XML dynamich using the URLLoader? The same works when embedding the XML:

	[Embed(source = "some_xml.xml", mimeType="application/octet-stream")]
	private static var xml_binary:Class;

	function doSomething():void
	{
		var xml:XML = new XML(new xml_binary());
		//do stuff
	}

A quite similar process is used to embed Pixelbender shaders. And if you want to embed text files you can access the content by converting the binary data to a String:

	[Embed(source = "ramblings.txt", mimeType="application/octet-stream")]
	private static var txt_binary:Class;

	function doSomething():void
	{
		var bytes:ByteArray = new txt_binary;
		var text:String = bytes.toString();
		//do stuff
	}

This is an extensive post allready but so far I’ve only touched the basics. In the second part I list some drawbacks of these simple methods. I explain an alternative approach in which multiple resources get packed in SWFs or SWCs and linked with the main project either dynamicly or staticly. I’m also showing how to use the Flash IDE to create such resource packs because this provides better worklfow and treats like automated encoding of WAV files with support for support gap-less looping.

For people interested in using Tiled for their flash game but unsure how to handle the level format I’ve put together a little example. It contains code that parses a tmx file and recreates the data on the flash side in form of custom classes designed to make all the data easily accessible. The code is generic enough to be used in about any AS3 based project. I support XML, CSV, base64 and zlib-compressed base64 encoding.

In my sample I modified a Flixel Framework v2.23 based demo (the original version called FlxCollision is available on githup) to reload the current game state out of a TMX file on keypress. If you run the editor and the swf simultanously you can make changes in the editor, save, switch to the swf, press the Enter key and see the changes taking effect.

Tiled Editor and Demo App

If you’re interested it’s easy to give it a try. No source compiling is required. Just get the files and unzip them somewhere. Then execute the FlxCollisions.swf file found in bin-debug by double clicking it and load the level map01.tmx found in bin-debug/data in the map editor. No restarting of the flash app should be required. Just trigger the reload ingame whenever you changed something!

If you want to use the same approach for your own project all relevant code is included. The interesting parts are found in the PlayStateTmx class where the TMX file is loaded and parsed and then used to populate the FlxState with level content matching the tiles and objects described in the level file. Have fun!