Cat Burton

[Update: The project is now available on Github. Feel free to contribute! ]

For a while now, I’ve had this project sitting in an unfinished state and figured it was time I gave it a tidy up and made it available for people to use.

A quick disclaimer before I go into the details: I started the project with the hopes of putting this as a package on the Unity Asset Store. However with a lot of other projects and responsibilities, I don’t have the time to dedicate to the project to make it as good as it could be and support it after release. As such, I’m making it available here for free in a working but basic state which can be used in your projects freely. I’ve given the code a quick clean-up so it should hopefully be easy for people to work with. It’s far from finished/perfect but I’ve tested this in Unity 4.2 Pro on a Mac and it seems to work fine. While I don’t have time to actively support this project at present, if anyone does spot any major issues or adds improvements, I would love to hear about them!

Here’s what the tool currently looks like in Unity 4.2 Pro:

So, on with the details…

A Bit of Background (why I made it)

As a developer, I feel much more secure when using test driven development. Having tests which automatically run and alert you to any issues as you expand/refactor your codebase is incredibly valuable and implementing them saves a lot of time in the long run. Unfortunately, for Unity projects there hasn’t been much in the way of utils/libraries which support unit testing. There are a number of unit testing frameworks available to use, but they require manual setup and provide no Unity-specific utilities to make them simple to use.

This is what my UnityUnitTesting package was intended to solve. I have taken NUnit Lite, added some simple wrapper scripts and implemented a UI to enable you to run and visualise your unit test results from within the Unity editor. The library has the ability to watch your code for changes and automatically run your unit tests whenever your scripts are recompiled (after you see the spinner in the bottom-right of the unity window). This removes the manual step and prevents you forgetting to run them. If you don’t want the editor window visible all the time, the system still logs an error or warning for any broken/ignored/skipped tests it finds.

I’ve tried with this system to have it auto-detect your tests so you shouldn’t have to do any set up. Just add the package to your project, write your tests and have them run. Again on the disclaimer front – I’ve only done limited testing of this, but the code is simple enough that you should be able to easily customise/patch it for your specific requirements. It currently works by browsing the two assemblies you’re likely to be working with (“Assembly-CSharp”, “Assembly-CSharp-Editor”) for any available test fixtures. It then runs all your tests on a per-assembly basis. If you wish to add/remove an assembly, you can do so by adding it to the _assemblyNamesToTest HashSet at the top of the UnityUnitTester class. For most of you though, you hopefully shouldn’t have to change anything.

Setup

You can download the package from this link.

Once you’ve added the package to your project (Assets -> Import Package -> Custom Package…), you should see the following folder/files added to your project:

As you’ll see from the screenshot, I’ve added four TestFixture classes as examples. Here you’ll find a lot of example unit tests making use of various options in the NUnitLite API. It’s worth keeping these files initially so you can ensure the system works and can even use them as a template for your own tests. Once you’re happy with the setup, feel free to delete all of the example tests.

To view the editor window and test results display, go to Window -> UnitTesting -> ShowWindow:

This will display the unit testing results window which has options to manually run the tests or disable the auto-running of them. Below is what you should see if you’ve kept the example test fixtures. I’ve expanded the results in the screenshot to show the details:

From this screenshot, you can see that any failed tests or errors are shown in red. Anything which was skipped or ignored is shown in yellow. I have removed highlighting of passed results (they used to be green) to help these other tests stand out, however that would be easy for you to re-implement should you wish to have that feature back. With the highlighting set up this way, you can quickly browse the collapsed list of fixtures and easily spot any red lines to help you quickly identify failing tests.

If you wish to disable the automatic running of tests, you simply need to check the checkbox. This setting should be saved in your preferences automatically (again, disclaimer, I’ve only given that a very quick test).

The window will no doubt get rather large as you add more tests. In case you’d rather not see it all the time, I’ve set the system to debug log a summary of the test results. The way I tend to work is to have the window hidden and only show it if I spot an error/warning in my console:

And that’s it! I hope someone finds this project useful!

Useful References / Links

• NUnitLite
• [Package Download Link] 

Over the last weekend, I’ve been hard at work trying to get an unannounced Mind Candy project (made in Unity) to export to Flash.  I thought it would be useful to share some details from the experience since most of the issues I’ve encountered would probably be avoidable if your project is architected in a way that lends itself to Flash export.

