gum-tool-font-generation

name	gum-tool-font-generation
description	Gum bitmap font generation — tool converts font properties into .fnt/.png via bmfont.exe or KernSmith. Triggers: BmfcSave, HeadlessFontGenerationService, FontManager, FontFileGeneratorSelector, KernSmithFileGenerator, BmfcTemplate.bmfc, texture size estimation, dropshadow.

Font Generation Pipeline

Gum generates BMFont-format bitmap fonts (.fnt + .png atlas). Pipeline: collect font properties → build BmfcSave → pick a generator backend → produce .fnt + .png. Two interchangeable IFontFileGenerator backends exist, chosen per-project via GumProjectSave.FontGenerator (FontGeneratorType.BmFont, the default for back-compat, or .KernSmith):

• BmFontExeFileGenerator shells out to the embedded bmfont.exe (Windows-only). Legacy path; does not support dropshadow at all — BmfcTemplate.bmfc has no dropshadow placeholders, so BmfcSave.HasDropshadow/Dropshadow* fields are silently ignored on this backend.
• KernSmithFileGenerator calls the KernSmith library in-process (cross-platform, no external exe, supports dropshadow). This is the newer, recommended backend.

FontFileGeneratorSelector picks between them at generation time (project isn't loaded yet when DI wires services up, so selection can't happen at construction).

Architecture

FontManager (tool facade)
  └─ HeadlessFontGenerationService (core logic, headless)
       ├─ BmfcSave (data model + .bmfc serialization)
       │    └─ BmfcTemplate.bmfc (template file with placeholders, bmfont.exe only)
       └─ FontFileGeneratorSelector → BmFontExeFileGenerator | KernSmithFileGenerator

FontManager is the tool-facing entry point. It wires IFontGenerationCallbacks (UI output, spinner, file-watch suppression) and delegates all real work to HeadlessFontGenerationService via IHeadlessFontGenerationService.

HeadlessFontGenerationService is platform-checked for the bmfont.exe backend only (throws PlatformNotSupportedException off-Windows when FontGeneratorType.BmFont is selected). It owns:

• Collecting all unique fonts a project needs (CollectRequiredFonts)
• Deciding whether a font file already exists or needs (re)generation
• Invoking the selected IFontFileGenerator — one call per font, all awaited via Task.WhenAll for parallelism
• Texture size estimation (heuristic) and optimization (binary search over AvailableSizes)

Texture-size estimation is bmfont.exe-specific and does not run for KernSmith. EstimateBlocksNeeded's heuristic (and the dropshadow blindness that falls out of it) only matters for BmFontExeFileGenerator. IFontFileGenerator.RequiresSizeEstimation (false on KernSmithFileGenerator, true on BmFontExeFileGenerator) gates the whole AssignEstimatedNeededSizeOn call in HeadlessFontGenerationService — KernSmith instead sizes its own atlas via FontGeneratorOptions.AutofitTexture.

BmfcSave holds the six font properties (FontName, FontSize, OutlineThickness, UseSmoothing, IsItalic, IsBold) plus ranges, spacing, and output dimensions. Its Save() method loads BmfcTemplate.bmfc and does string replacement to produce the .bmfc file that bmfont.exe consumes. It also owns FontCacheFileName which determines the output path.

Generation Flow

1. Property collection: TryGetBmfcSaveFor reads font properties from a StateSave (with optional instance prefix and forced overrides) and returns a BmfcSave or null. For direct Text instances this is sufficient, but for component instances containing Text, CollectFontsFromNestedTextInstances recursively descends using RecursiveVariableFinder to resolve font properties through exposed variables and inheritance.
2. Deduplication: CollectRequiredFonts iterates all elements/states/instances and deduplicates by FontCacheFileName (a deterministic name encoding all font parameters).
3. Size estimation: Before generating, AssignEstimatedNeededSizeOn either runs a binary-search optimization (GetOptimizedSizeFor, controlled by AutoSizeFontOutputs project setting) or uses a heuristic lookup table (EstimateBlocksNeeded) based on effective font size.
4. Template expansion: BmfcSave.Save() loads Content/BmfcTemplate.bmfc, replaces placeholders, and writes the .bmfc file alongside the target .fnt path.
5. bmfont.exe invocation: CreateBitmapFontFilesIfNecessaryAsync launches bmfont.exe -c "<bmfc>" -o "<fnt>" via Process.Start with UseShellExecute = true. The process is awaited async (WaitForExitAsync) or synchronously depending on createTask.
6. File-watch suppression: Before writing, all expected output paths (.bmfc, .fnt, .png pages) are registered with IFontGenerationCallbacks.OnIgnoreFileChange so the file watcher doesn't trigger reloads.

