LogoLogo
  • Gum Tool
    • Introduction
    • Setup
      • Running from Source
    • Showcase
    • Tutorials and Examples
      • Intro Tutorials
        • 1 - The Basics
        • 2 - Variables Tab
        • 3 - Files
        • 4 - Components
        • 5 - Exposing Variables
        • 6 - Parent
        • 7 - States
        • 8 - State Categories
      • Animation Tutorials
        • 1 - Introduction to Animation
        • 2 - Creating an Animation
        • 3 - Playing Animations inside other Animations
        • 4 - Combining Multiple Categories
      • Examples
        • Bottom-Up Stack
        • Centering
        • Custom NineSlice
        • Health Bar
        • Padding
    • Gum Elements
      • General Properties
        • Alpha
        • Base Type (Inheritance)
        • Blend
        • Clips Children
        • Has Events
        • Height Units
        • Ignored By Parent Size
        • Locked
        • Max Height
        • Max Width
        • Min Height
        • Min Width
        • Order
        • Parent
        • Rotation
        • Visible
        • Variable References
        • Width Units
        • X
        • X Origin
        • X Units
        • Y
        • Y Origin
        • Y Units
      • Behaviors
        • Default Implementation
      • Circle
      • ColoredRectangle
      • Component
        • Default Child Container
      • Container
        • Children Layout
        • Contained Type
        • Is Render Target
        • Stack Spacing
        • Wraps Children
      • NineSlice
        • Blend
        • Custom Frame Texture Coordinate Width
        • Texture Address
        • Texture Left
        • Texture Top
      • Polygon
        • Points
      • Skia Standard Elements
        • General Properties
          • Has Dropshadow
          • Is Filled
          • Use Gradient
        • Arc
          • Start Angle
          • Sweep Angle
          • Thickness
        • Canvas
        • ColoredCircle
        • LottieAnimation
        • RoundedRectangle
          • Corner Radius
        • Svg
      • Sprite
        • Color
        • Source File
        • Texture Address
        • Wrap
      • States
        • Categories
      • Text
        • Blue
        • Color
        • Font
        • Font Scale
        • Font Size
        • Green
        • Is Bold
        • Is Italic
        • MaxLettersToShow
        • Outline Thickness
        • Red
        • Text
        • Text Overflow Horizontal Mode
        • Text Overflow Vertical Mode
        • Use Custom Font
        • Use Font Smoothing
    • Project Tab
    • Code Tab
      • Runtime Generation Details
      • Generation Scope
      • Inheritance Location
      • Is CodeGen Plugin Enabled
      • Show CodeGen Preview
    • Localization
    • Menu
      • Content
      • Project Properties
    • Plugins
      • AddAndRemoveVariablesForType
      • AddMenuItem
      • Export
      • Setting Up Post Build Events
    • Variables
      • Add Variable
    • Bitmap font generator (.fnt)
    • Upgrading
      • Migrating 2025 April 27 to Preview
      • Breaking Changes
        • Removal of Variable Spaces
  • Code
    • Gum Code Reference
      • AnimationRuntime
      • BitmapCharacterInfo
      • BitmapFont
      • Camera
      • CircleRuntime
      • ColoredRectangleRuntime
      • Component Runtimes
      • ContainerRuntime
      • Cursor
      • Gum Class Overview
      • DataUiGrid
        • Reflection
        • Categories
      • ElementSave
        • ToGraphicalUiElement
      • GraphicalUiElement
        • Absolute Values
        • AddToManagers
        • AnimateSelf
        • ApplyState
        • BlendState
        • CanvasHeight
        • CanvasWidth
        • Children
        • ContainedElements
        • Font Values
        • GetAbsoluteHeight
        • GetAbsoluteWidth
        • GetChildByNameRecursively
        • GetFrameworkElementByName
        • IsAllLayoutSuspended
        • Parent
        • RemoveFromManagers
        • UpdateLayout
      • GumProjectSave
      • IDataUi
      • InstanceMember
      • InstanceSave
      • InteractiveGue
        • CurrentInputReceiver
        • RaiseChildrenEventsOutsideOfBounds
        • RollOverBubbling
      • IPositionedSizedObject
      • Layer
      • NineSliceRuntime
      • RectangleRuntime
      • Renderer
        • SinglePixelTexture
      • SelectedState
      • SpriteRenderer
        • LastFrameDrawStates
      • SpriteRuntime
        • TextureAddress
        • TextureHeight
        • TextureLeft
        • TextureTop
        • TextureWidth
      • TextRuntime
        • Color
        • FontScale
        • FontSize
        • HorizontalAlignment
        • Text Wrapping
        • VerticalAlignment
      • VariableSave
    • FNA
    • Kni
    • Meadow
    • MonoGame
      • Setup
        • Linking Game Project to Source (Optional)
      • Tutorials
        • Gum Project Forms Tutorial
          • Setup
          • Gum Screens
          • Common Component Types
          • Styling
          • Multiple Screens
        • Code-Only Gum Forms Tutorial
          • Setup
          • Forms Controls
          • ListBox Items
          • Input in Forms
        • [Deprecated] Gum Project (.gumx) Tutorial
          • Setup
          • Gum Screens
          • Gum Forms
          • Customizing Forms
          • Strongly Typed Components Using Code Generation
          • Multiple Screens
      • Setup for GumBatch (Optional)
      • Loading a Gum Project (Optional)
      • async Programming
      • Custom Runtimes
      • GumBatch
      • Gum Forms
        • Binding (ViewModels)
        • Controls
          • Button
          • CheckBox
          • FrameworkElement
            • BindingContext
            • IsEnabled
            • IsFocused
            • ModalRoot and PopupRoot
            • SetBinding
          • ListBox
          • ListBoxItem
          • MenuItem
          • PasswordBox
          • RadioButton
          • ScrollViewer
            • VerticalScrollBarValue
          • StackPanel
          • Slider
          • TextBox
        • Control Customization In Code
          • MenuItem
        • Control Customization in Gum Tool
        • Gamepad Support
        • Keyboard Support
        • Troubleshooting
      • File Loading
      • Resizing the Game Window
      • Known Issues
      • Samples
        • MonoGameGumFormsSample
    • Nez
    • Silk.NET
    • SkiaGum
      • Setup
        • WPF
    • .NET MAUI
      • Setup
