MonoGame Content Processing

Kristoffer Parsons edited this page Mar 24, 2015 · 45 revisions

NOTICE: This wiki contains stale information from older releases of MonoGame. We recommend you first check the website documentation before delving into these pages!


MonoGame like Microsoft XNA depends on game content being processed at build time into an optimal format for runtime use.

The process requires some hand editing of your game project and some simple changes to your content project.


The following are the system requirements for building content for all MonoGame target platforms:

  • Windows XP w/SP2, Windows Vista, Windows 7, Windows 8.
  • Visual C# 2010 Express or Pro with SP1 installed.
  • Windows Phone SDK 7.1 (NOTE: Ensure that you install the Windows Phone SDK 7.1.1 Update shown below.)
  • Windows Phone SDK 7.1.1 (older XNA versions do not work!)

Linux and OSX

At this time MonoGame does not include an independent implementation of the XNA content pipeline. We depend on Microsoft's XNA content pipeline implementation and Visual Studio 2010 on Windows to build content for all MonoGame platforms.

This means you must have a Windows system or virtual machine available to run the content pipeline regardless of what platform you're developing for.

MonoGame Content Project

With the 3.x series of releases there is a new "MonoGame Content Project" template. This template will create a place holder XNA project to build the content, and a Content Project for you to add your content too. The template comes with a bunch of pre set build configurations for all the supported platforms including iOS.

With this new template building platform specific content should be easy. Simply add the asset to the Content Project as you would a normal XNA project, then select one of the MonoGame flavour content processors (see below for more detail). The next step is to select the appropriate build configuration from the drop down in visual studio. Then Build. Your content will appear in a bin\Release\$Configuration\Content folder, you will be able to link the the resultant .xnb file from that location.

Game Project

In Microsoft XNA the game project controls the execution of content building. For MonoGame we follow the same rule with some simple workarounds for non-Windows platforms.

Windows and VS2010

If you're targeting MonoGame for Windows you can simply add the content project to your existing solution just like you do in any other XNA project.

Then you then edit your game project (not your content project) to <Import> the MonoGame content pipeline target file and include the <MonoGamePlatform> property set to Windows:

<Project DefaultTargets="Build" xmlns="" ToolsVersion="4.0">
   <Import Project="$(MSBuildExtensionsPath)\MonoGame\v3.0\MonoGame.ContentPipeline.targets" />
      <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
      <Platform Condition=" '$(Platform)' == '' ">x86</Platform>

Note that above we assume that MonoGame.ContentPipeline.targets has been installed to the MSBuild extension path. If you're using source control you can just as easily have it point to a relative or absolute path to where MonoGame/MonoGame.ContentPipeline/MonoGame.ContentPipeline.targets is checked out on your system.

Windows 8 and VS2012

Microsoft has at this time not shipped the XNA Studio bits for Visual Studio 2012 (they are due around August 2012). For the moment you must install VS2010 and the Windows Phone 7 SDK on Windows 8 and use a dummy XNA project to execute the content project.

As detailed in the Windows build instructions above, edit the dummy game project to <Import> the MonoGame content pipeline target file. If running on Windows 8, set the <MonoGamePlatform> value to Windows8 (or simply Windows if running on Windows 7 or earlier).

Build the dummy project to create the xnb files that are required by your game. These will typically appear in the bin\debug\x86\Content** folders.

Once you build your content you need to include it in the game project as "Content" and "Copy If Newer". One way to do this is to use a wildcard include to include everything within a specified subfolder:

<Content Include="Content\**\*.*">

Non-Windows Platforms

On non-Windows native platforms, e.g. iOS, Android, the recommended solution is to create an empty XNA 4 project using Visual Studio 2010. The empty game project in that solution will be used to run the content build process that targets the specific MonoGamePlatform you are targeting. After getting the build for one of the targets working, you may find that multiple MonoGamePlatform target builds in the same solution is more convenient, but not required.

Note that this is the part of this guide where you must hand edit the project file of your empty game project. The project file must contain the tag in the root project group (, usually at the top of the project file). You can either make one dummy project per-platform and put the <MonoGamePlatform> property to either the main <PropertyGroup> or use a single dummy project with a different <MonoGamePlatform> property in each configuration <PropertyGroup>.

Here is an image of the dummy project:

dummy project

The supported platforms include:

  • <MonoGamePlatform>iOS</MonoGamePlatform> (Apple iPhone/iPod/iPad)
  • <MonoGamePlatform>Android</MonoGamePlatform> (Google Android devices)
  • <MonoGamePlatform>Linux</MonoGamePlatform> (Linux desktop)
  • <MonoGamePlatform>OSX</MonoGamePlatform> (MacOS desktop)
  • <MonoGamePlatform>PSM</MonoGamePlatform> (Play Station Mobile, e.g. Vita)

Don't forget to add the MonoGame .target file <Import>, as described in the Windows and VS2010 section

