agentleFS
vchelaruvchelaru/Gum/.claude/skills/gum-runtime-fonts/SKILL.md

gum-runtime-fonts

Skill659 starsChanged 2 months agoMITView on GitHub

Gum runtime font loading (MonoGame/KNI) — three loading paths (custom, font-property cache, in-memory generation), lookup cascade, FontCache naming. Triggers: TextRuntime font properties, BitmapFont loading, CustomSetPropertyOnRenderable.UpdateToFontValues, IInMemoryFontCreator.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the file doesn't exist, load silently skips — element gets DefaultBitmapFont

    line 32
  2. Distinctive:

    No property-to-filename mapping.

    line 33
  3. Very specific:

    When registered on CustomSetPropertyOnRenderable.InMemoryFontCreator, font-property changes (Path 2) automatically create fonts on demand.

    line 68
  4. Very specific:

    When UseCustomFont = false and a font property changes, UpdateToFontValues tries these sources in order:

    line 72

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Runtime Font Loading

Gum renders text using BitmapFont — a .fnt descriptor file plus one or more .png texture atlases. There are three ways to get a BitmapFont onto a TextRuntime, each with different tradeoffs. Path 3 (in-memory generation, typically KernSmith) is the recommended route for new projects; pre-generated .fnt files on disk are the older path.

For crisp text under camera/layer zoom, see docs/code/files-and-fonts/font-oversampling.md — TextRuntime.UseFontOversampling rebuilds the font bigger automatically when zoom changes; unrelated to the three loading paths below.

Oversampled text positions

While oversampled, a Text draws from the bigger display font but lays out with the pinned native font, and the two fonts' whole-pixel advances add up to different widths. Layout (wrapping, sizing) uses MeasureString; a position within a line (caret, selection, click, alignment offset) uses IFormsText.MeasureDrawnString or GetDrawnCharacterAdvance. Never fit the drawn glyphs to the measured width: the exact inverse raster ratio keeps each atlas pixel on one screen pixel.

.fnt encodings

BMFont defines three encodings for the same data, and ParsedFontFile picks a branch off the first character. Gum's tool and KernSmith both emit text, so that is the only branch normal users reach. XML requires hand-authoring a file from BMFont's XML export and deserializes via XmlSerializer (so it is not Native AOT safe); binary throws outright. Treat gaps confined to the XML or binary branch as near-zero user impact.

Three Font Loading Paths

Path 1: Custom Font File (UseCustomFont = true)

User provides a pre-built .fnt file directly:

textRuntime.UseCustomFont = true;
textRuntime.CustomFontFile = "fonts/MyFont.fnt";
  • File path resolves relative to FileManager.RelativeDirectory (typically Content/)
  • Loaded via new BitmapFont(path), cached in LoaderManager
  • If the file doesn't exist, load silently skips — element gets DefaultBitmapFont
  • No property-to-filename mapping; user controls the exact file

Path 2: Font Property Cache Lookup (UseCustomFont = false, the default)

Six properties combine into a deterministic filename in FontCache/:

PropertyDefaultEffect on filename
Font / FontFamily"Arial"Base name (spaces → underscores)
FontSize18Base size number
OutlineThickness0_o{N} suffix if non-zero
UseFontSmoothingtrue_noSmooth suffix if false
IsItalicfalse_Italic suffix if true
IsBoldfalse_Bold suffix if true

Naming formula: FontCache/Font{size}{name}[_o{N}][_noSmooth][_Italic][_Bold].fnt

Examples: FontCache/Font18Arial.fnt, FontCache/Font24Times_New_Roman_o1_Bold.fnt. A font file adds _ttf and, in a project at Version 6 or later, a path hash after it; see gum-tool-font-generation.

BmfcSave.GetFontCacheFileNameFor() produces this name. Every property setter on TextRuntime (Font, FontSize, etc.) calls UpdateToFontValues(), which regenerates the filename and attempts to load. The load happens at assignment, before layout, because layout measures the text from the loaded font; see "Layout Runs on Every Assignment" in gum-property-assignment.

Key gotcha: Unless an IInMemoryFontCreator or IRuntimeFontService is registered, the .fnt file must already exist in FontCache/. Users often set FontSize = 24 expecting it to work, but silently get DefaultBitmapFont because Font24Arial.fnt was never generated. There is no error or warning — the text just renders in the default font. A font that was missing is remembered as unresolvable (_knownUnresolvableFontKeys in GetOrCreateBakedFont) only while its file is still missing; the mark is dropped when the file appears.