Powered by GitBook
On this page
  • Creating a Gum Project
  • Adding the Gum Project Files to Your .csproj
  • Loading a Gum Project
  • ToGraphicalUiElement
  • Troubleshooting Gum Project Loading

Was this helpful?

Edit on GitHub
Export as PDF
  1. Code
  2. MonoGame

Loading a Gum Project (Optional)

PreviousSetup for GumBatch (Optional)Nextasync Programming

Last updated 1 month ago

Was this helpful?

Gum projects can be loaded in a game project. Gum projects are made up of multiple files including:

  • .gumx - the main Gum project

  • .gusx - Gum screen files

  • .gucx - Gum component files

  • .gutx - Gum standard element files

  • .png - image files

  • .fnt - font files

You are not required to use the Gum tool or .gumx projects - you are free to do everything in code if you prefer. Of course using the Gum tool can make it much easier to iterate quickly and experiment so its use is recommended.

Creating a Gum Project

Before creating a Gum project, it is recommended that you already have a functional MonoGame. It's best to put your Gum project in a subfolder of the game's Content folder so that it stays organized from the rest of your content files. Remember, Gum creates lots of files.

To create a Gum project:

  1. Open the Gum tool

  2. Select File->New Project

  3. Navigate to the Content's subfolder (such as GumProject/) to select a location for the project

Adding the Gum Project Files to Your .csproj

To add the files to your .csproj:

  1. Open your .csproj file in a text editor

  2. Verify that all gum files (see the extension list above) are marked as Copy if newer in Visual Studio\

For more information about wildcard support in .csproj files, see this page on how to include wildcards in your .csproj:

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 a Gum Project

