gum-integration

name	gum-integration
description	Gum Integration in FlatRedBall2. Use when working with UI, HUD, menus, buttons, labels, text display, StackPanel, Panel, layout, Gum Forms controls, Add, AddOverlay, screen-space vs world-space UI, blurry or low-res text, FontSize, text opacity/alpha, or any Gum-related question. Also trigger when user asks about displaying text on screen.

Gum Integration in FlatRedBall2

See content-boundary skill first. UI composition is a human task — AI should scaffold named controls in a flat list and let the human compose the layout in the Gum Tool. Do not try to hand-author a polished visual hierarchy in code.

Gum is FlatRedBall2's UI system, backed by the Gum.MonoGame NuGet package. It is automatically initialized by FlatRedBallService.Initialize — no setup required. Gum also bundles Gum.Shapes (dashed strokes, gradients, drop shadows) and can render in world space, not only screen-space UI — so it's the home for advanced shape visuals that FRB's AARect/Circle/Polygon don't provide (see shapes).

Three Gum Usage Modes

Choose the mode that matches the project setup (see gumcli skill for how to create the project):

Mode	Description	When to use
Code-only	No .gumx file. All controls created in C# with new Button() etc.	Prototypes, no Gum editor needed
Project + dynamic access	.gumx loaded; retrieve named elements at runtime via GetFrameworkElementByName<T>()	Editor integration, no codegen
Project + codegen	.gumx loaded + gumcli generates strongly-typed C# classes; instantiate and use typed properties directly	Best DX; recommended for new projects

Two Levels of Gum API

Forms Controls — interactive UI (Gum.Forms.Controls)

High-level controls with built-in click, hover, focus, and Tab/accessibility keyboard navigation:

Control	Use for
Button	Clickable buttons
Label	Display-only text
TextBox	Text input
CheckBox	Toggle on/off
StackPanel	Vertical/horizontal layout container
Panel	Free-layout container

Use Forms controls for menus, buttons, and any interactive element. Label is also the right choice for simple score/status text.

Visual Types — non-interactive rendering (MonoGameGum.GueDeriving)

Raw visual objects with no built-in input handling. Use these for non-interactive HUD elements — health bars, icons, solid-color shapes — when no Forms control fits:

Type	Use for
TextRuntime	Text with custom FontSize/FontScale not exposed by Label
ColoredRectangleRuntime	Solid-color rectangle (health bars, UI frames, heart indicators)
SpriteRuntime	Textured image
ColoredCircleRuntime	Anti-aliased filled circle (Gum.Shapes package)
RoundedRectangleRuntime	Anti-aliased rounded rectangle, optional gradient (Gum.Shapes package)
ArcRuntime	Anti-aliased arc/ring segment (Gum.Shapes package)

using MonoGameGum.GueDeriving;

// Health bar fill
var fill = new ColoredRectangleRuntime { Width = 100, Height = 12, Color = Color.Red };
fill.Anchor(Anchor.TopLeft);
fill.X = 20; fill.Y = 20;
Add(fill);

// Shrink it as health decreases:
fill.Width = _health / _maxHealth * 100f;

Rule: use Forms controls for interactive elements. Use visual types directly for non-interactive HUD (health indicators, icons, status bars).

Quick Start

// Always import BOTH — Forms controls and Wireframe (Anchor/Dock) live in different namespaces:
using Gum.Forms.Controls;  // Label, Panel, StackPanel, Button, etc.
using Gum.Wireframe;        // Anchor, Dock

// In Screen.CustomInitialize():
var button = new Button();
button.Text = "Click Me";
button.Click += (_, _) => Debug.WriteLine("clicked");

Add(button);   // pass FrameworkElement directly

Add / Remove (Gum elements)

Add registers the element for rendering and per-frame input updates (cursor, clicks, hover, keyboard). All Forms controls work out of the box — no additional input wiring needed.

Always use Add instead of adding directly to RenderList:

Add(button);          // FrameworkElement
Add(textRuntime);     // GraphicalUiElement (low-level visual)
Remove(button);
Remove(textRuntime);

Do not call button.AddToRoot() — this bypasses the FRB2 render-order system.

Displaying Text (HUD, Score, Labels)

Option A — Label (preferred):

var scoreLabel = new Label();
scoreLabel.Text = "0";
scoreLabel.Anchor(Anchor.TopRight);
scoreLabel.X = -20;
scoreLabel.Y = 20;
Add(scoreLabel);

// Update at runtime:
scoreLabel.Text = _score.ToString();

Option B — TextRuntime (low-level): Use only when you need FontSize, FontScale, etc. not exposed by Label.

using MonoGameGum.GueDeriving;   // TextRuntime lives here, NOT Gum.Wireframe

var scoreText = new TextRuntime { Text = "0", FontSize = 48 };
Add(scoreText);

For Label, text styling still lives on the underlying TextRuntime. Changing Label.Text updates content only; change the visual for FontSize/Color/opacity:

