Category Archives: Windows

Building a Windows Plugin for Unity: Lessons Learned

Here’s some fun trivia about Cosmic DJ: the way that we achieve our rock-solid musical timing and responsive tap input is by using an external audio engine that I wrote. Generally speaking I would not recommend doing this! However, it’s just not really possible to have perfect metronomic time if you are running your metronome in the main game loop. Fluctuations in frame rate mean fluctuations in the smallest timestep available to the metronome, so if a frame takes longer than a 16th note you’ll hear the rhythm get a little wonky! Anyway, that’s a separate discussion, I’m going to talk about all of the things I got caught on while trying to build this non-trivial plugin.

Develop in Visual Studio 2008

A major thing I got stuck on for a while was trying to build the plugin with Visual Studio 2010. It seemed reasonable enough to do so, but it turns out you must build the plugin against .NET 2.0, which was not something I was even able to select in VS2010. I attempted to install older versions of .NET to build against by searching around the Microsoft download site, but only wound up with installers that didn’t work properly in Windows 7. Visual Studio 2008, meanwhile, defaulted to .NET 2.0, so I used that. Other build settings that seemed to matter a lot were:

  • General > Common Language Runtime support => No Common Language Runtime Support
  • General > Charater Set => Use Multi-Byte Character Set
  • C/C++ > Code Generation > Enable C++ Exceptions => Yes (/EHsc)
  • C/C++ > Code Generation > Runtime Libarary => Multi-threaded (/MT)

Unity has a really simple example plugin in their documentation that I’d recommend simply copying all of the settings out of. It’s called Simplest Plugin and is linked under the Examples section of Build Plugins For Desktop Platforms in the Unity Manual. I suggest looking for this page in your local documentation, just to be safe.

Create A Single Project Solution

There are a couple other libraries included in the plugin that I wanted to statically link to, such as my own partial port of Minim to C++ (YMMV), and like you do I wanted to have a solution that included the vcproj for Minim as a sub-project. This turned out to be mostly problematic because of the very particular build settings required by Unity. I found it difficult to make sure all of my projects agreed in their settings and also linked together properly.

Put DLL Dependencies In The Correct Place

Windows doesn’t have audio file reading routines built-in (like CoreAudio does in OSX for instance), so we leverage a couple open source libraries to make this happen (libsndfile and mpg123 if you must know). Both of these libraries are distributed such that you link against a .lib, but the real code lives in a DLL that is loaded at runtime. Unity can handle this but not quite in the way you’d expect.

To work in the Editor: Any DLLs that your plugin depends on must be put in the top level of your Unity Project folder, not in Assets/Plugins as you might expect.

To work in the Standalone Player: Any DLLs that your plugin depends on must be put in the same folder as the exe file, which either means copying them by hand or writing a post-process script to copy them.

You Can Debug Your DLL Using Visual Studio

A cool thing: it’s possible to debug your plugin code in Visual Studio while the DLL runs in the Unity Editor. For your debug flavor you’ll want Runtime Library set to Multi-threaded debug (/MTd). With your project open in Visual Studio: start the Unity Editor, go to the Tools menu in Visual Studio and choose “Attach To Process…”, choose Unity.exe from the list (Visual Studio might hang out for a bit before becoming responsive again), set some breakpoints, and press Play on a scene in Unity that has a script that calls into your plugin. When you call into code that has a breakpoint, VS will catch it and you can inspect variables and do like you would normally do. Important: Unity won’t load your plugin until the first time a script calls out to it, so when you initially attach to the Unity process it’ll look like your breakpoints are inaccessible, which is true because the DLL hasn’t been pulled into the executable yet.

Use String Marshaling When Returning Strings

Behavior seems inconsistent across platforms with regard to how Mono deals with strings returned from plugin functions. In OSX it seems to work fine to return static strings, but in iOS and Windows this causes a problem when Mono tries to deallocate that memory. If you search around the web you’ll see that some folks recommend allocating a new string and returning that, so that everything is cool when Mono tries to deallocate it, but I was still getting crashes on Windows with that method. Instead, what you want to do is return a const char * from your plugin code and then have this in the C# binding:

