Edit May 25, 2012 – Start
A LOT has changed since I first wrote this guide. The versions of MonoGame, MonoDevelop and Mono Framework are different enough now to cause some confusion when reading this guide. I don’t have the time to do a full re-write especially considering that things are going to continue to keep changing, but if you encounter a problem please do not hesitate to post your question in the comments section. I will do my best to help out. You can also check out the existing comments to find solutions to some discrepancies or just visit the MonoGame and MonoMac forums. Thanks!
Edit May 25, 2012 – End
This guide has a total of 4 parts. If you have a 2D Windows XNA game or engine that you would like to port over to MacOS, you should strongly consider using the MonoGame and MonoMac frameworks. Before I found out about MonoGame and MonoMac, I started porting from scratch using Objective C and Cocoa and it was a disaster. Perhaps it might have been much easier for someone familiar with Objective C and Cocoa, but for someone like me who had no experience whatsoever with the language or the API it was…sad…to say the least. Probably would’ve taken me months had I followed through. And even if I was an Objective C and Cocoa master I’m still guessing it would’ve taken about a month of work. That’s when MonoGame and MonoMac swooped in to save the day and I had my game running 99% correctly in just a few hours. This will be a guide to get that 99% going for you and also hopefully finishing out that final 1%. Thanks to Dominique (CarteBlanche) for adding video to the project and super dooper special thanks to Kenneth (kjpou1) for fixing all the issues I found when I started with MonoGame. If it wasn’t for him this guide would be 10 times longer! Ok, let’s get started!
Make sure your Windows XNA game will be compatible with MonoGame
The current version of MonoGame (2.0) doesn’t officially support 3D but there are cases of people modifying some libraries and getting 3D to work. I don’t cover any 3D in this guide, so if your game has 3D it’s really going to be up to you to figure it out.
You will not be able to use audio with XACT. A very simple alternative is using SoundEffect SoundEffectInstance classes. It is incredibly easy to modify your Windows XACT code to use SoundEffect SoundEffectInstance, HOWEVER, I personally have had problems getting SoundEffect/SoundEffectInstance to work correctly under Windows XP where as XACT works just fine. So I decided to leave XACT on my Windows game and just use SoundEffect/SoundEffectInstance on Mac. But again if XACT is critical to you then you should read next section and experiment with some samples before proceeding.
The original project on Windows must be compiled with XNA 4.0 or higher
It should be using the Reach Profile not the HiDef profile
If your game has video, please be aware that MonoGame for now only accepts the following video file types: mp4, mov, avi, m4v, 3gp. If you can’t convert your video to one of these types, MonoGame will not be able to load it. Video in MonoGame also takes a lot of work to get high functionality from so perhaps you’ll want to try out the Monogame Video sample which I go into in the next section. Lets start by downloading all the necessary tools on your Mac.
Download the complete XCode developer toolset for Mac, iPhone and iPad.
-The best place to get it is from
*In the downloads search bar, all the way on the left, type in XCode, then download the .dmg file for the latest version of XCode toolset which at this time is XCode 4.1 for Lion (3.1 gigs) and XCode 4.1 for Snow Leopard (4.6 gigs). This will ensure you have all the tools necessary, like Icon Composer and PackageMaker, to complete your project.
*Double click the .dmg file once it’s been downloaded and install with all default settings.
*Go to http://monodevelop.com/
*From main page click on Download button->Choose MacOSX
*At the time of this writing the latest stable version is MonoDevelop 2.8.2 so download that package (.dmg file) and if you see any other required packages, which as of right now is Mono 2.10.5 + GTK#, click on the download link, you will be taken to a new page.
*1. “Select Platform:” MacOSX
*2. “Download Mono for MacOSX:” Click on the SDK link and download that .dmg file
-Install the MonoFramework by double clicking on the .dmg file which right now is
*This launches installer, leave all default values, keep hitting Continue button then finally Install button, close when done.
-Install MonoDevelop by double clicking its .dmg file which right now is MonoDevelop-2.8.2.dmg
*Drag MonoDevelop icon into applications. Hit replace if upgrading from an older version. Wait till it’s finished processing then close that window.
Install MonoMac plug in
-Install the MonoMac plug in, by running MonoDevelop from Applications
*MonoDevelop Menu Item->Add-In Manager->Gallery Tab
*Make sure “All Repositories” is selected
*Expand “Mac Development”
*Highlight “MonoMac Development”
*When it’s installed, restart MonoDevelop
*To confirm that it’s installed go to File->New->Solution->C#->MonoMac and you should see 3 MonoMac templates
Download MonoGame framework
-Download the MonoGame framework that you will eventually add to your project:
*All the way on the right it says “Current Branch:” make sure it says “Develop”, there is a dropdown box that should allow you to choose that. This is the most up to date version and as of this writing contains a lot of the framework fixes that I partially helped debug.
*There is a “Zip” button near the top, click on this and download it and unzip it
*You should rename the unzipped folder “MonoGameFramework” for easier reference in this guide.
Getting the samples
That’s all you need to port your game. But I STRONGLY suggest you also download MonoGame and MonoMac samples as they will come in handy when trying to figure things out.
MonoMac samples can be found here https://github.com/mono/monomac/archives/master just click the “Download zip” button near the top.
MonoGame samples can be found here: https://github.com/CartBlanche/MonoGame-Samples just click on the “Zip” button near the top. You should rename the unzipped folder “MonoGameSamples” for easier reference in this guide.
Once unzipped the MonoMac samples are pretty simple to run, just double click on the .sln files, MonoDevelop should open up, then just go to Run->Debug and the sample should start running. Not all of them work though, but most do.
Getting MonoGame samples to work
The MonoGame samples take a bit more work to get going. This is what you do:
*Go to MonoGameSamples\Samples and double click on the MonoGame.Samples.MacOS.sln file.
*MonoDevelop should launch and you will immediately get a notification that 2 projects could not be found. This is fine, just hit OK.
*If you can’t see the Solution Explorer on the left, go to View->Debug and it should appear.
*If you expand the solution you will see “load failed” errors next to Lidgren.Network.MacOS and MonoGame.Framework.MacOS.
*Right click on each one (just those 2 projects) and hit Delete->Remove->Ok
*Right click on the listing for the Solution all the way at the top of the Solution Explorer and hit Add->Add Existing Project… If you renamed your unzipped framework to MonoGameFramework as I suggested, then navigate to MonoGameFramework\ThirdParty\Lidgren.Network\Lidgren.Network.MacOS.csproj file and hit Open->Ok
*Do the same as above but add the MonoGameFramework\MonoGame.Framework\MonoGame.Framework.MacOS.csproj file and hit Open.
These 2 projects are ALWAYS necessary in any MonoGame solution. And always make sure that the MonoGame.Framework.MacOS project always has a reference to the Lidgren.Network.MacOS project. To do this expand MonoGame.Framework.MacOS project in Solution Explorer. Expand “References” and you should see it listed there. If not, right click on “References” folder Edit References->Projects Tab->Check Lidgren.Network.MacOS->Ok
And you also have to make sure that any of these sample projects have at least a reference to MonoGame.Framework.MacOS, sometimes they require both. A simple project that should work right off the bat would be PerPixelCollisionSample. It should be referencing MonoGame.Framework.MacOS. If not add the reference.
Right click on PerPixelCollisionSample and select “Debug item” and it should just run. Most other samples should run fine as well just always check to make sure all references are correct.
A few words regarding video
If your game has video you should definitely try out the Video sample and see if you feel comfortable with it. (btw, the current video sample opens up in full screen which makes you have to force quit the program to close it. To fix this, in the Game1 constructor change graphics.IsFullScreen = true; to false and it will work right ). If MonoGame’s implementation of video is just what you need then great! But if not, you may have to put a bit of work into it. Video, by far, took me the most amount of effort to get it to work the way I wanted. In Solution Explorer, if you go to MonoGame.Framework.MacOS\MacOS\Media\Video.cs file you will see near the top:
private QTMovie mMovie; private QTMovieView mMovieView;
So as you can see MonoGame basically used MonoMac’s implementation of QTMovie and QTMovieView. I created my own QTMovie and QTMovie view objects and bypassed MonoGame’s implementation altogether to get the functionality I required. You can research these classes fully at developer.apple.com. Because MonoMac is so awesome you can basically do anything with it that you can do with Cocoa so any documentation you read on developer.apple.com will for the most part apply to MonoMac’s implementation of it as well. Sometimes the method names are a bit different but it’s all basically there. Don’t worry you won’t need to learn OpenGL or anything like that. Just study the documentation and study MonoGame’s implementation of Video and VideoPlayer and I’m sure you’ll be able to work it out.
This concludes Part 1 of the guide. In Part 2 I will begin to detail how to create the MonoDevelop project that you will use to port over your game.