Introduction

This series of tutorials covers how to load a Gum project using all of the functionality provided by Gum for creating and maintaining MonoGame projects. This tutorial is intended for brand new users of MonoGame Gum. It covers the following topics:

• Creating a new Gum project (.gumx)

• Loading the Gum project (.gumx) in MonoGame

• Displaying Screens

• Interacting with Gum Forms UI

• Accessing Gum instances in code

• Working with Gum code generation for strongly-typed components

• Managing multiple screens

Introduction

This tutorial walks you through creating a brand new Gum project and adding it to an existing MonoGame project. The MonoGame project can be empty or it can be an existing game - the steps are the same either way.

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

• 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.MonoGam project.

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.

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.

In the Gum tool click File -> Save Project.

Select the GumProject folder created earlier as the target location. Give your Gum project a name such as GumProject.

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

We can add default Forms components to our 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

This tutorial will not use the DemoScreenGum, so leave this option unchecked and press OK.

Forms components modify your default components (such as Text) for styling. Click OK to apply these changes.

Your project now includes Forms components.

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
3. Set the file to 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.
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\**\*.*

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.

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:

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

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

        base.Initialize();
    }

    protected override void Update(GameTime gameTime)
    {
        MonoGameGum.GumService.Default.Update(this, gameTime);
        base.Update(gameTime);
    }

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

The code above has the following three calls on GumService:

