From caebd66a8715bb734ba7249f386c1b404acaf49e Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Fri, 14 Nov 2025 17:58:44 +0000 Subject: [PATCH 1/5] Updated CB docs with section on `csproj` update --- .../content_builder_project.md | 66 +++++++++++++++++-- 1 file changed, 61 insertions(+), 5 deletions(-) diff --git a/articles/getting_started/content_pipeline/content_builder_project.md b/articles/getting_started/content_pipeline/content_builder_project.md index b0f22fd6..cb25d1be 100644 --- a/articles/getting_started/content_pipeline/content_builder_project.md +++ b/articles/getting_started/content_pipeline/content_builder_project.md @@ -23,11 +23,12 @@ From MonoGame `3.8.5` we are making a new `Console Project Style` solution to mo 1. [What is the ContentBuilder?](#what-is-the-contentbuilder) 2. [Getting Started](#getting-started) -3. [Understanding ContentBuilderParams](#understanding-contentbuilderparams) -4. [Creating Your ContentCollection](#creating-your-contentcollection) -5. [Including and Excluding Content](#including-and-excluding-content) -6. [Working with Importers and Processors](#working-with-importers-and-processors) -7. [Advanced Scenarios](#advanced-scenarios) +3. [Adding the Content Builder Project to your Game](#adding-the-content-builder-project-to-your-game) +4. [Understanding ContentBuilderParams](#understanding-contentbuilderparams) +5. [Creating Your ContentCollection](#creating-your-contentcollection) +6. [Including and Excluding Content](#including-and-excluding-content) +7. [Working with Importers and Processors](#working-with-importers-and-processors) +8. [Advanced Scenarios](#advanced-scenarios) --- @@ -122,6 +123,61 @@ This is the default (recommended) layout for a Content Builder project, but you > [!TIP] > While it is possible to include the builder as part of your game code, rather than a separate project, at this time we do not recommend this. Based on experience, it is always better to build your content separate from your runtime game to avoid collisions or issues arising in game production/deployment. +## Adding the Content Builder Project to your Game + +Once you have created your `Builder` project, you have two options: + +1. After building your game, you need to copy the build output from the Builder to the output of the Game, so the `exe` and the `content` folder are in the same output folder. +2. Add a `Target` definition to your `csproj` to automatically copy the Builder output to the game output when the project is built (like how the current MGCB solution works) + +This section will focus on Option 2 to replicate what happens in `3.8.4` projects. + +### 1. Clean up redundant files + +As the Content Builder project is **NOT** a DotNet tool, you no longer need the `dotnet-tools.json` configuraton. + +1. Remove any `.config` folders from your solution that contain `dotnet-tools.json` files. + +### 2. Remove legacy MGCB references from your `csproj` + +As you would expect, we no longer need any old `Content` references or tools for building that content, aka, the `MonoGame.Content.Builder.Task` reference. + +Per platform/game project: + +1. Remove any `MonoGameContentReference` elements from your games `csproj`. +2. Remove references to `MonoGame.Content.Builder.Task`. +3. Update the MonoGame version to match the Builder (not essential, but recommended) + +### 3. Add the Builder task + +To complete the process, add the following `Target` section to your `csproj` (before the final `````` entry): + +```xml + + + $(ProjectDir)$(OutputPath) + $(ProjectDir)$(IntermediateOutputPath) + build -p $(MonoGamePlatform) -s Assets -o $(ContentOutput) -i $(ContentTemp) + + + + +``` + +Of note, you should take care with the following elements: + +- `-s Assets` - this assumes you are using the default "Assets" source folder in the builder project. If your source content is elsewhere you will need to provide the path to it. +- `-i $(ContentTemp` - this uses the default `obj` folder for building the content, if you are short on space, you can provide an alternate path for temp storage. +- `Projects="..\Content\Content.csproj"` - This should **MATCH** the folder and project name of your Builder. If you called your Builder something else or renamed the folder/csproj, make sure it matches. + +You should not need to touch anything else. + +> [!NOTE] +> Additionally, if you want to control HOW and WHEN your content is built/rebuilt, then you can change the `Targets="Build;Run"` options to only execute the last on Build OR Run, or a different action. +> +> See the [MS Documentation on Built targets](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-targets) for reference. + ## Basic Builder Project Structure The default `Builder.cs` file looks like this, which contains everything needed to build all content in the designated Assets/Content folder using the default [Importers and Processors](/articles/getting_to_know/whatis/content_pipeline/CP_StdImpsProcs) (how MonoGame compiles content) into processed `.XNB` files for consumption by your runtime project: From f6716a6a695b0f3d9bfb4462a03cff8c25aa7292 Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Fri, 14 Nov 2025 18:02:17 +0000 Subject: [PATCH 2/5] Update articles/getting_started/content_pipeline/content_builder_project.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../getting_started/content_pipeline/content_builder_project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/getting_started/content_pipeline/content_builder_project.md b/articles/getting_started/content_pipeline/content_builder_project.md index cb25d1be..b50e4a12 100644 --- a/articles/getting_started/content_pipeline/content_builder_project.md +++ b/articles/getting_started/content_pipeline/content_builder_project.md @@ -134,7 +134,7 @@ This section will focus on Option 2 to replicate what happens in `3.8.4` project ### 1. Clean up redundant files -As the Content Builder project is **NOT** a DotNet tool, you no longer need the `dotnet-tools.json` configuraton. +As the Content Builder project is **NOT** a DotNet tool, you no longer need the `dotnet-tools.json` configuration. 1. Remove any `.config` folders from your solution that contain `dotnet-tools.json` files. From ce597d57f30d459fb2b9c778a25bb6fcc2e68e5e Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Fri, 14 Nov 2025 18:02:24 +0000 Subject: [PATCH 3/5] Update articles/getting_started/content_pipeline/content_builder_project.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../getting_started/content_pipeline/content_builder_project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/getting_started/content_pipeline/content_builder_project.md b/articles/getting_started/content_pipeline/content_builder_project.md index b50e4a12..34c53ce0 100644 --- a/articles/getting_started/content_pipeline/content_builder_project.md +++ b/articles/getting_started/content_pipeline/content_builder_project.md @@ -144,7 +144,7 @@ As you would expect, we no longer need any old `Content` references or tools for Per platform/game project: -1. Remove any `MonoGameContentReference` elements from your games `csproj`. +1. Remove any `MonoGameContentReference` elements from your game's `csproj`. 2. Remove references to `MonoGame.Content.Builder.Task`. 3. Update the MonoGame version to match the Builder (not essential, but recommended) From 252bee8554f24a39cfed6555681013557f64d17e Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Fri, 14 Nov 2025 18:02:41 +0000 Subject: [PATCH 4/5] Update articles/getting_started/content_pipeline/content_builder_project.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../getting_started/content_pipeline/content_builder_project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/getting_started/content_pipeline/content_builder_project.md b/articles/getting_started/content_pipeline/content_builder_project.md index 34c53ce0..2005564f 100644 --- a/articles/getting_started/content_pipeline/content_builder_project.md +++ b/articles/getting_started/content_pipeline/content_builder_project.md @@ -168,7 +168,7 @@ To complete the process, add the following `Target` section to your `csproj` (be Of note, you should take care with the following elements: - `-s Assets` - this assumes you are using the default "Assets" source folder in the builder project. If your source content is elsewhere you will need to provide the path to it. -- `-i $(ContentTemp` - this uses the default `obj` folder for building the content, if you are short on space, you can provide an alternate path for temp storage. +- `-i $(ContentTemp)` - this uses the default `obj` folder for building the content, if you are short on space, you can provide an alternate path for temp storage. - `Projects="..\Content\Content.csproj"` - This should **MATCH** the folder and project name of your Builder. If you called your Builder something else or renamed the folder/csproj, make sure it matches. You should not need to touch anything else. From 9b114201519c1eabfe48543d93c3fbdb7c4d3d07 Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Fri, 14 Nov 2025 18:16:22 +0000 Subject: [PATCH 5/5] Update articles/getting_started/content_pipeline/content_builder_project.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../getting_started/content_pipeline/content_builder_project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/getting_started/content_pipeline/content_builder_project.md b/articles/getting_started/content_pipeline/content_builder_project.md index 2005564f..7c9329b1 100644 --- a/articles/getting_started/content_pipeline/content_builder_project.md +++ b/articles/getting_started/content_pipeline/content_builder_project.md @@ -159,7 +159,7 @@ To complete the process, add the following `Target` section to your `csproj` (be $(ProjectDir)$(IntermediateOutputPath) build -p $(MonoGamePlatform) -s Assets -o $(ContentOutput) -i $(ContentTemp) -