Importantly, PtrToStringAnsi copies the string represented by the IntPtr and also expands characters to unicode, so now you’ve got a string that is made from managed memory and will not cause crashes when it goes away. Of course this means you definitely do not want to allocate a new string when you return one to Unity because that memory will be leaked.

Bug Fixing, Build Process.

Among all of the things that I have learned while working as a professional game dev, two very important things are 1) how to document and test bug fixes and 2) the importance of having a sane build process. I didn’t have a terribly good handle on either of these things when I first created Minim and as a result pushing out a release was a very painful process.

Bug Fixing

I’ve not always been good about keeping track of exactly which bugs I’ve fixed in a release, or which new features I’ve added. No longer! The past two days have seen verbose comments in my check-ins, which means I should be able to create a pretty exact changelog for the next release. Here’s my most recent check-in comment, to give you an idea of the kinds of things coming up:

Build Process

Creating and uploading new JAR files is not the hard part of doing a release. No, the hard part is making sure all of my online examples are up-to-date and making sure the Manual reflects any additions or changes to the API. The biggest pain with the examples is that the directory structure that I use on the website does not match the local directory structure, so it’s not just an easy drag-and-drop. I have my examples set up as a subdirectory in my Processing sketch folder, but what actually gets uploaded to the website are the contents of the applet directory that is generated for each sketch when I export it. Man, I would love to know a way to tell Processing to export an applet to a location other than the sketch folder, because then I could export to a directory structure that is the same as what’s on the web.

In any event, that’s a pain, and I need to figure that out, but I also finally got around to creating a subversion repository for all of the example source files. This will at least make it easier for me to tell at a glace which sketches need to have applets re-exported and uploaded. Maybe I can even figure out how to create an automated process for this. But, one thing I had to do before I could commit all of the examples, was delete all of the applet directories. To do that, I googled around and found this totally helpful batch file:

FOR /F "tokens=*" %%G IN ('DIR /B /AD /S *.svn*') DO RMDIR /S /Q %%G

That particular code will delete all subdirectories that match the name “*.svn*” under the directory it is executed in. All I had to do was change the name to match to “applet”. It’s all really clearly explained in this forum post and worked liked a charm.

So, that’s at least one part of my build process that’s been sanitized (by which I mean: made sane)!

Paradigm Shift?

Ever since reading this post about moving the Start menu to the top of the screen, I’ve occassionally considered it. I’ve also often found myself wishing that the Quick Launch toolbar in Windows behaved a bit better so that I could actually have it set on auto-hide and not have it jump out every time I try to use the scroll bar on a full screen program. In fact, I found myself wishing it would behave more like the Dock on a Mac. Well, recently I came across a program called RocketDock that emulates the Dock on a Mac and also is as customizable as the Quick Launch toolbar (moreso, actually).

My new desktop configuration.

It hasn’t broken my computer yet, so I feel pretty good about recommending it to people who maybe wish their PC was more like a Mac. One nice feature is that you can set it so that when you minimize something it becomes an icon in the dock and disappears from the Start bar. This helps keep the Start bar uncluttered when there are a lot of programs open but many of them are minimized. One down side to this is that when an icon does the little bounce thing to get your attention, it doesn’t bounce onto the screen. This means you have to periodically check the dock to see if any of your minimized windows are trying to get your attention, like an IM window or something.

Since I now I have Dock-like shortcut bar, I thought I’d just go whole hog and move the Start bar up to the top of the screen. It’s a little strange, but not so bad. I’ve locked it so it doesn’t have the funky looking beveled edge that it does when it’s resizable. The other thing I’m trying to retrain myself on is using the button on the side of my mouse to bring up an the application switcher instead of mousing up to the top of the screen and clicking on the program tab, or worse, mousing over to make the dock appear so I can click on a minimized window. If I’m switching back and forth between two programs, which is often the case when I’m working on the port or the unit test suite for the port, all it takes is two clicks of the mouse button to switch to the window I want.

I’m not entirely sure what it means to be rocking such a faux-Mac desktop. Maybe it just means that OSX has a better UI. In any event, it’s a nice change of scene and will hopefully reduce some unecessary mousing around and clicking.