Setup

Gum Forms gives you a full set of UI controls in code, and a single line restyles every control with a built-in theme — so your game's UI can look like any of these without changing a line of control code:

DarkPro	Bubblegum	Neon

Retro 95	Forest Glade	Editor

This tutorial uses Gum's default visuals to keep the dependency footprint minimal, but you can drop in any of the themes above (or author your own) with one Apply call. See the Themes reference for the full gallery and usage.

Introduction

This tutorial walks you through turning an empty MonoGame or Raylib project into a code-only Gum project, which acts as a starting point for the rest of the tutorials.

This tutorial covers:

• Adding Gum NuGet packages
• Adding the code to initialize, update, and draw Gum
• Adding your first Gum control (Button)

Everything after you have a root container is identical across MonoGame and Raylib. The only part that differs is the host application skeleton on this Setup page — once Gum is initialized, the rest of the tutorial series is fully shared.

Adding Gum NuGet Packages

Before writing any code, add the Gum NuGet package for your platform.

MonoGame

Add the Gum.MonoGame package to your game. For more information see the MonoGame/KNI/FNA setup page.

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

Gum.MonoGame NuGet package

Raylib

Adding Gum to Your Game

Gum requires a few lines of code to get started. The host application skeleton differs by platform — MonoGame uses a Game subclass whose Initialize/Update/Draw methods the framework calls for you, while Raylib uses a Program.Main with a game loop you own. The Gum calls themselves are the same on both backends: initialize once, then update and draw each frame.

A simplified host with the required calls would look like the following code:

MonoGame

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

namespace MyGumProject;

public class Game1 : Game
{
    private GraphicsDeviceManager _graphics;

    GumService GumUI => GumService.Default;

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

    protected override void Initialize()
    {
        GumUI.Initialize(this);

        var mainPanel = new StackPanel();
        mainPanel.AddToRoot();

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

Raylib

The code above includes the following sections:

• Initialize - the initialization code prepares Gum for use. It must be called one time for every Gum project. Once Gum is initialized, we can create controls such as the StackPanel which contains all other controls. By calling AddToRoot, the mainPanel is drawn and receives input. All items added to the StackPanel will also be drawn and receive input, so we only need to call AddToRoot on the StackPanel.

// Initialize
var mainPanel = new StackPanel();
mainPanel.AddToRoot();

• Update - this updates the internal keyboard, mouse, and gamepad instances and applies default behavior to any forms components. For example, if a Button is added to the StackPanel, this code is responsible for checking if the cursor is overlapping the Button and adjusting the highlight/pressed state appropriately.
• Draw - this draws all Gum objects to the screen. This does not yet perform any drawing since StackPanels are invisible, but we'll be adding controls later in this tutorial.

We can run our project to see a blank screen filled with the clear color.

Empty project

Adding Controls

Now that we have Gum running, we can add controls to our StackPanel (mainPanel). The following code adds a Button which responds to being clicked by modifying its Text property. Add it right after mainPanel is created:

// Initialize
// Creates a button instance
var button = new Button();
// Adds the button as a child so that it is drawn and has its
// events raised
mainPanel.AddChild(button);
// Initial button text before being clicked
button.Text = "Click Me";
// Makes the button wider so the text fits
button.Width = 350;
// Click event can be handled with a lambda
button.Click += (_, _) =>
    button.Text = $"Clicked at {System.DateTime.Now}";

Try on XnaFiddle.NET

Conclusion

Now that we have a basic project set up with a single Button. The next tutorial covers the most common forms controls.