Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

Per-Runtime Availability

Runtime
Dynamic generation today

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.

Available in preview NuGet packages (use a -preview version), or now if building Gum from source.

  1. Add the KernSmith.MonoGameGum NuGet package to your project.

  2. 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.

  1. Add the KernSmith.KniGum NuGet package to your project.

  2. Call UseKernSmith() after initializing Gum:

Once this is set up, font properties work automatically:

  1. Add the KernSmith.RaylibGum NuGet package to your project.

  2. 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.

  1. Add the KernSmith.FnaGum NuGet package to your project.

  2. 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 Font to that family name. That is what this section covers.

  • Assign the .ttf path to Font or CustomFontFile and skip registration. See Using a .ttf Path Directly below.

To register a .ttf file:

  1. Add the .ttf file to your project's Content folder.

  2. Set its Copy to Output Directory to Copy if newer. For an easier approach that handles all content files at once, see the wildcard .csproj setup in Loading a Gum Project (.gumj/.gumx).

  3. Call RegisterFont before using the font. The method is on the font creator type for your runtime: KernSmithFontCreator on MonoGame, KNI, and FNA, and KernSmithRaylibFontCreator on 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:

A byte[] overload is also available for fonts loaded from embedded resources, HTTP responses, or other non-file sources. For example: KernSmithFontCreator.RegisterFont("MyFont", fontBytes).

Registered fonts take priority over system fonts. If you register a font with the family name "Arial", KernSmith uses your registered .ttf instead of the system-installed Arial.

Shipping September 2026: the raylib KernSmithRaylibFontCreator.RegisterFont(familyName, filePath) overload ships in the September release, or now if building Gum from source. Before this, raylib had only the byte[] overload, so a raylib game had to read the file itself.

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.

Gum detects a font file from its extension. See Supported Files for the extensions each runtime accepts.

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.

Shipping September 2026: loading a .ttf from a bundle or a custom source ships in the September release, or now if building Gum from source. Before this, Gum read a .ttf straight off the filesystem, and the byte[] overload of RegisterFont was the workaround.

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.

This is KernSmith's behavior, so it covers MonoGame, KNI, FNA, and raylib. SkiaSharp-based runtimes behave differently, see Bold and Italic on SkiaGum.

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:

GenerateRangesFromFile reads every character in the file. A localization file holding every supported language returns the union of all of them, not just the language your player selected. Split the file per language first for a tighter range.

Both AddFontRange and AddCharacters are static and apply to every BmfcSave created afterward, so call them once before creating any Text.

AddFontRange and AddCharacters only add to the default range, they can't replace it. To generate a font from an exact character set instead of extending the default, see Custom Character Sets, which replaces the set entirely but requires the manual generation path rather than TextRuntime's font properties.

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 .fnt files 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.

Font/CustomFontFile is detected as a file path purely by whether the string ends in a font file extension, not by whether it looks like a path. A bare filename with no directory ("MyFont.ttf") is loaded from disk the same as a full path, and it never falls through to an OS font-name lookup. See Supported Files for the extensions each runtime accepts.

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.RegisterFont falls 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 a Bold and an Italic version if you need those styles.

  • A .ttf assigned by path points at one file, and that file is what you get whatever IsBold and IsItalic are 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.

A dedicated SkiaGum fonts page is planned. For now, this section is the canonical reference. If something is unclear, ask on Discord or open an issue.

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:

CustomFontFile also accepts a .ttf path, which is a different strategy: the font is rasterized on demand and the style properties above do apply. See Using a .ttf Path Directly. Everything on this page's Custom Font File section is about the .fnt case.

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.

WhitePeaberryOutline font in the Solution Explorer

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.

Copy if newer property set

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 .fnt file backs a given TextRuntime.

  • 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

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.

This path requires the KernSmith package for your runtime (KernSmith.MonoGameGum, KernSmith.KniGum, or KernSmith.RaylibGum). The bridge type GumFontGenerator lives in KernSmith.GumCommon, which is a transitive dependency.

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:

The Channels setting matters. Gum's text renderer expects a specific channel layout: alpha = glyph (RGB = 1) when there is no outline, and alpha = outline (RGB = glyph) when there is one. GumFontGenerator.BuildOptions sets this for you — if you build options from scratch you must set it yourself or text will render incorrectly.

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 BitmapFont instance shared across many TextRuntimes 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 TextRuntime does 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.Ranges value you'd want to ship.

  • You need a different rasterizer backend, such as RasterizerBackend.StbTrueType on 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

This approach is primarily useful when your project already has pre-generated font files from the Gum tool. For MonoGame, KNI, FNA, and Raylib, Dynamic KernSmith Generation is the recommended approach; for SkiaSharp-based runtimes see Dynamic Generation on SkiaGum.

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?