Documentation Docs/en/reference/font-format/validation.md

Font Validation Contract

Generated reference. Do not edit directly. Update BuildTools/FontFormatInterface.json, then run python BuildTools/docs_font_format.py --write.

Index

Formats

Stable ID	Rule	Requirement	Why	Source
`font-format.validation.descriptor-and-image-presence`	Descriptor and image presence	Fail the asset gate when the descriptor is missing, FOFNT omits Image, or the relative image cannot load as an atlas sprite. The runtime reports missing descriptor and image files, but currently has no explicit empty-Image guard.	Pre-runtime validation must cover the omitted-Image case because the loader reaches image_name.back() before it can produce a diagnostic.	Source/Client/FontManager.cpp
`font-format.validation.fofnt-header`	FOFNT header and UTF-8	Reject a FOFNT whose first key is not Version, whose version exceeds 2, or whose Letter line does not contain one valid UTF-8 codepoint.	These are hard parser failures rather than recoverable missing-glyph cases.	Source/Client/FontManager.cpp
`font-format.validation.bmfont-header`	BMFont header, padding, and pages	Reject BMFont descriptors that are not binary v3, do not use 1/1/1/1 padding, or declare any page count other than one.	The runtime has explicit exceptions for all three incompatibilities.	Source/Client/FontManager.cpp
`font-format.validation.signed-bmfont-metrics`	Unsigned BMFont metric limitation	Track that the current loader reads xoffset, yoffset, and xadvance with GetLEUInt16 even though bundled binary fonts contain negative bearings.	Values such as -2 are currently reinterpreted as 65534 and can move rendered glyphs far outside their intended position; the runtime fix belongs in a separate code change.	Source/Client/FontManager.cpp, Source/Common/FileSystem.h
`font-format.validation.scale-range`	Scale range	Reject NaN, infinity, zero, negative values, and values greater than one before mutating the font table or atlas.	The Engine supports deterministic bind-time downscaling, not bitmap upscaling.	Source/Client/FontManager.cpp
`font-format.validation.generated-contract`	Generated contract drift	Regenerate and check the font-format model whenever parser keys, binary constants, font enums, binding dispatch, raw-copy defaults, scale, cache, or bundled descriptors change.	The checked model makes silent source/documentation drift fail CI.	BuildTools/docs_font_format.py
`font-format.validation.engine-tests`	Engine regression gates	Run the focused documentation test and the full generated Engine unit-test target after FontManager or font descriptor changes.	Structural checks pin source-derived contracts while native tests cover resource and client construction paths.	Source/Tests/Test_Mapper.cpp, Source/Tests/Test_ClientServerIntegration.cpp
`font-format.validation.embedding-project`	Embedding-project bake and visible check	Bake descriptor and image resources, run measurement tests for every bound scale, and visibly inspect regular, bordered, wrapped, aligned, localized, and missing-glyph cases.	A raw-copy success cannot prove glyph coverage, atlas padding, typography, backend rendering, or GUI fit.	Source/Scripting/ClientGlobalScriptMethods.cpp, Source/Client/FontManager.cpp

Validation commands

python BuildTools\docs_font_format.py --check
python -m unittest BuildTools.tests.test_docs_font_format
cmake --build <build-dir> --config RelWithDebInfo --target RunUnitTests

An embedding project must also bake the descriptor and image together, run its text-measurement regression, and inspect representative regular, bordered, scaled, wrapped, and localized text in a visible client.