agentleFS
vchelaruvchelaru/Gum/.claude/skills/gum-runtime-hot-reload/SKILL.md

gum-runtime-hot-reload

Skill659 starsChanged 2 months agoMITView on GitHub

Runtime hot reload — FileSystemWatcher rebuilds the Gum element tree when .gumx/.gusx/.gucx/.gutx/.fnt files change. Triggers: GumHotReloadManager, IGumHotReloadManager, GumService.EnableHotReload, debounce, font cache eviction during reload.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are 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.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If a matching design-time child exists, compare its visual's ElementSave.Name against the new BaseType.

    line 66
  2. Distinctive:

    If a same-named non-design-time child exists, leave it alone (runtime owns that slot).

    line 67
  3. Very specific:

    Prefer injecting a custom IGumHotReloadManager rather than adding game-specific logic to GumHotReloadManager.

    line 110

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Runtime Hot Reload Reference

What It Is

Hot reload lets a running game pick up changes saved in the Gum tool without restarting. GumService.EnableHotReload(absoluteGumxSourcePath) starts a FileSystemWatcher on the source project directory; file changes trigger a debounced rebuild of GumService.Default.Root's children from freshly loaded save data.

User-facing docs: docs/code/debugging/hot-reload.md. User docs are the source of truth for the public API; keep them in sync when behavior changes.

Key Files

FilePurpose
GumCommon/HostServices/GumHotReloadManager.csIGumHotReloadManager + GumHotReloadManager; host-specific steps (texture filter, animation load, cache eviction) come in as constructor delegates
MonoGameGum/GumService.cs, Runtimes/SkiaGum/GumServiceSkiaBase.csEnableHotReload, per-frame Update, Uninitialize stop
docs/code/debugging/hot-reload.mdPublic documentation

Platform Gating

The entire file is wrapped in #if !IOS && !ANDROID. The EnableHotReload method on GumService is likewise gated. The file is shared by every runtime through GumCommon. Any new API surface must respect both gates.

Source vs Bin Paths — Critical Distinction

The watched path is the source .gumx (the file the Gum tool edits), not the bin/Content copy. Two directories matter:

  • _projectSourcePath / sourceDirectory — where files change, where FontCache/ is read from
  • _binGumDirectory — snapshot of FileManager.RelativeDirectory at Start(); where fonts are copied to and where the runtime loads from

During PerformReload, animations are reloaded by enumerating *Animations.ganx under the source directory through a LooseFileGumFileProvider rooted there (via GumService.LoadAnimationsFromProvider). FileManager.RelativeDirectory is not swapped — the provider's root is the source directory. (This replaced an older approach that swapped RelativeDirectory and probed FileManager.FileExists per element.) If you add asset-resolving logic to the reload path, root it at the source directory yourself rather than relying on a global-state swap.

Reload Pipeline

FileSystemWatcher event
  → HandleFileChange filters by extension (.gumx/.gucx/.gusx/.gutx/.fnt/.ganx)
  → sets _pendingReload + _lastChangeTime
  → (.fnt paths also appended to _changedFontFiles under _fontFileLock)

GumService.Update → _hotReloadManager.Update(Root)
  → if _pendingReload && 200ms elapsed since last change → PerformReload

The 200 ms debounce coalesces the Gum tool's multi-file save burst into one reload. Don't shorten it without testing against a real tool save — partial saves will otherwise rebuild against an inconsistent on-disk state.

