gumcli

# Gum CLI Setup > **This skill is the mechanical setup only.** `gumcli` scaffolds the project and flat named controls; the user owns visual layout and composition in the Gum editor afterward — see the `content-boundary` skill for that AI/human split. **Ask the Gum mode question at game-start time** — before any code is written, not when Gum UI is about to be implemented. This affects project structure and cannot be changed easily mid-build. When starting any new game or sample, ask: > "Before we start: will this project use Gum for UI (menus, HUD, labels)? If so, which mode? > 1. **Code-only** — UI defined entirely in C#, no .gumx file, no Gum editor > 2. **Project + dynamic access** — .gumx project file (editable in the Gum editor), access elements at runtime via `GetFrameworkElementByName<T>()` (returns a cast, no compile-time safety) > 3. **Project + codegen** — .gumx project file + gumcli generates strongly-typed C# classes; access screens/components directly as typed properties with full IntelliSense" If the user chooses **code-only (mode 1)**, skip this skill and proceed with the `gum-integration` skill. If the user chooses **mode 2 or 3**, follow the steps below to create the project. For mode 3, also run codegen after any edits to the Gum XML files. --- ## Step 1 — Install gumcli gumcli ships as a .NET global tool ([docs](https://docs.flatredball.com/gum/cli/cli)). Install once per machine: ```bash dotnet tool install -g GumCli ``` After install, invoke as `gumcli` from any terminal. Upgrade with `dotnet tool update -g GumCli`. --- ## Step 2 — Create the Gum Project Run from the game/sample project directory: ```bash gumcli new Content/GumProject/GumProject.gumx ``` This creates: ``` Content/GumProject/ GumProject.gumx Screens/ Components/ Standards/ Behaviors/ ExampleSpriteFrame.png ``` Use `GumProject.gumx` as the default name unless the user requests otherwise. **The generated project includes ready-to-use Forms controls** (Button, TextBox, CheckBox, ListBox, etc.) as component and standard files under `Components/` and `Standards/`. These controls are fully functional out of the box — no extra setup needed. **Important**: When adding Forms controls to a screen, define them as instances in the Gum screen `.gusx` XML file (or a component `.gucx` file), not just in C# code. Defining them in the XML lets the user open the project in the Gum editor and tweak visuals after the fact. Only fall back to pure-code instantiation for controls that are fully dynamic (e.g., a list whose count is data-driven at runtime). --- ## Step 3 — Add Content Includes to .csproj Add a wildcard include so all Gum project files are copied to output: ```xml <ItemGroup> <Content Include="Content\GumProject\**" CopyToOutputDirectory="PreserveNewest" /> </ItemGroup> ``` --- ## Naming Convention (Mode 3 — Codegen) When using codegen, Gum screen/component names collide with FRB2 `Screen` subclass names if both use the same identifier in the same namespace. **Use a `Gum` suffix on all Gum XML elements** to avoid this: - Gum XML screen: `MainMenuScreenGum` → generates class `MainMenuScreenGum : FrameworkElement` - FRB2 screen: `MainMenuScreen : Screen` → instantiates `new MainMenuScreenGum()` This convention applies to screens and any components that would otherwise conflict with C# class names in the project. Standard controls (Button, Label, etc.) already have unique names and don't need the suffix. --- ## Step 4 — Codegen (Required for Mode 3, Optional for Mode 2) **Do not manually create `ProjectCodeSettings.codsj`** — run `codegen-init` once to auto-detect the `.csproj` and generate it: ```bash gumcli codegen-init Content/GumProject/GumProject.gumx ``` This sets `CodeProjectRoot`, `RootNamespace`, and `OutputLibrary` automatically. Only needed once per project. Then run codegen after any edits to Gum XML files: ```bash gumcli codegen Content/GumProject/GumProject.gumx ``` Or generate a specific element only: ```bash gumcli codegen Content/GumProject/GumProject.gumx --element MainMenuScreenGum ``` Exit codes: `0` = success, `1` = elements blocked by errors, `2` = load/config failure. **Codegen generates two files per element**: `ElementName.Generated.cs` (never edit) and `ElementName.cs` (partial stub with `CustomInitialize()` for UI-specific setup). The FRB2 `Screen` class is separate — do not confuse the Gum `CustomInitialize` partial with the FRB2 screen's `CustomInitialize`. **Old generated files are NOT deleted automatically** when you rename a Gum element. Always manually delete stale `.Generated.cs` and `.cs` stub files before re-running codegen after a rename. **Workflow rule (mode 3)**: After any edit to a `.gusx`, `.gucx`, or `.gutx` file — including adding instances, renaming, or changing types — always run `gumcli check` then `gumcli codegen` before writing C# code that references those elements. The generated classes live in the project as regular `.cs` files — check them in alongside the Gum XML. --- ## Font Generation FRB2 can generate fonts in memory from installed system font families, so plain `Font="Arial"` style usage often works without pre-baked files. Use this command when the Gum project relies on generated bitmap caches (especially `UseCustomFont=true` + `CustomFontFile`) and needs deterministic `.fnt`/`.png` output: ```bash gumcli fonts Content/GumProject/GumProject.gumx ``` - **Windows-only** — bmfont.exe does not run on Linux/macOS. On non-Windows the command exits with code `2`. - Only generates fonts that don't already exist on disk; safe to re-run. - Font files land in `FontCache/` next to the `.gumx` file. Add that folder to `.gitignore` or check it in depending on your CI setup. - Run this after `gumcli new` if the project template includes screens with font-bearing Text instances, or any time a new font/size combination is added in the Gum editor. ### Google Font workflow (issue #371 class of requests) Google Fonts links are usually specimen pages, not runtime font files. The reliable flow is: download the `.ttf`/`.otf` into the Gum project, point Gum text styles at that file, then regenerate font caches. 1. Save the font file under `Content/GumProject/Fonts/` (for example `Content/GumProject/Fonts/Inter-Regular.ttf`). 2. In Gum (usually on a shared text style like `Styles/Normal`), set: - `UseCustomFont = true` - `CustomFontFile = Fonts/Inter-Regular.ttf` (project-relative path) 3. Run `gumcli check`, then `gumcli fonts`: ```bash gumcli check Content/GumProject/GumProject.gumx gumcli fonts Content/GumProject/GumProject.gumx ``` 4. If using mode 3 (codegen), run `gumcli codegen` after the Gum XML change. --- ## Known Warnings in Generated Code After running codegen, the standard controls (`ButtonStandard`, `TextBox`, `CheckBox`, etc.) produce CS0114/CS0108 "hides inherited member" warnings. These come from the Gum-generated `*.Generated.cs` files and are expected — do not try to fix them. They do not affect runtime behavior. ## Step 5 — Verify the Project After creation, check for errors: ```bash gumcli check Content/GumProject/GumProject.gumx ``` Exit code `0` = no errors. Fix any reported errors before continuing. --- ## Loading the Gum Project at Runtime See the `gum-integration` skill for how to pass the project path to `EngineInitSettings` and instantiate Gum screens from the project in C#.