Font Strategies
Introduction
This page covers each font loading strategy in detail with code samples and tradeoffs. To decide which strategy fits your game, start with the decision tree on the Fonts hub page.
The strategies are:
Dynamic KernSmith Generation — recommended for MonoGame, KNI, FNA, and Raylib.
Dynamic Generation on SkiaGum — SkiaSharp-based runtimes rasterize glyphs themselves via SkiaSharp, separate from KernSmith.
Custom Font File — load a specific
.fntfile you ship with the game.Direct BitmapFont Assignment — fully manual.
Build-Time Font Cache — pre-baked atlases from the Gum tool.
Per-Runtime Availability
MonoGame
Yes — via KernSmith.
KNI
Yes — via KernSmith.
Raylib
Yes — via KernSmith (KernSmith.RaylibGum).
FNA
Yes — via KernSmith (KernSmith.FnaGum).
Yes, uses SkiaSharp's own glyph rasterization; no KernSmith package needed. See Dynamic Generation on SkiaGum.
Dynamic KernSmith Generation
KernSmith is an in-memory font generator for MonoGame, KNI, FNA, and Raylib. Install the NuGet package for your runtime and KernSmith generates font atlases at runtime so you can freely change font properties without managing files on disk.
Add the
KernSmith.MonoGameGumNuGet package to your project.Call
UseKernSmith()after initializing Gum:
Once this is set up, font properties work automatically. Setting Font, FontSize, IsBold, IsItalic, OutlineThickness, UseFontSmoothing, and baked drop shadow (HasDropshadow plus the dropshadow fields) on a TextRuntime generates the needed font in memory without any font files on disk:
Any combination of font properties can be used and the font is created on demand.
Add the
KernSmith.KniGumNuGet package to your project.Call
UseKernSmith()after initializing Gum:
Once this is set up, font properties work automatically:
Add the
KernSmith.RaylibGumNuGet package to your project.Call
UseKernSmith()after initializing Gum:
Once this is set up, font properties work automatically — the same TextRuntime fields as MonoGame/KNI, including baked drop shadow. See TextRuntime Fonts — Baked drop shadow.
Add the
KernSmith.FnaGumNuGet package to your project.Call
UseKernSmith()after initializing Gum:
Once this is set up, font properties work automatically:
Dynamic font generation is not yet available on Sokol. Use the Build-Time Font Cache strategy.
System Fonts vs Registered Fonts
By default, KernSmith resolves the Font property by looking up fonts installed on the operating system. Setting Font = "Times New Roman" works because that font is typically installed on Windows.
System fonts are convenient for quick prototyping, but they have drawbacks for shipping a game:
Platform differences — a font installed on your development machine may not exist on a player's machine or on other platforms (Linux, macOS, mobile).
Version inconsistency — different OS versions may ship different versions of the same font, causing subtle rendering differences.
Licensing — system fonts may have licenses that restrict redistribution in games.
For these reasons, registering your own .ttf (or .otf) files is recommended for any font you plan to ship with your game. This guarantees every player sees the same font regardless of their operating system.
Registering Custom .ttf Fonts
There are two ways to use a .ttf file with KernSmith:
Register it under a family name, then set
Fontto that family name. That is what this section covers.Assign the
.ttfpath toFontorCustomFontFileand skip registration. See Using a .ttf Path Directly below.
To register a .ttf file:
Add the
.ttffile to your project's Content folder.Set its Copy to Output Directory to Copy if newer. For an easier approach that handles all content files at once, see the wildcard
.csprojsetup in Loading a Gum Project (.gumj/.gumx).Call
RegisterFontbefore using the font. The method is on the font creator type for your runtime:KernSmithFontCreatoron MonoGame, KNI, and FNA, andKernSmithRaylibFontCreatoron raylib. The parameters are the same on both.
Once registered, use the font by its family name just like a system font:
You can register multiple fonts, including different styles for the same family:
Using a .ttf Path Directly
Gum loads a Font value ending in .ttf as a font file rather than looking it up as an installed font family. It decides this from the extension alone, so a path works with no register call:
CustomFontFile accepts a .ttf path the same way when UseCustomFont is true. Both properties resolve their paths relative to FileManager.RelativeDirectory, which is your Content folder, or the folder holding your .gumj project. This is the same starting point every other Gum asset uses, including RegisterFont's filePath overload. See File Loading.
Where a .ttf Can Live
Gum reads a .ttf the same way it reads any other asset, whether you hand the path to RegisterFont or assign it to Font. A font packed into a .gumpkg bundle loads exactly like a file on disk, and so does one served by your own FileManager.CustomGetStreamFromFile function. That lets you keep fonts in an asset zip, an embedded resource store, or a download cache.
When no source has the font, Gum quietly falls back to the 18 pixel Arial embedded in the libraries. Subscribe to CustomSetPropertyOnRenderable.PropertyAssignmentError to see what went wrong.
Bold and Italic With One Registered Face
KernSmith uses a real bold or italic face when one is available. When none is, it builds the style out of the regular letters instead, thickening them for bold and slanting them for italic. Type designers call that faux bold and faux italic.
A face counts as available if you registered it under that family name, or, for a system font, if the operating system has it installed. All three of these produce bold text:
A real bold face almost always looks better than a built one, so register the styles you care about when you have the files. Either way the text comes out bold, and it stays in your typeface.
KernSmith can also build the style even when a real face exists, which makes every platform render the same letters. TextRuntime does not expose that option, so reaching it means calling KernSmith yourself. See Forcing Synthetic Bold and Italic on the Advanced Font Effects page.
Character Ranges
Every BmfcSave starts with BmfcSave.DefaultRanges, 32-126,160-255 (ASCII plus Latin-1 Supplement). Extend that default project-wide with BmfcSave.AddFontRange, which takes the same comma-separated start-end/single-codepoint format, or BmfcSave.AddCharacters, which takes literal characters and converts each one to its codepoint:
For a localized game, BmfcSave.GenerateRangesFromFile builds the range from your actual localization file instead of guessing a Unicode block:
Both AddFontRange and AddCharacters are static and apply to every BmfcSave created afterward, so call them once before creating any Text.
When to Use This Strategy
You're using Latin, Cyrillic, Greek, or another small-charset script.
You want to change font, size, style, outline thickness, or baked drop shadow without rebuilding atlases.
You don't want to check generated
.fntfiles into source control.For CJK or other large charsets, this strategy still works. Pair it with Character Ranges to build a range that matches your actual content, and with Font Preloading so the per-atlas generation cost happens on a loading screen rather than during gameplay.
Player-typed or localized text can introduce characters you didn't plan for ahead of time — see Automatic Glyph Growth to grow the live atlas instead of silently falling back to a blank glyph.
Dynamic Generation on SkiaGum
Every SkiaSharp-based runtime shares this font path, and none of them uses KernSmith. SkiaSharp rasterizes glyphs directly, so dynamic font generation works out of the box. No NuGet package to install, no UseKernSmith() call.
System Fonts
Assign the font properties directly on the TextRuntime; the family name must be installed on the system to resolve:
Custom .ttf Files
Point Font (or CustomFontFile with UseCustomFont = true) at a .ttf path instead of a family name. SkiaSharp-based runtimes load and cache the file automatically, the same as the .ttf-path route on the KernSmith runtimes:
SkiaSharp-based runtimes read the file the same way they read any other asset, so a .ttf served by your own FileManager.CustomGetStreamFromFile function loads exactly like a file on disk. See Where a .ttf Can Live.
For a font you already hold as bytes, an embedded resource for example, call SkiaGum.Content.Fonts.GumFontMapper.RegisterFont(familyName, fontBytes) and then assign Font = familyName. That method also takes an optional style name, so you can register a bold or italic version alongside the regular one.
Bold and Italic on SkiaGum
SkiaSharp-based runtimes answer IsBold and IsItalic by picking a typeface, never by building one. The KernSmith runtimes instead fall back to faux bold and faux italic (see Bold and Italic With One Registered Face). What you get here depends on where the font came from:
A font registered with
GumFontMapper.RegisterFontfalls back to the family's regular version when you have not registered one for the style you asked for. The text stays in your font, at regular weight. Register aBoldand anItalicversion if you need those styles.A
.ttfassigned by path points at one file, and that file is what you get whateverIsBoldandIsItalicare set to.A system font family name goes to SkiaSharp, which returns the closest face the operating system has installed for the weight and slant you asked for.
Custom Font File
If you have a specific .fnt file (created with the Gum tool, Angelcode Bitmap Font Generator, Hiero, or another tool), you can load it directly by setting UseCustomFont to true and assigning CustomFontFile:
For information on creating your own .fnt file with Angelcode Bitmap Font Generator, see the Use Custom Font page.
This code assumes a font file named WhitePeaberryOutline.fnt is located in the Content/WhitePeaberryOutline folder. By default all Gum content loading is performed relative to the Content folder. See the File Loading page for more information.
.fnt files reference one or more image files, so the image file must also be added to the correct folder. In this case the WhitePeaberryOutline.fnt file references a WhitePeaberryOutline.png file, so both files are in the same folder.

