Command Reference
generate
Generate BMFont files from a font. This is the main command.
kernsmith generate -f <font> -s <size> [options]
Font Source (one required)
| Flag | Description |
|---|---|
-f, --font <path> |
Font file path (TTF, OTF, WOFF, WOFF2) |
--system-font <name> |
Use a system-installed font by family name |
--face <n> |
Face index for .ttc collections (default: 0) |
Size and Rendering
| Flag | Description |
|---|---|
-s, --size <n> |
Font size in pixels — accepts fractional (e.g. 10.5) (required) |
--dpi <n> |
DPI (default: 72) |
--aa <mode> |
Anti-aliasing: none, grayscale, light, lcd (default: grayscale) |
--lcd-filter <filter> |
LCD filter for --aa lcd: default, light, smooth, none (Native only; other backends ignore it). .bmfc key lcdFilter |
--lcd-order <order> |
LCD subpixel order for --aa lcd: rgb (default), bgr, vrgb, vbgr (Native only; other backends ignore it). .bmfc key lcdOrder |
--mono |
Disable anti-aliasing (alias for --aa none) |
--sdf |
Enable Signed Distance Field rendering |
--sdf-spread <n> |
SDF search radius (spread) in pixels (default: 8) |
--sdf-mode <mode> |
Distance field: none, sdf, msdf or mtsdf. msdf/mtsdf write RGBA multi-channel fields and need --rasterizer native |
--super-sample <n> |
Super sampling level 1-4 (default: 1). Not applied to --aa lcd output, which renders at the final size |
--gamma <n> |
Gamma correction applied during rasterization (FreeType, default: 1.8) |
--hinting / --no-hinting |
Enable/disable hinting (default: on). Native hints only with --aa light |
--rasterizer <name> |
Rasterizer backend: freetype (default), gdi, directwrite, stbtruetype, native (experimental, not on NuGet) |
--height-percent <n> |
Vertical height scaling percentage (default: 100) |
--width-percent <n> |
Synthetic condensed/expanded width percentage, 10-1000 (default: 100). Native only; other backends fail with a generation error. .bmfc key widthPercent |
--match-char-height |
Match rendered height to requested pixel height |
--advance-x <n> |
Global horizontal advance adjustment added to every glyph (alias --advance-adjust-x, default: 0) |
--fallback-char <char> |
Fallback character for missing glyphs |
Style
| Flag | Description |
|---|---|
-b, --bold |
Enable bold (uses native face when available, falls back to synthetic) |
-i, --italic |
Enable italic (uses native face when available, falls back to synthetic) |
--synthetic-bold |
Force synthetic bold, skip native bold face lookup |
--synthetic-italic |
Force synthetic italic, skip native italic face lookup |
--italic-angle <deg> |
Synthetic italic slant in degrees, -60 to 60, positive leans right (default: 12). Other values need Native. .bmfc key italicAngle |
--color-font |
Enable color font rendering (COLR/CPAL layers, CBDT/sbix bitmaps) |
--color-palette <n> |
Color palette index (default: 0) |
With --font (file path), --bold and --synthetic-bold produce identical results since there is no font family to search. With --system-font, --bold tries the native bold face first; --synthetic-bold forces synthetic on the regular face. GDI backend limitation: cannot apply synthetic bold when a native bold face exists -- use FreeType or DirectWrite.
Character Set
| Flag | Description |
|---|---|
-c, --charset <preset> |
Preset: ascii (default), extended, latin |
--chars <string> |
Explicit characters to include |
--chars-file <path> |
Read characters from a UTF-8 text file |
--range <start-end> |
Unicode range in hex (repeatable) |
Character set options can be combined. Multiple --range flags are allowed.
# Specific characters only
kernsmith generate -f font.ttf -s 32 --chars "ABCabc0123"
# Unicode range
kernsmith generate -f font.ttf -s 32 --range 0020-007E --range 00A0-00FF
Texture Atlas
| Flag | Description |
|---|---|
--max-texture <n> |
Maximum texture size in pixels (default: 1024) |
--max-texture-width <n> |
Maximum texture width (independent of height) |
--max-texture-height <n> |
Maximum texture height (independent of width) |
--autofit |
Auto-fit smallest texture size for all glyphs |
--padding <n> |
Uniform padding around each glyph (default: 0) |
--padding <u,r,d,l> |
Per-side padding (up, right, down, left) |
--spacing <n> |
Spacing between glyphs (default: 1) |
--spacing <h,v> |
Horizontal and vertical spacing |
--pot / --no-pot |
Force power-of-two textures (default: on) |
--packer <alg> |
Packing algorithm: maxrects (default), skyline |
--channel-pack |
Pack glyphs into individual RGBA channels |
--equalize-heights |
Equalize all glyph cell heights |
--force-offsets-zero |
Set all xoffset/yoffset to zero |
Effects
| Flag | Description |
|---|---|
--outline <n>[,color] |
Outline width in pixels, optional hex color |
--outline-shape <shape> |
Outline corner shape: round (default), square, or plus; .bmfc key is outlineShape |
--outline-mode <mode> |
effect (default: core's bitmap outline, every backend) or vector (the backend draws the outline from the glyph's vector outline; Native only, other backends keep the effect; not with SDF). .bmfc key outlineMode |
--fill-color <color> |
Base glyph fill color as hex #RRGGBB or #RRGGBBAA (default: FFFFFF, opaque white) |
--gradient <top>,<bottom> |
Vertical gradient with hex colors |
--gradient-angle <degrees> |
Gradient rotation angle |
--gradient-midpoint <0.0-1.0> |
Gradient midpoint / bias |
--gradient-offset <n> |
Gradient positional offset along its axis (default: 0) |
--gradient-scale <n> |
Gradient scale factor along its axis (default: 1) |
--gradient-cyclic |
Repeat (cycle) the gradient instead of clamping at its ends |
--shadow <x>,<y>[,color[,blur]] |
Drop shadow with offset, optional color and blur |
--shadow-blur-kernel <n> |
Shadow blur kernel size (default: 0) |
--shadow-blur-passes <n> |
Number of shadow blur passes; more = softer (default: 1) |
--hard-shadow |
Use a crisp shadow silhouette instead of soft antialiased edges |
--shadow-variant |
Also emit an unoffset, untinted "-shadow" .fnt/atlas (shared atlas pass) for draw-time positioning/coloring; .bmfc equivalent is variantShadow=1 |
Effects can be combined freely. All color values are hex (e.g., FF0000 for red).
# 3px red outline
kernsmith generate -f font.ttf -s 32 --outline 3,FF0000
# Tinted glyph fill
kernsmith generate -f font.ttf -s 32 --fill-color "#FF8800"
# Gradient with shadow
kernsmith generate -f font.ttf -s 48 --gradient FFFFFF,888888 --shadow 2,2,000000,1
# Offset/scaled cyclic gradient
kernsmith generate -f font.ttf -s 48 --gradient FF0000,0000FF --gradient-offset 0.25 --gradient-scale 2 --gradient-cyclic
# Soft shadow via blur kernel + passes
kernsmith generate -f font.ttf -s 48 --shadow 2,2,000000 --shadow-blur-kernel 3 --shadow-blur-passes 2
# All three effects
kernsmith generate -f font.ttf -s 48 --outline 2,000000 --gradient FFFFFF,888888 --shadow 2,3,000000,2
Kerning
| Flag | Description |
|---|---|
--kerning |
Enable kerning (default: on) |
--no-kerning |
Disable kerning pair extraction |
Variable Fonts
| Flag | Description |
|---|---|
--axis <tag>=<value> |
Set a variation axis value (repeatable) |
--instance <name> |
Use a named instance's axis values (--axis overrides single axes; an unknown name lists the font's instances) |
kernsmith generate -f RobotoFlex.ttf -s 32 --axis wght=700 --axis wdth=90
kernsmith generate -f RobotoFlex.ttf -s 32 --instance "Bold"
Output
| Flag | Description |
|---|---|
-o, --output <path> |
Output path without extension (default: ./<fontname>) |
--format <fmt> |
Output format: text (default), xml, binary |
--texture-format <fmt> |
Texture format: png (default), tga, dds |
Configuration and Debugging
| Flag | Description |
|---|---|
--config <path> |
Load settings from a .bmfc or .hiero configuration file (format auto-detected by inspecting file content, with the extension used only as a fallback when the content is inconclusive) |
--save-config <path> |
Save current settings to a .bmfc or .hiero file (format chosen by the file extension; .hiero writes a Hiero config, otherwise BMFont) |
--dry-run |
Show what would be generated without writing files |
--time |
Print actual generation time (excludes CLI startup) |
--profile |
Print stage-level timing breakdown |
-v, --verbose |
Show detailed progress |
-q, --quiet |
Suppress all output except errors |
Exit Codes
Commands report their outcome with these process exit codes:
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Invalid arguments (and batch when any job failed) |
2 |
File not found |
3 |
Font could not be parsed |
4 |
Generation error -- including a backend rejecting the font or an option (e.g. --rasterizer stbtruetype --color-font), printed to stderr as Error: Generation error (<backend> rasterizer): <message> |
5 |
Output could not be written |
10 |
Config file could not be parsed |
init
Generate a .bmfc or .hiero configuration file from CLI flags without rendering a font. Accepts all the same flags as generate.
kernsmith init [options]
The -o flag sets the output config file path; the format is chosen by its extension. A .hiero extension writes a Hiero (libGDX) config; a path with no extension defaults to .bmfc (default: font.bmfc).
# Scaffold a config
kernsmith init --system-font "Arial" -s 32 -o my-font.bmfc
# Config with effects
kernsmith init --system-font "Arial" -s 48 --outline 3,0055AA -o my-font.bmfc
# Write a Hiero (.hiero) config instead
kernsmith init --system-font "Arial" -s 32 -o my-font.hiero
# Then generate from it
kernsmith generate --config my-font.bmfc
batch
Process multiple .bmfc and/or .hiero config files in a single invocation. Each file's format is auto-detected by inspecting its content (the extension is used only as a fallback when the content is inconclusive), so mixed batches are allowed. A failed job does not stop other jobs.
kernsmith batch <config1.bmfc> [config2.hiero ...] [options]
| Flag | Description |
|---|---|
<paths> |
One or more .bmfc / .hiero paths (supports glob patterns) |
--jobs <file> |
Text file listing config paths (one per line, # comments) |
--parallel <n> |
Max parallel jobs (default: 1, 0 = all CPU cores) |
--time |
Show total elapsed time in summary |
kernsmith batch fonts/*.bmfc --parallel 4 --time
kernsmith batch configs/*.bmfc configs/*.hiero --parallel 4
kernsmith batch --jobs jobs.txt --parallel 0
benchmark
Benchmark font generation performance. Runs N+1 iterations (first is warmup) and reports timing statistics. No files are written.
kernsmith benchmark -f <font> -s <size> [options]
| Flag | Description |
|---|---|
-f, --font <path> |
Font file path |
--system-font <name> |
System font by family name |
-s, --size <n> |
Font size in pixels — accepts fractional (e.g. 10.5) (default: 32) |
-c, --charset <preset> |
Character set (default: ascii) |
--packer <alg> |
Packing algorithm (default: maxrects) |
--iterations <n> |
Number of timed iterations (default: 10) |
kernsmith benchmark -f roboto.ttf -s 32 --iterations 20
inspect
Inspect an existing .fnt file. Auto-detects text, XML, and binary formats.
kernsmith inspect <path> [--json]
Shows font face, size, style, character count, kerning pairs, page count, texture dimensions, line height, Unicode ranges, and page filenames.
kernsmith inspect myfont.fnt
kernsmith inspect myfont.fnt --json
convert
Convert between BMFont .fnt formats. Atlas page images are automatically copied to the output directory.
kernsmith convert <input> -o <output> [--format <text|xml|binary>]
Output format is inferred from the file extension when --format is not specified (.fnt = text, .xml = XML, .bin = binary).
kernsmith convert myfont.fnt -o myfont.xml
kernsmith convert myfont.fnt -o output/myfont.fnt --format binary
list-fonts
List system-installed fonts, grouped by family.
kernsmith list-fonts [--filter <pattern>] [--json]
kernsmith list-fonts
kernsmith list-fonts --filter "roboto"
kernsmith list-fonts --json
benchmark-fonts
Benchmark font resolution (LoadFont) cost across every installed font family — distinct from benchmark, which times font generation. Runs a cold pass (first resolution per family) and a warm pass (repeat resolution) in the same process, so the effect of the per-family resolved-font cache is visible in one invocation.
kernsmith benchmark-fonts [--filter <pattern>] [--json]
| Flag | Description |
|---|---|
--filter <pattern> |
Only benchmark families matching this substring (case-insensitive) |
--json |
Output as JSON |
kernsmith benchmark-fonts
kernsmith benchmark-fonts --filter "roboto"
kernsmith benchmark-fonts --json
list-rasterizers
List available rasterizer backends on the current platform. Shows each backend's availability, platform support, and capabilities (color fonts, variable fonts, SDF, vector outline, synthetic bold/italic, system fonts).
kernsmith list-rasterizers
FreeType is the default backend and is available on Windows, Linux x64, and macOS (not Linux arm64 -- use StbTrueType there; see the platform support table). The GDI and DirectWrite backends are Windows-only alternatives.
kernsmith list-rasterizers
Rasterizer Examples
# Use GDI for BMFont-parity rendering (Windows only)
kernsmith generate -f font.ttf -s 32 --rasterizer gdi
# Use FreeType for color/variable font support (cross-platform)
kernsmith generate -f font.ttf -s 32 --rasterizer freetype --color-font
# KernSmith's own pure-C# rasterizer (experimental)
kernsmith generate -f font.ttf -s 32 --rasterizer native
# Default (FreeType, cross-platform)
kernsmith generate -f font.ttf -s 32
The native backend is experimental and ships with the CLI only (there is no NuGet package yet). It renders TrueType (.ttf) and CFF/CFF2 (.otf) outlines, variable fonts of both kinds (--axis, --instance), COLR version 0 and 1 color glyphs and CBDT/sbix bitmap emoji (--color-font, scaled to the requested size) and synthetic bold/italic. It is the only backend for --sdf-mode msdf|mtsdf, --outline-mode vector, --width-percent, --italic-angle other than 12, and --lcd-order/--lcd-filter. --aa light with hinting on applies its own vertical-only auto-hinting, --aa lcd renders LCD subpixel RGBA glyphs, and --aa none keeps thin strokes with dropout control. It has no TrueType bytecode hinting (other modes render unhinted) and no system fonts.
info
Show metadata from a font file (TTF, OTF, WOFF, WOFF2). Displays family name, style, glyph count, kerning pairs, variation axes, named instances, and Unicode coverage.
kernsmith info <path> [--json]
kernsmith info Roboto-Regular.ttf
kernsmith info RobotoFlex.ttf --json