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.

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

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

Modify csproj:

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

Or add through command line:

dotnet add package Gum.KNI

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

Modify csproj:

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

Or add through command line:

dotnet add package Gum.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.

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" />

Add the following projects to your solution:

<Gum Root>/MonoGameGum/KniGum/KniGum.csproj
<GumRoot>/GumCommon/GumCommon.csproj

Next, add KniGum 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\KniGum\KniGum.csproj" />

Add the following projects to your solution:

<Gum Root>/MonoGameGum/FnaGum/FnaGum.csproj
<GumRoot>/GumCommon/GumCommon.csproj

Next, add FnaGum 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\FnaGum\FnaGum.csproj" />

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.

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 Gum;
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);
        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);
    }
}

Next, add code to your Core-inheriting class to Initialize, Update, and Draw Gum as shown in the following code block:

using Gum;
using Gum.Forms;

public class Game1 : Core
{
    GumService GumUI => GumService.Default;    
    protected override void Initialize()
    {
        base.Initialize();

        GumUI.Initialize(Core.GraphicsDevice);
        
        Scene = new BasicScene();
    }

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

    protected override void Draw(GameTime gameTime)
    {
        base.Draw(gameTime);
        // Add GumUI.Draw after base.Draw or else graphics won't show up
        GumUI.Draw();
    }
}

Adding Shape Support (Recommended)

Gum's Circle and Rectangle elements have a fill and an outline (stroke). On MonoGame, KNI, and FNA, an outlined Circle or Rectangle renders out of the box — StrokeColor, StrokeWidth, StrokeWidthUnits, and the geometry properties (Width, Height, Radius, CornerRadius) all work with no extra package.

Filling a shape and the richer effects need the shape support package. We recommend installing it for most projects so that fill, gradient, drop shadow, dashed stroke, and anti-aliasing all draw. Without it, the following properties are stored and round-trip correctly, but silently do not draw: FillColor (and the fill color channels), gradient (UseGradient and the gradient properties), drop shadow (HasDropshadow and the dropshadow properties), dashed stroke (StrokeDashLength / StrokeGapLength), anti-aliasing (IsAntialiased), and Blend. Nothing throws — the shape simply renders without that feature.

To enable fill and effects, add the shape support package for your platform (the Gum.Shapes.* package, which uses Apos.Shapes under the hood):

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

Or add through command line:

dotnet add package Gum.Shapes.MonoGame

Next, add the following line after GumUI.Initialize(...) in your Initialize method:

// Initialize
GumUI.Initialize(this);
ShapeRenderer.Self.Initialize();

The fill + outline Circle and Rectangle surface ships in the May 2026 release. Before then, you can use it by building Gum from source.

For the full set of fill, outline, gradient, drop shadow, and corner-radius properties, see the Shapes page.

Adding Dynamic Fonts (Optional)

By default, Gum uses pre-built bitmap font (.fnt) files for text rendering. You can enable dynamic in-memory font generation using KernSmith, which lets you set Font, FontSize, IsBold, IsItalic, OutlineThickness, and UseFontSmoothing on any TextRuntime without needing .fnt/.png files on disk.

First, add the KernSmith NuGet package for your platform:

<PackageReference Include="KernSmith.MonoGameGum" Version="*" />

Or add through command line:

dotnet add package KernSmith.MonoGameGum

Next, add the following line after GumUI.Initialize(this) in your Initialize method:

// Initialize
Gum.Wireframe.CustomSetPropertyOnRenderable.InMemoryFontCreator =
    new KernSmith.Gum.KernSmithFontCreator(GraphicsDevice);

For shipping games, you should register custom .ttf fonts rather than relying on system fonts. For more information, see the Fonts page.

Adding Expression Support (Optional)

If your Gum project uses arithmetic expressions in variable references (such as Width = OtherInstance.Width + 20), you can add the Gum.Expressions NuGet package for full expression evaluation at runtime. Without this package, simple variable references like Width = OtherInstance.Width still work.

Add the NuGet package:

dotnet add package Gum.Expressions

Then call GumExpressionService.Initialize() after GumUI.Initialize. Expression support is typically used with a Gum project that has variable references defined in the tool:

// Initialize
GumUI.Initialize(this, "GumProject/GumProject.gumx");
GumExpressionService.Initialize();

If linking to source instead of NuGet, add <Gum Root>/Runtimes/GumExpressions/GumExpressions.csproj to your solution.

For more information, see the Runtime Variable References page.

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);

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

Try on XnaFiddle.NET

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

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:

Open your project in Visual Studio
Expand the Dependencies item
Right-click on Packages and select Manage NuGet Packages\
Right-click Manage NuGet Packages... option
Click on the Browse tab
Search for MonoGame.Framework
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
Click the Install button to add the NuGet package

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

PreviousAdding/Initializing Gum NextVisual Studio Code and Linking Source

Last updated 29 days ago

Was this helpful?