Documentation
Docs/en/reference/font-format/bmfont.md
Binary BMFont Contract
Generated reference. Do not edit directly. Update
BuildTools/FontFormatInterface.json, then runpython BuildTools/docs_font_format.py --write.
| Index | Formats | FOFNT | BMFont | Binding | Layout | Rendering | Validation | Canonical JSON | Guide |
| Stable ID | Rule | Requirement | Why | Source |
|---|---|---|---|---|
font-format.bmfont.binary-v3-signature |
Binary v3 signature | The first four bytes must be B, M, F, and binary-format version 3. | Any other signature or BMFont version is rejected before block parsing. | Source/Client/FontManager.cpp |
font-format.bmfont.block-order |
Fixed block order | Export Info, Common, Pages, and Chars blocks in standard binary order without interposed optional blocks. | The parser advances by each block size and reads the next block payload directly; it does not search by block type. | Source/Client/FontManager.cpp |
font-format.bmfont.info-padding |
One-pixel exporter padding | Set BMFont Info padding up, right, down, and left to exactly one pixel each. | The loader requires the four padding bytes to equal 0x01010101 and later removes one pixel from each side of every glyph rectangle. | Source/Client/FontManager.cpp |
font-format.bmfont.single-page |
Single texture page | Export exactly one texture page. | The Common block page count must be one; multi-page BMFont descriptors are rejected. | Source/Client/FontManager.cpp |
font-format.bmfont.relative-page-image |
Relative page image | Store a NUL-terminated page filename resolvable relative to the .fnt descriptor directory. | The Pages payload is read as one string and combined with the descriptor directory before sprite loading. | Source/Client/FontManager.cpp |
font-format.bmfont.char-records |
Twenty-byte character records | Encode each Chars record in the 20-byte BMFont v3 layout. The format defines signed xoffset, yoffset, and xadvance fields, but the current loader reads all three as unsigned little-endian uint16 values; avoid negative metrics until that runtime defect is fixed separately. | Bundled fonts contain negative bearings, so this source-backed limitation must remain visible instead of being documented as correct signed decoding. | Source/Client/FontManager.cpp, Source/Common/FileSystem.h |
font-format.bmfont.metric-conversion |
Engine metric conversion | Reserve one transparent pixel around every glyph; the loader shifts x/y inward, removes two pixels from width/height, negates bearings, and adds one pixel to xadvance. | The Engine samples an expanded rectangle for antialiasing and optional border dilation while keeping the visible glyph metrics separate. | Source/Client/FontManager.cpp |
font-format.bmfont.line-metrics |
Derived line metrics | Expect Engine LineHeight to use the visible W glyph height when W exists, otherwise Common.base; YAdvance is half that resulting height. | The BMFont Common.lineHeight field is used for bearing conversion but is not copied directly into the Engine line height. | Source/Client/FontManager.cpp |
font-format.bmfont.gray-bordered |
Grayscale and border preparation | Binary BMFont bindings always normalize nontransparent pixels to gray and create a second bordered atlas copy. | This makes runtime tinting and FontFlag::Bordered available without descriptor-specific switches. | Source/Client/FontManager.cpp |