> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/code/files-and-fonts/fonts.md). # Fonts ## Introduction Gum supports several font loading strategies. The right one depends on your character set, your localization needs, and what you're willing to pay in build time, memory, and runtime cost. This page is a decision tree. Pick the path that matches your game, then follow the link for the full details and code samples. For the API surface (which properties on `TextRuntime` control the font), see the [TextRuntime Fonts](/gum/code/standard-visuals/textruntime/fonts.md) page. ## Pick a Strategy ### Path A — Small charset (Latin, Cyrillic, Greek, and similar) **Use dynamic font generation.** No font files on disk, no cache to manage, no preloading needed. The first time a `(font, size, style)` combination is used, the atlas is generated in memory — fast enough for most games with small character sets to do during gameplay without a noticeable hitch. How this works depends on the runtime: MonoGame and KNI use the KernSmith NuGet package. SkiaGum has its own built-in dynamic generation. Raylib, Sokol, and FNA don't have dynamic generation today — for those, follow Path D. This is the default recommendation for most projects. → See [Font Strategies — Dynamic KernSmith](/gum/code/files-and-fonts/fonts/font-strategies.md#dynamic-kernsmith-generation) (MonoGame/KNI) or [Dynamic Generation on SkiaGum](/gum/code/files-and-fonts/fonts/font-strategies.md#dynamic-generation-on-skiagum). ### Path B — Large charset (CJK), single locale per build **Use KernSmith with a preloading step.** A CJK atlas is large enough that generating it mid-gameplay produces a visible hitch. Generate every `(font, size, style)` combination your game uses during a loading screen, then play the game. → See [Font Preloading](/gum/code/files-and-fonts/fonts/font-preloading.md) and [Font Strategies — Dynamic KernSmith](/gum/code/files-and-fonts/fonts/font-strategies.md#dynamic-kernsmith-generation). ### Path C — Large charset, runtime locale switching **Use per-locale atlases and regenerate on locale change.** The player picks Japanese; you generate the Japanese atlas. They switch to Korean; you swap. The full design (per-locale character ranges, `FontCache//` layout, hooking the `ILocalizationService.CurrentLanguageChanged` event) is in [Phase 3 of the font roadmap](https://github.com/vchelaru/Gum/issues/2695) and is not fully implemented yet. → See [Font Localization](/gum/code/files-and-fonts/fonts/font-localization.md) for the current state, the planned design, and the limitations to plan around today. ### Path D — Pre-baked FontCache (.fnt files on disk) **Use the build-time FontCache.** Useful when: * You want pixel-perfect determinism (atlases are checked into source control and never regenerated). * Dynamic generation is not yet available for your runtime (Raylib, Sokol, FNA today). * You have hand-tuned `.fnt` files from another tool and want to ship them as-is. The Gum tool generates these atlases automatically while you edit your project. There is no opt-out yet. → See [Font Cache](/gum/code/files-and-fonts/fonts/font-cache.md). ## Hub Contents * [Font Strategies](/gum/code/files-and-fonts/fonts/font-strategies.md) — concrete details and code samples for each strategy above. * [Font Performance](/gum/code/files-and-fonts/fonts/font-performance.md) — what costs each strategy, where the hitches live. * [Font Preloading](/gum/code/files-and-fonts/fonts/font-preloading.md) — making sure every font/size/style your game uses is ready before gameplay starts. * [Fonts on Web](/gum/code/files-and-fonts/fonts/fonts-web.md) — bandwidth vs CPU tradeoffs for web targets. * [Font Localization](/gum/code/files-and-fonts/fonts/font-localization.md) — current behavior, known limitations, and the per-locale design that's coming. * [Font Cache](/gum/code/files-and-fonts/fonts/font-cache.md) — the build-time `.fnt` atlas system, naming convention, and when to use it. ## Need Outline Color, Shadows, or Gradients? The strategies above all drive fonts through `TextRuntime`'s property surface, which exposes only a subset of what KernSmith can actually generate. If you want outline color (not just thickness), drop shadows, gradient fills, SDF, color fonts, custom glyph subsets, or a non-default rasterizer backend, build a `BitmapFont` via KernSmith yourself and assign it directly. See [Advanced Font Effects](/gum/code/files-and-fonts/fonts/advanced-font-effects.md) for the per-effect catalog and [Font Strategies — Direct BitmapFont Assignment](/gum/code/files-and-fonts/fonts/font-strategies.md#direct-bitmapfont-assignment) for the construction walkthrough. ## Known Limitations The following items are not yet supported. None of them are dealbreakers for shipping a game, but they're worth knowing about so you can plan around them: * **No multi-texture batching.** Gum renders one texture per draw call. A text-heavy UI (for example a long list with a background atlas and a text atlas) alternates atlases on every row, costing one draw call per alternation. See [Font Performance](/gum/code/files-and-fonts/fonts/font-performance.md) for what this means in practice. * **No packing of font glyphs into UI sprite sheets.** Font atlases are their own textures; they don't share with `NineSlice` or `Sprite` art. * **No on-disk cache for KernSmith-generated atlases.** Every cold start regenerates them. (Planned — [Phase 4](https://github.com/vchelaru/Gum/issues/2696).) * **No project-wide unified atlas.** Text and UI live in separate textures by design. * **No opt-out for the tool's FontCache generation.** The tool bakes `.fnt` files for every text instance you edit, even if your shipped game uses KernSmith exclusively. (Planned — [Phase 3](https://github.com/vchelaru/Gum/issues/2695).) * **No per-locale character ranges yet.** The tool currently bakes a single FontCache containing the union of every character used anywhere in the project. (Planned — [Phase 3](https://github.com/vchelaru/Gum/issues/2695).) ## Related Pages * [TextRuntime Fonts](/gum/code/standard-visuals/textruntime/fonts.md) — the API reference: properties on `TextRuntime` that control font selection. * [BitmapFont](/gum/code/files-and-fonts/bitmapfont.md) — text measurement API and character info. * [File Loading](/gum/code/files-and-fonts/file-loading.md) — `RelativeDirectory`, file caching, and general file loading. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.flatredball.com/gum/code/files-and-fonts/fonts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.