File Loading

Introduction

A typical Gum project references many file types. Aside from the XML files created by the Gum tool (such as a .gumx file), a Gum project also references .png files and .fnt files.

Files referenced by your Gum project (as created in the Gum UI tool) automatically load their necessary dependencies assuming the files are part of the built file system. Usually your project game project should copy all Gum XML, PNG, and FNT files to the output folder. Gum does not use the MonoGame content pipeline.

Files in Gum Projects

When a file is added to a Gum project, the Gum UI tool checks the location of the file. If the file is not relative to the Gum project file (.gumx), the Gum UI tool warns you about the file being located outside of the project's folder. The tool recommends that the file should be copied so that your project remains portable.

If all of your project files are located relative to the .gumx root project file, then your project should be portable, and all referenced files will be automatically resolved for you when instantiating Screens and Components from your Gum project.

The Gum runtime library performs all of its loading from-file, so all of your files must be present in the destination directory. As explained in the Loading .gumx page, all of your files should be set to Copy if newer in Visual Studio.

bear.png file set to Copy if newer

Loading Files Through Runtime Objects

Gum runtime objects can reference files. For example both SpriteRuntime and NineSliceRuntime can reference a Texture2D. Similarly, the TextRuntime type can reference BitmapFonts which are loaded from .fnt and .png files.

All runtime types support the assignment of these files by direct assignment of their appropriate type, or by string name.

For example, a Sprite's texture could be assigned either through the SourceFileName property or the Texture property:

// Initialize
SpriteRuntimeInstance.SourceFile = "bear.png";
// or
SpriteRuntimeInstance.Texture = MyTexture;

In the case of the SourceFile assignment, the SpriteRuntime loads the Texture2D from disk. By default the file is loaded relative to the Content folder.

Setting FileManager.RelativeDirectory

Whenever a file is assigned on a runtime object, Gum looks for the file in the ToolsUtilities.FileManager.RelativeDirectory directory. This directory defaults to your game's Content folder.

If you call GumService.Default.Initialize and pass a .gumx file, then RelativeDirectory is set to the directory containing the Gum project.

If your Gum project (.gumx) is located in the Content folder, RelativeDirectory is set to "Content/".

GumProject.gumx located in the Content folder

If your project is located in a subfolder of Content, then RelativeDirectory is set to the folder containing the Gum project. In this case, RelativeDirectory would be set to "Content/gum/"

Gum project in a subfolder

RelativeDirectory is used whenever files are loaded. These operations include:

• Calling ToGraphicalUiElement
• Assigning SourceFileName
• Setting custom or cached fonts on a Text object
• Setting states (which may assign variables)

It's recommended practice to set the RelativeDirectory to your Gum project's location and to leave it there so you never have to consider subfolders in any code that accesses files directly or indirectly.

Loading from a .gumpkg Bundle

In addition to loose files, Gum can load a project from a single-file .gumpkg bundle produced by gumcli pack. When GumService.Initialize is called with a .gumx path:

• If the loose .gumx exists, Gum loads from loose files (the dev-time path; hot reload also works in this mode).
• If only a sibling .gumpkg exists, Gum reads element XML, textures, and fonts from inside the bundle via FileManager.CustomGetStreamFromFile. No loose copy is needed in the output directory.

This means a published build can ship a single .gumpkg next to the executable instead of a folder tree of .gusx/.gucx/.png/.fnt files. See the pack page for the producer side and the runtime contract.

File Caching

By default Gum caches loaded textures. In other words, the following code only results in a single file IO operation:

// Initialize
Sprite1.SourceFile = "MyFile.png";
Sprite2.SourceFile = "MyFile.png";

File caching can be disabled by setting the LoaderManager's CacheTextures property to false as shown in the following code:

// Initialize
LoaderManager.Self.CacheTextures = false;

Of course, doing so means that Gum will go to disk for every file which can increase load times and result in significantly more video memory usage.

Note that setting CacheTextures to false flushes the cache and disposes all cached content, so you can force the reload of all files by calling setting CacheTextures to false, then back to true as shown in the following code:

