MonoGame Content Processing
NOTE: This is preliminary documentation of a feature in progress for MonoGame3... it does not apply to 2.5!
MonoGame like Microsoft XNA depends game content being processed at build time to 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.
- Windows Phone SDK 7.1.1 (older XNA versions do not work!)
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.
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.
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="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
<Import Project="$(MSBuildExtensionsPath)\MonoGame\MonoGame.ContentPipeline.targets" />
<PropertyGroup>
<ProjectGuid>{2CAE49BD-8B39-42BE-A010-D3E62657000E}</ProjectGuid>
<ProjectTypeGuids>{6D335F3A-9D43-41b4-9D22-F6F17C4BE596};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
<Platform Condition=" '$(Platform)' == '' ">x86</Platform>
<MonoGamePlatform>Windows</MonoGamePlatform>
</PropertyGroup>
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.
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\**\*.*">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>
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:
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
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:
Note: Do not confuse this with MonoGame.Framework.Content.Pipeline which is the work in progress for the new cross-platform content pipeline.
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. 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.
The following is a list of the specialized MonoGame content processors and details on their use.
This processor serves as a replacement for Texutre - 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.
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.
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.
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.
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).
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.
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);
else
textureProcessor = typeof(TextureProcessor);