Migrate MonoGame.Extended from 3.x to 4.1.0

In this article, I explain how to migrate a project using MonoGame.Extended to version 4.1.0, including MonoGame 3.8.4 and .NET 8 upgrades, package changes, and best practices.

Introduction

Migrating to MonoGame.Extended 4.x brings improved performance, consolidated packages, and better support for modern .NET projects. This guide walks you through upgrading your project from MonoGame.Extended 3.x to 4.1.0 (or newer), including updating dependencies, removing deprecated packages, and ensuring your project works with .NET 8.

1. Upgrade to .NET 8.0

First, migrate your C# project from .NET Core 3.1 to .NET 8.0. If you haven’t done this yet, see this post for a step-by-step guide.

2. Update MonoGame Framework to 3.8.4

Migrate your MonoGame project to the version 3.8.4: see this post for a step-by-step guide.

Why?
MonoGame 3.8.4 is fully compatible with .NET 8 and MonoGame.Extended 4.x releases.

3. Update MonoGame.Extended Packages

MonoGame.Extended 4.x consolidates many features into the main package. Begin by updating the main package in your project:

dotnet add package MonoGame.Extended --version 4.1.0

Tip: Consider using the latest 4.x stable version if available.

Check your .csproj file for PackageReference entries. You may see something like:

<ItemGroup>
    <PackageReference Include="MonoGame.Extended" Version="3.8.0" />
    <PackageReference Include="MonoGame.Extended.Animations" Version="3.7.0" />
    <PackageReference Include="MonoGame.Extended.Content.Pipeline" Version="3.8.0" />
    <PackageReference Include="MonoGame.Extended.Entities" Version="3.8.0" />
    <PackageReference Include="MonoGame.Extended.Input" Version="3.8.0" />
    <PackageReference Include="MonoGame.Extended.Tiled" Version="3.8.0" />
    <PackageReference Include="MonoGame.Framework.DesktopGL" Version="3.8.0.1641" />
    <PackageReference Include="MonoGame.Content.Builder.Task" Version="3.8.0.1641" />
</ItemGroup>

Update the main package to 4.1.0 (or newer) and remove deprecated sub-packages as described below.

Add the following property group to your .csproj file if you use the content pipeline:

<PropertyGroup>
    <MonoGameExtendedPipelineReferencePath>$(MSBuildThisFileDirectory)pipeline-references</MonoGameExtendedPipelineReferencePath>
</PropertyGroup>

4. Remove Deprecated MonoGame.Extended Packages

MonoGame.Extended 4.x combines many features into the main package. You should remove the following packages:

dotnet remove package MonoGame.Extended.Animations
dotnet remove package MonoGame.Extended.Entities
dotnet remove package MonoGame.Extended.Input
dotnet remove package MonoGame.Extended.Tiled

Why?
These sub-packages are now part of the main MonoGame.Extended package, reducing complexity and ensuring compatibility.

5. Update the Content Pipeline

If you use the MGCB Editor or custom content importers, update the content pipeline package:

dotnet add package MonoGame.Extended.Content.Pipeline --version 4.1.0

6. Test and Troubleshoot

• Build your project to ensure all dependencies are resolved.
• Run your game and test all features, especially those related to animations, entities, input, and tiled maps.
• Review the MonoGame.Extended documentation for any API changes or migration notes.
• If you encounter issues, check for breaking changes between 3.x and 4.x, and update your code accordingly.

Namespaces

Update your source code in order to replace any removed using MonoGame.Extended.*; with the proper one:

using MonoGame.Extended.Sprites; // Removed
using MonoGame.Extended.TextureAtlases; // Removed

Becomes:

using MonoGame.Extended.Graphics;

Renamed classes

Some classes name may have changed:

• TextureAtlas is now named Texture2DAtlas

Constructors

Some classes now require to be initialized in the constructor, instead of using setters:

- var spriteSheet = new SpriteSheet { TextureAtlas = atlas };
+ var spriteSheet = new SpriteSheet(name: $"SpriteSheet/{name}", textureAtlas: atlas);

Sprite sheets and Animations

Animations are now defined through the spritesheet:

spriteSheet.DefineAnimation(
    name,
    builder =>
    {
        builder.IsLooping(isLooping);
        foreach (var f in frameIndices)
        {
            builder.AddFrame(f, TimeSpan.FromSeconds(0.2f));
        }
    }
);

7. Migration Checklist

• Upgrade project to .NET 8.0
• Update MonoGame to 3.8.4 (or latest)
• Update MonoGame.Extended to 4.1.0 (or latest)
• Remove deprecated sub-packages
• Update content pipeline package if needed
• Add pipeline reference property group to .csproj if using content pipeline
• Build and test your project

Documentation

See the MonoGame.Extended documentation for more details and the latest updates.

By following these steps, you can migrate your project to MonoGame.Extended 4.1.0 and take advantage of the latest features and improvements.

Troubleshooting

• Upgrade to MonoGame 3.8.4
  • TiledMapTilesetProcessor Error and Solution