using MonoGameGum.GueDeriving;

if (scoreLabel.Visual is TextRuntime text)
{
    text.FontSize = 28;
    text.Color = Color.White;
    text.Alpha = 180; // 0..255 opacity
}

With Gum codegen, many text instances are already typed as TextRuntime properties (for example mainMenu.TitleText), so set FontSize/Color/Alpha directly there.

The is TextRuntime cast only holds for the default visual. A .gumx-authored custom Label component makes Visual something else, so the cast silently no-ops. Use scoreLabel.Visual.GetGraphicalUiElementByName("TextInstance") instead — Gum's own Label looks up its text part by that same name, so any custom Label component already needs an instance called TextInstance for Label.Text to work.

See also: Gum's controls and styling individual controls docs for state-safe styling — a highlight/push/focus state change can revert a color set this way.

Render Ordering (Layers / Z)

Unlayered renderables draw behind layered ones. Gum elements added without a layer will be hidden behind any layered game objects. Always assign Gum UI to an explicit layer.

Within the same layer, items sort by Z. Within the same layer and Z, insertion order is preserved (stable sort).

UI Layers

Most games need one or more UI layers. Create them in CustomInitialize and add them to Layers in back-to-front order. Gum elements on a layer draw on top of all unlayered world objects and on top of lower-indexed layers.

Three common UI layers (create only what the game needs):

Layer	Purpose	Examples
InGameUI	Transient visuals attached to world position or floating near entities	Floating damage/heal numbers, "+100" score popups, level-up announcements, entity health bars
HUD	Persistent screen-anchored status display	Score, health bar, fuel gauge, minimap, timer
TopUI	Modal overlays that block gameplay	Pause menu, "Exit game?" confirmation, options screen, critical messages

For pause menus (TopUI), also call PauseThisScreen() / UnpauseThisScreen() to actually freeze entity activity — adding the overlay alone does not pause the game. See the screens skill.

// In CustomInitialize — order matters: later = drawn on top
var hudLayer = new Layer("HUD");
Layers.Add(hudLayer);

// Add Gum elements with the layer: parameter
var scoreLabel = new Label();
scoreLabel.Text = "Score: 0";
scoreLabel.Anchor(Anchor.TopLeft);
scoreLabel.X = 10; scoreLabel.Y = 10;
Add(scoreLabel, layer: hudLayer);

When to create which layers:

• HUD only — most games (score, health, fuel, timer)
• HUD + TopUI — games with a pause menu or confirmation dialogs
• InGameUI + HUD — games with floating combat text, score popups near enemies, or entity health bars
• All three — RPGs, complex action games with both world-space feedback and modal menus

Screen-Space vs World-Space

Screen-space (default): screen.Add(element) places elements in Gum's native coordinate system (pixels, Y-down, origin top-left). Use for HUDs, menus.

World-space: entity.Add(element) places a Gum element at the entity's world position. It follows the entity and shifts when the camera pans. The visual is automatically removed when the entity is destroyed. entity.IsVisible = false hides it — don't reach into element.Visible.

Overlay vs Camera UI: Rendering Quality

Add() parents UI under the camera's UiRoot, whose canvas matches the design resolution. Gum generates font bitmaps at FontSize design pixels; the render batch upscales them by Camera.PixelsPerUnit. At 2× (e.g. 480→960 window), a 22px font bitmap renders at 44px — each source pixel becomes a 2×2 block on screen, visibly lowering quality.

FlatRedBallService.Initialize turns on TextRuntime.UseFontOversampling, which rebuilds the font at the upscaled size instead of stretching it — this fixes the blur here too, as long as Font points at a real .ttf rather than a system font name (see the .ttf note near the end of this skill).

AddOverlay() parents UI under Screen.OverlayRoot, sized to the back-buffer and rendered 1:1. FontSize=22 generates a 22px bitmap rendered at 22px — sharp at any PixelsPerUnit. AddOverlay() renders 1:1 regardless and needs no font rebuild — still the simplest option when a system font name is unavoidable.

Add()'s PixelsPerUnit also bakes in Camera.Zoom — so HUD zooms whenever you animate Zoom for a cinematic effect. AddOverlay() is immune to this too, but it's screen-wide and can't be confined to one camera's viewport in split-screen. For a per-camera, zoom-immune HUD (e.g. one player's minimap border that shouldn't zoom with their camera), pass a Layer { IsScreenSpace = true } to Add() instead — it parents to Camera.ScreenSpaceRoot, which tracks the window-vs-design-resolution scale but not Zoom.

Coordinate values for overlay elements are in back-buffer pixels (design coords × PixelsPerUnit). For hit-testing overlay UI from world-space cursor input:

float s  = Camera.PixelsPerUnit;
float cx = (worldPos.X - Camera.Left) * s;
float cy = (Camera.Top - worldPos.Y)  * s;

Loading Gum Screens from a .gumx Project File