• 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 = MonoGameGum.GumService.Default.Initialize(
            this.GraphicsDevice,
            // 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.

MonoGameGum.GumService.Default.Update(this, 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.

MonoGameGum.GumService.Default.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.

The next tutorial adds our first screen.

Introduction

Gum screens are top level items which can contain instances of Gum objects. We'll be creating our first Gum screen in this tutorial. We'll also load this screen in code and work with gum objects.

Creating a Screen in the Gum Tool

To add a new Screen:

1. Open the project in the Gum tool

2. Right-click on the Screens folder and select Add Screen

3. Name the screen TitleScreen and click OK

The newly created TitleScreen is now in the Screens folder.

Adding Instances

We can add instances to Gum Screen by drag+dropping the files onto the Game screen.

Add a Text instance by dropping the Standard/Text onto TitleScreen.

Instances can also be created by selecting the TitleScreen, then drag+dropping the item in the editor window.

Add a ButtonStandard instance by dropping Components/Controls/ButtonStandard onto TitleScreen.

Be sure to select the TitleScreen first, then drag+drop. If you click the component instead, then it will be selected, so you must re-select the TitleScreen.

The Gum tool includes lots of functionality for creating and customizing UI. For a more complete tutorial covering the Gum tool, see the Gum Tool Intro Tutorials. Feel free to spend some time creating your TitleScreen.

Showing a Gum Screen in Your Game

To show the screen in game, modify the Initialize method as shown in the following snippet:

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

// Start of new code
    // the Screens list contains all screens. Find the screen you want
    var screen = gumProject.Screens.Find(item => item.Name == "TitleScreen");
    // Calling GraphicalUiElement creates the visuals for the screen
    screen.ToGraphicalUiElement(
        RenderingLibrary.SystemManagers.Default, addToManagers: true);
// End of new code

    base.Initialize();
}

The game now displays the Gum screen. Notice that if you attempt to interact with the button, it does not show highlighted/clicked states. This is because we haven't yet passed the Screen to the Update method where UI interaction is performed. We'll do that in the next section.

Keeping a Screen Reference (Root)

Games usually need to interact with Gum screens in code. By convention the Screen is stored in a variable named Root. We can modify the Game project by:

1. Adding a Root member to Game

2. Assigning Root when calling ToGraphicalUiElement

3. Adding the Root to the Update call

The modified code is shown below in the following code snippet:

public class Game1 : Game
{
    private GraphicsDeviceManager _graphics;

// Start of new code
    GraphicalUiElement Root;
// End of new code

    ...
    
    
    protected override void Initialize()
    {
        var gumProject = MonoGameGum.GumService.Default.Initialize(
            this.GraphicsDevice,
            // This is relative to Content:
            "GumProject/GumProject.gumx");      
            
        var screen = gumProject.Screens.Find(item => item.Name == "TitleScreen");
            
// Start of new code
        Root = screen.ToGraphicalUiElement(
            RenderingLibrary.SystemManagers.Default, addToManagers: true);
// End of new code

        base.Initialize();
    }
    

    protected override void Update(GameTime gameTime)
    {
// Start of new code
        MonoGameGum.GumService.Default.Update(this, gameTime, Root);
// End of new code
        base.Update(gameTime);
    }

Notice that we've added the Root as a parameter to the Update call. By doing this, we get the built-in behavior for Forms control such as Button.

Accessing Instances in Code

Now that we have our screen stored in the Root object, we can access objects.

We can modify the displayed string by getting an instance of the Text and modifying its properties as shown in the following code:

protected override void Initialize()
{
    var gumProject = MonoGameGum.GumService.Default.Initialize(
        this.GraphicsDevice,
        // This is relative to Content:
        "GumProject/GumProject.gumx");      
        
    var screen = gumProject.Screens.Find(item => item.Name == "TitleScreen");
        
    Root = screen.ToGraphicalUiElement(
        RenderingLibrary.SystemManagers.Default, addToManagers: true);

// Start of new code
    var textInstance = Root.GetGraphicalUiElementByName("TextInstance")
        as TextRuntime;
    textInstance.Text = "I am set in code";
// End of new code

    base.Initialize();
}

The code above casts TextInstance to a TextRuntime. Each standard type in Gum (such as Text, Sprite, and Container) has a corresponding runtime type (such as TextRuntime, SpriteRuntime, and ContainerRuntime). Therefore, if we wanted to interact with a Sprite in code, we would cast it to a SpriteRuntime.

We can also interact with Forms objects in code. The base type for all Forms objects is FrameworkElement, so we can use the GetFrameworkElementByName extension method as shown in the following code:

protected override void Initialize()
{
    var gumProject = MonoGameGum.GumService.Default.Initialize(
        this.GraphicsDevice,
        // This is relative to Content:
        "GumProject/GumProject.gumx");      
        
    var screen = gumProject.Screens.Find(item => item.Name == "TitleScreen");
        
    Root = screen.ToGraphicalUiElement(
        RenderingLibrary.SystemManagers.Default, addToManagers: true);

    var textInstance = Root.GetGraphicalUiElementByName("TextInstance")
        as TextRuntime;
    textInstance.Text = "I am set in code";

// Start of new code
    var button = Root.GetFrameworkElementByName<Button>("ButtonStandardInstance");
    button.Click += (_, _) => textInstance.Text = "Button clicked at " + DateTime.Now;
// End of new code

    base.Initialize();
}

Notice that the code above uses the GetFrameworkElementByName. This code returns an instance of a FrameworkElement (Forms instance). As we'll cover in the next tutorial, only some Components can be used as Forms instances.

Conclusion

This tutorial showed how to load a Gum screen in code and how to interact with objects. The next tutorial discusses Forms controls and explains the difference between GraphicalUielements and Forms controls.

Introduction

The types used in the previous tutorials fall into two categories:

• Standard runtime types like TextRuntime

• Forms types like Button

Games often need to interact with custom components which do not fall into either of these two categories. This tutorial shows how to create custom classes, which we refer to as runtime types for custom components.

Creating a Component

For this tutorial we'll create a component which can be used to display score. It has three parts:

1. A NineSlice for the background

2. A text for the "Score:" label

3. A text for the score value

Interacting with Custom Components in code

If we add an instance of this component to our screen, we can interact with it as shown in code. First, we need to drag+drop an instance of the ScoreComponent into our Screen.

We can interact with ScoreComponentInstance by using the following code:

var scoreComponentInstance = 
    Root.GetGraphicalUiElementByName("ScoreComponentInstance");
var scoreValue = 
    scoreComponentInstance.GetGraphicalUiElementByName("ScoreValue") as TextRuntime;
scoreValue.Text = "999";

Although this code is functional, it can be difficult to maintain in a larger project. We are relying on values like "ScoreValue" to find the text object. If we spell this wrong, or if we change the name of our Text in Gum, this code breaks. Also, this code is quite verbose and it can be difficult to write from memory.

We can use strongly-typed classes to solve these problemsl

Enabling Code Generation

The Gum tool supports code generation which allows us to interact with Gum components without needing to cast or use string names. We can enable code gen in Gum by checking the check boxes in the Code tab. Also, be sure to switch the Output Library to MonoGame.

This produces a fully-generated class named ScoreComponentRuntime. In this case, the code is using FullyInCode instantiation type, which means the generated code shows the code necessary to create this component without loading the gum project. If you would like to use generated code without loading a Gum file, then this approach might be useful. Usually this approach is useful if you would like to avoid file IO or if you cannot read from disk (such as on an embedded device).

Since our project loads from disk, we'll switch to using FindByName as our Object Instantiation Type. By switching to this Object Instantiation Type, the generated code is modified to look for instances by name.

The code should look similar to the following:

public partial class ScoreComponentRuntime
{
    public NineSliceRuntime NineSliceInstance { get; protected set; }
    public TextRuntime ScoreLabel { get; protected set; }
    public TextRuntime ScoreValue { get; protected set; }

    public ScoreComponentRuntime(bool fullInstantiation = true, bool tryCreateFormsObject = true)
    {


    }
    public override void AfterFullCreation()
    {
        NineSliceInstance = this.GetGraphicalUiElementByName("NineSliceInstance") as NineSliceRuntime;
        ScoreLabel = this.GetGraphicalUiElementByName("ScoreLabel") as TextRuntime;
        ScoreValue = this.GetGraphicalUiElementByName("ScoreValue") as TextRuntime;
        CustomInitialize();
    }
    //Not assigning variables because Object Instantiation Type is set to By Name rather than Fully In Code
    partial void CustomInitialize();
}

Using Generated Code

We can enable automatic saving of generated code in Gum by specifying the location of our .csproj file. To do this, set Code Project Root to the full path of folder containing your .csproj:

We can force code generation once by clicking the Generate Code button.

This creates two code files - a generated code file and a custom code file:

• The generated code file contains the same code as is shown in the code generation preview.

• The custom code file can be used to customize the runtime class

This component can be used in code as shown in the following snippet:

var scoreComponentInstance = Root.GetGraphicalUiElementByName("ScoreComponentInstance")
    as ScoreComponentRuntime;
scoreComponentInstance.ScoreValue.Text = "999";

Note that all screen and components default to a Generation Behavior of GenerateAutomaticallyOnPropertyChange. This means that any changes result in re-generation of the .Generated.cs file.

Screen Runtimes

We can also create runtimes for screens. Once properties have been set up, adding additional runtimes is much easier. In fact, clicking Generate Code button the produces generated code for the screen.

Once we have a runtime class for our Screen, we can delete code from Game1 and write it in the CustomInitialize method as shown in the following snippet:

partial class TitleScreenRuntime : Gum.Wireframe.GraphicalUiElement
{
    partial void CustomInitialize()
    {
        ScoreComponentInstance.ScoreValue.Text = "999";
    }
}

Conclusion

This tutorial shows how to generate types for screens and components which are used automatically when loading a Gum project.

The next tutorial shows how to work with multiple screens.

Introduction

So far we've been working with a single Screen. This tutorial covers how to work with multiple screens, including how to add and destroy screens in response to UI events.

Creating Multiple Screens

Before we write any code, we'll create two screens. A real game might have screens like a TitleScreen, OptionsScreen, GameScreen (which includes hud and a pause menu), and a GameOverScreen. For this tutorial we'll create two simple screens, each with a single button and a Text.

Modifying Game1

Next we'll make the following modifications to Game1:

• Change the first screen to Screen1

• Make the Root property public static so that it can be accessed by the Screens

A full game may keep the Root in a dedicated object which provides access to the Screens, but we're making it public static to keep the tutorial simple.

public class Game1 : Game
{
    ...
    public static GraphicalUiElement Root;
    ...
    protected override void Initialize()
    {
        ...
        var screen = gumProject.Screens.Find(item => item.Name == "Screen1");
        ...

Modifying Screen1Runtime and Screen2Runtime

Now we can modify both Screen1Runtime.cs and Screen2Runtime.cs to include code that links from one to the other as shown in the following code:

partial class Screen1Runtime : Gum.Wireframe.GraphicalUiElement
{
    partial void CustomInitialize()
    {
        this.GetFrameworkElementByName<Button>("ButtonStandardInstance").Click += (_, _) =>
        {
            Game1.Root.RemoveFromManagers();
            var screen = ObjectFinder.Self.GumProjectSave.Screens.Find(
                item => item.Name == "Screen2");
            Game1.Root = screen.ToGraphicalUiElement(
                RenderingLibrary.SystemManagers.Default, addToManagers: true);
        };
    }
}

partial class Screen2Runtime : Gum.Wireframe.GraphicalUiElement
{
    partial void CustomInitialize()
    {
        this.GetFrameworkElementByName<Button>("ButtonStandardInstance").Click += (_, _) =>
        {
            Game1.Root.RemoveFromManagers();
            var screen = ObjectFinder.Self.GumProjectSave.Screens.Find(
                item => item.Name == "Screen1");
            Game1.Root = screen.ToGraphicalUiElement(
                RenderingLibrary.SystemManagers.Default, addToManagers: true);
        };

    }
}

Each screen removes itself from managers when its button is clicked, then creates and adds the next screen to managers.

Conclusion

This tutorial showed how to switch between two screens by removing the old screen with RemoveFromManagers and creating a new screen with ToGraphicalUiElement.

Introduction

Gum Forms provides a collection of standardized, fully functional UI elements. MonoGame Gum includes the following types:

• Button

• CheckBox

• ComboBox

• ListBox

• ListBoxItem (used by ListBox)

• PasswordBox

• RadioButton

• ScrollView

• Slider

• TextBox

We can use all of the types above by adding instances of components which map to these controls.

Adding Forms Instances to a Screen

The previous tutorial showed how to add a Button instance to our screen. We can add other functional controls by drag+dropping instances into the TitleScreen.

Our forms controls already have some functionality even before we write any code in our game.

Interacting with Forms Instances

We can interact with any of the Forms instances by using GetFrameworkElementByName. For example, the following code can be used to add items to the ListBoxInstance:

Forms types such as Button are associated with Gum components based on their category. For example, the following components can be used to create Button instances.

Although the prefix "Button" suggests that these controls are Forms Buttons, the name can change and these would still create buttons. At runtime the type of Forms control associated with a component is determined by the state categories defined in the component.

For example, each of these components has a state category named ButtonCategory.

Although we won't cover the details in this tutorial, you can customize the existing components or create new components which will map to the Forms types so long as they have the appropriate category.

Additional Documentation

Conclusion

This tutorial showed how to create Forms instances in a screen, interact with them in code, and how to work with the different forms types.

The next tutorial covers how to generate code for custom components.