Files are loaded from-file rather than using the content pipeline. This means that extensions (such as .fnt) are included in the file path, and that both the .fnt and .png files must have their Copy to Output Directory value set to Copy if newer.

The easiest way to mark all content as "Copy to Output Directory" is to use wildcard items in your .csproj. For instructions (including Android), see Loading a Gum Project (.gumj/.gumx).
When to Use This Strategy
You have a single hand-authored bitmap font you want to ship as-is.
You want full control over which
.fntfile backs a givenTextRuntime.You don't need to vary size/style/outline at runtime — the file you assign is the file you get.
Direct BitmapFont Assignment
You can construct a BitmapFont yourself and assign it directly, bypassing the font property system entirely. Two sources for the BitmapFont are common:
From a .fnt file on disk — when you already have a baked atlas.
From KernSmith with custom options — when you want visual effects (outline color, gradient fills, SDF, color fonts, custom glyph subsets) or backend control beyond what
TextRuntimeexposes. Baked drop shadow is on the property path — see TextRuntime Fonts.
From a .fnt File on Disk
Load a BitmapFont from a .fnt file (and its companion .png page textures) and assign it:
From KernSmith with Custom Options
TextRuntime exposes a subset of KernSmith's options (Font, FontSize, IsBold, IsItalic, OutlineThickness, UseFontSmoothing, and baked drop shadow via HasDropshadow and the dropshadow fields). To use outline color, gradient fills, SDF, color fonts, custom glyph subsets, or a non-default rasterizer backend, build a BitmapFont yourself by calling KernSmith directly, then assign it.
For the full catalog of effects available through this path, see Advanced Font Effects.
Flow 1: Start from a BmfcSave, mutate options, then generate
This is the most common flow. BmfcSave carries the same font descriptor TextRuntime uses internally — start there so size, style, charset, and smoothing match your normal text, then layer in the extras KernSmith supports:
The helper that wraps a BmFontResult into a BitmapFont is the same pattern KernSmithFontCreator.TryCreateFont uses internally — one Texture2D per atlas page, then the BitmapFont(Texture2D[], string) constructor:
Flow 2: Build FontGeneratorOptions from scratch
If you don't have a BmfcSave to start from — for example you're constructing a one-off display font for a title screen — build the options directly:
Sharing One BitmapFont Across Many TextRuntimes
A single BitmapFont instance can be assigned to any number of TextRuntimes. Generate once, assign many times — there is no per-runtime regeneration cost and the underlying atlas textures are shared:
When to Use This Strategy
You want a single
BitmapFontinstance shared across manyTextRuntimes without each one re-loading from disk.You're loading fonts from a non-standard source (embedded resource, network, custom pipeline) and want to keep the load step out of the property-driven path.
You need effects that
TextRuntimedoes not expose — outline color, gradient fills, SDF, color fonts, or custom glyph subsets. Baked drop shadow is on the property path. See Advanced Font Effects.You need a custom character set that doesn't match any
BmfcSave.Rangesvalue you'd want to ship.You need a different rasterizer backend, such as
RasterizerBackend.StbTrueTypeon Blazor WASM, where the native FreeType library is missing. KernSmith starts with FreeType on every platform, so on web this is a step you have to take, not a tweak. See Backend Selection.
Build-Time Font Cache
If UseCustomFont is false (the default) and no InMemoryFontCreator is registered, a TextRuntime's font is determined by its font component values. These values combine to produce a file name, and the corresponding .fnt file must already exist in a FontCache folder.
For the naming convention, generation rules, and full details, see Font Cache.
When to Use This Strategy
Pixel-perfect determinism: the atlas in source control is the atlas the player sees, every time.
Dynamic generation isn't available for your runtime (Sokol today).
You want zero runtime CPU cost for font generation (atlases are loaded from disk, not generated).
Missing Font Exceptions
By default TextRuntime instances do not throw exceptions for missing font files even if GraphicalUiElement.ThrowExceptionsForMissingFiles is set to CustomSetPropertyOnRenderable.ThrowExceptionsForMissingFiles. This is because a TextRuntime's font is decided by a combination of multiple properties.
If UseCustomFont is false, the font is determined by the combination of font values (size, style, etc.). If UseCustomFont is true, the font is determined by CustomFontFile.
Ultimately the variables which are used for fonts can be assigned in any order and from multiple spots (direct assignments, states, Gum projects). The TextRuntime doesn't know when variable assignment is finished. We can address this in a few ways:
The first is to explicitly load the desired BitmapFont as discussed above. Calling the BitmapFont constructor causes missing files to throw immediately.
Another option is to use the GraphicalUiElement.ThrowExceptionsForMissingFiles method to verify that a font is valid after a TextRuntime has been fully configured:
Last updated
Was this helpful?

