gum-variable-deep-dive
Skill655 starsChanged 2 months agoMITView on GitHub
Full variable lifecycle — VariableSave on ElementSave through runtime application on GraphicalUiElement and Forms controls. Triggers: styling, theming, RefreshStyles, value flow from save data to live visuals.
In this repository68 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- debuggingSkill
- frb-build-verificationSkill
- frb-pixel-harnessSkill
- gum-architecture-layersSkill
- gum-bundleSkill
- gum-cliSkill
- gum-cross-platform-unificationSkill
- gum-docs-writingSkill
- gum-file-pathsSkill
- gum-forms-behaviorsSkill
- gum-forms-controlsSkill
- gum-forms-default-visualsSkill
- gum-forms-itemscontrolSkill
- gum-forms-theme-importSkill
- gum-iconsSkill
- gum-issue-creationSkill
- gum-kernsmith-integrationsSkill
- gum-layout-engineSkill
- gum-layoutSkill
- gum-localizationSkill
- gum-monogame-renderingSkill
- gum-monthly-releaseSkill
- gum-project-versioningSkill
- gum-property-assignmentSkill
- gum-raylib-renderingSkill
- gum-releaseSkill
- gum-runtime-animation-chainsSkill
- gum-runtime-bindingSkill
- gum-runtime-fontsSkill
- gum-runtime-hot-reloadSkill
- gum-runtime-syntax-versionSkill
- gum-runtime-systemmanagers-initSkill
- gum-runtime-topologySkill
- gum-runtime-variable-referencesSkill
- gum-samplesSkill
- gum-serviceSkill
- gum-source-linked-projectSkill
- gum-themingSkill
- gum-tool-animationsSkill
- gum-tool-codegenSkill
- gum-tool-copy-pasteSkill
- gum-tool-delete-logicSkill
- gum-tool-dialogsSkill
- gum-tool-errorsSkill
- gum-tool-file-watchSkill
- gum-tool-font-generationSkill
- gum-tool-import-from-gumxSkill
- gum-tool-outputSkill
- gum-tool-pluginsSkill
- gum-tool-save-classesSkill
- gum-tool-screenshotsSkill
- gum-tool-selectionSkill
- gum-tool-tree-viewSkill
- gum-tool-undoSkill
- gum-tool-variable-gridSkill
- gum-tool-variable-referencesSkill
- gum-tool-viewmodelsSkill
- gum-unit-testsSkill
- gum-visual-eventsSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 48
After this, save data changes do NOT automatically propagate.
- Very specific: line 83
After calling ApplyAllVariableReferences() to propagate variable reference changes into VariableSave values, call RefreshStyles() to push …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Variable Lifecycle Deep Dive
For individual subsystem references, see: gum-tool-save-classes (save model), gum-property-assignment (instantiation + SetProperty), gum-forms-controls (Forms state machine), gum-runtime-variable-references (ApplyAllVariableReferences).
This skill connects them into one end-to-end picture.
The Three Layers
| Layer | Classes | Role |
| Save data | ElementSave, StateSave, VariableSave, StateSaveCategory | Serialized project data (XML). Edited by the Gum tool. |
| Visual runtime | GraphicalUiElement / InteractiveGue | Live layout + rendering. Holds references to StateSave objects. |
| Forms behavioral | FrameworkElement subclasses (Button, CheckBox, etc.) | Logical controls. Drive categorical state changes (Highlighted, Disabled, etc.) on the Visual. |
Key Insight: Shared References, Not Copies
During ToGraphicalUiElement → SetGraphicalUiElement, the method
AddStatesAndCategoriesRecursivelyToGue stores the same StateSave and
StateSaveCategory instances from the ElementSave into the GUE's mStates and
mCategories dictionaries. No cloning occurs.
This means: when ApplyAllVariableReferences() modifies VariableSave.Value entries on an
ElementSave's states, those changes are immediately visible through the GUE's state
dictionaries. The data is already updated — but the live visuals haven't re-read it yet.
Instantiation Flow (One-Time)
ElementSave.ToGraphicalUiElement() → SetGraphicalUiElement():
- AddStatesAndCategoriesRecursivelyToGue — walks inheritance chain, stores state/category references on the GUE
- CreateGraphicalComponent — creates the underlying
IRenderable - AddExposedVariablesRecursively — registers exposed variable bindings
- CreateChildrenRecursively — for each
InstanceSave, callsinstance.ToGraphicalUiElement()recursively (each child gets its own full instantiation) - SetInitialState →
SetVariablesRecursively— applies default state values including instance-qualified variables (e.g.,"MyButton.Width") that set properties on children - AfterFullCreation — triggers Forms wrapping (e.g.,
DefaultFromFileButtonRuntimesetsFormsControlAsObject = new Button(this))
After this, save data changes do NOT automatically propagate. The GUE must be told to re-read.
Runtime Usage: With vs Without a Gum Project
- With a loaded project:
ElementSave/ScreenSave/ComponentSaveare present.ToGraphicalUiElementcreates the full tree. States on the GUE reference the ElementSave's states (shared instances). - Without a project:
ElementSaveclasses are not used. ButStateSave,StateSaveCategory, andVariableSaveare still used directly — code can create states in code and callApplyState()on any GUE.
Applying States at Runtime
Default (uncategorized) state
SetInitialState() calls SetVariablesRecursively(elementSave, elementSave.DefaultState),
which walks the inheritance chain (base type defaults first), then applies the element's own
default state via ApplyState. This includes instance-qualified variables that set properties
on children.
Categorical states (Forms)
Forms controls call UpdateState() in response to interactions (hover, click, disable).
UpdateState() determines the current state name (e.g., "Highlighted") and calls
Visual.SetProperty("ButtonCategoryState", stateName), which triggers ApplyState on the
matching StateSave within the category. This applies on top of the default state.
The ordering matters
During creation, the order is: children get their own defaults first, then the parent's default state applies instance-qualified overrides on top. Categorical states (Forms) are applied last.
Refreshing After Style Changes
After calling ApplyAllVariableReferences() to propagate variable reference changes into
VariableSave values, call RefreshStyles() to push those values to live visuals:
GraphicalUiElement.RefreshStyles()— recursively re-applies default states, current Forms categorical states, and runtime properties on a subtreeGumService.Default.RefreshStyles()— convenience that callsRefreshStyles()on all three roots (Root, PopupRoot, ModalRoot)
Three-pass architecture
RefreshStyles uses a three-pass approach to preserve runtime state:
- Save — walks the tree calling
FrameworkElement.SaveRuntimeProperties()on each Forms control. Controls save values that are stored on the visual layer and would be lost during state re-application. - Refresh — walks the tree calling
SetVariablesRecursively(children first, then parent instance-qualified variables on top). - Restore — walks the tree calling
UpdateState()+ApplyRuntimeProperties()on each Forms control. This re-applies the current categorical state and restores any saved runtime values.
The save must happen before ANY state re-application, and the restore must happen AFTER ALL
state re-application. This prevents parent instance-qualified variables (e.g.,
"TextBoxInstance.Text" = "") from overwriting restored values.
Controls with runtime state preservation
| Control | SaveRuntimeProperties | ApplyRuntimeProperties |
| Slider | — | UpdateThumbPositionAccordingToValue() |
| ScrollBar | — | UpdateThumbPositionAccordingToValue() |
| ScrollViewer | — | Re-syncs innerPanel.Y/X from ScrollBar values |
| TextBoxBase | Saves text, caret index, selection length | Restores text, caret, selection; calls UpdatePlaceholderVisibility, UpdateToSelection, UpdateToIsFocused |
| ComboBox | Saves displayed text | Restores displayed text |
| CheckBox/RadioButton | — | No override needed; UpdateState() factors in IsChecked |
| Expander | — | No override needed; UpdateState() sets contentContainer.Visible |
The delegates SaveFormsRuntimePropertiesAction and UpdateFormsStateAction on
GraphicalUiElement bridge the GumRuntime → MonoGameGum boundary (GumRuntime cannot
reference FrameworkElement directly).
Typical workflow:
// 1. Change a style variable
var colorState = ObjectFinder.Self.GetElementSave("Standards/ColoredRectangle")
.DefaultState;
colorState.GetVariableSave("Red").Value = 255;
// 2. Propagate variable references across the project
ObjectFinder.Self.GumProjectSave.ApplyAllVariableReferences();
// 3. Push to all live visuals
GumService.Default.RefreshStyles();Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