To load a Gum Project:

  1. Open Game1.cs

  2. Modify the Initialize method it calls Initialize with the name of your .gumx file:

protected override void Initialize()
{
    var gumProject = Gum.Initialize(
        this, 
        "GumProject/GumProject.gumx");

    // This assumes that your project has at least 1 screen
    var screenRuntime = gumProject.Screens.First().ToGraphicalUiElement();
    screenRuntime.AddToRoot();
    
    base.Initialize();
}

The code above loads the Gum project using the file path "GumProject/GumProject.gumx". By default this path is relative to your game's Content folder. If your Gum project is not part of the Content folder you can still load it by using the "../" prefix to step out of the Content folder. For example, the following code would load a Gum project located at <exe location>/GumProject/GumProject.gumx:

Gum.Initialize(
    this, "../GumProject/GumProject.gumx");

ToGraphicalUiElement

Once a Gum project is loaded, all of its screens and components can be accessed through the object returned from the Initialize method. The code above stores the project in a variable called gumProject. Any screen or component can be converted to a GraphicalUiElement, which is the visual object that displays in game.

The code in the previous section creates a GraphicalUiElement from the first screen in the project.

You can get a reference to elements within the screen by calling GetGraphicalUiElementByName, as shown in the following code:

// Load the gum project (see code above)
var screenRuntime = gumProject.Screens.First().ToGraphicalUiElement();
screenRuntime.AddToRoot();

// Items in the screen can be accessed using the GetGraphicalUiElementByName method:
var child = screenRuntime .GetGraphicalUiElementByName("TitleInstance");

// All GraphicalUiElements have common properties, like X:
child.X += 30;

// you can also set properties which may not be common to all GraphicalUiElements,
// like Text:
child.SetProperty("Text", "Hello world");

A full Game1 class which loads a project might look like this:

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

    protected override void Initialize()
    {
        var gumProject = Gum.Initialize(
            this, "GumProject/GumProject.gumx");
        // This assumes that your project has at least 1 screen
        var screenRuntime = gumProject.Screens.First().ToGraphicalUiElement();
        screenRuntime.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);
    }
}

Troubleshooting Gum Project Loading

If your Gum project load results in an exception, you can inspect the exception message for information about the failure. The most common type of failure is a missing file reference.

If you are missing files, you may have not set up the file to copy to the output folder. The following screenshot shows an incorrect setup - the CardInstance.gucx file is not copied, but it probably should be:

This can be changed to copy in Visual Studio, or the .csproj can be modified to include wildcards for copying files over, which can make maintenance easier as the project grows. See the section above for information and examples on setting up your project loading.

If you haven't already downloaded it, you should down the Gum tool. See the for information on downloading Gum.

Add a line to copy all files in the Gum project folder including the .gumx file itself. For an example, see the .csproj file for the MonoGameGumFromFile project: Your .csproj may look like this:

If you are using the Contentless project () , you need to explicitly exclude Gum and all of its files by adding and modifying Content/Contentless.json .

For an example of a Game1.cs file which loads a project file, see the MonoGameGumFromFile:

Note that calling ToGraphicalUiElement creates a (Gum object) from the first screen. You can access any screen in the gumProject.Screens if your project has mutliple Screens.

https://github.com/vchelaru/Gum/blob/0e266942560e585359f019ac090a6c1010621c0b/Samples/MonoGameGumFromFile/MonoGameGumFromFile/MonoGameGumFromFile.csproj#L37
https://learn.microsoft.com/en-us/visualstudio/msbuild/how-to-select-the-files-to-build?view=vs-2022#specify-inputs-with-wildcards
https://github.com/Ellpeck/Contentless
https://github.com/vchelaru/Gum/blob/0e266942560e585359f019ac090a6c1010621c0b/Samples/MonoGameGumFromFile/MonoGameGumFromFile/Game1.cs#L76-L82
GraphicalUiElement
Introduction page
GumProject folder in the game's Content folder
Example of wildcard pattern in .csproj
Gum project set to Copy if newer
Incorrect setting on .gucx