Setup

Introduction

This tutorial walks you through creating a brand new Gum project and adding it to an existing MonoGame project.

This tutorial covers:

• Adding Gum NuGet packages

• Creating a new Gum project using the Gum tool

• Modifying the game .csproj to include all Gum files

• Adding Forms Components

• Loading the Gum project in your game

This tutorial presents the minimum amount of code necessary to work with Gum. You may need to adapt the code to fit in your game project.

Adding Gum NuGet Packages

Before writing any code, we must add the Gum NuGet package. Add the Gum.MonoGame package to your game. For more information see the Setup page.

Once you are finished, your game project should reference the Gum.MonoGame project.

Gum.MonoGame NuGet package

Creating a new Gum Project

Next we'll create a project in the Gum UI tool. If you have not yet run the Gum tool, you can get setup instructions in the Gum Setup page.

Once you have the tool downloaded, run it. You should have an empty project.

Empty Gum Project

We need to save our Gum project in the Content folder of our game. Gum projects include many files. it's best to keep a Gum project and all of its files in a dedicated folder.

Add a new folder to your Game's Content folder which will contain the Gum project, such as GumProject.

GumProject folder in Visual Studio

In the Gum tool click File -> Save Project.

File -> Save project menu item

Select the GumProject folder created earlier as the target location. Usually the save location is an empty folder inside your game's Content folder. Give your Gum project a name such as GumProject.

Save GumProject in the newly-created GumProject folder

After your project is saved it should appear in Visual Studio.

Gum project in Visual Studio

Next, add default Forms components to the Gum project. Forms components are premade components for standard UI elements such as Button, TextBox, and ListBox. We'll use these components in later tutorials.

To add Gum Forms components in Gum, select Content -> Add Forms Components.

Add Forms Components menu item

Later tutorials will reference the demo screen, so check the Include DemoScreenGum option and click OK. Don't worry, you can delete this screen later as you develop your game.

Include DemoScreenGum

If asked, click Yes when asked about overwriting the default standards.

Click, Yes to modify standards with the default Forms styling

Your project now includes Forms components.

Forms Components in Gum

Modifying the Game .csproj

Now that we have our Gum project created, we can load it in our game.

First, we'll set up our project so all Gum files are copied when the project is built. To do this:

1. Right-click on any Gum file in your project, such as GumProject.gumx

2. Select the Properties item

   

   Properties right click option
3. Set the file to Copy if Newer. If using Android, see instructions below.

   

   Mark the Gum file as Copy if newer
4. Double click your game's csproj file to open it in the text editor and find the entry for the file that you marked as Copy if newer.

   

   Entry for GumProject.gumx in the csproj file.
5. Modify the code to use a wildcard for all files in the Gum project. In other words, change Content\GumProject\GumProject.gumx to Content\GumProject\**\*.*

   

   Wildcard entry for all files in the GumProject folder

   Now all files in your Gum project will be copied to the output folder whenever your project is built, including any files added later as you continue working in Gum.

   

   All Gum files automatically are marked as Copy if newer.

At the time of this writing, Gum does not use the MonoGame Content Builder to build XNBs for any of its files. This means that referenced image files (.png) will also be copied to the output folder.

As you build your Gum project it's best to keep all referenced PNGs inside your Gum folder to keep it portable.

Future versions may be expanded to support using either the .XNB file format or raw PNGs.

Android

If you are using Android, then your files must be marked as Android Assets rather than copied files.

The steps to do this are:

1. Open your project file

2. Find the entry for the Gum project if you followed the previous section which copies file using wildcard

3. Change it to an Android Asset. For example your code might look like this:

<AndroidAsset Include="Content\GumProject\**\*.*" />

Loading the Gum Project

Now that we have a Gum project added to the .csproj, we can load the Gum project. We need to add code to Initialize, Update, and Draw. A simplified Game class with these calls would look like the following code:

using MonoGameGum;

public class Game1 : Game
{
    private GraphicsDeviceManager _graphics;
    GumService Gum => GumService.Default;
    
    public Game1()
    {
        _graphics = new GraphicsDeviceManager(this);
        Content.RootDirectory = "Content";
        IsMouseVisible = true;
    }

    protected override void Initialize()
    {
        var gumProject = Gum.Initialize(this,
            // This is relative to Content:
            "GumProject/GumProject.gumx");

        base.Initialize();
    }

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

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

The code above has the following three calls on Gum:

• Initialize - this loads the argument Gum project and sets appropriate defaults. Note that we are loading a Gum project here, but the gum project is optional. Projects which are using Gum only in code would not pass the second parameter.

        var gumProject = Gum.Initialize(this,
            // This is relative to Content:
            "GumProject/GumProject.gumx");

• Update - this updates the internal keyboard, mouse, and gamepad instances and applies default behavior to any components which implement Forms. For example, if a Button is added to the Screen, this code is responsible for checking if the cursor is overlapping the Button and adjusting the highlight/pressed state appropriately.

Gum.Update(gameTime);

• Draw - this method draws all Gum objects to the screen. Currently this method does not perform any drawing, but in the next tutorial we'll be adding a Gum screen which is drawn in this method.

Gum.Draw();

Conclusion

If you've followed along, your project is now a fully-functional Gum project. We haven't added any screens to the Gum project yet, so if you run the game you'll still see a blank (cornflower blue) screen.

Empty MonoGame project

The next tutorial adds our first screen.