agentleFS
vchelaruvchelaru/Gum/.claude/skills/gum-samples/SKILL.md

gum-samples

Skill659 starsChanged 2 months agoMITView on GitHub

Where runtime-feature demo screens go. Triggers: adding a sample/demo page for a new runtime feature, NineSliceScreen/SpriteScreen, shape demos, MonoGameGumInCode, Samples/raylib, SilkNetGum.

The file

Files
SKILL.md

Gum Sample Projects

When a runtime feature needs a visual demo (so a human can eyeball it across backends), add a screen to the three cross-backend feature samples, keeping them aligned. Shape demos included — they live in the feature samples on every backend, same as any other feature (see "Shape features" below).

The "big three" refers to the three backends below (Silk.NET/Skia, raylib, MonoGame) — one feature sample each.

The three feature samples (add here by default)

SampleBackendPathScreen base / registration
MonoGameGumInCodeMonoGame (XNA)Samples/MonoGameGumInCode/MonoGameGumInCode/FrameworkElement; nav button in Game1.BuildNavStrip
raylib galleryraylibSamples/raylib/FrameworkElement; nav button in Program.BuildNavStrip (Examples.Shapes namespace)
SilkNetGumSkiaSharp via Silk.NETSamples/SilkNetGum/SilkNetGumSample/FrameworkElement; factory in Program.codeScreenFactories, keyboard nav

Each has a Screens/ folder with one *Screen.cs per feature (SpriteScreen, NineSliceScreen, …). MonoGameGumInCode is the reference — mirror its screen section-for-section in the other two so the same screen can be opened side by side and any per-backend rendering difference stands out as a backend bug. The existing screen headers say exactly this ("Raylib mirror of …", "Mirror of MonoGameGumInCode.Screens…").

Prefer one shared screen file over three mirrors. A screen shared via <Compile Include Link=> (see the last gotcha below) cannot drift. SpriteScreen.cs, TextScreen.cs and the shape galleries already work this way: the canonical copy lives in MonoGameGumInCode/Screens/, and the file switches namespace and paths with #if RAYLIB / #elif SKIA / #else (SpriteScreen.cs is the smallest example). Set colors through Red/Green/Blue and add children with Children.Add so the body needs no per-backend types; use #if only for content path prefixes and for rows a backend cannot render yet. NineSliceScreen, ArcsScreen and PolygonsScreen are still per-backend mirrors.

Mirror even when the underlying bug is backend-specific. A fix that only reproduces on one backend (e.g. a raylib-only render-target/framebuffer quirk) is still a reason to add the demo cell to every mirrored screen, not just the one you're fixing — the point of mirroring is a side-by-side visual comparison, and skipping the other backends breaks that even though their code has nothing to fix. This applies to adding a new cell to an existing gallery screen (e.g. one more case in RenderTargetScreen), not just to creating a brand-new screen file. (Missed on issue #3464: only the raylib cell was added at first, because the fix itself was raylib-only — caught in review.)

Mirroring means the same relative position, not just presence. With TopToBottomStack layout, visual order is call order, so a new section must land at the same point in the sequence in every mirror, not just be appended wherever happens to compile. Landing it after a block of code that only exists in one backend shifts every later row out of alignment in that file relative to the others, breaking the side-by-side comparison even though every screen still "has" the section. Verify by reading all mirrored files top to bottom, not just diffing for the cell's presence. (Missed on issue #3496: MonoGame's TextScreen.cs carried a legacy AddCustomOutlineText block raylib never had, so a later section landed three rows lower in MonoGame than in raylib.)

Cross-backend gotchas when mirroring

  • Texture paths differ. MonoGame uses MGCB Content/ names ("Frame.png"); raylib loads from disk ("resources\\Frame.png", copied via the resources\**\*.* glob in GumTest.csproj); SilkNetGum loads from Content/GumProject/. Drop any new texture into each sample's content dir.
  • Color types differ. MonoGame Microsoft.Xna.Framework.Color, raylib Raylib_cs.Color, Skia SKColor. Pick the nearest named color per backend.
  • Not every property exists on every backend. A runtime property may be #if-gated away from a backend (see [[gum-cross-platform-unification]]). If the mirrored screen won't compile, the feature isn't wired on that backend yet — that's the actual work, not the screen.
  • raylib and SilkNetGum screens need using Gum.Forms.Controls; for FrameworkElement.
  • A backend can share a screen file via <Compile Include Link= instead of owning a physical copy (raylib's GumTest.csproj and SilkNetGum's csproj link TextScreen.cs and SpriteScreen.cs from MonoGameGumInCode/.../Screens/ — no such file sits under Samples/raylib/). Don't grep/find a backend's directory to conclude a screen is missing; check its .csproj for a Link= entry first.