Building MonoGame.ContentPipeline.Processors

Unless you have installed the MonoGame platform (version 3 of this writing), you must build the MonoGame content processors using your Windows desktop machine with Visual Studio installed.

Open the MonoGame.ContentPipeline/ContentProcessors/MonoGameContentProcessors.sln with VisualStudio 2010 and build the Release version of the content processors. This solution contains both C++ and C# projects requiring it to be built with a Professional version of VisualStudio or be built once with C# Express and once with C++ Express.

Once built the final assemblies will be in the MonoGame.ContentPipeline\ContentProcessors\bin\Release folder. Either reference them directly from that location or copy them to a dependencies folder in your own project.

Make sure you add a reference to all projects in the solution:

monogame processors

Note: Do not confuse this with MonoGame.Framework.Content.Pipeline which is the work in progress for the new cross-platform content pipeline.

Content Project

You should use a standard Microsoft XNA Content Project for MonoGame content.

In the content project you need to add a reference to the 'MonoGame.ContentPipeline.Processors' assembly which contains all the platform specific content processors. (This will be in C:\Program Files (x86)\MSBuild\MonoGame\v3.0\MonoGameContentProcessors.dll if you installed the binary) You then select the correct MonoGame version of the XNA content processors you're already using.

Note these processors will fall thru to normal XNA behavior if you're not building for MonoGame, so its safe to use them in your Xbox or Windows Phone projects as well. However also note that if you are using the content project from different c# projects at the same time you need to 'Rebuild' when you switch otherwise the content project will not regenerate all the files when it needs to.

Content Processors

The following is a list of the specialized MonoGame content processors and details on their use.

content processors image

MonoGame Texture

This processor serves as a replacement for Texture - XNA Framework with the same properties.


The MonoGame Texture processor will automatically generate iOS compatible PVRTC compressed textures when you use the Texture Format of DxtCompressed and the <MonoGamePlatform>iOS</MonoGamePlatform> property.

Because of how PVR Texture Compression works, you may find that some images do not look good after compression or look very different from the original. Your only option is to not compress the texture. You can set a texture to not compress on PVRTC platforms by changing the CompressionMode property in it's content processor. This allows you to have DXT compression on other platforms, but disabled when building on platforms where PVRTC is used like iOS.

Note that PVRTC compression is a much longer process than typical DXT compression. Expect much longer content build times if you have many compressed textures.

At this time the ResizePowerOfTwo option is not yet implemented by the MonoGame Texture processor when building PVRTC textures.

MonoGame SpriteFont

This is a replacement for SpriteFont Description - XNA Framework which ensures textures are compressed using the MonoGame Texture processor internally and thus correctly building compressed textures for all platforms. For example when building for iOS you will get PVRTC compressed font sheet textures.

MonoGame Effect

This replaces the Effect - XNA Framework processor and correctly generates an MGFX Effect for OpenGL or DirectX based on the <MonoGamePlatform> property. Note that some FX files may not compile to MGFX correctly. Please submit a bug report when this occurs.

MonoGame SoundEffect

This is a replacement for SoundEffect - XNA Framework content processors.


When targeting iOS the SoundEffect processor will decompress any incoming sound file and generate an uncompressed PCM sound effect at either the original sample rate (Best), 3/4 of the original sample rate (Medium), or 1/2 the original sample rate (Low).


When targeting any other platform the MonoGame SoundEffect processor falls thru to the default XNA behavior for Windows, Windows Phone, or Xbox.

MonoGame Song

This replaces the Song - XNA Framework content processor for converting music files to the appropriate platform specific format.

On all platforms the processor will first decompress the incoming music file to raw PCM data then recompress to the correct format for that particular platform. It is recommended to only provide it the raw uncompressed music file to avoid extra compression artifacts.


For iOS the MonoGame Song processor compress the music data to MP3 at either the 96K sample rate (Low Quality), 128K sample rate (Medium Quality), or 192K sample rate (Best Quality). Note that while the content builder outputs a small XNB file for the song, the asset you include in your game project is the MP3 file. The extraneous XNB file for the song is not needed.


For Linux the MonoGame Song processor will output an uncompressed WAV file at 96K/128K/192K based on the selected compression quality.


When targeting any other platform the MonoGame Song processor falls thru to the default XNA behavior for Windows, Windows Phone, or Xbox.

Custom Content Processors

If you happen to use a custom content processor for your game it may depends on platform specific content like textures or sound effects. It is just as simple for you to reference the MonoGame content processors to get content optimized for your target platform.

You simply reference the 'MonoGame.ContentPipeline.Processors' assembly from your project and add code like this:

if (ContentHelper.GetMonoGamePlatform() == MonoGamePlatform.iOS)
   textureProcessor = typeof(MGTextureProcessor);
   textureProcessor = typeof(TextureProcessor);