BitmapFontParser

View source
ceramic.BitmapFontParser (Class)

Parser for bitmap font definition files in BMFont format.

BitmapFontParser reads and parses font definition files (.fnt) that describe bitmap font layouts. It supports both plain text and XML formats commonly generated by tools like:

  • BMFont (AngelCode)
  • Hiero
  • msdf-bmfont-xml
  • Construct 3 SpriteFont

The parser extracts:

  • Font metadata (face, size, line height)
  • Character definitions with texture coordinates
  • Texture page references
  • Kerning pairs
  • Distance field information (for MSDF fonts)
// Parse a font definition file
var fontData = BitmapFontParser.parse(fontFileContent);

// Create textures from the page files
var textures = new Map<String,Texture>();
for (page in fontData.pages) {
    textures.set(page.file, loadTexture(page.file));
}

// Create the font
var font = new BitmapFont(fontData, textures);
See: BitmapFontData The data structure produced by parsing, BitmapFont The font class that uses parsed data

Static Members

parse(rawFontData: String, ?imagePath: String, ?imageWidth: Int): BitmapFontData

Parses a bitmap font definition file into structured data.

Accepts plain text (.fnt), XML (.xml), and Construct 3 SpriteFont formats. XML and Construct 3 formats are automatically detected and converted to text format before parsing.

Name Type Default Description
rawFontData String The raw content of the font definition file
imagePath String (optional) Optional path to the font image file (required for Construct 3 format)
imageWidth Int (optional) Optional image width in pixels (required for Construct 3 format)
Returns Description
BitmapFontData Parsed font data ready for use with BitmapFont

Private Members

convertXmlFontData(rawFontData: String): String

Converts XML format font data to plain text format.

XML format is commonly used by tools like Hiero and msdf-bmfont-xml. This method transforms the XML structure into the text-based format that the parser expects internally.

Name Type Description
rawFontData String XML font definition content
Returns Description
String Equivalent font data in plain text format
convertConstruct3FontData(rawFontData: String, imagePath: String, ?imageWidth: Int): String

Converts Construct 3 SpriteFont format to plain text BMFont format.

Construct 3 uses a different format that specifies:

  • Character width and height (cell size in the grid)
  • Character spacing (spacing when rendering text)
  • Character set (all supported characters)
  • Spacing data (width overrides for specific characters)

In Construct 3, characters are laid out in a grid from left to right, top to bottom, with no spacing between cells in the texture.

Name Type Default Description
rawFontData String Construct 3 font definition content
imagePath String Path to the font image file
imageWidth Int (optional) Width of the font texture in pixels (null for first-stage parsing)
Returns Description
String Equivalent font data in BMFont plain text format
parseLine(line: String, info: BitmapFontData): Void

Parses a single line of font definition data.

Each line starts with a token identifying the data type:

  • info: Font face and size
  • common: Line height and base size
  • page: Texture page definition
  • chars: Character count
  • char: Individual character metrics
  • kerning: Kerning pair data
  • distanceField: MSDF configuration
Name Type Description
line String A single line from the font file
info BitmapFontData The font data structure to populate
extractLineTokens(line: String, map: Map): String

Extracts key-value pairs from a font definition line.

Parses lines in the format: token key1=value1 key2="quoted value" Handles both quoted and unquoted values, with proper escape sequence support.

Name Type Description
line String The line to parse
map Map Output map to populate with key-value pairs
Returns Description
String The first token on the line (e.g., "char", "info")
unquote(s: String): String

Removes surrounding quotes from a string if present.

Used to clean up quoted values from the font file. Only removes quotes if they exist at both start and end.

Name Type Description
s String The string to unquote
Returns Description
String The string without surrounding quotes
ensureSpaceCharacter(info: BitmapFontData): Void

Ensures a space character exists in the font data. If missing, creates one based on common character widths.

The space character uses:

  • For monospace fonts: same advance as other characters
  • For proportional fonts: ~40-50% of average character width
  • Zero texture dimensions (no rendering needed)
Name Type Description
info BitmapFontData The font data to check and modify