MonoGame 3.8.5 Preview feedback and known issues #9155

SimonDarksideJ · 2026-01-03T09:18:03Z

SimonDarksideJ
Jan 3, 2026
Maintainer

The MonoGame 3.8.5 previews are here

This discussion is a central point for feedback regarding the 3.8.5 release and the previews, as well as up to date information on any known issues while everything is being tested out for release.

When will `3.8.5` be released?

The short answer is, when it is ready.

The last thing the foundation wants is for any developer, whether they are a newcomer to MonoGame or shipping games with MonoGame to be blocked or have issues.

Everyone's help is wanted

No matter your experience with MonoGame, if something is giving you pause, raising an eyebrow or confusing with getting started, let us know, so we can improve it for both you and everyone else.

Let us all make the next release of MonoGame the best it can be!
(we will also be releasing our 2026 roadmap, following the new funding announcement, very soon, likely in the next Open Hours meeting)

Updated Templates

The 3.8.5 release adds new templates for testing the preview features of the delivery, which includes a setup for the new Content Builder, the Vulkan and DX12 new graphics backends. These can be found in the following templates (found when installing the preview.3 c# templates)

mgblankmgcbstartkit - A blank multi-platform project with a CB project and new VK/DX12 platforms
mg2dmgcbstartkit - The 2D platformer project packaged up with content using a CB project and new VK/DX12 platforms
mgcb - A Blank Content Builder project for your solution (make sure to add the Imports and MonoGamePlatform definitions to your platform project to automatically build it.

Note

If you do not have the ios or android workloads installed, then simply remove those entries from the StartKit slnx solution definition to avoid issues when opening the project

Important

It goes without saying, but you CANNOT build the DX12 or WindowsDX platforms on a Mac or Linux. So if you are on a Mac or Linux, exclude these platforms from your slnx solution.

Known issues

These are the current known issues with the latest preview (currently preview.3)

(DX12) In initial testing, DX12 seem to not run on certain machine configurations, unclear why at this time, as it works 90% of the time. Additional test data/feedback is needed.
(Content Builder) Spaces in Windows Project paths are not supported currently due to a limitation in the command line parser currently used. Having spaces anywhere in the path will cause content build errors. We are looking to replace the command-line parser to resolve this. Mac and Linux are unaffected.
Content Importers/Processors used on multiple entities using the same resources (e.g. textures) causes rebuilds of the dependent resources. A fix is planned for the next release with a major refactor.
Late issue with the Content Builder .targets definition is "hard coded" for debug builds (fix applied for next release)
Workaround is to replace debug with $(Configuration) in the <ContentCommand> definition.
Another issue with the Content Builder .targets definition is that is is not "RuntimeIdentifier" aware. If you try to compile using a specific runtime identifier, it will fail. Investing options.

Resolved issues

These are the previously identified issues that have been resolved in the latest preview (currently preview.3)

(Vulkan/DX12) MediaPlayer is currently non-functional for VK/DX12 targets, resulting in "Song's" not playing. Sound effects still work as expected. This is being worked on in Code Time
(fix) Song now implemented for DX12/Vulkan
(Rider Integration) An issue has been reported with JetBrains Rider integration, which seems to crash the application when launched with the Rider debugger attached. More details are needed to send to JetBrains, or someone in the Rider community to raise an issue with them. The issue seems unrelated to MonoGame as other templates work fine.
(fix) Issue identified in the Vulkan Initialization, which tripped up Rider but not VS, fixed
(Content Builder) Selecting alternate Texture Compression formats, such as TextureFormat = TextureProcessorOutputFormat.PvrCompressed in a TextureProcessor results in a build failure.
(fix) The issue has been resolved.

3.8.x Upgrade

If you are using an existing MonoGame project, ensure it is up to date with MonoGame 3.8.4 using the existing upgrade guides (especially if coming from older versions of MonoGame, such as 3.8.2).

If you are still intending to use the MGCB Editor as with preview releases, then updating to the MonoGame 3.8.5 previews for testing is fairly easy, this guide has been prepared for installing and updating to the latest preview:

How to install MonoGame Preview packages

If you want to try out the new Content Builder solution, then these guides will help you test it out:

3.8.5.preview.2 upgrade

In 3.8.5-preview.2 we improved the project integration for the content builder by moving the majority of the Build Actions into the Builder project using a new BuildContent.targets definition.

So in your platform csproj, instead of:

  <Target Name="BuildContent" BeforeTargets="Build">
    <PropertyGroup>
      <ContentTarget>Windows</ContentTarget>
      <ContentOutput>$(ProjectDir)$(OutputPath)</ContentOutput>
      <ContentTemp>$(ProjectDir)$(IntermediateOutputPath)</ContentTemp>
      <ContentArgs>build -p $(ContentTarget) -s Assets -o $(ContentOutput) -i $(ContentTemp)</ContentArgs>
    </PropertyGroup>
    <MSbuild Projects="..\..\Content\Content.csproj" Targets="Build;Run" Properties="RunArguments=$(ContentArgs);" />
  </Target>

We now simply use

  <Import Project="..\mg2dmgcbstartkit.Content\BuildContent.targets" />

This reduces the complexity of Platform projects and moves the configuration for content building into the Content project itself.
When migrating, ensure you copy the BuildContent.targets from a new template and then update your project as above.

Note

This is not critical and is only advised, the original setup will still continue to work.

3.8.5.preview.3 upgrade

No major changes of note, with the exception of a new, more cross-platform supported .targets file for the Content Builder. Simply generate a new "Builder" project and copy the file, alternatively, update your BuildContent.targets to:

<Project>
  <Target Name="BuildContent" BeforeTargets="BeforeCompile">
    <PropertyGroup>
      <ContentOutput>$(ProjectDir)$(OutputPath)</ContentOutput>
      <ContentTemp>$(ProjectDir)$(IntermediateOutputPath)</ContentTemp>
      <ContentArgs>build -p $(MonoGamePlatform) -s Content/Assets -o $(ContentOutput) -i $(ContentTemp)</ContentArgs>
      <ContentCommand>$(MSBuildThisFileDirectory)bin\Debug\Content</ContentCommand>
    </PropertyGroup>
    <MSBuild Projects="$(MSBuildThisFileDirectory)Content.csproj" Targets="Build" RemoveProperties="Configuration;TargetFramework;RuntimeIdentifier;RuntimeIdentifiers" />
    <Exec Command="$(ContentCommand) $(ContentArgs)" WorkingDirectory="$(MSBuildThisFileDirectory)..\" CustomErrorRegularExpression="\[E\] .+" CustomWarningRegularExpression="\[W\] .+" />
   </Target>
</Project>

Builder.csproj adds a new "Property"

<AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>

Note

This is currently hardcoding to net9.0 which is the target framework for the Content Project, if you upgrade to net10.0 (which is untested atm, you will need to manually update this. We are looking into solutions to make it more dynamic.

Content Builder Strategies

Based on Community feedback, adding this section for reference while the documentation is being finalized.

The following strategies exist when using the new "Content Builder" solution with your project:

Style	Setup	Description
Default	A Content Project in your solution, and an `Imports` definition in each platform, including a `MonoGamePlatform` definition.	Replicates the existing MGCB setup, content built with project.
Only Build content on run	Use a custom version of the `BuildContent.targets` in your platform without the `msbuild` command.	Only uses a pre-built Content Builder (skips building the builder). Means that changes to the builder MUST be manually managed, builds without the EXE existing will fail.
Merge Content Manually	Do not use `Imports` or `Target` definitions in your project, Building content is manual or handled through another process.	Upside, code builds are quicker, so long as the content has been built at least once manually or through automation. Decoupled scenario.

We are open to feedback about any other scenarios developers are trailing.

Note

We have three sample repositories demonstrating using automation with the Content Builder here:

Feedback

Please report any additional feedback here on any issues found while testing out the previews.
We would like to thank our community for their support in testing out the new preview features before the full release to improve the use for everyone ❤️

MonoGame Foundation

leandiez · 2026-01-07T17:23:02Z

leandiez
Jan 7, 2026

Hello! Just here to share that I successfully updated the 2D Tutorial to Content Builder.

The only problem I had was cleaning up the old Content folder.
For some reason, after the delete and despites the game didn't have any reference to the old ContentBuilder, I had to run a dotnet restore and rebuild the game project like the first time, .

Beyond that no problem by now.

Thanks for all and congrats for the almost-release!

1 reply

SimonDarksideJ Jan 13, 2026
Maintainer Author

I believe I used the 2D tutorial as the template for the Upgrade demo video here:
https://youtu.be/QB43LgRmdNM?si=0jP1EJkwH3B3YOXJ

seclerp · 2026-01-13T15:42:56Z

seclerp
Jan 13, 2026

Hi! I’m really happy to see how MonoGame is evolving these days ❤️

I’m also a fan of moving away from .mgcb files for content building. That said, I’m a bit concerned about the new Content Builder approach, especially how it’s wired into the solution infrastructure. In my opinion, it could be improved.

Some observations about the new templates and documentation:

Even for the simplest cases, the Content Builder configuration feels unnecessarily verbose. I’m not sure how large or complex the average MonoGame project is, but having to explicitly define MSBuild tasks and targets and all default properties feels like something that could be hidden behind sensible defaults. This is a common pattern in the .NET ecosystem: frameworks hide and define defaults in MSBuild .props while still allowing full customization when needed in .csproj files. If done well, this would reduce friction for newcomers and for people looking for a lighter migration path, without limiting advanced use cases.
Currently, Content Builder tasks are run via a separate child MSBuild process. Why not make the Content project a <ProjectReference> of the game project instead? You could still hook your targets and tasks into the standard MSBuild pipeline through a .targets/project SDK coming with the Content Pipeline NuGet package. This would also simplify proper incremental builds and artifact caching (with proper Inputs and Outputs configured), and it might slightly improve performance by avoiding a separate MSBuild instance.

Regarding templates: They lack configuration. For example, by default, the StartKit bloats the solution with a full set of supported platforms, which is inconvenient because you have to manually unload or remove the ones you don’t need. The .NET templating engine supports conditional content based on parameters passed during project creation, including multi-select options (like Uno Platform does, see below), so this could be handled much more cleanly.

Overall though, the progress looks amazing, thanks for making MonoGame better! 🚀

8 replies

seclerp Jan 13, 2026

The 2 main problems with my proposed example that I currently see:

It's quite hard to tell which project initiated the Content Builder build process.
Content building should be done multiple times per each platform, while MSBuild by default will execute build of Content.csproj only once.

I would probably think more on that, maybe will drop some prototype.

SimonDarksideJ Jan 14, 2026
Maintainer Author

We fully welcome more feedback on the various approaches, so long as we keep in mind the two effective audiences:

Beginner - just wants it on a plate, no fuss, just build and go
Advanced - No barriers, I just want to do it how I want.

P.S.
The ONE major issue with your CSProj approach, and kinda why we veered away from it, is that it is LOCKED into a single platform because the Platform and where the content is output is effectively hard coded, whereas the current pattern allows you to inject which platform you want to build automatically. (no matter which platform you choose, or in a multi-platform scenario, it builds for each)

seclerp Jan 15, 2026

Beginner - just wants it on a plate, no fuss, just build and go

Advanced - No barriers, I just want to do it how I want.

Totally agree!

Yeah, seems like forcing MSBuild to build the same project multiple times per Platform via the <ProjectReference> isn't something intended and requires some hacks to work properly and not break restoring, intermediate output overwriting, etc...

Anyway, I still want to expand my feedback about templates - maybe it's worth reconsidering the decision of not making it configurable/pluggable? I would like to contribute there if you wish. It exactly covers the need for Beginners to be able to bootstrap their Game projects faster with fewer initial cognitive complexity. I haven't touched the MonoGame for a few years now and while I consider myself not a pure beginner there, templates at their current state really confuse. Nowadays .NET project templates have a good integration with the IDEs UI to be able to configure templates more easily. From my side, I can also improve discoverability of such template properties in Rider on behalf of my MonoGame plugin.

SimonDarksideJ Jan 18, 2026
Maintainer Author

Yeah, seems like forcing MSBuild to build the same project multiple times per Platform via the <ProjectReference> isn't something intended and requires some hacks to work properly and not break restoring, intermediate output overwriting, etc...

Check out the latest in the templates repo (will be in the next preview), we spent some more time on the feedback and came up with a strategy. All details in the updated notes above!

seclerp Jan 21, 2026

Thanks for looking into it and addressing it!

Uh oh!

MonoGame 3.8.5 Preview feedback and known issues #9155

Uh oh!

Uh oh!

SimonDarksideJ Jan 3, 2026 Maintainer

The MonoGame 3.8.5 previews are here

When will 3.8.5 be released?

Everyone's help is wanted

Updated Templates

Known issues

Resolved issues

3.8.x Upgrade

3.8.5.preview.2 upgrade

3.8.5.preview.3 upgrade

Content Builder Strategies

Feedback

MonoGame Foundation

Replies: 2 comments · 9 replies

Uh oh!

Uh oh!

leandiez Jan 7, 2026

Uh oh!

SimonDarksideJ Jan 13, 2026 Maintainer Author

Uh oh!

Uh oh!

seclerp Jan 13, 2026

Uh oh!

Uh oh!

seclerp Jan 13, 2026

Uh oh!

Uh oh!

SimonDarksideJ Jan 14, 2026 Maintainer Author

Uh oh!

seclerp Jan 15, 2026

Uh oh!

SimonDarksideJ Jan 18, 2026 Maintainer Author

Uh oh!

seclerp Jan 21, 2026

SimonDarksideJ
Jan 3, 2026
Maintainer

When will `3.8.5` be released?

Replies: 2 comments 9 replies

leandiez
Jan 7, 2026

SimonDarksideJ Jan 13, 2026
Maintainer Author

seclerp
Jan 13, 2026

SimonDarksideJ Jan 14, 2026
Maintainer Author

SimonDarksideJ Jan 18, 2026
Maintainer Author