Embed Almost Anything in Your SWF

Using mxmlc / Flex Builder, you can safely store any kind of binary data, text, or XML directly in your SWF if loading it at runtime is not possible or not desirable. Find out how below.

The Setup

My friend EJ was wondering if there was some way to compile XML directly into an application without putting it inline in code. Of course E4X allows you to type XML literals, but doing so with large blocks of XML can be problematic for a few reasons. You can’t edit this XML with an XML editor. The XML parsing inside Flex Builder can be faulty on occasion, causing ActionScript in the same file to be misinterpreted. Placing XML in your source files can make them unwieldy and large, and slow to parse.

An Idea, but Not the Right One

My initial idea was to use include. Even though #include is deprecated in AS3, the little-known include (no hash mark!) uses the same syntax and can include code in much the same way. The Flex framework uses this to include a common version number as a static field in many classes:

mx_internal static const VERSION:String = "3.0.0.0";

This line, found in the file Version.as is placed in the class definition of classes where include “Version.as” is found. However, you can’t just include arbitrary copy. The included code has to be one or more full lines. So my idea of using

protected var xml:XML =
include "static.xml"
;

wasn’t going to work. It did work when I included the whole variable declaration in the XML file, but then the file wasn’t valid XML any more! Not even close. And not too much better than just typing inline.

The Solution

The solution here is much, much more powerful than the original hack might have been. The MXML and AS3 compiler, mxmlc, which is used by Flex Builder as well, has the ability to embed all kinds of video, graphics, other swfs, and fonts into a SWF. The [Embed] metadata tag / compiler directive works whether you are using Flex or simply AS3. [Embed] associates a bit of data with a class that is capable of representing it.

If you haven’t seen it used before, here’s a simple example where we embed an image in the SWF:

[Embed(source="assets/photo.jpg")]
private const PhotoImage:Class;

And then you can use it:

var myPhoto:DisplayObject = DisplayObject(new PhotoImage());

So, I don’t know how Adobe is really implementing things under the hood, but I say the following with some certainty. The compiler, happening across your [Embed] directive, retrieves the source, and examines it to see what kind of file it is. Depending on the type of file you’ve asked the compiler to embed, the runtime class reference will produce a subclass of a particular kind of class which is appropriate for the data you’ve embedded. The compiler will take the source of that file, transcode it, preparing the data to be inlined in the SWF itself, and possibly preprocessing it, for example parsing SVG into vector shapes.

You should also know that depending on whether you’re using the Flex framework or not, I believe you will end up with different superclasses associated with your embedded assets. If you use Flex, you might see a FontAsset subclass where you would simply get a Font subclass were you only using ActionScript.

You can also embed SWFs and symbols from within SWFs, a technique I quite like. Simply use a symbol attribute in the compiler directive:

[Embed(source="MenuAssets.swf", symbol=”com.partlyhuman.assets.TopMenuItem”)]
protected const TopMenuItem:Class;

addChild(Sprite(new TopMenuItem()));

The transcoder should automatically know what to do with these kinds of assets:

• JPG/JPEG image files
• GIF image files
• PNG image files
• SVG/SVGZ vector image files (supports a subset of SVG 1.1)
• MP3 sound files
• TTF font files
• Installed system fonts
• SWF files and specific symbols inside SWFs

No, I Know What I’m Doing, Really

But get this! There are more things you can convince the transcoder to accept. By manually specifying the MIME type of the file, you can force the transcoder to interpret the data in some format. This is the solution to embedding any XML at compile time, and then some. In fact, you can embed any binary data you want in a SWF, as long as you know how to interpret it on the other side.

There may be additional interesting MIME types that are registered by the transcoder. These are, as far as I know, undocumented, so if you find an interesting one that’s not covered by the types above or these two introduced here, leave a comment.

Here, we see that we can import an XML file with MIME type text/xml, and it embedded as a subclass of XML.

[Embed(source="test.xml", mimeType=”text/xml”)]
protected const EmbeddedXML:Class;

var x:XML = XML(new EmbeddedXML());
trace(x.toXMLString()); //it should work!

To get this to work, you should keep the XML prolog in your XML file. With this technique, EJ didn’t have to load the XML asynchronously, it was embedded right in his SWF for instant access, binary compression, and easy deployment, and tight coupling with the build itself. He could also now use a normal, full-featured XML editor to mess with the XML source.

But it gets better! You can embed any binary data whatsoever in a SWF, as long as you know how to interpret it on the way out. To do this, use the directive to embed any file with MIME type application/octet-stream (an octet is just a fancy word for a byte, by the way, as a byte is eight bits, so a stream of octets is a fancy way of saying “a bunch of bytes”). The class comes out in ActionScript as a subclass of, can you guess? ByteArray!

Here, ActionScript genius Max knows how to parse a WAD file, which Doom and other ID games used for levels and sprites and all kinds of business. He puts it right in the SWF by embedding it as application/octet-stream and interpreting it as a ByteArray:

public class DoomTest extends Sprite {
    [Embed(source=”doom1-shareware.wad”, mimeType=”application/octet-stream”)]
    private const DoomWad:Class;

