Skip to main content

Installation (MonoGame)

Up to date

This page is up to date for MonoGame.Extended 4.0.3. If you find outdated information, please open an issue.

The following article details the steps necessary to get MonoGame.Extended installed and setup in your project. MonoGame.Extended can be used with either MonoGame, KNI, or FNA. This article wil detail how to setup and install MonoGame.Extended with an existing MonoGame project.

note

Prerequisites​

The following prerequisites are required when using MonoGame.Extended with MonoGame.

Installation​

MonoGame.Extended is distributed via a NuGet package. You can add the NuGet pacakge to your C# project through your IDE (Visual Studio, Rider, etc) or through the Command Line Interface (CLI) using the dotnet commands

dotnet add package MonoGame.Extended --version 4.0.3
caution

MonoGame.Extended is currently being updated and prepped for version 4.0 release. In the mean time, the current stable version is the 4.0.0 version shown above. Please use this version for now even though it is marked prerelease until version 4.0 is released. For more information, please see the MonoGame.Extended is Back blog post.

(Optional) Setup MGCB Editor​

MonoGame.Extended provides MonoGame Content Pipeline Extensions to extend the asset types that can be imported through the MonoGame Content Pipeline. All asset preprocessing extensions provided as pipeline extensions can be used to load the assets at runtime from disk if you want, meaning that setting this up is optional and only needed if you are using the content pipeline for asset management in your game.

Download Pipeline Nuget​

To get started first add the MonoGame.Extended.Content.Pipeline NuGet package to your MonoGame project

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

Add Reference to MGCB Editor​

In order for the MonoGame Content Builder (MGCB) Editor to make use of the extension provided by MonoGame.Extended.Content.Pipeline you will need to add a reference to the MonoGame.Extended.Content.Pipeline.dll assembly to the content project. This assembly is downloaded as part of the MonoGame.Extended.Content.Pipeline NuGet you just installed, however the necessary files to reference do not get automatically copied to your project directory. Additionally, when adding a reference to an assembly in the MGCB Editor, the path it creates in the Content.mgcb file is relative, meaning it will break if you move your project directory or change computers.

To resolve this, MonoGame.Extended.Content.Pipeline provides a unique method for users to ensure that the needed assembly references are copied locally to your project directory for easier referencing and so that the relative path in the Content.mgcb file doesn't break.

To set this up, first open your game project's .csproj file and add the following property group

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

This is the default recommended setting. The value of the MonoGameExtendedPipelineReferencePath is the directory where the MonoGame.Extended.Content.Pipeline.dll and its necessary references will be copied when you do a project build. You can adjust this value if you would prefer it be in a different directory. However, it is strongly recommended that you keep within your overall project directory.

After adding the property group, do a build of your project and you shoudl now see the MonoGame.Extended.Content.Pipeline.dll inside the directory specified above. Now we just need to add a reference to that dll in the MGCB Editor

  1. Open you Content.mgcb file in the MGCB Editor
tip

When using Visual Studio, double clicking the Content.mgcb file in your project should open it for you using the MGCB Editor automatically if you have the MonoGame Visual Studio Extension installed. If, for some reason, it opens it as a plain text file instead, you can right-click the Content.mgcb file, choose Open With, then set the default default application to open with as the MGCB Editor.

Alternatively, if you're not using Visual Studio, you can open it by using the following dotnet command in a command-line or terminal window from within your project directory

dotnet mgcb-editor ./Content/Content.mgcb
  1. Click the Content node located in the Project panel on the left.
  2. In the Properties panel below it, scroll down to the References field. Click this field to open the Reference Editor dialog window.
  3. Click the Add button in the Reference Editor dialog window.
  4. Find and add the MonoGame.Extended.Content.Pipeline.dll.
  5. Click Ok to close the Reference Editor dialog window.

You should now see the MonoGame.Extended.Content.Pipeline.dll in the References field of the Property panel.

Conclusion​

Setting up MonoGame.Extended with an existing MonoGame project is straight forward and only requires that you add the NuGet reference. Once added, you can immediately start taking advantage of what MonoGame.Extended has to offer.