Loading a Gum Project (.gumx)

Introduction

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.

Creating a Gum Project

Before creating a Gum project, it is recommended that you already have a functional Game project. Next, you'll need to save your Gum project:

Open the Gum tool
Select File->New Project
Navigate to the desired location for your project. See below for recommended locations:

Create a folder inside of your game's Content folder, such as Content/GumProject, then save the file in the newly-created folder.

Create a folder inside of your game's resources folder, such as resources/GumProject, then save the file in the newly-created folder.

Create a folder inside of your game's Content folder, such as Content/GumProject, then save the file in the newly-created folder.

Web targets (KNI BlazorGL and other WebAssembly hosts) must serve the Gum project from wwwroot. Create a folder inside your web project's wwwroot/Content folder, such as wwwroot/Content/GumProject, then save the file in the newly-created folder.

Files placed anywhere else are not published as static web assets and will fail to load at runtime with a 404.

Create a folder inside of your project's folder, such as GumProject, then save the file in the newly-created folder.

It's best to put your Gum project in a folder that is not shared with any other content that it stays organized from the rest of your content files. Remember, Gum creates lots of files.

Adding the Gum Project to your .csproj

To add the Gum files to your csproj:

Open your .csproj in a text editor
Add a line to copy all files in the Gum project folder including the .gumx file itself. For example, your .csproj might look this (see tabs below)

<ItemGroup>
    <None Update="Content\GumProject\**\*.*">
        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
</ItemGroup>

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

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

<ItemGroup>
    <None Update="resources\GumProject\**\*.*">
        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
</ItemGroup>

<ItemGroup>
    <None Update="Content\GumProject\**\*.*">
        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
</ItemGroup>

The Microsoft.NET.Sdk.BlazorWebAssembly SDK automatically publishes everything under wwwroot as static web assets, so a Gum project saved into wwwroot/Content/GumProject requires no additional <ItemGroup> entry to ship.

If you keep your Gum project outside wwwroot and want to include it via a wildcard, you can copy the files into wwwroot at build time:

<ItemGroup>
    <Content Include="..\Shared\GumProject\**\*.*"
             Link="wwwroot\Content\GumProject\%(RecursiveDir)%(Filename)%(Extension)"
             CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

The Gum project files must end up under wwwroot in the published output. Files placed anywhere else are not served by the WebAssembly host and GumService.Default.Initialize will fail to load the .gumx.

.NET MAUI projects do not currently reference Gum projects so the file does not need to be added ot the game project. Currently .NET MAUI projects must use full code generation to reference a Gum project.

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

https://learn.microsoft.com/en-us/visualstudio/msbuild/how-to-select-the-files-to-build?view=vs-2022#specify-inputs-with-wildcards

If your game targets multiple platforms, you may have multiple .csproj files. A single .csproj file can be linked by multiple projects. One way to achieve this is to create a linked wildcard include. For example, Gum files which are relative to a DesktopGL project can be included in an Android project using the following item in a .csproj file:

<ItemGroup>
    <AndroidAsset Include="..\DesktopGL\Content\GumProject\**\*.*" Link="Content\GumProject\%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>

Loading a Gum Project

To load a Gum Project:

Make sure that your Gum project has at least one Screen
Open your file that has your Gum initialization code, such as Game1.cs or Project.cs
Modify the Initialize method by passing it a Gum project file path

GumService GumUI => GumService.Default;

protected override void Initialize()
{
    GumUI.Initialize(
        this, 
        "GumProject/GumProject.gumx");

    // This assumes that your project has at least 1 screen
    if(ObjectFinder.Self.GumProjectSave.Screens.Count == 0)
    {
        throw new Exception(
            "No screen found in the Gum project, " + 
            "did you add a Screen in the Gum tool?");
    }
    var screen = ObjectFinder.Self.GumProjectSave.Screens[0]
        .ToGraphicalUiElement();          
    screen.AddToRoot();
    
    base.Initialize();
}

By default the Gum path is relative to your game's Content folder. On KNI BlazorGL (and other WebAssembly hosts) this resolves under wwwroot/Content, so the same "GumProject/GumProject.gumx" value works on web as long as the project lives at wwwroot/Content/GumProject/GumProject.gumx.

On web, the browser can serve a cached copy of your .gumx project, so changes may not appear after a rebuild. If your content looks stale, see Clearing Browser Cache (Web).

If your Gum project is not part of the the 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:

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

static GumService GumUI => GumService.Default;

public static void Main()
{
    // Additional code needed to initialize your raylib project goes here
    GumUI.Initialize(
        "resources/GumProject/raylibGumProject.gumx");
    
    // This assumes that your project has at least 1 screen
    if(ObjectFinder.Self.GumProjectSave.Screens.Count == 0)
    {
        throw new Exception(
            "No screen found in the Gum project, " + 
            "did you add a Screen in the Gum tool?");
    }    
    var screen = ObjectFinder.Self.GumProjectSave.Screens[0]
        .ToGraphicalUiElement();
    screen.AddToRoot();
    
    // Additional initialization logic goes here
}

// Initialize
GumService.Default.Initialize(canvas, inputContext, "Content/GumProject/GumProject.gumx");

// This assumes that your project has at least 1 screen
if (ObjectFinder.Self.GumProjectSave.Screens.Count == 0)
{
    throw new Exception(
        "No screen found in the Gum project, " +
        "did you add a Screen in the Gum tool?");
}
var screen = ObjectFinder.Self.GumProjectSave.Screens[0]
    .ToGraphicalUiElement();
screen.AddToRoot();

See the Silk.NET setup page for where canvas and inputContext come from — window/GL/Skia surface setup is elided here since it's the same regardless of whether you load a .gumx project.

.NET MAUI projects do not currently support loading .gumx projects.

The code above loads the Gum project using the desired file path, such as "GumProject/GumProject.gumx".

ToGraphicalUiElement

Once a Gum project is loaded, all of its screens and components can be accessed through the ObjectFinder.Self.GumProjectSave property. 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.

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

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

// Initialize
// Load the gum project (see code above)
var screenRuntime = ObjectFinder.Self.GumProject.Screens[0]
    .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");

PreviousWPF NextSetup for GumBatch (Optional)

Last updated 26 days ago

Was this helpful?

Good afternoon

Introduction

Creating a Gum Project

Adding the Gum Project to your .csproj

Sharing a .gumx File

Loading a Gum Project

ToGraphicalUiElement