Gum Codegen

Gum Code Generation in Glue

Glue does not rely on Gum's own runtime code generation for the standard element runtimes. Instead, the Gum plugin regenerates these classes itself from the Gum project data. The upside is tight control over what gets emitted; the downside is that whenever Gum adds, removes, or renames a variable on a standard type, Glue's generator has to be updated to match — otherwise the new variable is silently emitted (causing build/runtime errors on older projects) or silently omitted (causing missing properties on newer projects).

This skill is about the omission side: how Glue decides which Gum variables to skip when generating a standard runtime, and how to gate that decision on a GluxVersions value. For the version-numbering rules themselves, see the gluj-versions skill.

There are THREE independent decisions, not one

Generating a standard runtime like NineSliceRuntime.Generated.cs involves three independent code paths. All three must agree on whether a member exists in a given version, and each disagreement has its own compiler error:

1. Property generation — emits the public T Foo { get; set; } (or backing-field) property on the runtime class. Driven by StandardsCodeGenerator and per-type generators (NineSliceCodeGenerator, etc.).
2. State generation — emits the case VariableState.Default: Foo = …; assignments inside the state-switch. Driven by StateCodeGenerator.
3. Inheritance — emits the : global::Gum.Wireframe.IFooRuntime on the class declaration, via each per-type generator's AddAdditionalInheritance (wired up in StandardsCodeGenerator.GenerateStandardElementSaveCodeFor).

Property vs. state disagreement is CS0103: The name 'IsTilingMiddleSections' does not exist in the current context — a state-init assignment for a property nobody generated. Inheritance vs. property disagreement is CS0535: does not implement interface member (issue #1979).

Pipelines 1 and 2 are driven by the project's variables; pipeline 3 is driven by GluxVersions alone, so it is the one that most easily drifts. The Gum.Wireframe.I*Runtime interfaces it names are hand-written in the sibling Gum repo under #if FRB (Gum/Wireframe/CustomSetPropertyOnRenderable.cs) and mirror what Glue generates; they grow as Gum routes more of its property dispatch through the runtime instead of the renderable. Glue holds no reference to GumCore, so nothing in Glue can read one — NineSliceCodeGenerator.InterfaceMemberNames restates the contract by hand, and GumGeneratedCodeCompilesTests is what detects drift. ContainerCodeGenerator/PolygonCodeGenerator avoid the problem differently, by emitting their interface members from GenerateAdditionalMethods rather than relying on the project's variables at all.

When you add a version gate, update every pipeline that touches the member. Searching for an existing skipped variable name (e.g. "IgnoredByParentSize", "StackSpacing") is the fastest way to spot every place that needs a parallel change — they typically appear in both StandardsCodeGenerator.RefreshVariableNamesToSkipForProperties and StateCodeGenerator.RefreshVariableNamesToSkipBasedOnGlueVersion.

Glue never back-fills a loaded project's standard elements (landmine)

Codegen emits from the variables in the project's own .gutx, and Glue never reconciles that against Gum's canonical schema. Gum's tool does (GumProjectSaveExtensionMethods.Initialize back-fills each standard element from StandardElementsManager, gated by VariableSave.MinimumGumxVersion); Glue calls GumProjectSave.Load and never that. What it does call — FileReferenceTracker.InitializeElements — passes each element its own default state, which resolves variable types but back-fills nothing.

Consequences worth knowing before debugging "why isn't this variable generated":

• A .gutx written before Gum added a variable never gains it, at any Glue version. Every checked-in sample is in this state.
• Bumping GluxVersions alone will not make a variable appear — if the project's .gutx lacks it, no gate change helps.
• A fixture built from StandardElementsManager.Self.GetDefaultStateFor(name) is a current editor's output, so it cannot reproduce this. Load a real sample's .gumx and call Initialize(element.DefaultState) per element to match production — see GumGeneratedCodeCompilesTests.LegacyGutxStandardElementRuntimes_ShouldCompileAgainstTheRealEngine.
• ProjectLoader.LoadProject bumps the .gluj's FileVersion to LatestVersion on load. So the live combination is always current GluxVersions + whatever the .gutx happens to contain, which is exactly what produced #1979.

The compiler can never catch a runtime mismatch (landmine)

Glue has no compile-time knowledge of the runtime types it generates against. mStandardElementToQualifiedTypes holds fully-qualified type names as plain strings; RenderingLibrary.Graphics.Text is not a referenced assembly in any Glue project, and it is not among GumPlugin's embedded LibraryFiles resources either (LineRectangle.cs is embedded, Text.cs is not). So emitting ContainedText.DropshadowBlur for a member that doesn't exist compiles Glue perfectly and only fails in the user's game project, as CS1061.

This is why the bug class recurs: Rectangle/Circle's fill/stroke family (#1907), the Arc/ColoredCircle gradient CS0266, and Text's dropshadow-channel + LocalizeText family were each found by a user's build breaking, not by CI.

GlueUnitTests/GumPlugin/GumRuntimeMemberContractTests.cs is the guard: it builds the engine's Forms solution, reflects over the real GumCore/SkiaInGum assemblies, and asserts every ContainedXxx.Member the generator emits exists on the mapped runtime type. It's driven off StandardsCodeGenerator.StandardElementToQualifiedTypes, so a standard element added to that map is covered automatically. When Gum extends a standard element's schema, that test — not the compiler — is what tells you whether FRB's runtime can back it.

Note the fix is per-member, not per-type: Text legitimately backs HasDropshadow/DropshadowOffsetX/DropshadowOffsetY (it has a single DropshadowColor) while having no per-channel color, no blur, and no LocalizeText. Skip only what's actually unbacked.

Where it lives

Property pipeline:

• Central orchestrator: FRBDK/Glue/GumPlugin/GumPlugin/CodeGeneration/StandardsCodeGenerator.cs
• Per-type contributors: NineSliceCodeGenerator.cs, TextCodeGenerator.cs, ContainerCodeGenerator.cs, etc. (same folder)
• Wired up in MainGumPlugin.cs (each per-type generator is instantiated and passed into StandardsCodeGenerator).

State pipeline:

• FRBDK/Glue/GumPlugin/GumPlugin/CodeGeneration/StateCodeGenerator.cs
• Two relevant entry points: RefreshVariablesToSkipForStates() (unconditional skips and per-type contributions) and RefreshVariableNamesToSkipBasedOnGlueVersion() (version-gated skips, the right place for a GluxVersions-keyed gate).