Build it ahead of time

One of the biggest differences between the XNA content pipeline and the way many people are used to loading their game assets is that with the content pipeline, games no longer read directly from standard asset formats like .X, .BMP, and .FX. Instead, we process those files into a specialized binary format at the same time as compiling your game code.

The idea of processing assets during the build will be familiar to anyone who has worked on a console game, but may come as a surprise to people from a Windows background. There are actually several reasons why this is a good idea:

  • Windows has a very rich programming environment with many helper programs and libraries that can be useful for loading and converting asset files. Most of these libraries are not available on Xbox, so the only way to get access to them is to pre-process the assets on a Windows machine.

  • Game consoles only have limited amounts of RAM, and no virtual memory. Asset processing can need a lot of temporary memory, so it makes sense to run this on Windows during the build process.

  • Converting game assets into a format that is ready to render can take a long time. If we did this work while loading the asset, it would slow down load times for everyone who plays the game. By moving processing operations to the build process, the developer only has to process the content once, after which it can be loaded nice and quickly for everyone who plays the game.

  • By processing assets during the build, we can throw away any data that is not actually required by the game. This minimizes the size of the final game distributable.

  • The more processing work is done during the build, the more errors can be reported up front, rather than only being spotted as a runtime crash when you later try to load that content.

But what if you need to convert content yourself, outside of XNA Game Studio Express? For instance what if you want to use the content pipeline in a level editor, or to convert user provided assets so that modders can extend your game?

You're in luck, because all the content pipeline build functionality is exposed as an MSBuild task. I won't go into details about MSBuild here (you can find more about it on MSDN, or using Google), other than to explain that MSBuild runs tasks as described by XML project files. In fact the .csproj files that you load into Game Studio Express are just a special kind of MSBuild project.

So to manually build content, you simply have to generate an MSBuild project that invokes the content pipeline, run it using MSBuild, and then load in the compiled .xnb files that will have been created for you.

Here is an example MSBuild project that uses the content pipeline to build a single file called MyTexture.tga:

  <Project xmlns="">
<UsingTask TaskName="BuildContent" AssemblyName="Microsoft.Xna.Framework.Content.Pipeline, Version=, Culture=neutral, PublicKeyToken=6d5c3888ef60e27d" />
<XnaInstall>C:\Program Files\Microsoft XNA\XNA Game Studio Express\v1.0\References\Windows\x86</XnaInstall>
<PipelineAssembly Include="$(XnaInstall)\Microsoft.Xna.Framework.Content.Pipeline.TextureImporter.dll" />
<Content Include="MyTexture.tga">
<Target Name="Build">
<BuildContent SourceAssets="@(Content)" PipelineAssemblies="@(PipelineAssembly)" TargetPlatform="Windows" />

If you save this XML into a file called test.proj, you can then run this from the commandline by invoking "msbuild test.proj".


Comments (11)

  1. Epsicode says:

    The whole Content Pipeline is a very good idea ! Nice work.

  2. milow says:

    I’m working on a tool based on XNA that needs to load resources such as fbx files and convert them into the appropriate pipeline objects from code. I’ve been able to load an fbx file using FbsImporter, but I’m unable to convert the file to a model or xnb file. Is creating an msbuild script the only way to convert between an fbx file and xnb or can I do it all in code. If it is the only way, is it possible to do the build task without creating the script on disk?

  3. ShawnHargreaves says:

    Currently the only way to access this functionality is via the BuildContent MSBuild task.

    You can do this entirely in memory, though, using the Engine object and associated classes from the Microsoft.Build namespace. That lets you build up a project in memory as an object model, then pass it to an Engine that will build it for you.

  4. Danny Gregory says:

    I’m in the same position as Milow.  Does the XNA redistributable provide everything needed to get the above solution working on computers that do not have the XNA framework installed?

  5. ShawnHargreaves says:

    The framework redistributable doesn’t include any of the content pipeline functionality. This is currently only available by installing the full product.

  6. Way back in November I blogged about how to use MSBuild to run your own content build, bypassing the

  7. As I wrote the other day, I’d like to help out people that are having trouble understanding the content

  8. Derrick Lau says:

    Is it possible to build content at runtime?  For example, I copied a media file over to my XNA application’s content folder, and then created an instance of WmvImporter:

    WmvImporter videoImporter = new WmvImporter();

    I then tried to import and build the content for my XNA app using the Import() method:

    VideoContent videoContent = videoImporter.Import(filename, new ContentImporterContext());

    However, I cannot instantiate an instance of ContentImporterContext because it has no constructor, but I need an instance of the class to pass as a parameter to the Import() method.

    How should I accomplish this?

  9. ShawnHargreaves says:

    Derrick: check out the WinForms Content Loading sample on

  10. Cedric says:

    Hi Shawn, I’m working on an Editor for my XNA game engine, using Visual Studio Shell. I’m basically trying to replicate Game Studios’ Content Projects.

    But when I add the UsingTask element to my project file, VS throw an error when trying to create a new project:

    "Could not find any resources appropriate for the specified culture or the neutral culture. Make sure Microsoft.VisualStudio.Package.SecurityWarningDialog.resources was correctly embedded or linked into assemblyMicrosoft.StoryboardDesigner.ProjectBase at compile time, or that all the satellite assemblies required are loadable and fully signed."

    I have no clue what kind of resource it’s talking about. Any ideas ?


  11. Hamza says:

    Basically I'm trying to build an .fbx model with MSBuild following the example you have above and I get:

    error MSB4062: The "BuildContent" task could not be loaded from the assembly Microsoft.Xna.Framework.Content.Pipeline, Version=, Culture=neutral, PublicKeyToken=6d5c3888ef60e27d. Could not load file or assembly 'Microsoft.Xna.Framework.Content.Pipeline, Version=, Culture=neutral, PublicKeyToken=6d5c3888ef60e27d' or one of its dependencies. The system cannot find the file specified.

    I've put ToolsVersion="4.0" in the Project header.

    I've installed the latest everything (XNA GS, .NET 4.5, VS Express 2010 SP1)


Skip to main content