Shape features

Shapes (Circle, Rectangle, RoundedRectangle, Arc, Polygon, Line — the shape runtimes) are demoed in the normal feature samples on every backend, same as any other feature: CirclesScreen, RectanglesScreen, ArcsScreen, PolygonsScreen, GradientScreen, ClippingScreen. Mirror a new shape cell across all three like any feature.

raylib and Skia render shapes natively. MonoGame's shape rendering comes from the separate Gum.Shapes package (MonoGameGumShapes), which MonoGameGumInCode references via ProjectReference so its shape screens light up. There is no KNI feature sample — KNI shares the XNALIKE render path the MonoGame screens exercise, so it needs no separate shape demo.

MonoGame/KNI host init (landmine). Referencing the package is not enough — the game host must call ShapeRenderer.Self.Initialize() (namespace Gum.Renderables; the old MonoGameAndGum.Renderables is an obsolete shim) after GumService.Default.Initialize(...), and set GraphicsProfile.HiDef (Apos.Shapes uses an SM4 effect that Reach can't load). Miss either and shape fills/effects silently do not draw — no error. See docs/code/standard-visuals/shapes-apos.shapes.md.

Multi-service sample (MultiGumServiceSample)

Samples/MultiGumServiceSample/ runs two GumServices in one MonoGame window, each loading its own .gumj from Content/Game and Content/Editor. Its screens are generated JSON, so edit them in the Gum tool or by script, and run gumcli check on both projects afterward.

GameUiSamplesSkia (a game ported to the KNI Skia host)

Samples/GameUiSamplesSkia/ is Samples/GameUiSamples/ (Stardew, HyTale, Hollow Knight, FRB clicker) drawn by SkiaGum through Runtimes/KniSkiaGum instead of the XNA-family renderer. It is a copy with its own generated code (SyntaxVersion 5, so Gum.GueDeriving, not MonoGameGum.GueDeriving), so a change to the game's screens has to be made in both. Porting traps: Skia colors are SKColor (XNA Color in a state Value or property assignment fails at run time or compile time). Verify without running the exe by rendering each screen to an SKSurface and comparing against gumcli screenshot of the original project.

KNI Skia counterparts of the MonoGame/KNI samples

Samples/KniSkiaGumFromFile, KniSkiaGumImmediateMode, KniSkiaGumInCode, KniSkiaGumFontLoading and KniSkiaGumCodeGeneration are the KNI Skia versions of the samples with the same suffix, built on the Samples/KniSkiaGum host setup. KniSkiaGumFromFile has no Gum project of its own: its csproj copies Samples/KniGumFromFile/KniGumFromFileContent to Content/, so editing that project changes both samples. KniSkiaGumCodeGeneration owns a copy of the MonoGame sample's Gum project, because its ProjectCodeSettings.codsj names a different namespace; its *.Generated.cs come from gumcli codegen on that copy.

Host-embedded samples (SkiaGumWpfSample, MauiSkiaGum)

Samples/SkiaGumWpfSample/ and Samples/MauiSkiaGum/ aren't feature samples — they demo Gum embedded inside a host UI framework (WPF, MAUI) that already has its own native controls. There, Gum is typically the visualization/canvas layer, not a Forms-control replacement for the host's own buttons/text boxes — see GumSKElement/SkiaGumCanvasView (Runtimes/SkiaGum.Wpf/, Runtimes/SkiaGum.Maui/), each owning its own SystemManagers so one host app can embed multiple independent Gum canvases. Don't add a Forms-control (Button, TextBox) demo here just because Forms exist on this backend.

Verification is human-driven

These samples exist for visual confirmation. Samples wired to the automation driver (MonoGameGumInCode through Tests/Gum.Automation; the KNI Skia samples through Tests/Gum.Automation.KniSkia, which compiles the same sources with KNISKIA) can also run off-screen with --gum-automation Automation/smoke.ndjson --gum-automation-hide (Debug only); controls a script targets need a Name. After adding a screen, build the sample and tell the user to run it and eyeball the new screen. Behavioral correctness still gets a unit test in the matching Tests/* project (see [[tdd]]) — the sample is the visual complement, not a replacement.

A brand-new standalone sample project (not one of the "big three") still ships a .sln alongside its .csproj, mirroring FontPlayground.MonoGame.sln — the user opens and runs these in Visual Studio, not via dotnet run.

That .sln also enrolls the sample in CI automatically: build-samples.yaml runs .github/scripts/build-all.ps1 -Path Samples, which globs every .sln/.slnx under Samples/ and builds it on a windows-latest runner. A sample that can't restore or build there (a Mac-only head, a hand-cloned dependency) has to be added to that script's $excludeLeafNames.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.