Setup
Introduction
This tutorial walks you through turning an empty MonoGame 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
Modifying your Game class to support Gum and Gum Forms
Adding your first Gum control (Button)
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.

Adding Gum to Your Game
Gum requires a few lines of code to get started. A simplified Game class with the required calls would look like the following code:
using MonoGameGum.Forms.Controls;
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()
{
Gum.Initialize(this);
var mainPanel = new StackPanel();
mainPanel.Visual.AddToRoot();
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 includes the following sections:
Initialize - The Initialize method 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 callingAddToRoot
, themainPanel
is drawn and receives input. All items added to theStackPanel
will also be drawn and receive input, so we only need to callAddToRoot
for theStackPanel
.
Gum.Initialize(this);
var mainPanel = new StackPanel();
mainPanel.Visual.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 theStackPanel
, this code is responsible for checking if the cursor is overlapping theButton
and adjusting the highlight/pressed state appropriately.
Gum.Update(gameTime);
Draw - this method draws all Gum objects to the screen. This method does not yet perform any drawing since
StackPanels
are invisible, but we'll be adding controls later in this tutorial.
Gum.Draw();
We can run our project to see a blank (cornflower blue) screen.

Adding Controls
Now that we have Gum running, we can add controls to our StackPanel
(mainPanel
). The following code in Initialize adds a Button
which responds to being clicked by modifying its Text
property:
protected override void Initialize()
{
Gum.Initialize(this);
var mainPanel = new StackPanel();
mainPanel.Visual.AddToRoot();
// 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.Visual.Width = 350;
// Click event can be handled with a lambda
button.Click += (_, _) =>
button.Text = $"Clicked at {System.DateTime.Now}";
base.Initialize();
}

Conclusion
Now that we have a basic project set up with a single Button
. The next tutorial covers the most common forms controls.
Last updated
Was this helpful?