How To: Content Pipeline

The MonoGame content pipeline compiles raw assets (images, fonts, audio) into .xnb binary files optimised for the runtime. This guide covers installing the build tool, creating a build descriptor, and loading assets at runtime.

Reference files: Content/font.spritefont ยท Advanced/SampleGame.cs

Install dotnet-mgcb

dotnet tool install -g dotnet-mgcb

This installs the MonoGame Content Builder CLI globally. Verify with:

dotnet-mgcb --version

Create a .mgcontent build descriptor

A .mgcontent file records the source file, importer, and processor for each asset. The tool generates or updates these files automatically when you run it, but you can also create them by hand:

<?xml version="1.0" encoding="utf-8"?>
<PipelineBuildEvent
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SourceFile>/absolute/path/to/Content/myTexture.png</SourceFile>
  <DestFile>/absolute/path/to/Content/myTexture.xnb</DestFile>
  <Importer>TextureImporter</Importer>
  <Processor>TextureProcessor</Processor>
  <Dependencies />
  <BuildAsset />
  <BuildOutput />
</PipelineBuildEvent>

Build assets

dotnet-mgcb /path/to/Content/myTexture.mgcontent

This produces myTexture.xnb alongside the source file. Run once per asset, or script it as a pre-build step.

Copy compiled content to the output directory

Add the following to your .csproj so that .xnb files are copied next to the executable on every build:

<ItemGroup>
  <None Update="Content/**/*">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

Set Content.RootDirectory in the game constructor

public class MyGame : Game
{
    public MyGame()
    {
        _graphics = new GraphicsDeviceManager(this);
        Content.RootDirectory = "Content";   // relative to the executable
    }
}

Load assets in LoadContent

protected override void LoadContent()
{
    _spriteBatch = new SpriteBatch(GraphicsDevice);

    // Load a texture compiled to Content/myTexture.xnb
    _texture = Content.Load<Texture2D>("myTexture");

    // Load a SpriteFont compiled from a .spritefont definition
    _font = Content.Load<SpriteFont>("font");
}

The path passed to Content.Load<T>() is relative to Content.RootDirectory and omits the .xnb extension.

Alternative: TitleContainer.OpenStream

For assets you want to load from a raw stream (e.g. loading a PNG at runtime without pre-compiling it):

using var stream = TitleContainer.OpenStream("Content/myTexture.png");
_texture = Texture2D.FromStream(GraphicsDevice, stream);

TitleContainer.OpenStream resolves paths relative to the executable directory on desktop (same as File.Open for most purposes).

Sample content

The sample project ships two compiled assets in samples/MonoGame.Framework.Avalonia.Sample/Content/:

File Type Loaded as
font.xnb SpriteFont atlas Content.Load<SpriteFont>("font")
sprite.xnb Texture2D Content.Load<Texture2D>("sprite")

The corresponding .mgcontent build descriptor is font.mgcontent; the font source definition is font.spritefont.

latest ▼