-
Notifications
You must be signed in to change notification settings - Fork 5
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.
Since at this time MonoGame does not have an independent implementation of the XNA content pipeline we depend on Microsoft's implementation on Windows to build content for non-Microsoft platforms. This means you must have a Windows system available to run the content pipeline regardless of what platform you're developing for.
The process requires some hand editing of your game project and some simple changes to your content 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.
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 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>
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 checkout 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.
Like for the Windows build instructions above you edit the dummy game project to <Import> the MonoGame content pipeline target file and include the <MonoGamePlatform> property set to Windows8.
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:
<Content Include="Content\**\*.*">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>
You then just need to ensure to copy the right content into the content folder and reload your project file.
On these platforms the recommended solution is to use a dummy XNA project which executes the content build process. 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>.
These platforms include:
<MonoGamePlatform>iOS</MonoGamePlatform><MonoGamePlatform>Android</MonoGamePlatform><MonoGamePlatform>Linux</MonoGamePlatform><MonoGamePlatform>OSX</MonoGamePlatform><MonoGamePlatform>PSS</MonoGamePlatform>
If working from source code you must build the MonoGame content processors.
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.
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.
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 monochrome, or images without a lot of color changes appear corrupted. 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);