// Initialize
Sprite1.SourceFile = "MyFile.png"; // This loads the file from disk
Sprite2.SourceFile = "MyFile.png"; // This uses the cached Texture2D

LoaderManager.Self.CacheTextures = false; // This clears the cache:
LoaderManager.Self.CacheTextures = true;
Sprite1.SourceFile = "MyFile.png"; // This once-again goes to disk to load the file
Sprite2.SourceFile = "MyFile.png"; // This uses the cached Texture2D

LoaderManager.Self.CacheTextures = false; // This clears the cache
Sprite1.SourceFile = "MyFile.png"; // This once-again goes to disk to load the file
Sprite2.SourceFile = "MyFile.png"; // This also goes to disk to load the file

Be careful setting CacheTextures to false since all existing textures will be disposed. This means that if you have loaded textures which are still being referenced by runtime objects, you will get an exception if those are still being drawn after setting CacheTextures to false.

Customizing How Content Loads

By default Gum resolves a SourceFile name to a texture by reading a file from disk (relative to FileManager.RelativeDirectory). You can replace this behavior with your own logic — for example, to load assets from a custom store, or to hand back a texture your game engine has already loaded so the same image isn't loaded into memory twice.

Gum performs all of its loading through an IContentLoader, which has two methods:

// Class scope
public interface IContentLoader
{
    T LoadContent<T>(string contentName);
    T TryLoadContent<T>(string contentName);
}

The active loader is held by LoaderManager.Self.ContentLoader. Each runtime (MonoGame, Raylib, and so on) installs a default loader during initialization. To customize loading, assign your own implementation to that property. This is the same property and the same IContentLoader interface on every backend, so the approach is identical across MonoGame, KNI, FNA, and Raylib.

Wrapping the Built-in Loader

The cleanest approach is to wrap the built-in loader: intercept only the content names you care about, and forward everything else to the default loader. This keeps Gum's normal file loading — and its texture caching — working for all the assets you don't handle yourself.

// Class scope
public class CustomContentLoader : RenderingLibrary.Content.IContentLoader
{
    RenderingLibrary.Content.IContentLoader _defaultLoader;

    public CustomContentLoader(RenderingLibrary.Content.IContentLoader defaultLoader)
    {
        _defaultLoader = defaultLoader;
    }

    public T LoadContent<T>(string contentName)
    {
        // typeof(T) is the standard way to branch in an IContentLoader.
        if (typeof(T) == typeof(Texture2D) &&
            MyAssetSource.TryGetTexture(contentName, out Texture2D texture))
        {
            return (T)(object)texture;
        }

        // Forward everything else so default loading and caching still apply.
        return _defaultLoader.LoadContent<T>(contentName);
    }

    public T TryLoadContent<T>(string contentName)
    {
        if (typeof(T) == typeof(Texture2D) &&
            MyAssetSource.TryGetTexture(contentName, out Texture2D texture))
        {
            return (T)(object)texture;
        }

        return _defaultLoader.TryLoadContent<T>(contentName);
    }
}

Install it after Gum has initialized (so the default loader exists to wrap) but before any content loads:

// Initialize
var loaderManager = RenderingLibrary.Content.LoaderManager.Self;
loaderManager.ContentLoader = new CustomContentLoader(loaderManager.ContentLoader);

Texture caching lives inside the content loader, not above it. A custom IContentLoader that does not delegate to the built-in loader will bypass Gum's cache (LoaderManager.CacheTextures) entirely — every load goes straight to your code. Wrapping the built-in loader, as shown above, preserves caching for the names you forward. If your custom source already manages its own assets, that's usually fine — you simply don't need Gum's cache for those.

Loading Through the MonoGame Content Pipeline

On the XNA-family backends (MonoGame/KNI/FNA), the built-in ContentLoader also exposes an XnaContentManager property. When set, files referenced without an extension are loaded as content-pipeline (.xnb) assets through that ContentManager. This is an XNA-only convenience; there is no equivalent on Raylib, which has no content pipeline.