gum-tool-file-watch
Skill659 starsChanged 2 months agoMITView on GitHub
Gum FileWatch system. Triggers: external file change detection, IgnoreNextChangeUntil, FileWatchManager, FileWatchLogic, FileChangeReactionLogic, reloading assets/elements when files change on disk.
In this repository69 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-font-generationSkill
- gum-tool-import-from-gumxSkill
- gum-tool-loggingSkill
- 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-variable-deep-diveSkill
- The first 60 shown.
The file
Files
Gum Tool File Watch System Reference
Architecture
Three cooperating classes handle the full pipeline — all three now live in the headless Gum.Presentation assembly (ADR-0005):
FileWatchManager(Tools/Gum.Presentation/FileWatchPlugin/FileWatchManager.cs): OwnsFileSystemWatcherinstances, queues changed files, manages the ignore list, and exposesFlush().FileWatchLogic(Tools/Gum.Presentation/FileWatchPlugin/FileWatchLogic.cs): Determines which directories to watch by scanning all project elements for referenced files. CallsEnableWithDirectories()on project load/unload/variable change.FileChangeReactionLogic(Tools/Gum.Presentation/Managers/FileChangeReactionLogic.cs): Dispatches a queued file to the correct reload handler based on file extension.
MainFileWatchPlugin (Tools/Gum.Presentation/FileWatchPlugin/MainFileWatchPlugin.cs, shared by both heads) is the plugin entry point — it only owns the glue (control/tab/menu-item creation, timer subscription). Its event-reaction logic (project load/unload, variable-set, debug-panel display refresh) is extracted into FileWatchPluginController (Tools/Gum.Presentation/FileWatchPlugin/FileWatchPluginController.cs), also headless.
Change Pipeline
FileSystemWatcher event (watcher thread)
↓
FileWatchManager.RunOnUiThread()
- Checks the ignore list, then posts the reaction through IDispatcher
↓
Posted reaction (UI thread)
- Verifies file's directory is being watched
- Adds to ChangedFilesWaitingForFlush, records LastFileChange
↓
PeriodicUiTimer (500ms interval, GumStartupSequence.cs)
- Calls FileWatchManager.Flush() every 500ms
↓
Flush() early-outs if TimeToNextFlush > 0 (waits 500ms after last change)
↓
FileChangeReactionLogic.ReactToFileChanged(file) per queued file
↓
Extension-specific reload (texture, element, project, font, CSV, behavior...)A second PeriodicUiTimer at 200ms drives the File Watch debug panel UI only — it does not trigger flushes.
Watched Directories
FileWatchLogic.GetFileWatchRootDirectories() builds the watch set by:
- Collecting all files referenced by every screen, component, and standard element via
ObjectFinder.Self.GetFilesReferencedBy() - Adding the gum project's own directory
- Adding localization and font-character-file directories if configured
Deduplication: the project directory is added last, so a final pass in GetFileWatchRootDirectories removes every root nested under another; each folder gets one watcher, and subdirectories are covered by IncludeSubdirectories = true. A nested root left in the set would raise a copy of every event.
RefreshRootDirectory() is called on project load and whenever a variable that IsFile == true changes value.
Saving Edits Back to Disk
Edits are written out through IFileCommands.TryAutoSaveElement(ElementSave) /
TryAutoSaveCurrentElement() / TryAutoSaveObject(object) in
Tools/Gum.Presentation/Commands/FileCommands.cs, each of which no-ops unless
IProjectManager.AutoSave is true (ProjectManager.cs, backed by GeneralSettingsFile,
user-toggleable on the Settings window's General page).
Landmine: "the element is edited" does not imply "the file on disk changed" — with AutoSave off,
in-memory changes sit unsaved until an explicit save. Code that mutates an element other than the
currently-selected one (e.g. a cascading delete affecting other elements' instances) should call
TryAutoSaveElement for that element, not assume it needs saving unconditionally.
A project-load default fill goes in IProjectLoadFills, not a plugin's ProjectLoad handler. Auto-saves
during ProjectLoad are ignored (IsNotifyingProjectLoad).
Ignore Mechanism
IgnoreNextChangeUntil(FilePath, DateTime?) suppresses the next detected change for a file until the given time. Default is 5 seconds from now.
When to call it: Any time Gum itself writes a file to disk, to prevent the watcher from triggering a reload of the file it just saved.
Callers:
FileCommands.cs— element/project savesProjectManager.cs— full project save (ignores .gumx and all element files)FontManager.cs— font generation (ignores .bmfc, .fnt, and .png pages)AnimationCollectionViewModelManager.cs— animation saveTextureCoordinateSelectionPlugin— sprite sheet edits
The ignore list (FileWatchIgnoreList) is time-based by default. A save path that also calls RecordWrittenContent(path) after the write (element and behavior saves in FileCommands, the project and element files in ProjectManager.SaveProject) adds a content check: inside the window an event is ignored only while the file still holds the bytes the tool wrote, so an outside edit shortly after a save still reloads. IgnoreNextChangeUntil clears the record, so events during the next save are ignored by time until that write is recorded. Other callers (JSON conversion, theme/gumx import, font generation, animation and sprite-sheet saves) are time-only; add RecordWrittenContent after their write when it can be followed by an outside edit.
ReactToFileChanged Extension Dispatch
| Extension | Action |
Any file a container's SourceShaderFile names (any extension) | Drop the cached effect and rebuild the shown element if any element references the shader (FileChangeReactionLogic.IsShaderFile: named by a SourceShaderFile variable; slang/fx also count, so an unreferenced one stays untouched) |
A file a shader #includes (any extension, nested too) | Same reaction for each recorded shader that an element references. The canvas's RenderTargetShaderResolver records what each shader read in IShaderIncludeMap when it compiles (a failed compile too); IsReferencedFile admits those files so the watcher queues them. An entry lives until that shader compiles again. An extensionless include is not seen by the watcher |
Any other file (images, svg, lottie json, achx, fnt, a decoder plugin's format), except the types below that keep their own reaction | If an element references it (see below) or the canvas cached it, drop the whole LoaderManager cache and reload the canvas and Variables tab |
gusx, gutx, gucx (and JSON siblings) | Reload element from disk, refresh tree + wireframe, then re-apply the references that read it (see below) |
gumx | Reload entire project |
ganx, ganj | The StateAnimationPlugin reloads the Animations tab when it is the selected element's sidecar |
gumfcs (font character file) | MainFontsPlugin regenerates the ranges and missing fonts |
behx, behj | Reload behavior definition, then re-apply its tool-only references to implementing components and elements holding their instances (see below) |
csv, resx | Reload localization file (RESX also matches satellites via IsLocalizationFileThatShouldTriggerReload) |
ProjectCodeSettings.codsj | Handled by the code output plugin's ReactToFileChanged (CodeOutputPluginBase.HandleFileChanged): reload only, never regenerate or migrate; an unreadable file keeps the current settings and makes the Code tab read-only until a readable version arrives or the user resets it |
The project's engine profile (.gumengine, GumProjectSave.EngineProfile) | IProjectRestrictions.Reload() (the profile folder is a watch root even outside the project folder), then the tree refreshes via its Changed event and the canvas and Variables tab refresh; a missing or broken file leaves the project unrestricted with an Output warning |
Debug UI Panel
The File Watch tab (hidden by default, toggled via View > Show File Watch) shows live state from FileWatchManager. A 200ms PeriodicUiTimer drives MainFileWatchPlugin, which delegates each tick to FileWatchPluginController.RefreshDisplay(), and displays:
- Which directories are being watched
- Files queued in
ChangedFilesWaitingForFlush(up to 15) - Countdown to next flush
- Currently active ignores with their remaining ignore time
FileWatchViewModel (Tools/Gum.Presentation/FileWatchPlugin/FileWatchViewModel.cs) is the data-bound VM; FileWatchControl.xaml (Gum/Plugins/InternalPlugins/FileWatchPlugin/) is the WPF view and FileWatchView (Tool/Gum.Avalonia/Panels/ToolPanelViews.cs) the Avalonia one.
Non-Obvious Behaviors
Created for Gum files: a Created for a Gum file (.gumx/.gusx/.gutx/.gucx/.ganx/.behx and their JSON siblings) queues only when the project already contains that file (FileChangeReactionLogic.IsKnownToProject: a loaded element or its *Animations sidecar, a behavior, the project file) or Gum's ignore list holds it. macOS reports an atomic swap over the target (renamex_np with RENAME_SWAP, the safe-save pattern of NSDocument apps such as TextEdit) as Created with no Changed and no Renamed, so dropping every Created loses real edits. A repeat event for the same path collapses in the queue, so Created plus Changed reloads once. A Created for a file nothing has loaded (a new file dropped in) is skipped. Non-Gum files (e.g., PNG) always process Created.
Dropped events can print a reason: with "Print file changes to output" on (File Watch tab), a skipped Gum file prints at once as File change skipped (<reason>): <path> (own save, unknown Created, temp file). Skips of other files are counted per reason and printed once per flush (x300, e.g. a, b, c), and a rename or delete of a type Gum does not react to prints nothing, so a build touching hundreds of files stays readable. A save that prints nothing never reached the manager, so look at the OS events first.
Referenced files follow the project, not an extension list: every file a variable names (IsFile), an animation chain's frames and a font's pages is reached through FileChangeReactionLogic.IsReferencedFile (referenced or cached by the canvas, and not a type with its own reaction: ganx, ganj, gumfcs, codsj, which the project walk lists too). A new file-backed type needs no change here. The project walk parses every referenced .achx and .fnt, so IProjectReferencedFiles keeps its result and the rename, delete and flush checks read that set; the walk runs once until something calls FileWatchManager.InvalidateReferencedFiles (the File Watch plugin does for element, instance, state, category and variable edits, undo and canvas refreshes; an edit that adds a file reference without firing one of those events leaves the set stale, so a new add path must fire its *Add event, and GumxImportService invalidates when an import ends) or a reload here changes what is referenced. A walk per event freezes the UI when a build touches hundreds of files. Everything the canvas loads by path sits in LoaderManager, so a change drops the whole cache and reloads even when the shown element does not use the file itself: a per-element file walk misses nested instances, base types and frame textures, and an element selected later would draw the cached copy. A flush of several such files reloads once, when DeferDependentUpdates closes, and their check against the set also waits for that point, so element reloads interleaved with picture edits walk the project once. Shaders (the files a SourceShaderFile variable names, whatever the extension) are the exception and drop only their own cache entry.
Renames are routed for every reacted-to extension: ReactToRename forwards renames for the extensions in its list (images, Gum files, .csv, .resx, .codsj, ...) and for any file an element references. Many editors (Vim, JetBrains, some VS Code modes) save by writing a temp file and renaming it over the target, so a type missing from that list silently misses external edits.
Delete reacts for element files, shaders and referenced files: ReactToDelete queues them like a change, so the flush can flag the element's source as missing or rebuild the canvas to report the missing file. Other deletes are ignored.
A reloaded element updates the elements that read it, after the whole flush is reloaded: ReactToElementSaveChanged calls IVariableReferenceLogic.ApplyReferencesToElement(element, trySave: true), the cascade an in-tool edit runs, so readers get new materialized values, are saved (Auto Save on) and the canvas and Variables tab refresh. FileWatchManager.Flush wraps its loop in FileChangeReactionLogic.DeferDependentUpdates(), so a reader that is itself in the batch is reloaded before any save of it; saving it first would overwrite the external edit still waiting in the queue. The reloaded element is never saved by this path. Readers keep their object and undo history, so IUndoManager.RebaseStoredValues writes the changed values into every snapshot of them; otherwise a later Ctrl+Z restores the replaced value and saves it.
Flush debounce is cumulative: TimeToNextFlush = (LastFileChange + 500ms) - Now. Every new file change resets LastFileChange, pushing the flush window out by another 500ms. Rapid successive changes delay flushing until things settle.
Watcher callbacks only check the ignore list, then post to the UI thread: HandleFileSystemChange/HandleRename/HandleFileSystemDelete run on a watcher thread and hand their work to the UI thread through IDispatcher. New callback code goes inside the posted reaction; anything else runs off the UI thread against UI-owned state.
FileWatchManager is a singleton: Registered in Tools/Gum.Presentation/Services/GumCoreServiceCollectionExtensions.cs as both FileWatchManager and IFileWatchManager.
Key Files
| File | Purpose |
Tools/Gum.Presentation/FileWatchPlugin/FileWatchManager.cs | Core watcher, queue, flush |
Tools/Gum.Presentation/FileWatchPlugin/FileWatchIgnoreList.cs | Time-based ignore list |
Tools/Gum.Presentation/FileWatchPlugin/FileWatchLogic.cs | Computes watched directories, enables/disables watcher |
Tools/Gum.Presentation/FileWatchPlugin/FileWatchPluginController.cs | WPF-free reactions (project/variable events, debug-panel display refresh) extracted from the plugin |
Tools/Gum.Presentation/Managers/FileChangeReactionLogic.cs | Dispatches flushed files to reload handlers |
Tools/Gum.Presentation/FileWatchPlugin/MainFileWatchPlugin.cs | Plugin entry point (shared by both heads); owns tab/menu-item wiring only |
Tools/Gum.Presentation/Services/PeriodicUiTimer.cs | UI-thread-safe periodic timer used for both flush and display |
Tools/Gum.Presentation/Startup/GumStartupSequence.cs | Creates the 500ms flush timer and calls fileWatchManager.Flush() |
Tools/Gum.Presentation/Commands/FileCommands.cs | Calls IgnoreNextChangeUntil before saving elements |
Tools/Gum.Presentation/Managers/ProjectManager.cs | Calls IgnoreNextChangeUntil before saving project |
Tools/Gum.Presentation/Services/Fonts/FontManager.cs | Calls IgnoreNextChangeUntil before generating fonts |
A reloaded selected element keeps its selected instances, matched by name: the reload replaces every InstanceSave, and re-selecting the element clears the instance selection, so ReactToElementSaveChanged records the names first and re-selects the matches afterward. A name missing from the file (deleted or renamed outside Gum) is skipped; if none match, only the element stays selected.
Tool-only references are re-applied after a reload: a behavior's ToolOnlyVariableReferences are materialized into the default state of each implementing component and of every element holding an instance of one (BehaviorToolOnlyReferencesApplier.Apply), so a reload alone leaves them at what the old reference produced. A reloaded behavior calls IVariableReferenceLogic.ReapplyToolOnlyReferences(behavior, trySave: true); a reloaded element calls the ElementSave overload. Changed elements are saved (Auto Save on) and their readers cascade; both run in the same deferred batch as the element cascade above. A variable a removed reference line (or a behavior the component no longer implements) wrote is removed from the component and its instances; a component whose reference now resolves to the resting value gets that value written over the stale one (shared with in-tool edits). Undo snapshots are not rebased for these values (no reference row feeds them).
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.

