Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Upgrading File (GUMJ/GUMX) Version

Introduction

Gum project files include a Version tag which is used by the Gum tool and Gum runtimes to determine how to handle the file.

Unless otherwise stated below, these version upgrades are optional - you can continue to use old versions.

Upgrading Versions

To upgrade to a new version:

  1. If open, close the Gum tool.

  2. Open your Gum project file (.gumx) in a text editor

  3. Search for the <Version> XML tag. For example your file may have

    <Version>1</Version>
  4. Change the version number to the desired version.

  5. Save the .gumx file

  6. Open the Gum tool

Gum should detect the new version and if any changes are necessary to your project, Gum will perform them.

If the change modifies how the file is saved, you may need to use the File -> Save All command to forcefully save all files to disk.

Version 1

The initial file version, which was used until February 2026.

Version 2

Required Gum Tool Version: February 2026

This version uses XML Attributes to greatly reduce the size of XML files and to make manual editing and diffing of files easier.

✅No manual changes are needed to your project beyond changing the version number.

❗Be sure that your entire team is using the new version of the Gum (February 2026 or later) before making any upgrades, and once the upgrade has been made, make sure that no one on your team is still making Gum changes on V1. This can cause a "hybrid" file which is partially V2 and partially V1, which can break a project.

After changing the version number:

  1. Open the Gum project in the Gum tool

  2. Select File->Save All to save all files to disk using the new attribute format.

You should notice significant reduction in file size and number of lines. The following files will be affected by this change:

  • Screen files

  • Component files

  • StandardElementSave files

  • Main Gum project file

Before:

After:

Note that the file savings vary by project type and by content type.

The savings are both in file size, but also in line number which makes comparing files in diffs much easier than before. Here are some typical savings in line count. These were taken from the Cranky Chibi Cthulhu game (https://store.steampowered.com/app/2631990/Cranky_Chibi_Cthulhu/)

  • GumProject .gumx file: 620 -> 180 lines

  • PauseMenu Component: 513 -> 248 lines

  • GameScreenGum Screen: 798 -> 381 lines

  • SplashScreenGum Screen: 63 -> 37 lines

  • PlayerHud Component: 2646 -> 1309 lines

  • Circle Standard Element File: 165 -> 72 lines

Version 3

Required Gum Tool Version: 2026 May (or later)

This version unlocks the expanded Circle and Rectangle shape variables — fill, gradient, drop shadow, stroke-and-fill, and antialiasing — along with the Circle Radius -> Width/Height change. The tool only shows these new variable categories for projects at version 3 or later, so a project still at version 2 keeps the new shape variables hidden even on a tool build that supports them.

✅No manual changes are needed to your project beyond changing the version number.

Unlike Version 2, which is a real XML-format change requiring a File -> Save All to rewrite every file, Version 3 uses the same XML format as Version 2. The version bump exists only to unlock the new variable surface and to make older tool builds refuse the file rather than silently dropping the new variables on the next save. There is no format conversion or Save All step — you only change the <Version> number.

❗Be sure that your entire team is using the new version of Gum (2026 May or later) before making this upgrade. As with Version 2, mixing tool versions across a team can produce a "hybrid" file which can break a project.

New projects created with the 2026 May tool (or later) are stamped Version 3 automatically. Only projects created before this release need the manual bump.

Version 4

Required Gum Tool Version: 2026 July (or later)

This version unlocks the Localize Text variable on the Text standard element, which controls whether that instance's text is translated when a localization database is loaded. The tool only shows and back-fills this variable for projects at version 4 or later, so a project still at version 3 keeps it hidden even on a tool build that supports it.

✅No manual changes are needed to your project beyond changing the version number.

Version 4 uses the same XML format as Version 3. The version bump exists only to unlock the new variable and to make older tool builds refuse the file rather than silently dropping it on the next save. There is no format conversion or Save All step, you only change the <Version> number.

❗Be sure that your entire team is using the new version of Gum (2026 July or later) before making this upgrade. As with previous versions, mixing tool versions across a team can produce a "hybrid" file which can break a project.

New projects created with the 2026 July tool (or later) are stamped Version 4 automatically. Only projects created before this release need the manual bump.

Version 5

Required Gum Tool Version: 2026 October (or later)

This version unlocks the Color Operation variable on the Sprite and NineSlice standard elements (Modulate, Color Texture Alpha, Add). The tool only shows and back-fills this variable for projects at version 5 or later, so a project still at version 4 keeps it hidden even on a tool build that supports it.

✅No manual changes are needed to your project beyond changing the version number.

Version 5 uses the same XML format as Version 4. There is no format conversion or Save All step, you only change the <Version> number.

❗Be sure that your entire team is using the new version of Gum (2026 October or later) before making this upgrade.

New projects created with the 2026 October tool (or later) are stamped Version 5 automatically.

Version 6

Required Gum Tool Version: 2026 November (or later)

This version changes the name of the generated font files for fonts loaded from a font file, such as Fonts/Icons.ttf. At Version 5 and below, the name only used the file's name, so Fonts/Icons.ttf and Other/Icons.ttf shared one .fnt and only one of them was ever generated. At Version 6, the name also includes a short code made from the file's path, for example FontCache/Font18Icons_ttf_3fa91c2b.fnt, so each file gets its own. Fonts that are installed on the system, such as Arial, keep their names.

⚠️Changing the version number is not enough if your game ships generated font files. After the upgrade, Gum looks for the new names and no longer finds the old ones, so text using a font file falls back to the default font until the new files exist. Open the project in the Gum tool so it generates the new files, copy them into your game's FontCache folder, and delete the old font file entries. A project that only uses system fonts, or that generates its fonts at runtime, needs nothing else.

Version 6 uses the same XML format as Version 5. There is no format conversion or Save All step, you only change the <Version> number.

❗Be sure that your entire team is using the new version of Gum (2026 November or later) before making this upgrade.

New projects created with the 2026 November tool (or later) are stamped Version 6 automatically.

Version 7

Required Gum Tool Version: 2026 November (or later)

This version unlocks the Shader Parameters variable on a render target Container. When the container has a Source Shader File, the Variables tab lists the parameters the shader declares, and the tool saves your edits in this variable. The tool only shows and back-fills it for projects at version 7 or later.

✅No manual changes are needed to your project beyond changing the version number.

Version 7 uses the same XML format as Version 6. There is no format conversion or Save All step, you only change the <Version> number.

❗Be sure that your entire team is using the new version of Gum (2026 November or later) before making this upgrade.

New projects created with the 2026 November tool (or later) are stamped Version 7 automatically.

Version 8

Required Gum Tool Version: 2026 December (or later)

This version unlocks the Raise Children Events Outside Of Bounds variable in the Behavior category of the standard elements that have children events. When it is true, children placed outside the object's bounds, such as the resize borders of a Window, still receive the cursor. The tool only back-fills it into the standard elements of projects at version 8 or later.

✅No manual changes are needed to your project beyond changing the version number.

Version 8 uses the same XML format as Version 7. There is no format conversion or Save All step, you only change the <Version> number.

❗Be sure that your entire team is using the new version of Gum (2026 December or later) before making this upgrade.

Available in December 2026, or now if building Gum from source. New projects created with the 2026 December tool (or later) are stamped Version 8 automatically.

Last updated

Was this helpful?