After seeing back-to-back issues on Stack Overflow, it’s come to my attention that just getting MonoGame’s equivalent to Hello World running in Xamarin Studio on OS X is … rough. There are multiple pain points that will get in your way, so today’s post is a guide to hopefully get you past that first stumbling block. This information is accurate as of September 2013. In the future, these pain points will hopefully go away, so please leave a comment if this information has become obsolete.
If you’re really just getting started, then start by downloading the latest version of Xamarin Studio. During installation, you will be given the option of starting trials for Xamarin’s 3 commercial products, Xamarin.Touch (iOS), Xamarin.Android (Android), and Xamarin.Mac (OS X), for building self-contained and app-store compatible apps on those respective platforms. If you’d rather wait for a better time to start these trials, you can opt out of all of them. Xamarin Studio will fall back onto the free MonoMac for OS X building, which will be fine for getting started.
You also want to download MonoGame for Xamarin Studio (the third download). At time of writing, 3.0.1 is still the latest release version posted to CodePlex, but I’m expecting a new release to show up sooner than later. A newer version may fix some or all of the template issues we’ll encounter getting started.
The MonoGame download is an .mpack file. Once you’ve installed Xamarin Studio, open “Add-in Manager” in the application menu, and then select “Install from file” at the bottom. Find the MonoGame mpack to load it into Xamarin Studio. This will give you the MonoGame templates to get started with.
MonoGame Demo, First Attempt
Open Xamarin Studio and create a new Solution. Select the MonoGame Mac Application template. Once created, you’ll have the default demo project with Main.cs, Game1.cs, Content/logo.png, and your references setup. Everything should be ready to run.
When you go and hit the play button on your debug build, you’ll see everything build, and the game will attempt to launch. That’s all it will ever do though. On my machine the launch icon seems to bounce indefinitely and nothing ever happens. It’s not even debuggable. It seems to have paused execution, but attempting to advance the debugger in any meaningful way will just terminate the demo. If you’re sharp-eyed though, you’ll see the first sign of trouble as a yellow ! triangle in the build bar. Expanding the error console shows us this:
With “Warning: The referenced library ‘MonoGame.Framework.dll’ is not used from any code, skipping extraction of content resources.” That’s funny, the reference is right there in our references list, how could it not be included? Opening the edit references window sheds some light:
The template has selected the WindowsGL version of the framework instead of the Mac version. Strange, but this should be an easy fix! Well, it should be as easy as unselecting WindowsGL and selecting Mac. But if you play around with the checkboxes for a bit, you’ll discover that every version of the framework you check will also check WindowsGL. Further, unchecking WindowsGL after you’ve selected another framework will remove the framework from your references entirely. I don’t know if this is a problem with the template, or with Xamarin Studio, but it simply won’t let you select the right framework. Period.
Build From Source, Second Attempt
I could take a moment to point out that you could select the reference manually by picking the “.NET Assembly” tab and manually browsing to the MonoGame Mac framework assembly buried somewhere in Xamarin Studio’s application data. It happens that there’s other problems with the MonoGame 3.0.1 release that make this a non-starter anyway. The better answer is to build from source.
Download the latest MonoGame source archive off their GitHub page, and unzip it somewhere. The base directory contains lots of solution (.sln) files. Open MonoGame.Framework.MacOS.sln. Be careful not to confuse this with the content project — some of the names will be partially obfuscated due to their length. Perform a “Build All” on the solution. There will be lots of warnings reported, but they are benign.
Jump back to your demo game project. In the Edit References window, on the .Net Assembly tab, browse to the MonoGame source directory you unpacked. Then find the MonoGame.Framework.dll you built in MonoGame.Framework/bin/MacOS/Debug, and add it to your reference list. Don’t forget to remove the old MonoGame.Framework reference first.
Clean your solution, then rebuild and run again. Now you’ll be confronted with…
If you pry into the exception, you’ll see that it couldn’t load the “logo” content item because an expected file is missing. In my case, that path is the heinously long “/Users/jaquadro/Projects/DemoGame/DemoGame/bin/Debug/DemoGame.app/Contents/Resources/Content/logo.xnb”.
The Content/logo.xnb in the path corresponds to the Content/logo.png in your project. This file should be getting copied into your built app package (DemoGame.app), but if you manually poke around in Finder, you won’t even find a Resources directory in DemoGame.app/Contents.
If you examine the Build Action of Content/logo.png, you’ll see it’s set to ‘None’. Instead, this should be set to ‘BundleResource’, which will cause it to be copied into the app bundle. I have also found the ‘Content’ build action to do the same thing, but official word is ‘Content’ is obsolete and don’t use it.
If you’re curious as to whether the BundleResource action is turning your logo.png into logo.xnb, it is not. Normally you would compile your assets in the Visual Studio XNA pipeline, giving you XNB files to populate your Content directory with. However, MonoGame seems capable of finding and loading a png file fore a texture resource if the corresponding XNB is not present. If you want further evidence that there’s no magic going on, you can manually copy logo.png into your built app bundle, and it should run.
Your final attempt to run your game should yield success.
Hooray! On to the next challenge!