Loading a Unity SWF in Flex

With the release of Unity 3.5's Flash export option there are many new opportunities for Unity and Flash developers. Since my career has mainly involved working with both technologies, I wanted to try loading a Unity-exported SWF file into a Flex application to prove the possibility of a Flash game incorporating Unity content. It's straightforward to do, but the requirements aren't documented in one spot. This article should help solve that. It does not cover Flash-to-Unity communication, but it's the right place to start. Below is a short list of requirements that I'll be explaining:

• Flex project must use at least Flex SDK 4.6
• Flex project build should target Flash Player 11.1.0
• Add the Additional Compiler Argument: -swf-version 13
• The flash player embed needs to include the attribute wmode=direct
• Your .mxml application tag might need to include backgroundAlpha="0"
• Include the UnityShared.swc file in your project
• Download the files provided by Unity in this forum post by Unity

Using Flex SDK 4.6 You must have at least Flex SDK version 4.6 to make sure your project has the neccessary Molehill and AIR APIs available. If you don't already have it, download it here and then set your Flex SDK version by going to: Project -> Properties -> Flex Compiler -> Configure Flex SDKs -> Add... Then select your downloaded 4.6 SDK folder. After selecting the folder, be sure to come back to select it from the list on the Configure Flex SDKs panel.

Targetting Flash Player 11 Your project must build to Flash Player 11 because it's the first Flash Player to support molehill's 3D rendering. You won't be able to set Flex to use this version until you've set your project to use SDK 4.6. You can set your application to target Flash Player 11 by going to: Project -> Properties -> Flex Compiler Then check off Require Flash Player version and set it to 11.1.0. You will need Flash Player 11 installed on your computer to view the 3D content.

Additional Compiler Argument Setting the swf-version to 13 allows the Unity SWF to utilize AIR 3 APIs that it requires. You won't be able to do this until you have your project set to Flex SDK 4.6, otherwise it will throw an error. To set the swf version go to: Project -> Properties -> Flex Compiler In the Additional compiler arguments text box be sure to include the argument -swf-version 13. You can read more about SWF versions from Adobe's blog.

Using wmode="direct" In order for Stage 3D content to display, a Flash variable called wmode (window mode) needs to be set to equal direct. This requirement causes a Unity SWF to not open properly in a browser directly and you'll see some errors. The wmode attribute is set in the embed code running your Flash content. I set it in the following two places in my HTML and JavaScript:

