Gum gum-runtime-variable-references

Reference guide for runtime variable reference propagation and the optional Gum.Expressions NuGet. Load this when working on ApplyAllVariableReferences, GumExpressionService, runtime styling/theming, or the GumExpressions project.

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-runtime-variable-references" ~/.claude/skills/vchelaru-gum-gum-runtime-variable-references && rm -rf "$T"

manifest: .claude/skills/gum-runtime-variable-references/SKILL.md

Runtime Variable References

Overview

Variable references defined in the Gum tool can be re-evaluated at runtime. The primary use case is theming: modify centralized style values in code, propagate them across all elements, then create UI.

Key API

ApplyAllVariableReferences (GumRuntime)

Extension method on

GumProjectSave

ElementSaveExtensions.GumRuntime.cs

. Iterates all elements (standards, components, screens) and applies variable references on every state including category states (e.g.,

ColorCategory

). Uses topological sort so dependencies are applied first — if B references A, A is applied before B. Handles circular dependencies gracefully (appends them at the end).

No Roslyn dependency — lives in GumRuntime/GumCommon, available to all platforms.

GumExpressionService (Gum.Expressions NuGet)

Located in

Runtimes/GumExpressions/

. Provides Roslyn-based expression evaluation for arithmetic in variable references (

Width + 10

Width * 2

). Optional — without it, only simple dot-path lookups work (

OtherInstance.Width

GumExpressionService.Initialize()

sets

ElementSaveExtensions.CustomEvaluateExpression

to a Roslyn-based evaluator. The evaluator is

EvaluatedSyntax

, which was extracted from the Gum tool into this project.

Two Apply Overloads (ElementSaveExtensions)

```
ApplyVariableReferences(ElementSave, StateSave)
```
— writes hard values into the StateSave. Use before creating UI.

ApplyVariableReferences(GraphicalUiElement, StateSave)

— sets properties on live runtime visuals via

SetProperty

Architecture

GumCommon (no Roslyn)
    ↑
Gum.Expressions (adds Roslyn) — optional NuGet
    ↑           ↑
Gum Tool    Game (opt-in)

The decoupling mechanism is

ElementSaveExtensions.CustomEvaluateExpression

— a static

Func<StateSave, string, string, object>

delegate. When null, falls back to

RecursiveVariableFinder

(simple lookups only). When set by

GumExpressionService.Initialize()

, uses Roslyn for full expression support.

After applying variable references, call

GraphicalUiElement.RefreshStyles()

GumService.Default.RefreshStyles()

to push the updated values to live visuals. For a deep dive into how this works end-to-end, see the gum-variable-deep-dive skill.

Known Limitation

Division expressions (

Width / 2

) are broken when routed through

EvaluatedSyntax.ConvertToCSharpSyntax

because it replaces all

characters with a Unicode placeholder for path disambiguation. The division operator gets corrupted. Addition, subtraction, and multiplication work correctly.