Migrating to 2025 November

Introduction

This page discusses breaking changes and other considerations when migrating from 2025 October to 2025 November .

Upgrading Gum Tool

To upgrade the Gum tool:

1. Download Gum.zip from the release on Github: https://github.com/vchelaru/Gum/releases/tag/Release_November_30_2025

2. Delete the old tool from your machine

3. Unzip the gum tool to the same location as to not break any file associations

Upgrading Runtime

Upgrade your Gum NuGet packages to version 2025.11.30.1. For more information, see the NuGet packages for your particular platform:

• MonoGame - https://www.nuget.org/packages/Gum.MonoGame/

• KNI - https://www.nuget.org/packages/Gum.KNI/

• FNA - https://www.nuget.org/packages/Gum.FNA/

• raylib - https://www.nuget.org/packages/Gum.raylib

• SkiaSharp - https://www.nuget.org/packages/Gum.SkiaSharp/

For other platforms you need to build Gum from source

See below for breaking changes and updates.

Moved .csproj Files

A number of csproj files have been moved. If your project depends on any of these (if you link to source), you will need to adjust your file references.

Old Location	New Location
<Gum Root>\SkiaGum.Wpf\SkiaGum.Wpf.csproj	<Gum Root>\Runtimes\SkiaGum.Wpf\SkiaGum.Wpf.csproj
<Gum Root>\SvgPlugin\SkiaInGumShared\SkiaInGum.csproj	<Gum Root>\Gum\SvgPlugin\SkiaInGumShared\SkiaInGum.csproj

FlatRedBall Projects which link to source will have a broken reference to SkiaInGum.csproj. Add an extra "Gum\" to the path to resolve the issue.

Warnings on Invalid Variables

Previous versions of Gum would not report errors if a Screen or Component included an invalid variable. The current version of Gum reports these.

These type of errors are primarily reported becase they can have an impact on code generation. Although the code generator handles these types of variables in most cases, they can sometimes cause confusing code generation or compile errors.

Currently these errors must be fixed manually in XML files, but this may change in future versions of Gum.

A typical error indicates which variable is causing the problem, as shown in the following screenshot:

To solve these:

1. Right-click on the Screen or Component with the invalid variable and select View in Explorer.

2. Open the file in a text editor

3. Locate the variable in the XML structure

4. Delete or modify the variable

   1. If the variable is an old variable which is not used, delete the variable

   2. If the variable should be used, modify the type or name according to the error displayed. Often these can be modified by appending the word "State" to the variable name

V3 Visuals

The November 2025 release of Gum introduces an improvement to the default code-only controls. These new V3 visuals add the following improvements over V2:

• Simplified styling - new color properties can be assigned without needing to make changes to states.

• Better consistency with the Gum UI tool - code-only projects look even more similar to projects which use the Gum UI tool

Upgrading to V3

To upgrade a project to V3, make the changes listed below.

First, find the initialize method and change it from V2 to V3:

//GumUI.Initialize(this, DefaultVisualsVersion.V2);
GumUI.Initialize(this, DefaultVisualsVersion.V3);

Replace usage of the default Visuals namespace with V3:

//using Gum.Forms.DefaultVisuals;
using Gum.Forms.DefaultVisuals.V3;

Replace any explicit qualification of Visuals. If you are relying on namespaces this is not necessary, but if you are using explicit visual types, you need to switch to the V3 version. For example, the following code shows how to change a ButtonVisual reference from V2 to V3:

var button = new Button();
//var buttonVisual = (Gum.Forms.DefaultVisuals.ButtonVisual)button.Visual;
var buttonVisual = (Gum.Forms.DefaultVisuals.V3.ButtonVisual)button.Visual;

Optionally, your code can remove state assignments on visual colors since V3 now simplifies setting colors.

For example, the following code can be used to set a button's background:

var button = new Button();
button.AddToRoot();
var buttonVisual = (ButtonVisual)button.Visual;
buttonVisual.BackgroundColor = Color.Red;

For more information on working with the new Visuals, see the Code-Only Styling section;

Adjust the dimensions, positions of controls if desired. Some of the controls have changed size to match the Gum UI tool more closely. Note that a few names have also been changed to match the naming of the visuals in the Gum tool.

The following changes have been made to V3:

Visual Element	Variable	V2	V3
CheckBox	Height	32	24
ListBoxItem	Height	0	6 (RelativeToChildren)
ListBox	Height	150	256
ListBox	Width	150	256
ListBox.FocusedIndicator	Y	-2	2 (fixed overlap bug)
MenuItem	Width	6	0 (still RelativeToChildren)
MenuItem	Height	6	0 (still RelativeToChildren)
MenuItem.TextInstance	X	2	0
MenuItem.TextInstance	Height	2	0 (still RelativeToChildren)
MenuItem .SubmenuIndicatorInstance	Width	2	0
PasswordBox	Height	32	24
RadioButton	Height	32	24
RadioButton	Background	Background	Renamed to RadioBackground
RadioButton	InnerCheck	InnerCheck	Renamed to Radio
TextBox	Width	100	256