AC_FL_RunContent(
		"wmode", "direct",
		....
	
if (hasRequestedVersion) {
	// if we've detected an acceptable version
	// embed the Flash Content SWF when all tests are passed
	AC_FL_RunContent(
			"wmode", "direct",
	....
    

And lastly make sure that the HTML embed tag has the attribute wmode="direct".

Change the Stage Transparency I believe there are two stages when working with molehill. There is your normal stage layer that we've always known and loved. And then there is the Stage 3D layer. The Stage 3D layer is rendered behind the normal stage.

If you load a Unity SWF into an empty stage you'll likely see a blank white screen. The trick is to turn the transparency of the normal stage to zero and it will reveal the Stage 3D content behind it. This can be done in your .mxml file by giving whatever application tag you use to have the attribute backgroundAlpha="0".

The cool thing about the two stages is you could create UI elements in Flash that overlay your Unity content. The down side is I don't believe it is easily possible to show Unity content above Flash content. For instance your game probably couldn't have a pop-up window displaying Unity content unless you can easily detect and hide whatever Flash objects are overlapping it.

Include the UnityShared SWC file To load and communicate with the Unity SWF you're going to need to include a SWC file called UnityShared.swc in your project. This file is created when you export a SWF from Unity. For convenience you can also download it from me. After moving the file into your project go to: Project -> Properties -> Flex Build Path Click Add SWC... and select UnityShared.swc. This SWC file contains a few classes made by Unity. The class we care about is UnityContentLoader.

Loading Unity Content To load the Unity content you're going to need to look at this forum post provided by Unity and at least download the file entitled "AS3Communication_as3_src.zip". Add the two ActionScript files to your Flex project as well as the images. You will probably want to edit the file called SimplePreloader.as and change the line that says:

unityContentLoader = new UnityContentLoader("unity-flash-small.swf", this, params, false);
    

You want the string "unity-flash-small.swf" to be the name and path of the Unity SWF you want to load. You might even want to change this class to accept a string URL for the file you are loading to make it more reusable. This class can load in remote Unity SWFs from web servers, or it can load local files. Once you have this part set up the way you want, you can get things rocking and rolling with the following code wherever you want to load the Unity SWF in your project.

import com.unity.UnityContentLoader;

private var unityContentLoader:UnityContentLoader;

private function startLoad() : void {
	var loader:SimplePreloader = new SimplePreloader();
	stage.addChild(loader);
}
    

This should be all you really need to get started with loading in Unity content to a Flash application. If you want to know about communicating with the loaded Unity content I recommend continuing to read this forum topic . To export a SWF file from Unity, read this page on their website.

Comments...

Why I Don't Use Unity's JavaScript

When I started using Unity in 2005 I was very attracted to programming with JavaScript. It had easier syntax and less rules for me to bother with. And Unity's documentation at the time was completely done (I think) with JavaScript examples. It just made sense to use it.

I continued using JavaScript for 4 years. During that time I ran into many confusing frustrations and started to gradually strictly type my JavaScript to avoid problems. It eventually reached the point where it just made sense to switch over to C#. I can't stress enough how much of a difference this has made in my coding experience with Unity. Here's why...

Compiler Confusion
There's quite a bit you can get away with using Unity JS. So much in fact that you might actually have many errors in your code, but they only occur during run-time. This mostly happens when an untyped variable is assigned to a typed variable. For example

var aVector;
var anInt : int;

function Start() {
	aVector = Vector3.zero;
	anInt = aVector;
}

This code compiles just fine. But as soon as it's executed during run-time an error will occur. A pretty easy fix as soon as the error pops up. But that's just it. What if you never hit the case where the error occurs? You end up releasing your game with a bug just waiting to happen. And it probably will. Strictly typing your code or using C# will avoid this issue.

IDE Confusion
This is more of a convenience frustration. If you're using an IDE like MonoDevelop and you're programming with untyped elements of your code, then your IDE won't be able to use some of its convenient features. Looking at the code example above, your IDE would not know to list Vector methods when dealing with variable aVector. Strictly typing your code or using C# will avoid this issue.

Improved Run-Time Performance
You may not ever notice it, but strictly typing your code or using C# will actually make your game faster during run-time. Cool!

Benefits of C#
Some major benefits of using C# (not strictly typed JS) is that it's a completely documented language. If you ever want to know how to do something, just look it up. JavaScript doesn't have official documentation and Unity's implementation of JavaScript is not the same as the JavaScript known to the web. So it can be annoying just to look up even the simplest thing. In fact some times you'll need to look up C# syntax to figure out the correct syntax for Unity's JavaScript.

Using JavaScript will restrict you from using some libraries that C# will be able to use. But C# can use all the libraries JS has access to. For example C# can access the LINQ libraries but Unity JavaScript cannot.

Compiler Confusion Continued
There are areas of the Unity API where both JavaScript and C# users are led into avoidable issues with the compiler missing errors. A big culprit being the GetComponent function. One way of using it is by passing a string for the name of a component, rather than a type. This caused me major headaches. I used to love it because I could simply type in a string of the component I wanted and BAM it worked. Really awesome; until you make a typo that's not obvious at all and the compiler isn't pointing it out. Here's an example of just how much you can get away with without the compiler throwing an error. In the example below the component and its variable do not exist, but Unity is totally cool with it during compilation.

var c : int  = GetComponent("Something I Just Made Up").someVariable;

If you're cautious with your decisions and ensure the compiler can catch as many problems as possible, your development process is going to go much smoother.

See you at Unite 11

Hello again folks! Today I'm happy to share with you that I'll be heading off to Unite 11 in a few days to represent Lumos Game Analytics with my good pal Matthew Miner. So if you'd like to meet up at some point, whether it be to discuss Lumos or just to grab a drink or two, just give one of us a shout.

We had a lot of awesome developments over the summer while preparing for Unite. We have a lovely new site design, a new charting system, and new features that will rock your world. You can also download Lumos from the Unity Asset Store now. Pretty sweet eh? More importantly though, we have saved our biggest new features to be released right around Unite. So stay tuned for that cause I'm told I'm not allowed to spill the beans just yet. But I wish I could, cause they are some damn tasty beans.

It's a big moment for Matthew and I. It was about 5 years ago now I think where I remember the two of us being in school and playing around with the Unity engine in our spare time. Unity announced they'd be having a conference in San Francisco called Unite. We thought of ways we could get there, but as broke teenagers living 4067 km away it just wasn't gonna happen. I was fortunate enough to make it to Unite last year in Montreal representing my previous employer, dimeRocker. But it wasn't beautiful San Francisco and Mr. Miner wasn't able to make it. So I'm really looking forward to the coming week, it's a great feeling making an old dream come true. Hope you can be a part of it and hope to see you there!