Click here to Skip to main content
15,745,306 members
Articles / Mobile Apps / iOS
Posted 17 Dec 2014


20 bookmarked

All Hail the Old and the New – The MonoGame Content Builder Tool

Rate me:
Please Sign up or sign in to vote.
4.54/5 (14 votes)
17 Dec 2014CPOL9 min read
All Hail the Old and the New – The MonoGame Content Builder Tool

Image 1

Thought I might try and write the longest title ever on my blog, not sure I’ve made it but it was a worthy effort.

The World of Content

Back in the hay day of XNA, we had a lovely little extension that allows us to create a separate project for all our games assets and then reference them with a single pointer, these were the content projects!

Image 2

The XNA Content Project and content reference

These were fantastic devices and automagically compiled, compressed and built our XNA assets in to our project.

When MonoGame first started, they attempted to emulate this but had to resort to reusing the existing Content Project setup, still using the XNA content project template and a custom build MSBuild project to compile the XNB files needed in your game solutions.

Image 3

The MonoGame Content Builder project and its XNA content project

Once the content was built, you had to either copy or link the XNB output files manually in to your game solution, not an ideal scenario but necessary to maintain backwards compatibility with XNA.

Enter MGCB – the MonoGame Content Builder Tool

Image 4

MonoGame Content Builder Tool (MGCB)

Deep in the bowels of the current MonoGame development is a new tool for handling content, within its walls there are a multitude of enhancements and changes to better handle content consumption and packaging as well as simplifying adding and managing content building with your game projects.

Like the XNA Content Project of old, you create a new Asset Database in the tool, add your content to it as normal (setting the relevant content importer types for each file) and save the project to a new “.MGCB” content project definition. Armed with new content definition file, you finally add it to your project and set its build action to “MonoGameContentReference”, then hay presto you have referenced your content project:

Image 5

The new MGCB Content reference