When a .gumx project is loaded (via EngineInitSettings.GumProjectFile), you can instantiate a Gum screen defined in the project and add it to the FRB2 screen (e.g., as a background visual):

using Gum.Forms;     // GetFrameworkElementByName extension method
using Gum.Managers;  // ObjectFinder
using Gum;           // ToGraphicalUiElement — easy to miss, different namespace from Gum.DataTypes

var gumScreenSave = ObjectFinder.Self.GumProjectSave.Screens
    .Find(s => s.Name == "MainMenuScreen");
Add(gumScreenSave!.ToGraphicalUiElement());

• using Gum; is required even though ScreenSave lives in Gum.DataTypes — the extension method is in Gum. The MonoGameGum forwarder for this call is [Obsolete]; it still compiles but warns.
• This only works for a project Gum itself loaded (via GumProjectFile). Assigning ObjectFinder.Self.GumProjectSave from your own GumProjectSave.Load(...) leaves the runtime half-configured — ToGraphicalUiElement() then builds children and throws NotImplementedException deep in UnitConverter.ConvertToGeneralUnit, which reads like bad data rather than bad setup.
• GumProjectFile path must NOT include Content/ — Gum's FileManager is already rooted at the MonoGame Content/ directory. Use "GumProject/GumProject.gumx", not "Content/GumProject/GumProject.gumx". The double-Content causes a runtime load failure.

If the project was created with gumcli

gumcli new scaffolds the project with all standard Forms controls already included as component and standard files (Button, TextBox, CheckBox, ListBox, etc.). These are immediately available — no additional setup required.

Prefer defining Forms control instances in Gum XML files (screen .gusx or component .gucx) rather than creating them purely in C# code. XML-defined instances are visible in the Gum editor so designers can adjust layout and visuals without touching code. Only instantiate controls in C# when they are fully dynamic (e.g., a variable-length list driven by runtime data).

Mode 2 — Dynamic access via Get calls

When the Gum screen XML is loaded with ToGraphicalUiElement(), any Forms control instances declared in it are constructed and wired automatically — just hook up events in C#:

// using Gum.Forms;            // GetFrameworkElementByName extension method
// using Gum.Forms.Controls;   // Button, Label, etc.
// using MonoGameGum;          // ToGraphicalUiElement

var root = gumScreenSave!.ToGraphicalUiElement();
Add(root);

// Retrieve a named instance and hook up events:
var startButton = root.GetFrameworkElementByName<Button>("StartButton");
startButton.Click += (_, _) => MoveToScreen<GameScreen>();

• GetFrameworkElementByName<T> is an extension method in Gum.Forms — add using Gum.Forms;.
• Button and other Forms types are in Gum.Forms.Controls — do not use MonoGameGum.Forms.Controls; those wrappers are [Obsolete(error: true)].
• Forms controls (new Button(), etc.) created in C# still use built-in default visuals unless the project includes matching component files. Mix freely.

Mode 3 — Codegen (strongly-typed)

After running gumcli codegen, each Gum screen and component gets a generated C# class with the same name as the Gum XML element (use the Gum suffix on element names — see the gumcli skill — to avoid colliding with FRB2 Screen subclasses). Instantiate the class directly — no ToGraphicalUiElement() or string-based lookup needed:

// Gum element "MainMenuScreenGum" → generated class MainMenuScreenGum:
var mainMenu = new MainMenuScreenGum();
Add(mainMenu);

// Properties match the instance names defined in the Gum XML:
mainMenu.StartButton.Click += (_, _) => MoveToScreen<GameScreen>();
mainMenu.QuitButton.Click += (_, _) => Exit();

• Generated classes inherit from Gum.Forms.Controls.FrameworkElement. The parameterless constructor builds the visual tree from a [ModuleInitializer]-registered template — just new XxxGum() and Add(...).
• Accessing a property that doesn't exist is a compile error — much safer than string-based GetFrameworkElementByName.
• State categories on a component generate enum types and nullable property setters that apply the state on assignment (e.g., card.SuitState = CardGum.Suit.Hearts).
• After any edit to the Gum XML, re-run gumcli codegen before referencing new/renamed instances in C#.

Showing / Hiding a Control

The API differs by type:

• FrameworkElement (Label, Button, etc.) — use IsVisible:

  label.IsVisible = false;
  label.IsVisible = true;
  

• Visual types (ColoredRectangleRuntime, TextRuntime, SpriteRuntime) — use Visible:

  rect.Visible = false;
  rect.Visible = true;
  

Gotchas

• "Keyboard navigation" on Forms controls means Tab/accessibility focus only — not arrow keys. Game action menus (battle commands, pause menus) require custom logic: maintain a _selectedIndex int and drive selection with WasKeyPressed(Keys.Up/Down/Left/Right) in Screen.CustomActivity. Apply visual highlight by toggling a property on the selected element. Do not try to use Button.IsFocused or OnKeyDown for this — Forms focus is designed for form tab-order, not game input.