gum-forms-behaviors
Covers Gum's behaviors system and the design-time → runtime Forms wrapping lifecycle. Load this when working on BehaviorSave, ElementBehaviorReference, StandardFormsBehaviorNames, FormsUtilities.RegisterFromFileFormRuntimeDefaults, DefaultFromFileXxxRuntime classes, or when investigating why Forms properties cannot be set at design time in the Gum tool.
Best use case
gum-forms-behaviors is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Covers Gum's behaviors system and the design-time → runtime Forms wrapping lifecycle. Load this when working on BehaviorSave, ElementBehaviorReference, StandardFormsBehaviorNames, FormsUtilities.RegisterFromFileFormRuntimeDefaults, DefaultFromFileXxxRuntime classes, or when investigating why Forms properties cannot be set at design time in the Gum tool.
Teams using gum-forms-behaviors should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/gum-forms-behaviors/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How gum-forms-behaviors Compares
| Feature / Agent | gum-forms-behaviors | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Covers Gum's behaviors system and the design-time → runtime Forms wrapping lifecycle. Load this when working on BehaviorSave, ElementBehaviorReference, StandardFormsBehaviorNames, FormsUtilities.RegisterFromFileFormRuntimeDefaults, DefaultFromFileXxxRuntime classes, or when investigating why Forms properties cannot be set at design time in the Gum tool.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Gum Forms Behaviors ## What Behaviors Are Behaviors are named capability contracts stored as `.behx` XML files in the project's `Behaviors/` folder. Each behavior (`BehaviorSave`) declares: - A `Name` (e.g. `"ButtonBehavior"`) - Required visual state `Categories` (with state names like Enabled/Disabled/Highlighted/Pushed) - Optional `RequiredVariables` and `RequiredInstances` - A `DefaultImplementation` path pointing to the default visual (e.g. `"Controls/ButtonStandard"`) An `ElementSave` (component or screen) opts into a behavior via a `List<ElementBehaviorReference>`, where each reference holds only a `BehaviorName` string. This is the signal used at runtime to select which Forms control wraps the visual. ## The Wrapping Lifecycle At project load time, call order is: 1. **`FormsUtilities.RegisterFromFileFormRuntimeDefaults()`** iterates every component in the loaded `GumProjectSave`, checks each component's `Behaviors` list against constants in `StandardFormsBehaviorNames`, and calls `ElementSaveExtensions.RegisterGueInstantiationType(component.Name, typeof(DefaultFromFileXxxRuntime))` for each match. 2. **`DefaultFromFileXxxRuntime`** (in `MonoGameGum/Forms/DefaultFromFileVisuals/`) is an `InteractiveGue` subclass selected as the runtime type. Its **`AfterFullCreation()`** override fires after the full visual tree is instantiated. Inside `AfterFullCreation()`, the runtime sets `FormsControlAsObject = new Button(this)` (passing itself as the visual), completing the pairing. 3. **`ReactToVisualChanged()`** fires on the Forms control when its `Visual` is assigned. The control caches named child references (`Visual.GetGraphicalUiElementByName(...)`) and `base.ReactToVisualChanged()` subscribes to input events and calls `UpdateState()`. The `DefaultFromFileXxxRuntime` classes exist solely to bridge the file-loading path into the Forms object model. They are distinct from the `DefaultVisuals` classes (which serve the code-only construction path). ## Behavior → Forms Control Mapping `StandardFormsBehaviorNames` constants → `DefaultFromFile` runtime registered: | Behavior name constant | Runtime type | |------------------------|-------------| | `ButtonBehaviorName` | `DefaultFromFileButtonRuntime` | | `CheckBoxBehaviorName` | `DefaultFromFileCheckBoxRuntime` | | `ComboBoxBehaviorName` | `DefaultFromFileComboBoxRuntime` | | `ListBoxBehaviorName` | `DefaultFromFileListBoxRuntime` | | `TextBoxBehaviorName` | `DefaultFromFileTextBoxRuntime` | | `LabelBehaviorName` | `DefaultFromFileLabelRuntime` / `DefaultFromFileLabelTextRuntime` | | `ItemsControlBehaviorName` | `DefaultFromFileItemsControlRuntime` | | `RadioButtonBehaviorName` | `DefaultFromFileRadioButtonRuntime` | | `SliderBehaviorName` | `DefaultFromFileSliderRuntime` | | `ScrollBarBehaviorName` | `DefaultFromFileScrollBarRuntime` | | `ScrollViewerBehaviorName` | `DefaultFromFileScrollViewerRuntime` | | `MenuBehaviorName` | `DefaultFromFileMenuRuntime` | | `MenuItemBehaviorName` | `DefaultFromFileMenuItemRuntime` | | `PasswordBoxBehaviorName` | `DefaultFromFilePasswordBoxRuntime` | | `PanelBehaviorName` | `DefaultFromFilePanelRuntime` | | `StackPanelBehaviorName` | `DefaultFromFileStackPanelRuntime` | | `WindowBehaviorName` | `DefaultFromFileWindowRuntime` | ## The Property Promotion Gap The Gum tool operates at the visual layer — layout, colors, fonts, dimensions saved as `VariableSave` entries. The Forms behavioral layer (state, data, interaction) is added entirely at runtime. No bridge exists between them. **Concrete examples of Forms properties with no Gum variable equivalent:** - `Button.Text` / `Label.Text` — visual has a `TextInstance` child, but no top-level "Text" variable on the component - `CheckBox.IsChecked` / `ToggleButton.IsChecked` — runtime-only boolean, not representable in the save file - `TextBox.Text` — initial text cannot be authored in the tool - `Slider.Minimum`, `Slider.Maximum`, `Slider.Value` — numeric range exists only on the Forms control - `ListBox.SelectionMode`, `ListBox.DisplayMemberPath`, `ItemsControl.Items` — entirely runtime constructs **Why this gap exists:** The visual save model (`VariableSave`) has no notion of Forms semantics. The Gum tool has no awareness of which Forms properties correspond to which visual structure. The wrapping is a pure runtime event. **Impact:** Game code must set all behavioral defaults in code after loading, even properties that logically belong to component design. ## Key Files | Path | Purpose | |------|---------| | `GumDataTypes/Behaviors/BehaviorSave.cs` | Behavior definition model (`.behx`) | | `GumDataTypes/Behaviors/ElementBehaviorReference.cs` | Per-element reference holding only `BehaviorName` | | `GumDataTypes/Behaviors/StandardFormsBehaviorNames.cs` | String constants for all standard behavior names | | `GumDataTypes/ElementSave.cs` | `Behaviors` list on components/screens | | `MonoGameGum/Forms/FormsUtilities.cs` | `RegisterFromFileFormRuntimeDefaults()` — drives the mapping | | `MonoGameGum/Forms/DefaultFromFileVisuals/` | `DefaultFromFileXxxRuntime` classes — `AfterFullCreation()` creates Forms objects | | `GumRuntime/InteractiveGue.cs` | `FormsControlAsObject` back-link property |
Related Skills
gum-forms-itemscontrol
Reference guide for ItemsControl and ListBox — the Items/ListBoxItems relationship, templates, InnerPanel sync, and gotchas. Load this when working on ItemsControl, ListBox, ListBoxItem, VisualTemplate, FrameworkElementTemplate, Items collection behavior, ListBoxItems desync, or adding/removing items from a list box.
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.
gum-forms-controls
Reference guide for Forms controls — classes inheriting from FrameworkElement. Load this when working on Button, CheckBox, ListBox, ComboBox, TextBox, ScrollViewer, or any class in Gum.Forms.Controls (or FlatRedBall.Forms.Controls). Also load when working on FrameworkElement itself, the Visual/InteractiveGue relationship, state machines, DefaultVisuals, or ReactToVisualChanged.
validate-code-changes
Validate all code changes on the current branch. Spawns QA and refactoring agents in parallel to review for correctness, edge cases, code quality, and pattern adherence. Use when ready to review branch changes before merging.
skills-writer
Creates and updates skill files (.claude/skills/*/SKILL.md) by reading source code and condensing knowledge into concise reference guides. Use when asked to create a new skill, update an existing skill, or document a subsystem for Claude Code agent context.
gum-variable-deep-dive
Deep dive into the full variable lifecycle — from VariableSave on ElementSave through runtime application on GraphicalUiElement and Forms controls. Load this when working on styling, theming, RefreshStyles, or when you need to understand how variable values flow from save data to live visuals.
gum-unit-tests
Reference guide for writing unit tests in the Gum repository. Load this when writing or modifying tests in Gum.ProjectServices.Tests, Gum.Cli.Tests, or any other Gum test project.
gum-tool-viewmodels
Reference guide for Gum tool ViewModel conventions. Load this when working on ViewModels, XAML views, data binding, DependsOn, or visibility properties in the Gum tool.
gum-tool-variable-references
Reference guide for Gum's variable reference system — Excel-like cross-instance/cross-element variable binding using Roslyn-parsed assignment syntax. Load this when working on VariableReferenceLogic, EvaluatedSyntax, ApplyVariableReferences, VariableChangedThroughReference, or the VariableReferences VariableListSave.
gum-tool-variable-grid
Reference guide for Gum's Variables tab and DataUiGrid system. Load this when working on the Variables tab, DataUiGrid control, MemberCategory, InstanceMember, category population, property grid refresh, or category expansion state persistence.
gum-tool-undo
Reference guide for Gum's undo/redo system. Load this when working on undo/redo behavior, the History tab, UndoManager, UndoPlugin, UndoSnapshot, or stale reference issues after undo.
gum-tool-selection
Reference guide for Gum's editor selection system. Load this when working on click/drag selection, the rectangle/marquee selector, input handlers (move, resize, rotate, polygon points), the IsActive flag, locked instance behavior, SelectionManager coordination, or the selection event cascade (plugin events, forced default state, tree view sync).