MonoGame/KNI/FNA

Introduction

This page assumes you have an existing MonoGame project. This can be an empty project or an existing game.

MonoGame Gum works on a variety of platforms including DesktopGL, DirectX, and mobile. It's fully functional with all flavors of XNA-like libraries including MonoGame, Kni (including on web), and FNA. It can be used alongside other libraries such as MonoGameExtended and Nez. If your particular platform is not supported please contact us on Discord and we will do our best to add support.

Adding Gum NuGet Package

The easiest way to add Gum to your project is to use the NuGet package. Open your project in your preferred IDE, or add Gum through the command line. Each Gum NuGet package works on any platform. For example, MonoGame Desktop and Android project types use the same Gum NuGet package.

MonoGame

Add the Gum.MonoGame NuGet package (https://www.nuget.org/packages/Gum.MonoGame)

Modify csproj:

<PackageReference Include="Gum.MonoGame" Version="*" />

Or add through command line:

dotnet add package Gum.MonoGame

KNI

FNA

Adding Source (Optional)

You can directly link your project to source instead of a NuGet package for improved debuggability, access to fixes and features before NuGet packages are published, or if you are interested in contributing.

To add source, first clone the Gum repository: https://github.com/vchelaru/Gum

If you have already added the Gum NuGet package to your project, remove it.

MonoGame

Add the following projects to your solution:

• <Gum Root>/MonoGameGum/MonoGameGum.csproj

• <GumRoot>/GumCommon/GumCommon.csproj

Next, add MonoGameGum as a project reference in your game project. Your project might look like this depending on the location of the Gum repository relative to your game project:

<ProjectReference Include="..\Gum\MonoGameGum\MonoGameGum.csproj" />

KNI

FNA

If using Visual Studio Code, see the Visual Studio Code and Linking Source page.

Adding Gum to Game

Gum can be added to a Game/Core class with a few lines of code. Projects are encouraged to create a local GumService property called GumUI for convenience.

The code in this example assumes that you are using retained mode rendering. If you are interested in immediate mode rendering, see the Setup for GumBatch page.

Game Class

Add code to your Game class to Initialize, Update, and Draw Gum as shown in the following code block:

using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Graphics;
using MonoGameGum;
using Gum.Forms;
using Gum.Forms.Controls;

namespace MonoGameGum1;

public class Game1 : Game
{
    private GraphicsDeviceManager _graphics;
    private SpriteBatch _spriteBatch;

    GumService GumUI => GumService.Default;

    public Game1()
    {
        _graphics = new GraphicsDeviceManager(this);
        Content.RootDirectory = "Content";
        IsMouseVisible = true;
    }

    protected override void Initialize()
    {
        GumUI.Initialize(this, DefaultVisualsVersion.V3);
        base.Initialize();
    }

    protected override void Update(GameTime gameTime)
    {
        GumUI.Update(gameTime);
        base.Update(gameTime);
    }

    protected override void Draw(GameTime gameTime)
    {
        GraphicsDevice.Clear(Color.CornflowerBlue);
        GumUI.Draw();
        base.Draw(gameTime);
    }
}

Core (Nez)

The code above initializes Gum using V3 (version 3) visuals. Future versions of Gum may introduce new versions of visuals.

Old version will continue to be supported when new versions are released, but you may want to upgrade to new versions to take advantage of new features.

Adding a Button (Testing the Setup)

Gum can be tested by adding a Button after Gum is initialized. To do so, add code to create a Button as shown in the following block of code after Gum is initialized:

protected override void Initialize()
{
    base.Initialize();

    GumUI.Initialize(Core.GraphicsDevice, DefaultVisualsVersion.V3);
    
    var button = new Button();
    button.AddToRoot();
    button.Click += (_,_) =>
        button.Text = "Clicked at\n" + DateTime.Now;
    
    // additional code omitted

If everything is initialized correctly, you should see a clickable button at the top-left of the screen. Keep in mind that this is simply a test to make sure Gum is working properly. You may want to delete this button once you begin working on your game.

Troubleshooting

Nez

Could not load file or assembly 'MonoGame.Framework, Version=3.8.1.303

If you add the Gum code to your project, you may experience this exception internally from Nez:

The reason this is happening is because currently (as of July 2024) Nez links MonoGame 3.8.0 instead of 3.8.1 (the latest).

To solve this problem, your project must explicitly link MonoGame 3.8.1 or else you will have this exception.

To do this:

1. Open your project in Visual Studio

2. Expand the Dependencies item

3. Right-click on Packages and select Manage NuGet Packages\

   

   Right-click Manage NuGet Packages... option
4. Click on the Browse tab

5. Search for MonoGame.Framework

6. Select the MonoGame.Framework NuGet package for your particular project type. This is most likely MonoGame.Framework.DesktopGL, but it may be different if you are targeting another platform.\

   

   MonoGame.Framework NuGet packages
7. Click the Install button to add the NuGet package

After adding MonoGame, your NuGet packages should similar to the following image: