gum-service
Skill659 starsChanged 2 months agoMITView on GitHub
GumService — runtime entry point for MonoGame/Raylib/KNI/FNA. Triggers: GumService init, Uninitialize, DeferredQueue, hot reload, Root/PopupRoot/ModalRoot containers.
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-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-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
GumService Reference
What It Is
GumService is the runtime-facing API that game developers use to initialize, update, and draw Gum UI. It lives in MonoGameGum/GumService.cs (compiled for XNALIKE, RAYLIB via #if) under the Gum namespace (since issue #3119 / syntax version 3). Legacy MonoGameGum.GumService / RaylibGum.GumService names are permanent [Obsolete] subclass shims in MonoGameGum/GumServiceCompat.cs (linked into RaylibGum.csproj). WindowZoomMode, GumHotReloadManager, and related hot-reload types also live in namespace Gum.
The soft migration is intentional and finished — do not flag it as incomplete. What matters is what the user types: new code uses using Gum; and types the service as GumService (= Gum.GumService) with no using MonoGameGum; / using RaylibGum; — that is 100% future-proof. Gum.GumService.Default is deliberately typed as the derived [Obsolete] shim so legacy using MonoGameGum; / using RaylibGum; declarations keep compiling; the user never names the obsolete type, so the modern path is warning-free. The GumService shim stays and keeps warning; the other shims in that file are removed no earlier than November 2027. One part is planned for later: retyping Default to Gum.GumService, because the typed setter cannot hold a plain Gum.GumService (multi-service code uses IGumService.Default). It is a breaking change held in the Future milestone for a release the maintainer picks, so do not do it or open new issues about it until asked. The issue is titled "GumService.Default should be typed as Gum.GumService so it can hold any service".
Not the CLI. Gum.Cli / Gum.ProjectServices are separate tools for headless project validation and codegen.
Lifecycle
GumService.Default.Initialize(game) // one-time setup
↓ per frame:
GumService.Default.Update(gameTime)
GumService.Default.Draw()
↓ on teardown (optional):
GumService.Default.Uninitialize()Initialize throws if called twice without an intervening Uninitialize. A failed Initialize (missing .gumx) rolls itself back, so the service can be initialized again. Draw() with no SystemManagers throws InvalidOperationException ("not been initialized"), except that a never-initialized service draws SystemManagers.Default when a host assigned one by hand. Update() has no service check of its own: it throws InvalidOperationException only because FormsUtilities.Update finds no cursor or keyboard, so it does not throw once those are installed without Initialize (the unit-test base class does this) while Draw() still does.
Draw() draws everything through SystemManagers.Default in one call — for manual control over what's drawn when/to-which-target (e.g. compositing onto multiple RenderTarget2Ds in one frame), use GumBatch's immediate-mode Begin/Draw/End instead (docs/code/rendering/gumbatch.md; internals in the gum-monogame-rendering skill).
Only the gumProjectFile overload loads a project. Initialize(game, gumProjectFile) loads the .gumx and runs the project-load path — which applies project-level settings (standard-element defaults, localization, and the project's TextureFilter → Renderer.TextureFilter, issue #3199). The Initialize(game, DefaultVisualsVersion) / parameterless overloads are code-only and never touch that path. So when manually verifying anything that depends on a loaded project, you must pass the .gumx path or the behavior under test never runs. The cheapest from-file smoke test is Initialize(game, "GumProject/GumProject.gumx") plus a SpriteRuntime (SourceFileName set, scaled up) added to Root.
GumService vs IGumService
Both stay supported long term. GumService is strongly typed and the more convenient choice for most games. IGumService (RenderingLibrary/IGumService.cs) is for code that should be truly cross-platform, for users who expect to migrate or support several runtimes, and it exposes interfaces. Neither replaces the other; each should be as fully featured as it can be, so a platform-neutral capability a game gets from GumService should also be reachable through IGumService.
Design rule. Gum offers a concrete class and an interface for its runtime services (GumService/IGumService, Cursor/ICursor, Keyboard/IInputReceiverKeyboard). The concrete class uses the platform's own types (XNA Keys and Matrix on MonoGame, KNI and FNA) and is the most convenient choice for most users. The interface uses platform-neutral types (Gum Keys, System.Numerics) for cross-platform code and users who expect to migrate or support several runtimes. Gum's own internal code should depend on the interfaces, which removes platform #ifs. So a concrete member keeps its platform type (Keyboard.KeysTyped stays XNA-typed; the interface exposes Gum Keys), and a platform-typed concrete member is never a reason to break existing code.
Cursor and keyboard accessors. GumService.Cursor / Keyboard return the concrete Cursor / Keyboard and stay that way, so they are null while a custom ICursor / IInputReceiverKeyboard is installed with FormsUtilities.SetCursor / SetKeyboard. IGumService.Cursor / Keyboard and FormsUtilities.Cursor / Keyboard return whatever is installed. FormsUtilities.SetCursor / SetKeyboard only assign FrameworkElement.MainCursor / MainKeyboard (no event is raised), and the MonoGame service reads them per service (process statics for the first service, GumContext for later ones). A new IGumService implementation reads FormsUtilities.Cursor / Keyboard; never forward to the typed property.
Adding a member to IGumService. A member belongs on the interface when a game reasonably calls it on GumService and its natural type is not engine specific. Add it as a default interface member so existing implementers (mocks, Moq proxies, FRB2 automation) keep compiling, and give it a default that is correct for a custom implementer: build it from other interface members when possible (UseKeyboardDefaults, RefreshStyles, PopupRoot), otherwise a no-op or null that the doc comment states. Members whose natural type is engine specific stay concrete-only: Game, GameTime (the typed one), ContentLoader, SystemManagers, the Initialize(...) overloads, Update(GameTime ...), Draw(Camera2D) / Draw(SKCanvas). IGumService.Update(double totalSeconds) is total seconds since startup; MonoGame/KNI/FNA and KNI Skia build a GameTime from it (elapsed is the gap since the previous Update, zero on the first after every Initialize; raylib does the same through the shared FrameClock). The concrete members that match an interface member by signature implement it implicitly, so most hosts need no code; a host that lacks the member gets the default.
Singleton Pattern
Default is lazily initialized via ??=. Uninitialize() sets _default = null, so after teardown GumService.Default creates a fresh instance — any stored reference to the old instance is now orphaned.
Uninitialize — Non-Obvious Details
Uninitialize() resets a large amount of shared static state across multiple singletons. Key things it does that are surprising:
- Nulls
GraphicalUiElement.SetPropertyOnRenderable,AddRenderableToManagers, etc. — delegates wired byFormsUtilities.InitializeDefaults - Calls
ElementSaveExtensions.ClearRegistrations()— clearsRegisterGueInstantiation/RegisterDefaultInstantiationTypecallbacks - Calls
LoaderManager.Self.DisposeAndClear()— disposes GPU content and empties the cache - Nulls and removes
FrameworkElement.PopupRootandFrameworkElement.ModalRootfrom managers - Resets
FileManager.RelativeDirectoryto"Content/"(only meaningful if a project was loaded) - Calls
_systemManagers.Renderer.Uninitialize()(XNALIKE only) - Sets
_default = null— next access toDefaultcreates a newGumService - Skips the teardown when this service is not initialized and a different service is live, so a stray or repeated
Uninitializecannot reset the live service's statics - Clears
SystemManagers.Default/ISystemManagers.Default/IGumService.Defaultonly when they belong to this service; restoresFileManager.CustomGetStreamFromFileonly if nobody replaced the bundle hook since; drops the language-change subscription - A service given its own
SystemManagers(Initialize(game, managers)) adopts them asSystemManagers.Defaultonly when none exists
FormsUtilities.Uninitialize() is internal; tests access it via InternalsVisibleTo.
Skia differs: GumServiceSkiaBase (Runtimes/SkiaGum/GumServiceSkiaBase.cs) wires the runtime-type registrations and property/renderable delegates once per process, so its Uninitialize keeps them and removes only what the loaded project added. Clearing them the way MonoGame does leaves a later Initialize without them.
Roots
| Property | Purpose |
Root | Main scene container; sized to canvas on each Update |
PopupRoot | Overlaid above Root; for non-modal popups |
ModalRoot | Topmost layer; blocks input to everything below |
PopupRoot and ModalRoot are FrameworkElement statics, not instance fields — they are shared across all GumService instances.
Multiple GumService Instances
The constructor is public (new GumService()) and each XNA-like instance owns its project lookup, cursor, canvas and element registrations through a GumContext (GumRuntime/GumContext.cs). IGumService.Default is the current service: Initialize sets it only when none exists, Update/Draw set it for the call and restore it, and code that builds or changes another service's elements outside those calls must assign it first (a sample doing this: Samples/MultiGumServiceSample/). Raylib, Skia and Silk stay single-service. User docs: the "More Than One GumService" section of docs/code/gum-code-reference/gumservice-gumui/README.md; the remaining shared state is listed in Direction/multi-gum-service-audit.md.
Key Files
| File | Purpose |
MonoGameGum/GumService.cs | Main class (namespace Gum) |
MonoGameGum/GumServiceCompat.cs | [Obsolete] subclass shims for MonoGameGum.GumService / RaylibGum.GumService (permanent); also holds the AddChild and ToGraphicalUiElement forwarders (obsolete, dated retention, not permanent) |
MonoGameGum/Forms/FormsUtilities.cs | Input/cursor/gamepad setup; Uninitialize() lives here |
GumRuntime/ElementSaveExtensions.GumRuntime.cs | ClearRegistrations() called during Uninitialize |
RenderingLibrary/Content/LoaderManager.cs | DisposeAndClear() called during Uninitialize |
Tests/MonoGameGum.Tests.V3/GumServiceUninitializeTests.cs | Tests for GPU-accessible Uninitialize behavior |
Tests/Gum.ProjectServices.Tests/UninitializeTests.cs | Tests for non-GPU Uninitialize behavior |
Testing Split
Uninitialize tests are split across two projects because FormsUtilities, LoaderManager, and ElementSaveExtensions don't all require a GPU:
Gum.ProjectServices.Tests—LoaderManager,ElementSaveExtensions,ObjectFinder(no GPU needed)MonoGameGum.Tests.V3—FormsUtilities, root containers,FrameworkElementstatics (require test setup with a mockSystemManagers)
Hot Reload
GumService.EnableHotReload(absoluteGumxSourcePath) wires up a GumHotReloadManager that watches the source project directory and rebuilds Root.Children when .gumx/.gusx/.gucx/.gutx/.fnt files change. GumService.Update ticks it each frame; Uninitialize stops and nulls it. For details on the reload pipeline, debounce, font cache eviction, and gotchas, load the gum-runtime-hot-reload skill. Public docs: docs/code/hot-reload.md.
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.

