gum-runtime-topology - SKILL.md Agent Skill

name: gum-runtime-topology description: Map of Gum's render-backend projects and every place that compiles shared Gum source. Triggers: moving/renaming/deleting runtime or GumCommon/RenderingLibrary files, AllLibraries.sln, SkiaGum.Wpf, FRB GumCoreShared/Forms shproj, duplicate same-FQN build errors, "what must I rebuild after a runtime refactor."

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/Gum and GitHub/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/LineCircle are full filled + rounded + drop-shadowed shapes (they mirror Apos/Skia — see the <inheritdoc cref="SkiaGum...SkiaShapeRuntime"> in Runtimes/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-specific RoundedRectangleRuntime/ColoredCircleRuntime types — 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. GumCommon is the runtime-agnostic core (net8.0, no XNA/WPF). It cherry-picks files from RenderingLibrary/, 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. GueDeriving runtimes are canonical in MonoGameGum/GueDeriving/ and <Compile Include ... Link>-ed into the Raylib/Skia/Sokol csprojs. These are deliberately excluded from GumCoreShared.projitems (FRB generates its own runtime classes).
FRB shared projects (the two ../FlatRedBall/...shproj above) — source-sharing for an out-of-repo consumer on a net6 floor.

Landmines

RenderingLibrary is not a built assembly. It's a source directory distributed by links/projitems, so RenderingLibrary.* types exist in several compiled assemblies at once.
Same-FQN forks. Because of the above, two files can define the same RenderingLibrary.X type for different consumers and silently diverge. Confirmed example: GumCommon/Content/LoaderManager.cs (XNA-free; used by every GumCommon-referencing runtime) vs RenderingLibrary/Content/LoaderManager.cs (XNA-coupled — InvalidTexture, Initialize, LoadOrInvalid; compiled only by GumCoreShared.projitems + FRB GumPlugin.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 LoaderManager into GumCommon/Content/ meant dropping its explicit <Compile Include> link and removing SkiaGum's <Compile Remove>.)
projitems / Forms / net6 sync. Adding/renaming/deleting files under GumCommon/ or MonoGameGum/ (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).