Font Cache Naming

BmfcSave.FontCacheFileName produces paths like FontCache/Font18Arial.fnt. The name encodes all parameters that affect output:

• Base: Font{size}{name} (spaces in font name → underscores)
• Suffixes: _o{N} (outline), _noSmooth, _Italic, _Bold

This means two elements with identical font settings share one cached file.

Channel Behavior (Outline vs No-Outline)

When OutlineThickness is 0: alpha=0, RGB channels=4 (glyph in alpha channel). When OutlineThickness > 0: alpha=1, RGB channels=0 (outline uses color channels).

Texture Size Optimization

GetOptimizedSizeFor does a binary search over AvailableSizes (32x32 up to 8192x8192) to find the smallest texture that keeps the font on a single page. Each probe generates the font to a temp directory and parses the pages= line from the resulting .fnt file.

The heuristic fallback (EstimateBlocksNeeded) uses a lookup table mapping effective font size to a number of 256-pixel blocks, then factors the block count into width x height.

Character Ranges

• Default: 32-126,160-255 (ASCII + Latin-1 Supplement)
• Project-level FontRanges setting overrides for all fonts
• Ranges are validated (no spaces, proper start < end), with automatic fallback to default
• Space character (32) is always included via EnsureRangesContainSpace
• Large range sets are split across multiple chars= lines (max 10 blocks per line) for bmfont.exe compatibility
• GenerateRangesFromFile can derive ranges from a text file's unique characters

Embedded Resources

bmfont.exe and BmfcTemplate.bmfc are embedded in the Gum.ProjectServices assembly and extracted on first use by EnsureToolsExtracted. The template uses placeholder tokens like FontNameVariable, FontSizeVariable, {UseSmoothing}, etc.

Standalone CLI

GumProjectFontGenerator is a standalone console app that loads a .gumx project and generates all missing fonts. It uses HeadlessFontGenerationService directly with no callbacks.

Font Creation Paths

All font generation now routes through HeadlessFontGenerationService. There are two call sites:

On-demand: CustomSetPropertyOnRenderable resolves IFontManager via DI (Builder.Get<IFontManager>()) and calls CreateFontIfNecessary(BmfcSave) when a font property changes. The BBCode path (GetAndCreateFontIfNecessary) uses the same pattern for inline font tags.

Bulk (tool-only): CreateAllMissingFontFiles scans the entire project on load or "regenerate fonts" and generates all missing font files in parallel.

Both delegate to HeadlessFontGenerationService. Legacy IRuntimeFontService, GenerateMissingFontsForReferencingElements, and the embedded bmfont.exe in RenderingLibrary have been removed.

Key Files

File	Purpose
Gum/Services/Fonts/IFontManager.cs	Interface for the tool-facing font manager
Gum/Services/Fonts/FontManager.cs	Tool facade — delegates to headless service via DI
Tools/Gum.ProjectServices/FontGeneration/HeadlessFontGenerationService.cs	Core generation logic — collection, size estimation, bmfont.exe invocation
Tools/Gum.ProjectServices/FontGeneration/IHeadlessFontGenerationService.cs	Interface for the headless service
Tools/Gum.ProjectServices/FontGeneration/IFontGenerationCallbacks.cs	Callback interface (output, spinner, file-watch ignore)
Gum/Services/Fonts/ToolFontGenerationCallbacks.cs	Tool-specific callback implementation
RenderingLibrary/Graphics/Fonts/BmfcSave.cs	Font data model, .bmfc serialization, cache file naming, range utilities
Gum/Content/BmfcTemplate.bmfc	Template with placeholders for bmfont.exe config
GumProjectFontGenerator/Program.cs	Standalone CLI for batch font generation