    public function DoomTest() {
        var wad:ByteArray = new DoomWad() as ByteArray;
        new DoomCore(this,wad);
    }
}

(Full source here) And, passing it to his Doom playing engine, you start playing the shareware level of Doom that was embedded right in the SWF!

You can apply this technique to any binary data you’ve cleverly figured out how to parse. Of course, Flash knows very well how to parse all the file types described in the list above, but with some creative coding, that’s just the beginning!

14 Comments »

RSS feed for comments on this post. TrackBack URI

1. Holly Hell. That is quite intense. Someone do Hexen as well!

   Comment by SatanHead — October 1, 2007 #

2. i just could not get the xml embedding to work as you said.

   i kept getting Syntax Error: xmltagstartend unexpected if i included a doctype, or my xml would come out as null.

   if anyone else is having this problem, i tried your second method and it worked:

   [Embed(source=”info.xml”, mimeType=”application/octet-stream”)]
   protected var EmbeddedXML:Class;

   var ba : ByteArray = (new EmbeddedXML()) as ByteArray;
   var s : String = ba.readUTFBytes( ba.length );
   xml = new XML( s );
   xml.ignoreWhitespace = true;

   Comment by e.j. — October 9, 2007 #

3. oh and thanks for everything roger!!!! :)

   Comment by e.j. — October 9, 2007 #

4. HI,
   I have been trying to get the Embed with mimeType = “text/xml” to work with no luck,Keep getting a syntax errors. here is my code :

   package {

   import flash.display.*;

   public class Embed extends MovieClip {
   [Embed(source=”/assets/employees.xml”, mimeType =”text/xml”)]
   var theClass:Class;
   public function Embed() {

   var xml:XML = XML(new theClass());

   trace(xml.toXMLString());

   }
   }
   }

   any idea ?

   Comment by Tareq — October 9, 2007 #

5. Thanks, it worked.

   Comment by Tareq — October 9, 2007 #

6. Hello,
   I have the same problems mentioned in the other comments. I get also the error xmltagstartend unexpected. So how does it really work to embed XML?
   Please help!

   Comment by Matthias — October 15, 2007 #

7. Hey Roger, are you sure the XML-example works for you? I tried it out in Flex Builder (2) and all I got was the toString() representation (”[object Model_EmbeddedXML]”)..

   Comment by Ruben Swieringa — November 13, 2007 #

8. Hello Roger,

   I’m having issues using your xml embed technique. I have a feeling it may be my prolog.

   Would you be open to providing us with test.xml that you used in the example above so that we can test with an XML file that works?

   Thanks!

   Comment by Jun Heider — November 15, 2007 #

9. Hey Roger :)
   That is cool example u have here.
   Is there a chance it will work with *.flv ?
   Actually I managed to embed it as byte array, but i could not figure how to translate it backwards.
   The problem I’m dealing with is that my client wants to put the player I made on a CD and he wants the videos to be part of the swf.
   Another way could be embedding the whole folder into swf.
   Is there a chance someone ever had to do it ?
   Thanks a lot.
   Fell free to contact me on my skype, the address is : atlaseli

   Comment by Eli — December 2, 2007 #

10. @Eli, I’m not sure you will have success playing back embedded FLVs, since the NetStream object seems to only want to load FLVs from remote locations… The one way I thought might work, though not exactly what you want, is to compress the videos as SWFs instead of FLVs, and then embed them and display with Loader.loadBytes().

    Comment by Roger Braunstein — December 3, 2007 #

11. Hi Roger,

    I am trying to embed an SWF created in Flash (CS3). After embedding it I want to access a parameter from it (a:String).

    I am not able to do it.

    [Embed(source=”3.swf”)]
    private const SWFAsset:Class;

    and using it as

    var swfMovie:MovieClip = new SWFAsset() as MovieClip;

    now I want to access a variable “a” from the movie clip.

    tried trace(”Val ” + swfMovie[’a'].toString());

    Any ideas??

    Comment by Y — April 4, 2008 #

12. yeah I have to concurr this example does not seem to work or at least not in FB2.01 as an Actionscript project. Real shame as I am going nuts trying to embed XML too sensitive to load remotely. Do we have to set compiler properties or compile outside of flex builder using mxmlc to get this to work? Or will the XML parser only work within a Flex project?

    Comment by rudestar — April 17, 2008 #

13. looks like a bug in the transcoder perhaps or the relevant transcoder is unavailable for an Actionscript project this seems to work:

    
package
{
import flash.display.MovieClip;
import flash.utils.ByteArray;

    public class Test extends MovieClip
    {
    [Embed(source="data.xml", mimeType="application/octet-stream")]
    private static const MyData:Class;

    public function Test():void{
    var byteArray:ByteArray = new MyData() as ByteArray;
    var xml:XML = new XML(byteArray.readUTFBytes(byteArray.length));
    trace(xml.toXMLString());
    }
    }
    }

    Comment by rudestar — April 17, 2008 #

14. PS. Thanks Dan. http://www.dan-hunter.net

    Comment by rudestar — April 17, 2008 #