All platforms (MonoGame/KNI/FNA and Raylib) raise CustomSetPropertyOnRenderable.PropertyAssignmentError when a wired InMemoryFontCreator or FontService throws, or when nothing resolves a usable font. Every raise also goes to Console.Error; the event itself has no default subscriber (the tool's EditorTabPluginBase forwards it to the Output window).

A .fnt that loads but names a page PNG that is missing or undecodable is a different failure: BitmapFont.LoadPageTextureOrPlaceholder swaps in Sprite.InvalidTexture (red X) and raises the same event once per page path. A missing .fnt is never reported this way; that is the normal "not generated yet" case above.

Raylib .fnt loading

RaylibGum's ContentLoader.LoadFont parses every .fnt with Gum's ParsedFontFile, whether it comes from the CustomGetStreamFromFile hook or a loose file; Raylib.LoadFont is never called, because it can't see the hook and crashes the process on a .fnt it can't parse. A raylib Font holds one texture, so a multi-page font's pages are stacked vertically into one texture (BitmapFontAtlasMerger, pure and unit-tested) and each glyph's rec Y is shifted by its page's offset. A .fnt that fails to parse, or whose page can't be read, raises PropertyAssignmentError and yields an empty Font (BaseSize == 0). Binary .fnt is unsupported (see encodings above). RaylibGum.Tests needs a GL context: Windows CI supplies it with Mesa, and on macOS it uses the real GPU through the main-thread test host.

Path 3: In-Memory Font Creation (IInMemoryFontCreator) — New

Generates a BitmapFont entirely in memory at runtime — no pre-built .fnt files needed. The loading code already checks for this; it slots into the cascade between embedded resources and disk-based generation.

When registered on CustomSetPropertyOnRenderable.InMemoryFontCreator, font-property changes (Path 2) automatically create fonts on demand. This eliminates the FontCache pre-population requirement.

Lookup Cascade

When UseCustomFont = false and a font property changes, UpdateToFontValues tries these sources in order:

  1. LoaderManager cache — already-loaded BitmapFont by full path
  2. Embedded resource — MonoGameGum ships Font18Arial (plus Bold/Italic/Bold_Italic variants) as embedded resources; these are the default fonts
  3. IInMemoryFontCreator — generates BitmapFont in memory, no disk I/O
  4. IRuntimeFontService — generates .fnt/.png files on disk, then falls through to step 5 (typically tool-only, not used in game code)
  5. Disk load — new BitmapFont(fullPath) if the file exists
  6. DefaultBitmapFont fallback — Text.DefaultBitmapFont (Font18Arial, set during SystemManagers initialization)

The result is cached in LoaderManager so subsequent lookups for the same font properties hit step 1.

Wiring

SystemManagers initialization (called by GumService.Initialize) sets up the font system:

  • Loads embedded Font18Arial as Text.DefaultBitmapFont
  • Wires GraphicalUiElement.UpdateFontFromProperties → CustomSetPropertyOnRenderable.UpdateToFontValues

Game code can optionally set CustomSetPropertyOnRenderable.InMemoryFontCreator to enable Path 3.

Key Files

FilePurpose
MonoGameGum/GueDeriving/TextRuntime.csUser-facing font properties; each setter calls UpdateToFontValues()
RenderingLibrary/Graphics/Text.csRenderable; holds BitmapFont instance and static DefaultBitmapFont
RenderingLibrary/Graphics/Fonts/BitmapFont.csLoads .fnt + .png textures; stores character metrics
RenderingLibrary/Graphics/Fonts/BmfcSave.csGetFontCacheFileNameFor() — deterministic cache filename from properties
Gum/Wireframe/CustomSetPropertyOnRenderable.csUpdateToFontValues() — orchestrates the lookup cascade
RenderingLibrary/Graphics/Fonts/IInMemoryFontCreator.csInterface for runtime font generation without disk I/O
RenderingLibrary/Graphics/Fonts/IRuntimeFontService.csInterface for disk-based font generation (typically tool-only)
RenderingLibrary/SystemManagers.csWires font delegates and loads default embedded font

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.