PerformReload — What Actually Happens

  1. CopyAndUnloadChangedFonts() — for each changed .fnt anywhere in the project (FontCache/ or a CustomFontFile folder), copies it plus the pages it names (and <basename>*.png) to the same relative place under the bin folder, then LoaderManager.Disposes each under the path the game loads it by. A file already at its destination (Preview, or a build folder under the project) is not copied (CopyUnlessCurrent) but is still evicted. A source .fnt whose bin copy has another write time or length counts as changed even with no watcher event (copies keep the source's write time). A changed .png that a neighbouring .fnt names re-queues that font. When any font was evicted, ReapplyFonts runs after ApplyDiff and calls UpdateToFontValues() on every Text, because the diff only touches Text whose font variables changed.
  2. GumProjectSave.Load + Initialize; swap into ObjectFinder.Self.GumProjectSave.
  3. Reload animations: enumerate *Animations.ganx under the source directory via a LooseFileGumFileProvider and load each through GumService.LoadAnimationsFromProvider into the new project (no RelativeDirectory swap — the provider is rooted at the source dir).
  4. ApplyDiff(roots, newProject, SystemManagers.Default) — applies the in-place reconciliation walk described below.
  5. Fire ReloadCompleted (only when the reload applied), then ReloadFinished with a HotReloadResult (every attempt, applied or not). See "Reload Result" below.

ApplyDiff — In-Place Reconciliation Walk

Defined on GumHotReloadManager and exposed public static for direct test use; the four-argument overload takes the old project (PerformReload passes the one the finder held), and tests of "unchanged variable keeps its value" must pass it, since a builder that shares a standard element's default state between projects reads as edited in place. It first runs newProject.ApplyAllVariableReferences(), so a reader of a reference that is itself fed by a reference (control -> Styles.Primary -> Styles.Brand) sees the end of the chain even when only the last file was edited and the files between still hold their saved copies (HotReloadReferenceChainTests). References and base types resolve through ObjectFinder, so ApplyDiff sets ObjectFinder.Self.GumProjectSave to the new project for the call and puts the previous one back in a finally. It then walks every root and, at each visual whose ElementSave.Name matches an element in the new project:

  1. Re-point element.ElementSave to the new project's element.
  2. Structural diff against the new Instances list (DiffDesignTimeChildren). That list already holds every inherited instance: load and reload both run RepairMissingDefinedByBaseInstances (GumProjectSaveExtensionMethods.cs), which copies a base element's instances into each derived element with DefinedByBase set, so a base edit reaches derived visuals through this same diff (HotReloadInheritedInstanceTests).
    • Partition the visual's ContainedElements plus Children into design-time (those with Tag is InstanceSave) and everything else (runtime-added or Tag-cleared). Matching must use ContainedElements: an instance with a Parent variable (a ListBoxItem inside a ComboBox) is not in Children, and missing it duplicates the instance on every reload.
    • For each existing design-time child not present in the new Instances: Parent = null, ElementGueContainingThis = null, RemoveFromManagers().
    • For each new InstanceSave:
      • If a matching design-time child exists, compare its visual's ElementSave.Name against the new BaseType. Mismatch → remove+recreate (retype). Match → refresh the Tag to point at the new InstanceSave instance.
      • If a same-named non-design-time child exists, leave it alone (runtime owns that slot). Do not create a duplicate.
      • Otherwise call instance.ToGraphicalUiElement(systemManagers) and attach via Parent = parent + ElementGueContainingThis = parent.
  3. SetChangedVariablesRecursively(element, newEs, context) — applies the default-state values the project changed, layer by layer down the base types: a variable is set only when its value differs from the old project's (ReloadContext.OldByName, from the oldProject argument or the visuals' own ElementSaves), the old project has no such variable, or an earlier layer or rebuilt instance in this reload reset it (ReloadContext.Applied/Recreated); every other variable keeps its runtime value (#6980). A layer with no old version, or edited in place, is applied in full. ResetRemovedVariables runs per layer. Qualified-name variables (MyInstance.X, MyInstance.Parent, etc.) flow into the children by Name, which also handles reparenting and animates new instances into position.
    • Then ReorderDesignTimeChildren reorders, per container (the element, or any instance an instance is parented to), only the slots held by this element's own instances (matched by InstanceSave reference against newEs.Instances), so newEs.Instances order wins. It runs after variables so Parent has settled. A move inside an ItemsControl InnerPanel relies on the control syncing its collections (see gum-forms-itemscontrol).
  4. Recurse into runtime-added children (no InstanceSave tag). Design-time instances are recursed into before step 3, at any depth, so an edit to a component's own default state or instances reaches every instance of it, and this element's qualified-name overrides then win over the component's defaults. Standard-element instances are not recursed into. A design-time child is only diffed against the element that owns its InstanceSave (ParentContainer.Name): a screen instance parented under a component instance sits in that visual's Children but belongs to the screen.

Reload Result

HotReloadResult / HotReloadIssue / HotReloadIssueKind (GumCommon/HostServices/HotReloadResult.cs) are what ReloadFinished raises, forwarded by GumService.HotReloadFinished. Each place that used to print a problem now adds a HotReloadIssue and prints its Message: the walk adds them to ReloadContext (Report/ReportOnce), and TryLoadProject, HandleFailedReload and TryReload add the rest. A new problem kind is a new enum value plus its MatchesRestart rule, not a bare ReportError.

A stale-forever edit (a component's base type, its exposed variables, a standard element's default) is not applied by the diff: ReportDefinitionChanges / ReportStandardChange list it with MatchesRestart false, and ReloadMemory.BuiltShapes remembers what the visuals were built with (base type, exposed variables) so later reloads keep listing it. Any change of an element's own base type is listed, with no hand-picked comparison of what the bases contain (that kept missing real differences). The one exception is a pure rename (IsPureRename): the old base is gone, the new one is new, and the two serialize to the same text once their names are replaced. An element whose file is missing (MissingElements) only gets the MissingFile issue. Events are raised per subscriber inside try/catch; an attempt that will be retried raises nothing.

Landmine: _reportedProblems is the memory for printing only. It must never filter what goes into a result, or a subscriber misses a state that is still stale. Only PrintIssues reads it.

Non-Obvious Behaviors / Gotchas

  • Tag is the design-time marker. InstanceSave.ToGraphicalUiElement sets Tag = instanceSave (GumRuntime/InstanceSaveExtensionMethods.GumRuntime.cs:39). If user code nulls or replaces that Tag, the diff treats the visual as runtime-owned: not removed, not retyped, not duplicated. Variable application via Name still works. Documented limitation, see docs/code/debugging/hot-reload.md.
  • A visual whose element is gone from the new project is kept and reported once. ApplyDiffRecursive records it in ReloadContext.Problems (keyed gone:<name>) when byName has no match and it is not a standard element: a renamed, moved or deleted shown screen (no identity survives a rename), or a code-added component visual. The message says "screen", "component" or "element" by KindOf; screens and components get the same message. ReportProblems says it through ReportError at the end of the walk; the manager's _reportedProblems keeps it from repeating on every later save and clears it when the element comes back. The public static ApplyDiff has no memory and reports every time. Edits to the old screen or its replacement do not arrive (the message says so). Tests: HotReloadGoneElementTests.
  • An instance whose BaseType is no longer in the project is removed. The tool keeps such an instance in the owner's file; a restart cannot build it (InstanceSave.ToGraphicalUiElement returns null). DiffDesignTimeChildren checks ObjectFinder.GetElementSave(BaseType) before the retype comparison, which would otherwise match the visual to its own old element name and keep it. A removal is reported once (the next reload finds nothing to remove), and because the instance is gone before ApplyDiffRecursive recurses, the "element is gone" report above never fires for it: exactly one message per removal (HotReloadDeletedComponentTests). Contrast: a shown screen or component is kept, an instance of a deleted component is removed. Tests: HotReloadDeletedComponentTests.
  • The walk stops at instance loops with the build's own guard. ApplyDiffRecursive holds ElementSaveExtensions.EnterBuild(newEs) while it walks a visual, so an instance created below it of a component already above it is skipped by IsCircularInstance, exactly as a restart skips it (#7468). Without it each reload grew the tree a level per level walked until the stack overflowed (#7988). The skip is routed into the result as InstanceLoop (ReportCircularInstancesTo) instead of printed separately. Any new path that builds instances during the walk must stay inside that scope. Tests: HotReloadInstanceLoopTests (MonoGame, and Skia through PerformReload).
  • Retype detection uses ElementSave.Name, not the old Tag.BaseType. This is the visual's actual built-from type, which stays stable across diffs whether the caller passed a fresh project or mutated the existing one in place — important for tests.
  • Root.Children and any roots passed to Update(IEnumerable<GraphicalUiElement>) are the reload surface. PopupRoot / ModalRoot are untouched.
  • ApplyDiff runs RefreshStyles's three passes. It saves Forms runtime properties, applies the diff, then re-applies the categorical states code drove by name (_appliedCategoryStates on GraphicalUiElement) and runs UpdateState + ApplyRuntimeProperties on each Forms control. A new restore need goes in a control's SaveRuntimeProperties/ApplyRuntimeProperties, not in the diff. Values set in code on any other visual are left alone unless the project changed that variable (below).
  • Re-applying a category state puts the containers' values for that instance back (#8108). ReapplyAppliedCategoryStatesRecursive follows each state that was applied while the instance had no container yet (a build-time state, not a Highlighted-style runtime state, which keeps beating the container) with ReassertContainerOverrides: a build applies the state first and the containing elements' values (a ListBox's VerticalScrollBarInstance.Height, a screen's Box.VerticalScrollBarInstance.Height) after it, so a re-applied state (the ScrollBar's OrientationCategoryState = Vertical, 128 px Absolute) must not leave its own values on top. Tests: ThemedScrollBarHotReloadTests.
  • Forms-property variables (BehaviorFormsPropertyApplier) follow the same rule as other variables: the project wins when it changed the value, code-set values stay otherwise (#6980). ApplyDiff calls ReapplyChangedFormsPropertiesRecursive before the restore pass; ReapplyChanged writes only properties whose effective value (instance override, then component default) differs between the old and new element. A removed value returns to the behavior default, else to what the control held when it was created (SnapshotInitialValues). Without this the build-time write recorded as code-assigned (TextBox.Placeholder) won over the edit (#7470).
  • A visual keeps the StateSave/category objects it was created with (Categories/States dictionaries). RefreshStatesAndCategories re-points them at the new element when ApplyDiff swaps ElementSave; without it the first state change after a reload applies the pre-edit state values.
  • Children added with no Tag (or with a Tag that isn't an InstanceSave) are runtime-owned and preserved. This includes ItemsControl-generated rows and anything the user constructed programmatically.
  • Reparenting flows through the qualified <instance>.Parent variable — there is no explicit reparent step in the diff. The parent state's Foo.Parent = "Bar" line is what re-attaches Foo under Bar during SetVariablesRecursively. This is why both old and new parent visuals must exist before that step runs.
  • A variable the file stops setting is reset, not left alone. ResetRemovedVariables in GumHotReloadManager.cs compares the old and new default-state save objects (never the visuals, so values assigned in code are untouched) and restores each dropped variable's default from GetValueRecursive. "Dropped" includes a variable still present with SetsValue but no value, which is how the tool saves a detached Foo.Parent. A dropped Foo.Parent is detached directly, because SetProperty("Parent", "") is a no-op. A dropped categorized-state assignment is not undone. A project edited in place has no old state to compare, so tests of this must build a second project object (HotReloadRemovedVariableTests).
  • A variable a reference row wrote is applied from the file again, whatever the old file held. The live value came from the row, not the file, so an unchanged stored value would otherwise keep it after the row is removed, retargeted or becomes part of a loop (a restart skips looped rows and shows the stored value, #6871). GetRowTargets (LoadOrderRows of the old state) feeds CreateChangedState and ResetRemovedVariables; tests: PreviewAccuracy2CircularReferenceTests.cs (class PreviewAccuracy2Tests).
  • A project that cannot be read skips the reload. PerformReload loads the whole project into a temporary via GumProjectSave.Load(path, out result) before touching ObjectFinder or the tree. A parse error, locked file or empty file (ErrorMessage, or a thrown deserialize exception) retries once after the debounce (_failedAttempts, reset by any new NotifyFileChanged), then reports once through ElementSaveExtensions.ReportPropertyAssignmentError and leaves everything unchanged. MissingFiles alone (git checkout) is reported and the rest reloads. A throw after the load (ApplyDiff) restores the finder and is reported, but cannot roll the tree back. Tests: HotReloadUnreadableFileTests.
  • .ganx is only re-read by enumerating the source directory into the new project's ElementAnimations (via GumService.LoadAnimationsFromProvider). A non-Gum file goes to _changedOtherFiles and is matched against GraphicalUiElement.AssignedSourceFile (recorded in SetProperty("SourceFile"), because the visual keeps only the texture). .achx/.achj edits evict the cache entry, copy source to bin if they differ, and assign SourceFile again; chains are reassigned only while IAnimationChainRenderable.AnimationChainList is still the cached list (code-assigned chains are left alone), and a playing chain the new file lacks is reported as ReloadFailed. A changed image a visual showed before the reload (or a frame image its chain file names, found with ChainTexturePaths) is reported as ReloadFailed, never applied, and stays in _staleImages so every later result lists it.
  • Shader files are matched by reference, not extension (#7034). A changed file that is not a Gum/font file goes into _changedOtherFiles; after the debounce ReassignShaderFiles walks the roots and, for each container whose recorded ShaderParameterVariables.GetShaderFile resolves to that file, evicts the cached effect and re-sets SourceShaderFile. No reload or rebuild. #included files count too: the MonoGame/KNI/FNA and Skia ShadowDusk loaders record each compile's included files (also a failed one) in ShaderIncludeTracker (GumCommon) through the linked ReportingIncludeResolver, and ReassignShaderFiles matches a changed file against both the shader and its recorded includes. Not tracked: raylib, Slang import, extensionless includes (the watcher ignores them).
  • A changed .ttf/.otf is reported, not applied. Which generated fonts came from it is unknown here, so ReportChangedFontSources queues a FontSourceChanged issue (MatchesRestart false) that rides the next result, or is raised alone when no reload is pending.
  • Copying a font can make the file watcher report the source file as changed (seen on macOS). A change event for a font whose load-folder copy has the same length and write time is the manager's own copy and is dropped (IsCopyCurrent; copies keep the source's write time), and a copy that is a no-op evicts nothing. Events inside a load folder nested under the project folder are ignored, and so is that folder in the rescan. _changedFontFiles is a set, a reload copies at most MaxFontsPerReload fonts, and after MaxFontOnlyReloads reloads asked for by fonts alone the manager reports one ReloadFailed and ignores font events until a project file changes. A failed font copy is reported once, retried by the next reload, then dropped. A queued font that is gone and has no load-folder copy (an editor's hidden temp file) is dropped without a report, and hidden or ~ names are never queued.
  • Localization files are reloaded, but not through the extension list. A changed file that is not a Gum file goes to _changedOtherFiles; after the debounce Update runs PerformReload(roots, otherFiles) (project also changed) or PerformFileReload (alone). ReloadLocalization replaces the database when the new project's LocalizationFiles list differs from the old one or ProjectLocalizationLoader.IsLocalizationFile matches a changed file, then RefreshLocalization re-translates and lays out the roots. The service comes from the host through LocalizationServiceProvider (a static on CustomSetPropertyOnRenderable, unreachable from GumCommon); a manager built without it skips localization. An unreadable file is retried once (_failedFileAttempts), then reported; PerformFileReload catches everything because Update runs on the game thread.
  • _changedFontFiles is mutated off the game thread (watcher callback). It's protected by _fontFileLock; any new shared state added must be similarly synchronized.
  • Stop() is idempotent-safe but does not reset other state — GumService.Uninitialize just nulls the manager reference afterward.
  • Font cache path is built with FileManager.Standardize(..., preserveCase: true, makeAbsolute: true). The loader's cache keys are case-preserving absolute paths; any eviction added must match that exact shape or it will silently miss.

Extending

  • For new watched extensions: add to HandleFileChange's extension check. If the asset type has a cache, add eviction to PerformReload (follow the font pattern — copy source→bin, then LoaderManager.Dispose the standardized path).
  • Prefer injecting a custom IGumHotReloadManager rather than adding game-specific logic to GumHotReloadManager. (Currently EnableHotReload hardcodes new GumHotReloadManager() — if a test/custom manager seam is needed, add an overload accepting an IGumHotReloadManager.)
  • Subscribe to ReloadCompleted from game code to reapply runtime state after a rebuild, or to ReloadFinished to react to what the reload could not do.
  • Tool/GumPreview is the in-repo example: on MatchesRestart == false it rebuilds the shown element from the project the reload loaded (PreviewReloadPolicy, once per reload that reports MatchesRestart == false, and after every finished reload while the tool has a state selected: Preview applies that state itself, a reload only compares default states, so a value a removed, deleted or renamed state set would stay; PreviewSelectedStateReloadTests). Rely on MatchesRestart, never on specific issue kinds.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.