Skip to content


This is a config file reference. Click for instructions.

This page is reference material which explains every setting and option for this section of an MPF yaml config file. See the instructions for config files for formatting and other details. See our guide to config file examples for more examples of real configs in action.

Valid in
machine config files YES ✅
mode config files YES ✅

The bitmap_fonts: section of your config is where you configure non-default parameter values for any bitmap font assets you want to use in your game. Note: You do not have to have an entry for every single bitmap font you want to use, rather, you only need to add individual assets to your config file that have settings which differ from the default values. (This section is part of the MPF media controller and only available if you're using MPF-MC for your media controller.)

A bitmap font is one that stores each glyph (character) as an array of pixels (that is, a bitmap). It is less commonly known as a raster font. Bitmap fonts are simply collections of raster images of glyphs. For each variant of the font, there is a complete set of glyph images, with each set containing an image for each character. For example, if a font has three sizes, and any combination of bold and italic, then there must be 12 complete sets of images.

MPF-MC currently supports Portable Network Graphics (.png), Graphic Interchange Format (.gif), and bitmap (.bmp) image files for bitmap fonts. In order for MPF to use the bitmap font, a font descriptor must be present. This contains the information necessary to locate each glyph (character) in the bitmap image and other associated information. The font descriptor information may be loaded from a file or provided in the asset settings ( font descriptor file format). MPF supports both .xml, .fnt, and .txt files for font descriptor files (binary files are not currently supported).

There is a great online tool for generating bitmap fonts (and the associated font descriptor file) from True Type Fonts:

Here's an example:

    file: F1fuv.png
    descriptor: [' !"#$%&,()*+`-./', '0123456789:;<=>?', '@ABCDEFGHIJKLMNO', 'PQRSTUVWXYZ[\]^_', '''abcdefghijklmno', 'pqrstuvwxyz{|}~ ']
    file: example_font.png
    descriptor: example_font_descriptor.xml

Optional settings

The following sections are optional in the bitmap_fonts: section of your config. (If you don't include them, the default will be used).


Unknown type. See description below.

Here is an example of a descriptor list for a bitmap image that contains three rows of 15 characters and the specific characters mapped to each position in each row:

descriptor: [ 'abcdefghijklmno', 'pqrstuvwxyz 012', '3456789,.:=<>-+' ]

Remember the descriptor list only works for monospaced characters (characters that are all the same width and height).


Single value, type: string. Defaults to empty.

The file to load when using this bitmap font.


Single value, type: string. Defaults to empty.

When should the asset loader load this file? One out of mode_start, on_demand or preload.

Something missing or wrong? You can fix it!

This website is edited by people like you! Is something wrong or missing? Is something out of date, or can you explain it better?

Please help us! You can fix it yourself and be an official "open source" contributor!

It's easy! See our Beginner's guide to editing the docs.

Page navigation via the keyboard: < >

You can navigate this site via the keyboard. There are two modes:

General navigation, when search is not focused:

  • F , S , / : open search dialog
  • P , , : go to previous page
  • N , . : go to next page

While using the search function:

  • Down , Up : select next / previous result
  • Esc , Tab : close search
  • Enter : go to highlighted page in the results