Embedding MonoGame’s Content Pipeline vs. a Separate Content Project

The decision point

When you start a MonoGame project you must decide how assets will be built. The Content Pipeline (MGCB) can be run as a standalone project that produces .xnb files, or it can be pulled into the main game project via the MonoGame.Content.Builder NuGet package so that content is built automatically during the usual compile step. This choice affects iteration speed, team workflows, and continuous integration.

Why the choice matters

Asset builds are not free; each texture, model, or font triggers an importer/processor chain that can take seconds on large projects. If the pipeline runs outside the game project, developers must remember to launch mgcb-editor or the CLI before testing, which adds friction and a chance of running stale assets. Conversely, bundling the pipeline with the game means every dotnet build (or IDE rebuild) also rebuilds content, guaranteeing that the runtime sees the latest version but potentially lengthening the inner‑loop build time.

Embedding the pipeline with MonoGame.Content.Builder

Add the NuGet package to your game project:

dotnet add package MonoGame.Content.Builder --version 3.8.1

Then create an Content.mgcb file at the root of the project (or inside a Content folder) and reference it in the project file:

<ItemGroup>
  <None Update="Content.mgcb">
    <Generator>MonoGameContentBuilder</Generator>
    <LastGenOutput>Content.mgcb</LastGenOutput>
  </None>
</ItemGroup>

When you build, the package’s MSBuild target invokes mgcb with the Platform property set to the current target (e.g., DesktopGL on Windows, Android on a CI agent). The generated .xnb files appear alongside the compiled assemblies in bin\Debug\net6.0\Content (or the appropriate folder for your framework).

Keeping a separate content project

Alternatively, create a second project of type MonoGame Content Project (template available via the MonoGame Visual Studio extension). This project contains only the Content.mgcb file and any source assets. The game project references the content project as a dependency:

<ItemGroup>
  <ProjectReference Include="..\MyGame.Content\MyGame.Content.csproj" />
</ItemGroup>

In this setup, the content project builds independently, producing .xnb files in its own output folder. The game project then copies those files to its content root via a post‑build step or by setting CopyToOutputDirectory on the referenced assets. This separation makes it easier for artists or designers to open the content project in mgcb-editor without loading the entire game solution, and it allows CI pipelines to cache the content build step.

Worked example: switching modes

Suppose you have a DesktopGL game with a sprite sheet hero.png. First, embed the pipeline:

1. Add the NuGet package as shown above.
2. Create Content.mgcb and set Platform to DesktopGL.
3. Add hero.png to the mgcb file, leave the processor as TextureProcessor.
4. Run dotnet build. Verify that bin\Debug\net6.0\Content\hero.xnb exists.

To move to a separate content project:

1. Remove the NuGet package.
2. Create a new MonoGame Content Project named MyGame.Content.
3. Move Content.mgcb and hero.png into that project.
4. Add a project reference from the game to the content project.
5. In the game project, set CopyToOutputDirectory to PreserveNewest for the content folder.
6. Run dotnet build again and check that the .xnb appears in the game’s output folder.

Both approaches produce identical .xnb output; the difference lies in where the build target lives and how easily the workflow can be split.

Trade‑off and limitation

Embedding the pipeline simplifies onboarding for new developers because a single dotnet build yields a runnable game. However, it couples content rebuild frequency to code changes: even a minor script tweak triggers a full content rebuild, which can slow inner‑loop iteration on large asset sets. A separate content project decouples the two, allowing you to rebuild only when assets actually change, but it requires an extra step to ensure the content project is built before the game runs (e.g., a CI stage or a pre‑launch script).

Practical verification

To confirm that your chosen setup works, run the game and attempt to load an asset:

Texture2D tex = Content.Load("hero");

If the texture appears on screen without a ContentLoadException, the pipeline has produced a valid .xnb for the current platform. For CI, add a step that runs dotnet build (or msbuild for the content project) and asserts that the expected .xnb files exist in the output directory.

Actionable closing

If your team values a single‑command build and is comfortable with occasional extra rebuild time, embed the Content Pipeline via MonoGame.Content.Builder. If you have dedicated asset creators, want faster iteration on code changes, or need to cache content builds in CI, keep a separate content project and reference it from the game. Either way, verify the output by loading a known asset after each build to catch mismatched platform settings early.