Gum gum-forms-default-visuals

Reference guide for Forms DefaultVisuals — the code-only visual classes that back Forms controls. Load when working on ButtonVisual, any *Visual class in DefaultVisuals/, Styling, DefaultFormsTemplates registration, or building custom code-only Forms visuals.

install

source · Clone the upstream repo

git clone https://github.com/vchelaru/Gum

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/vchelaru/Gum "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/gum-forms-default-visuals" ~/.claude/skills/vchelaru-gum-gum-forms-default-visuals && rm -rf "$T"

manifest: .claude/skills/gum-forms-default-visuals/SKILL.md

Forms Default Visuals

What They Are

Default visuals are

InteractiveGue

subclasses that procedurally build a complete visual tree in their constructor — no Gum project file needed. Each one backs a specific Forms control (e.g.,

ButtonVisual

backs

Button

). They live in

MonoGameGum/Forms/DefaultVisuals/

Two Generations

V1 (legacy

Default*Runtime

) — Solid-colored rectangles (

ColoredRectangleRuntime

RectangleRuntime

). No textures, no centralized styling. Still shipped but superseded.

V2+ (

*Visual

) — Nine-slice textured backgrounds via

Styling.ActiveStyle

. Uses a shared sprite sheet for backgrounds, icons, and focus indicators. V3 variants exist under

DefaultVisuals/V3/

Both generations follow the same wiring pattern; they differ only in visual fidelity.

Construction Pattern (V2+)

Every

*Visual

constructor does four things in order:

Build child runtimes —
```
NineSliceRuntime
```
for background,
```
TextRuntime
```
for label, etc. Children are added via
```
Children.Add()
```
.
Create a
StateSaveCategory
— Populated with
```
StateSave
```
objects for each interaction state (Enabled, Disabled, Highlighted, Pushed, Focused, etc.). States are applied by the Forms control via
```
SetProperty
```
.
Pull styling from
Styling.ActiveStyle
— Colors, texture coordinates, font config.
Attach the Forms control —
```
FormsControlAsObject = new Button(this)
```
(or whichever control type). This triggers
```
ReactToVisualChanged
```
on the Forms side.

Initialization — Two Paths

GumService.Initialize()

always calls

FormsUtilities.InitializeDefaults()

first, which populates

FrameworkElement.DefaultFormsTemplates

with code-only default visuals. The

DefaultVisualsVersion

parameter controls which generation (V1/V2/V3/Newest).

If a

.gumx

project file is also passed to

Initialize()

, it then calls

FormsUtilities.RegisterFromFileFormRuntimeDefaults()

, which overrides the code-only defaults with project-defined Forms visuals (components with Forms behaviors). This is the path used when the Gum tool has authored the UI.

Code-only projects — call

Initialize(DefaultVisualsVersion)

with no project file. Controls get their visuals from the

*Visual

Default*Runtime

classes.

Project-based — call

Initialize(gumProjectFile)

. The code-only defaults are registered first, then project components replace them via

RegisterFromFileFormRuntimeDefaults()

Styling.cs

Centralized style constants consumed by V2+ visuals:

```
Colors
```
— Primary, Danger, Warning, Success palettes
```
NineSlice
```
— Texture coordinate presets (Solid, Bordered, Outlined, etc.)
```
Icons
```
— Coordinates for 70+ icon sprites on the shared sprite sheet
```
Text
```
— Font configuration (Normal, Strong, Emphasis)
Loads embedded
```
UISpriteSheet.png
```
by default via
```
UseDefaults()
```

Named Children Convention

Forms controls locate children by name (e.g.,

"TextInstance"

"FocusIndicator"

"InnerPanel"

). If a visual omits an expected named child, the Forms control silently skips it (or throws under

FULL_DIAGNOSTICS

). When building custom visuals, match the names the Forms control looks up in its

ReactToVisualChanged

Key Files

Path	Purpose
`MonoGameGum/Forms/DefaultVisuals/*Visual.cs`	V2+ visual classes
`MonoGameGum/Forms/DefaultVisuals/Default*Runtime.cs`	V1 legacy visual classes
`MonoGameGum/Forms/DefaultVisuals/Styling.cs`	Centralized colors, textures, fonts
`MonoGameGum/Forms/FormsUtilities.cs`	`InitializeDefaults()` — registers visuals in `DefaultFormsTemplates`
`MonoGameGum/Forms/Controls/FrameworkElement.cs`	`DefaultFormsTemplates` dictionary and Forms-first construction