Now we’re cooking, if everything is set right, your content project will build with your game (also it won't rebuild if there are no changes!) and we’ve almost achieved parity with the simplicity of the old days with XNA.

Have an XNA Content Project Already?

If you already have an XNA content project setup the way you want and don’t want to waste time building it all again!, then the MonoGame content builder tool has your back.

Image 6

Using the “Import” option in the file menu, you simply select an existing “.contentproject” then it will read the old definition and import all your settings and content into the new Content Project, as if by magic!

So Why All the Fuss?

So, apart from sanitation, medicine, education, wine, public order, irrigation, roads, a fresh water system and public health, what have the Romans ever done for us? (I do love Monty Python quotes –

Apart from a simpler system, why do all this? To which the answer is simple. The biggest issue with using the old Content Builder solution with XNA Content Projects was that it could only be built on Windows machines (since that’s where XNA’s main support lay).

However with the new MGCB tool, it is now possible to build content on all of MonoGame’s platforms.

There is one drawback that the team are still working on, the tool itself. At the time of writing, the tool itself is still being developed and on some platforms is not yet complete:

  • Windows – Core development platform and up to date
  • Linux – Mostly complete with a few of the processors still needing some testing / tweaking
  • MacOS / iOS – Currently in heavy development

This means that not only will you be able to build content in your projects, you will also be able to use the tool to create content projects on a variety of platforms.

Actually, since the .MGCB project file is just text, you can configure it manually if you wish, however I wouldn’t recommend it. Image 7

Getting Started with MGCB

If you want to use the MGCB tool now you can, you will just need the latest MonoGame installer which can be found in the Development Builds section of the main MonoGame download page, there are installers for Visual Studio and MonoDevelop on Windows, Linux and Mac here:

Once that is installed, you will have the current version of the MGCB tool installed. Additionally, all the MonoGame project templates have been updated to include a MGCB content project definition which you can edit and add your content to.

On Windows, the current list of templates includes:

Image 8

*Note, you still need XAMARIN’s extensions on Windows to use the Android, Ouya and iOS templates. Android can still be built using MonoDevelop on Windows.

Start any new solution and it will look like the project solution shown earlier (In the Enter MGCB section).

Samples Updates

AND there is even more, the multi-platform samples have been updated to use the new Content Builder tool as well, you can find them at:

Here you will find out 3 main samples in various states of development:

  • The Platformer 2D sample – Fully working on all platforms!
  • The Neon Shooter sample – Running on Windows GL but ready to be updated for all platforms
  • The SpaceWar sample – a development test bed as it has some leading content / dev requirements. (doesn’t run at the moment post update, but work continues – It’s a BIG sample)

The team continues to advance the sample set as a “Best Practice” example of how to make your games run on all platforms and show the best way to organise your multi-platform projects.

Yes, we are still working on the documentation for each sample, it’s a hard job and everyone has only so much time. Help out if you can!!

Of note is that EACH sample only has ONE content project, this project is then shared by ALL platforms and built for the correct platform at build time!!


Upgrading your Project

Now it is possible to upgrade your project to use the new Content Builder tool but at present it is a manual process. It is however just a couple of steps:

*Note, at the time of writing, the MGCB tool only fully works on Windows platforms, you still need a Windows machine to edit the MGCB configuration. Keep checking the website for full Linux and MacOS support.
However, the Content Project works and builds content for ALL platforms.

  1. Install the latest Dev installer (needed to install the tool itself) – We recommend you uninstall the old installer first if you already have it.
  2. Back up your existing project, if you are using source control, just push your latest changes up to the server first.
    If you aren’t using source control !!!Start using it!! (are you crazy?). Also make another backup “just in case” (you can never be too careful)
  3. Exclude / remove and content / links / build processes you already have for publishing your content in your project.
    Just move any pre-built XNBs elsewhere and if you have build scripts copying them, remove the script. If you are linking XNB files, remove the links from your project. This should leave your project in a clean state with NO content.
  4. Save your project – next comes the tricky part – manually editing your csproj file (the project file)
  5. Open up the project file (.csproj) in your favourite text editor (or use the VS powertools “edit project file function)
    You will find the VS powertools in the Visual Studio Extension library, click “Tools –> Extensions and updates “ (in the VS menu) and then search for power tools.
  6. At the end of the first <PropertyGroup> section, add a new <MonoGamePlatform> section as follows:
      <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
      <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
      <SolutionDir Condition="$(SolutionDir) == '' Or 
      $(SolutionDir) == '*Undefined*'">..\..\..\</SolutionDir>
  7. Set the name of the platform to the one your project file is targeting, the options are:
    Android, iOS, Linux, MacOSX, NativeClient, Ouya, PlayStation4, PlayStationMobile, RaspberryPi, Windows, WindowsGL, WindowsPhone, WindowsPhone8, WindowsStoreApp, Xbox360.
    Note for Windows 8 you should use the Windows target. WindowsStoreApp is for 8.1 games or Universal Windows targets.
  8. At the end of the project file before the </Project> marker (preferably with the other <Import> sections), add the following line:
    <Import Project="$(MSBuildExtensionsPath)\MonoGame\v3.0\MonoGame.Content.Builder.targets" />

    This will enable the “MonoGameContentReference” Build action to appear and enable the tool.

  9. Add a new text file in your “Content” folder and rename its extension to “.mgcb” (for example “Content\mycontent.mgcb”) – the simplest way to create a new MGCB project.
    Note, you should see a new icon for the file appear. If it doesn’t, then check your install of the MonoGame installer, make sure it’s a dev version and not the 3.2 release.
  10. Double-click the MGCB content file and open the MGCB tool, add in your assets manually or import them from your old .contentproject.

*Note, at the time of writing, there was a bug with the MGCB tool where it didn’t always open the file it was launched with. Just check and open it manually while in the tool to be sure. Hopefully, that will get fixed soon!

Once all that’s done, save your project file and reload your project in your code editor.

If you build your project now, it will spit out your compiled project together with your compiled assets automagically, never needing to link files or rely on a separate or scripted asset build again.

Ahh But for the Roses

Now as this is still a development build for the tool and there are a few caveats:

  1. It ain’t 100% finished and there are maybe bugs (however, you will note the Platformer sample is all updated, builds fine and runs on all platforms!)
  2. XACT projects aren’t supported (actually it was found that XNA didn’t even handle XACT, they were just pushed out the other side!, odd what you find out) just add your audio files individually and use them as normal with Content.Load<Song> etc.
  3. The Linux tool is almost there – why not help test it
  4. As noted above, the MGCB tool doesn’t always open the file you launched it from. Just check you are looking at the right content file before making changes. To be on the safe side, just open it manually from the tool (which was found out in a LIVE stream by Andy and Tom, it was fun Image 9)
  5. Multi-platform content is now a doddle! Have fun.

If you have any further questions / queries / rumblings or a tendency to fiddle, then jump on the GitHub site, test and report issues (only if you find them, an issue saying “What a fantastic tool” are nice but not helpful!!)

Jump in and get involved!

*No code was harmed in the production of this article but many Java beans were slaughtered for their juice!


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Written By
Architect ZenithMoon Studios
United Kingdom United Kingdom
Long-time game developer / IT maniac.
By day I architect, design, build and deliver enriching Mixed Reality solutions to clients, bringing the work of AR/VR to light in new and interesting ways, by night I Masquerade as the Master Chief of ZenithMoon Studios, my own game development studio.

At heart, I am a community developer breaking down lots of fun and curious technologies and bringing them to the masses.

I'm also a contributor to several open-source projects, most notably, the Reality Toolkit and all the services provided by the Reality Collective, The Unity-UI-Extensions project, as well as in the past the AdRotator advertising rotator project for Windows and Windows Phone.

Currently, I spend my time fulfilling contracts in the Mixed Reality space (primarily for an XR experience firm called Ethar), writing books, technically reviewing tons of material and continuing my long tradition of contributing to open-source development, as well as delivering talks, but that goes without saying Big Grin | :-D

Mixed Reality MVP, Xbox Ambassador, MS GameDevelopment Ambassador & Best selling author:

[Accelerating Unity Through Automation](
[Mastering Unity 2D Game Development] (
[Unity 3D UI Essentials] (

Comments and Discussions

QuestionMy Vote of 5 (As Well) Pin
Ed Schultz18-Dec-14 8:29
Ed Schultz18-Dec-14 8:29 
AnswerRe: My Vote of 5 (As Well) Pin
Simon Jackson18-Dec-14 8:54
Simon Jackson18-Dec-14 8:54 
GeneralMy vote of 5 Pin
Volynsky Alex18-Dec-14 8:13
professionalVolynsky Alex18-Dec-14 8:13 
GeneralRe: My vote of 5 Pin
Simon Jackson18-Dec-14 8:55
Simon Jackson18-Dec-14 8:55 
GeneralRe: My vote of 5 Pin
Volynsky Alex21-Dec-14 11:04
professionalVolynsky Alex21-Dec-14 11:04 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.