> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/gum-tool/upgrading/syntax-versions.md). # Syntax Versions ## What Is a Syntax Version? A syntax version is an integer stamped on each Gum runtime assembly (MonoGameGum, RaylibGum, SkiaGum, SilkNetGum, StrideGum) via the `GumSyntaxVersionAttribute`. It tells the Gum tool's code generator which namespaces and conventions to use when emitting C# code for your project. When the Gum team makes a breaking namespace change (such as moving enums to a unified namespace), the syntax version is incremented. The code generator reads the syntax version from the runtime your project references and emits code that matches. ## How It Works The Gum tool auto-detects the syntax version from your project: * **NuGet users:** The tool finds your Gum PackageReference in the `.csproj`, locates the DLL in the NuGet cache, and reads the attribute. * **Direct project reference (source linking):** The tool follows the ProjectReference path and reads the version from `AssemblyAttributes.cs`. * **Newer runtimes:** If the `.csproj` references no MonoGame, KNI, FNA, or SkiaSharp runtime, the tool assumes the newest syntax version. This covers Stride, Silk.NET, raylib, and any new runtime, which never used the legacy namespaces. * **Version not readable:** If a MonoGame, KNI, FNA, or SkiaSharp runtime is referenced but its version cannot be read (for example, the NuGet package has not been restored yet), the tool uses version 0 and generates code with the legacy namespaces. Restore the package and generate again. * **Manual override:** If auto-detection does not work for your setup, you can set the `SyntaxVersion` field in your `ProjectCodeSettings.codsj` file to an explicit number instead of `"*"` (auto-detect). The detected version is displayed as Syntax Version in the Output section of the Code generation page in Edit > Settings... ## Version Table | Version | Introduced | Changes | | ------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | 2026.4.x | Baseline. Attribute system introduced. No breaking changes from prior releases. All existing namespace conventions are preserved. | | 1 | 2026.6.x | Runtime class namespace unification (non-breaking). Runtime classes like `TextRuntime`, `SpriteRuntime`, etc. move to the unified `Gum.GueDeriving` namespace. Old namespaces (`MonoGameGum.GueDeriving`, `SkiaGum.GueDeriving`) continue to work via compatibility shims marked `[Obsolete]`. See [Syntax Version 1](/gum/gum-tool/upgrading/syntax-versions/syntax-version-1.md) for details. | | 2 | 2026.6.x | Shape runtime collapse. `ColoredCircleRuntime`, `ColoredRectangleRuntime`, and `RoundedRectangleRuntime` are collapsed into `CircleRuntime` and `RectangleRuntime`, which now expose `FillColor`, `StrokeColor`, and `StrokeWidth` (and `CornerRadius` on `RectangleRuntime`). See PR #2769 / issue #2768. Code generation emits the collapsed types starting at version 3, because some version 2 runtimes lack the fill and stroke channel properties. | | 3 | 2026.6.x | Setup/boot API namespace unification (non-breaking). `GumService` (with its companions `WindowZoomMode` and the hot-reload types) moves from `MonoGameGum` / `RaylibGum` to the unified `Gum` namespace; generated code emits `using Gum;` instead of `using MonoGameGum;`. The legacy `GumService` name continues to work via a permanent `[Obsolete]` subclass shim, and `GumService.Default` still returns the legacy-named type so existing declarations keep compiling. `AddToRoot` / `RemoveFromRoot` become instance methods on `GraphicalUiElement` (no `using` needed at all). See issue #3119. | | 4 | TBD | Layout enum namespace unification (breaking). Enums like `DimensionUnitType`, `ChildrenLayout`, `HorizontalAlignment`, etc. move to a unified namespace. The bundled Roslyn analyzer provides one-click migration. | | 5 | 2026.10.x | Generated code assigns `ColorOperation` on `SpriteRuntime` and `NineSliceRuntime` instances (the Sprite/NineSlice `Color Operation` variable). Older runtimes lack the property, so the code generator omits the assignment below this version. See issue #4880. | | 6 | 2026.11.x | Generated code sets `MenuItem.DefaultSubmenuPopupTemplate` to the project's MenuItemSubmenuPopup component, so every MenuItem submenu uses it instead of the ScrollViewer component. Older runtimes lack the property, so the code generator omits the assignment below this version. See issue #6741. | | 7 | 2026.11.x | Generated Screen and Component classes carry a `[GumElement]` attribute naming their element, and fetch it with `ObjectFinder.GetRequiredElementSave`, which throws when the element is missing instead of returning `null`. This lets [`gumcli pack --shake`](/gum/cli/cli/pack.md#keeping-elements-created-from-code) find the elements your code uses. Applies to Gum Forms, MonoGame, raylib, and Silk.NET output. Older runtimes lack both, so the code generator emits the previous lookup below this version. See issue #6817. | When a new syntax version is introduced, the corresponding monthly migration page will document the specific changes. ## What Happens When You Upgrade If you upgrade your Gum NuGet package to a version with a higher syntax version: 1. The Gum tool auto-detects the new version. 2. Code generation uses the new namespaces. It also rewrites legacy `MonoGameGum` usings from your Code tab settings in the generated output, and leaves your saved settings unchanged. See [Code Generation Updates Legacy Using Statements](/gum/gum-tool/upgrading/migrating-to-2026-november.md#code-generation-updates-legacy-using-statements). 3. Your existing hand-written code may have `using` statements that reference old namespaces. The Gum Roslyn analyzer (bundled with the NuGet package) will show warnings with one-click fixes in your IDE. Use "Fix all in solution" to update everything at once. If you reference Gum via direct project reference, the same flow applies — the tool reads the version from the source and the analyzer runs at compile time. ## Absent Attribute (Pre-2026.4 Assemblies) If the Gum runtime assembly does not have a `GumSyntaxVersionAttribute` (because it predates the system), the code generator treats it as pre-version-0 and emits the original namespaces. No action is needed — everything works as before. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.flatredball.com/gum/gum-tool/upgrading/syntax-versions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.