During the Christmas holidays, I made a game for Unity’s Flash in a Flash contest. It wasn’t the most exciting game, but it worked. The core mechanic of that game (including new 3.5 features such as nav mesh) exported to Flash well. The reason this game worked is because I had been paying close attention to the Flash export and knew what features wouldn’t work at that time. I avoided anything overly complicated and developed the game with the limitations in mind. Fundamentally, I decided to make a new, simple game rather than trying to port an existing one.

Now, I’m doing the opposite. I’m trying to get an existing game to publish to Flash. This project is a relatively large one. The game has been in development for quite a long time. It contains a lot of complex C# code and most importantly: a lot of features that don’t yet work in the Flash export. Trying to get this game to export to Flash is no easy task. I’ve spent numerous weekends on this since the 3.5 beta was made available and I still haven’t got it to work.

Despite the export (currently) not working for our project, there are a lot of lessons to be learned. Hopefully these will be of use to other people attempting the same task, and will be a good reference point for myself when I inevitably try to export the game again at a later date.

Currently Unsupported Features

Unity have already listed some of the unsupported features in the Flash export as part of the 3.5 preview faq. Some of these features (and the ones that have proved most problematic for me) are:

• LINQ
• Terrains
• Asset Bundles
• WWW
• Raknet networking

If you’re using these features, then you’ll encounter a lot of errors as soon as you try to get Unity to build to Flash. Some example errors I’ve seen are:

Networking

• error CS0246: The type or namespace name `ConnectionTesterStatus’ could not be found. Are you missing a using directive or an assembly reference?
• error CS0246: The type or namespace name `NetworkView’ could not be found. Are you missing a using directive or an assembly reference?
• error CS0246: The type or namespace name `BitStream’ could not be found. Are you missing a using directive or an assembly reference?
• error CS0246: The type or namespace name `WWW’ could not be found. Are you missing a using directive or an assembly reference?

MovieTextures

