MonoGame “Hello World” on Mac OS X and Xamarin Studio

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.

Getting Started

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.

mgmac_1

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:

mgmac_2

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:

mgmac_3

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…

mgmac_4

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.

mgmac_5

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.

mgmac_6

Hooray! On to the next challenge!

About jaquadro

I am a full time software developer and part time game and game tooling developer.
This entry was posted in Tutorials and tagged , . Bookmark the permalink.

9 Responses to MonoGame “Hello World” on Mac OS X and Xamarin Studio

  1. Misu says:

    Hello,

    I was wondering if your tutorial will work with Xamarin Starter edition ?

    Thanks

    • jaquadro says:

      I don’t know enough about Xamarin.Mac specifically to give a solid answer. One thing I’m pretty sure is that the bytecode restriction on Starter is too small to let you actually deploy a MonoGame project, even a simple hello world one like this. I suspect you could still develop and run it locally.

      The MonoGame team was trying to coordinate getting MonoGame whitelisted, but I don’t know if they’ve managed to do that yet. Any whitelisting also would not apply if you built MonoGame yourself, which is something you have to do in this guide.

      Xamarin Studio itself is not intrinsically tied to Xamarin.Mac (or Xamarin.iOS or Xamarin.Android), so by using the free MonoMac runtime library instead, you can still do unlimited development for OS X. The MonoGame template references MonoMac by default.

    • Noah says:

      Hi, great tutorial! Helped me get started with my monogame->iOS project.

      Misu,
      From what I understand, the app size limitation will be the issue with the Starter edition of xamarin, but you can successfully perform this tutorial with the starter by downloading a 30 day trial at build time (at least, it worked for me targeting iOS, not OSX, but it should be the same, I think?). Using the trial, you can temporarily bypass the app size restriction, but builds only work for 24 hours each.

      To the original author of the post, thanks again, this was very helpful.

  2. GRZ says:

    Nice tutorial, very clear, I followed all the steps and my project is working at last. Thanks a lot.

  3. Breaking Floor says:

    Oh thank you thank you,
    you saved me alot of research and agony

  4. Rhinan says:

    Thanks a lot! This helped me a lot, since I’m really a newbie when it comes to anything higher than actionscript 3.0.

    I wanted to say though, that I didn’t get any error anymore after referencing the new framework. Is that because of a Xamarin update, or did I do something wrong? Anyway, it works I guess. Thought I should let you know.

    Thanks again!

  5. Thank you so much! I started out following a tutorial designed for Visual Studio and then when I got errors, I tried to solve each individual error and wound up spending ten hours accomplishing nothing. But today I decided to try again, to delete Xamarin and start over from scratch, and with the help of your tutorial, I was able to get it in 15 minutes! I was starting to worry that I would have to install Windows onto my computer! Thank you so much!

  6. Matteo says:

    You are the BEST!
    Thanks, today your tutorial works fine!
    The error about “logo” is fixed now.
    I used monoGame 3.0.1 and xamarin studio 4.2.2 (build 2).

  7. This post is perfect. Thank you!

Leave a Reply

Your email address will not be published. Required fields are marked *