vchelaru Gum Runtime Topology
Gum has no single "runtime" assembly. The same RenderingLibrary.* / GumCommon source is compiled into many assemblies via three different source-sharing mechanisms, and is also consumed by FlatRedBall (FRB), a separate repo. A refactor that builds clean in AllLibraries.sln can still break the WPF runtime or FRB. Before moving/renaming/deleting any shared file, check it against every surface below.
FRB is a separate git repo, but Gum and FRB are always checked out side by side (
GitHub/GumandGitHub/FlatRedBall), so../FlatRedBall/...reaches FRB from the Gum repo root.
Compilation surfaces — rebuild/verify ALL for a runtime-level refactor
| Surface | What it is | Notes |
|---|---|---|
AllLibraries.sln |
All render backends + GumCommon + shapes + themes + CLI + ProjectServices + tests |
Must compile on Mac, so it EXCLUDES Windows-only projects. The broad verify command — but not complete. |
Runtimes/SkiaGum.Wpf/SkiaGum.Wpf.csproj |
WPF host for the Skia runtime | NOT in AllLibraries (WPF can't build on Mac). Build separately on Windows. The single easiest runtime to forget. |
GumFull.sln |
The Gum tool (KNI-based) + plugins | Tool work; $(SolutionDir) post-builds require the solution, not a bare csproj. |
GumCoreShared.shproj |
Gum-side shared project (imports GumCoreShared.projitems) |
Source-shares Gum core into FRB. The file lists live in the .projitems. |
../FlatRedBall/FRBDK/Glue/GumPlugin/GumPlugin/GumCoreShared.FlatRedBall.shproj |
FRB-side core consumer | FRB multi-targets down to net6.0 — gate net7+ BCL APIs. |
../FlatRedBall/Engines/Forms/FlatRedBall.Forms/FlatRedBall.Forms.Shared/FlatRedBall.Forms.Shared.shproj |
FRB-side Forms consumer | Picks up MonoGameGum/Forms/** files individually; new/renamed Forms files must be registered here. |
Render backends
XNA-family (MonoGameGum, KniGum, FnaGum), RaylibGum, SkiaGum (+ hosts SkiaGum.Maui, SkiaGum.Wpf), SokolGum. For the per-runtime file-sharing/unification pattern see gum-cross-platform-unification.
Shapes are NOT MonoGame/Skia-only — no backend is the outlier
Shape runtimes (RectangleRuntime/CircleRuntime — corner radius, two-slot fill/stroke, drop shadows, dashed strokes, gradients) are unified across all backends, and every backend reaches full capability via its recommended renderable; only the contained renderable differs:
| Backend | Contained renderable (recommended path) |
|---|---|
| raylib / Sokol | LineRectangle / LineCircle |
| Skia | RoundedRectangle (#2818) |
XNA-family + Apos.Shapes (MonoGameGumShapes/KniGumShapes, recommended) |
Apos RoundedRectangle |
| XNA-family, no Apos | SolidRectangle+LineRectangle split — degraded fallback, no real radius/shadow |
The no-Apos XNA split is a degraded fallback, not a separate tier or an outlier. Two traps that produced wrong conclusions here:
- ⚠ Don't infer capability from type names. raylib's
LineRectangle/LineCircleare full filled + rounded + drop-shadowed shapes (they mirror Apos/Skia — see the<inheritdoc cref="SkiaGum...SkiaShapeRuntime">inRuntimes/RaylibGum/Renderables/), despite the outline-suggesting names. A directory listing is not the API surface — read the renderable. - ⚠ The
MonoGameGumShapes/KniGumShapes↔SkiaGum"pair" (in gum-cross-platform-unification) is only a source-sharing link for the Apos-specificRoundedRectangleRuntime/ColoredCircleRuntimetypes — not a claim that shape support is MonoGame/Skia-only or that raylib lacks it.
Consequence for themes: a rounded/shadowed theme's visual code (new RectangleRuntime { CornerRadius = …, HasDropshadow = … }) is portable to raylib at the type level — the shape layer is a non-issue.
Three source-sharing mechanisms (each is a separate landmine)
- GumCommon project reference.
GumCommonis the runtime-agnostic core (net8.0, no XNA/WPF). It cherry-picks files fromRenderingLibrary/,GumDataTypes/,ToolsUtilities/via<Compile Include="..\X" Link="..."/>and globs its own folder. MonoGame/Raylib/Skia/Sokol reference it as a project. - Cross-project file links.
GueDerivingruntimes are canonical inMonoGameGum/GueDeriving/and<Compile Include ... Link>-ed into the Raylib/Skia/Sokol csprojs. These are deliberately excluded fromGumCoreShared.projitems(FRB generates its own runtime classes). - FRB shared projects (the two
../FlatRedBall/...shprojabove) — source-sharing for an out-of-repo consumer on a net6 floor.
Landmines
RenderingLibraryis not a built assembly. It's a source directory distributed by links/projitems, soRenderingLibrary.*types exist in several compiled assemblies at once.- Same-FQN forks. Because of the above, two files can define the same
RenderingLibrary.Xtype for different consumers and silently diverge. Confirmed example:GumCommon/Content/LoaderManager.cs(XNA-free; used by every GumCommon-referencing runtime) vsRenderingLibrary/Content/LoaderManager.cs(XNA-coupled —InvalidTexture,Initialize,LoadOrInvalid; compiled only byGumCoreShared.projitems+ FRBGumPlugin.csproj). Editing one does not touch the other; placing both in one compilation is a duplicate-type error. - Moving a file between a glob'd folder and a linked location requires a csproj edit. GumCommon and the runtime projects glob their own folders; external shared files are explicit links. (E.g. relocating the shared
LoaderManagerintoGumCommon/Content/meant dropping its explicit<Compile Include>link and removing SkiaGum's<Compile Remove>.) - projitems / Forms / net6 sync. Adding/renaming/deleting files under
GumCommon/orMonoGameGum/(and Forms files) has sync obligations to the FRB shared projects, with explicit exceptions (the LoaderManager fork,GueDeriving). These rules are authoritative in the coder agent (.claude/agents/coder.md) — follow them there, don't restate.
Cross-references
- gum-cross-platform-unification — per-runtime file unification (
#if/links). .claude/agents/coder.md— projitems/Forms/net6 sync rules (authoritative).