• error CS0246: The type or namespace name `MovieTexture’ could not be found. Are you missing a using directive or an assembly reference?

These errors are effectively a checklist of all the classes you’re using that aren’t yet supported and there’s only one thing you can do: remove them from your build. There are numerous ways to do this (depending on what you’re trying to achieve), from brute force deletion to telling Unity to skip these sections in a Flash build. You can do the latter by using platform dependant compilation.

All you need to do is wrap your Flash specific code in a platform check such as:

#if UNITY_FLASH
Debug.Log(“Flash build”);
#endif

In my case, the first thing I had to do was to try and remove these unsupported features. MovieTextures were easy to take out, as they’re not vital to our game. Networking, however was more problematic. And this is my first (and most important) lesson…

Lesson 1 – Separation of Networking Code

Our game currently uses the inbuilt RakNet networking solution. These networking elements are fundamental to our game, and as such, the networking code exists in many different areas of our codebase. When publishing to the web player or a standalone app/exe build this is fine. For Flash export, this suddenly creates a big problem when the networking solution isn’t yet supported.

As an example, if your game uses RPCs across clients to update core data in your game, then you’re going to have problems. I’m sure that there are other solutions which are better suited to Flash export, but this doesn’t fix my immediate problem: we have a game, where our chosen networking solution won’t publish to Flash. Unity suggest that you can use Flash networking instead of RakNet, but since I’m doing this export with tight time constraints (self imposed, by the mere fact it’s a weekend), that solution is not feasible for this test.

This has left me with one option in my mission to get our game working: rip out RakNet. This is not ideal, but luckily, our game copes with it ok.

This raises an interesting point in that the networking code should be as decoupled from the core mechanic of your game as possible. In some cases this can’t be done, but if you can find a way to make your networking layer easily removed/changed, then you’ll be in a much better place than I was regarding Flash export. It will also help you if you ever decide to switch to a different networking solution.

At this point, I’m going to gloss over about 10 other failed builds. It takes a few attempts at building to clear up this first wave of errors. Once you’ve cleared that first wave, you can breathe a sigh of relief and ready yourself for wave two: Attempting an actual build…

Attempting a Build

Once you’ve fixed/removed/hacked-out all the unsupported features, you’ll get to a point where the build process will now try to publish your game to Flash. The type of errors you get now will be more complex than those in wave one. Below is a screenshot of one of my build attempts at this stage:

You’ll note that these errors are more complicated than the “you can’t use ClassX because it’s unsupported” ones. In the case of these errors, it’s up to you to go into each of these classes and try to simplify your code as much as possible.

Some areas where our build failed were where we’d used generics. For example, we had fairly complex code to randomise the order of elements in an array. It wasn’t vital, so it went in the bin. This seems to be a common trend in trying to get this project to build to Flash. I’m slowly, over time, discarding features to the point where it’s a very stripped-down version of the game.

There are a couple of errors regarding our audio library in the above screenshot. This library wouldn’t convert at all (I got multiple waves of errors). My only solution at present has been to remove it.

The last item in that list is log4net. This caused a lot of issues. Rather than spending ages resolving them for this test, I decided it should also be removed. Since we used the logging in a lot of our code, I’ve ended up writing my own logging classes based on the log4net interfaces. This meant that I only had to fix up the imports in the class and our existing logging would still work using Unity’s own Debug.Log etc.

A few more iterations and build attempts occurred before wave 2 was complete. All in all, the first two waves have taken out large chunks of our features, and as a result the game feels somewhat unstable.

Akin to a game of [insert zombie survival FPS game of your choice here], we’ve just about survived the first few waves. We’re battererd, we’re bruised, but most importantly, we’re not defeated! We’re now ready for the next wave. Bring on the boss; the tank; the last major hurdle in the flash export – the conversion of your code to ActionScript.

Converting your code to ActionScript

At this stage, when you try to build, Unity will attempt to convert your source to ActionScript. Having previously spent years as a Flash developer, I find this part of the build rather exciting. The guys at Unity have done a fantastic job of getting this process to the stage it’s at.

That said, this is probably the toughest part of the process. Ripping out features and (to some extent) fixing the errors in the previous stage is easy. Trying to work out why the generated ActionScript doesn’t work is much more difficult. Luckily, when a build fails, you can find all the AS classes in a temp folder in your project (/Temp/StagingArea/Data/ConvertedDotNetCode/global/). This will enable you to look at them (if you wish) and try to understand where it might be going wrong, such that you can adjust your C# or js accordingly.

In my first attempt at this stage, I was left with 87 errors. The following are a small selection of these to give you an idea of the kind of problems I’ve seen:

Conversion Error 1

• Error: Access of possibly undefined property $Type through a reference with static type Class.

This error seems to be very common and occurs when reflection is used (and probably in other situations). Unfortunately, a lot of our core libraries use reflection, and as such, this is a large problem to try and fix.

Conversion Error 2

• Error: Call to a possibly undefined method IComparable$1_CompareTo_T through a reference with static type Number.

This has occurred because we’re trying to compare two values whose classes implement IComparable. In our case, this could be worked around relatively easily.

Conversion Error 3

• Error: Type was not found or was not a compile-time constant: ReadOnlyCollection$1

In some of our classes we’re providing access to ReadOnlyCollections. It seems that we can’t use these at present and we could work round this by simply returning a standard Collection.

Conversion Error 4

• Error: Call to a possibly undefined method String_Constructor_Char_Int32 through a reference with static type String.

A common style of conversion error that’s quite tricky to work out. I saw a lot of errors similar to this one.

These are just 4 of the 87 errors which need fixing. I expect that if/when all 87 are resolved, I’d have another wave or two to get through before the game would actually build. For now though, it’s Sunday night and I’ve run out of time to work on this test.

Next Steps…

My next challenge in this Flash export test is to go through the aforementioned 87 conversion errors and try to resolve them. I’m hoping that I’ll be able to get the game to build after another solid few days working on the export.

If that task proves too difficult then I will try a different approach of starting from a clean project and adding features one by one. In theory, that should be easier to get working, although that’s not how we’d want to export to Flash in the long run.

If I do get the export to work, I shall write a follow-up post with a walkthrough of some conversion errors.  For these, I’ll include (where possible) the raw C#, the converted AS, and examples of how the errors can be avoided/solved.

For now though, I’m going to give up and play some well-earned Killing Floor!