> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/code/getting-started/setup/loading-a-gum-project-.gumx.md).

# 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

{% hint style="info" %}
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.
{% endhint %}

## 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:

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

{% tabs %}
{% tab title="MonoGame/KNI/FNA" %}
Create a folder inside of your game's Content folder, such as `Content/GumProject`, then save the file in the newly-created folder.
{% endtab %}

{% tab title="raylib" %}
Create a folder inside of your game's resources folder, such as `resources/GumProject`, then save the file in the newly-created folder.
{% endtab %}

{% tab title="Silk.NET" %}
Create a folder inside of your game's Content folder, such as `Content/GumProject`, then save the file in the newly-created folder.
{% endtab %}

{% tab title="MonoGame/KNI Web" %}
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.
{% endtab %}

{% tab title=".NET MAUI" %}
Create a folder inside of your project's folder, such as `GumProject`, then save the file in the newly-created folder.
{% endtab %}
{% endtabs %}

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:

1. Open your .csproj in a text editor
2. 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)

{% tabs %}
{% tab title="MonoGame/KNI/FNA Desktop" %}

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

{% hint style="info" %}
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` .
{% endhint %}
{% endtab %}

{% tab title="MonoGame/KNI Android" %}

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

{% endtab %}

{% tab title="raylib" %}

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

{% endtab %}

{% tab title="Silk.NET" %}

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

{% endtab %}

{% tab title="MonoGame/KNI Web" %}
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:

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

{% hint style="warning" %}
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`.
{% endhint %}
{% endtab %}

{% tab title=".NET MAUI" %}
.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.
{% endtab %}
{% endtabs %}

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>

### Sharing a .gumx File

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:

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

## Loading a Gum Project

To load a Gum Project:

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

{% tabs %}
{% tab title="MonoGame/KNI/FNA" %}

```csharp
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`.

{% hint style="info" %}
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)](/gum/code/files-and-fonts/troubleshooting.md#clearing-browser-cache-web).
{% endhint %}

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`:

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

{% endtab %}

{% tab title="raylib" %}

```csharp
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
}
```

{% endtab %}

{% tab title="Silk.NET" %}

```csharp
// 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](/gum/code/getting-started/setup/adding-initializing-gum/silk.net.md) 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.
{% endtab %}

{% tab title=".NET MAUI" %}
.NET MAUI projects do not currently support loading .gumx projects.
{% endtab %}
{% endtabs %}

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/code/gum-code-reference/graphicaluielement.md) (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:

```csharp
// 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");
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flatredball.com/gum/code/getting-started/setup/loading-a-gum-project-.gumx.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.