Font modding

Creating a new font

Making a new font requires the program BMFont, which is used to generate the font page and descriptor file from a font.

Once BMFont is installed, open it up and open the options menu then font settings, import your font file then select the font from the dropdown menu (font files can be found and downloaded at google fonts) After that is done, you can begin to configure the font settings

Font settings

Having imported your font, it is time to setup how you want the font to look. To do this, open the Font Settings menu again. Below are the fields you need to change:

Charset: set this to Unicode.
Size: this is the font size for your font, set this to your desired size. (Note that higher values might make your file too large to be read by the game)
Match char height: tick this so each character has the same height.
Font smoothing: tick this if your font may look overly sharp in game.
Outline thickness: if you want your font to have an outline, set the desired thickness here.

After this is complete press "OK" to save your changes

Export options

Having setup your font, it is now time to setup how you want the font exported. To do this, open the Export Options menu. Below are the fields you may want to change:

Padding: controls the padding between each character in the font image. Only needed if you intend to manually edit the font file and don't want the characters too close together.
Bit depth: Set this to 32
Spacing: controls the minimum space between character in the font image. Set this to 1-1, or higher if you experience bleeding between characters.
Width: controls the width of the font image. Adjust this so that all the characters fit on one image. (Note that higher values might make your file too large to be read by the game)
Height: controls the height of the font image. Adjust this so that all the characters fit on one image. (Note that higher values might make your file too large to be read by the game)
Channels: controls how the characters are composited. Set them all to glyph unless you have specified an outline, in which case set the alpha channel (A) to outline, with the rest as glyph.
Presets: Pick any one that fits your text, but only pick ones with alpha
Font descriptor: needs to be set to text.
Textures: should be set to .dds

After this is complete press "OK" to save your changes

Selecting font characters

To the right are checkboxes for different types of characters, if a character is used which is not in the font it will show as a question mark of a box, choose whichever ones fit what you're using the font for remembering that the font files can be too large to be read by the game

Recommended characters are:

* Latin + Latin Supplement
* Latin Extended A
* Latin Extended B
* Latin Extended Additional
* General Punctuation

Saving the font

Having setup the font as you would like it, check that the characters all fit on one page by clicking on the Visualize button in the Options menu. If they don't, you need to increase the size of the font image width and height.

Save the font by clicking "Save bitmap font as..." in the options menu.

Both the image and font file should be named the exact same with the exception of the file extension. While the *.fnt files provide which image file should be used, the game ignores this entirely, opting to use the file with the same name before the extension instead. This can also be seen by the file extension lacking from the bitmapfont definition. The bitmapfont does not need to have the same name as the font files, so a file in /Hearts of Iron IV/gfx/fonts does not guarantee that a font with the same name exists.

The font's location is decided by the bitmapfont definition, so it is not necessary to use the /Hearts of Iron IV/gfx/fonts/ folder, however the base game keeps all of its fonts there. The map font is the tahoma_60 bitmapfont, which links to the /Hearts of Iron IV/gfx/fonts/hoi_mapfont4 files by default.

Quick check-list

Open BMFont and select a font.
Set the font settings appropriately and save changes.
Export the font with proper settings and necessary character sets.
Remove _0 from the end of the name of the resulting .dds file in order to make it have the same name as the file defining the font.
Add kerning to the font if necessary.
If adding a new font rather than editing an existing one, add a bitmapfont = { ... } definition.

Kerning

Many fonts will not be exported with kerning information included in the font descriptor file. This can lead to character overlaps ingame which can be unsightly. To fix this, you need to add kerning information to your font descriptor file.

To do this, open your font descriptor file and add a new line following this format for each kerning pair:

kerning first=<symbol position> second=<symbol position> amount=<pixel width>

A symbol's position within a font can be seen in BMFont by looking in the lower right at the status bar when hovering over a symbol in the font canvas.

The pixel amount is the space between the first and second symbol.

You may have realized that manually creating each kerning pair is not very feasible. It is best to use a programming language (such as Python) to generate the kerning lines for you. Below is an example script you can use in Python 3.x or above:

    file = open( "kerning.txt", "wt" )

    # Add the symbol positions of the blank symbol slots here.
    exclude = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14 , 15, 16, 17, 18, 19, 20, 21, 22, 23, 25, 26,
                27, 28, 29, 30, 31, 127, 129, 141, 143, 144, 156, 173, 181]

    for x in range( 1, 255 ):
        for y in range(1, 255):
            if x not in exclude:
                if y not in exclude:
                    file.write( "kerning first={0}  second={1}  amount=1\n".format( x, y ) )

    file.close()

Defining bitmaps

In order to link a new file in /Hearts of Iron IV/gfx/fonts to a font, an entry must be created in a /Hearts of Iron IV/interface/*.gfx file. If editing an already existing font, this entry already exists and does not need to be modified. An example entry looks like the following:

bitmapfonts = {
    bitmapfont = {
        name = "my_font"
        fontfiles = {
            "gfx/fonts/my_font"
            "gfx/fonts/my_second_font"
        }
        color = 0xffffffff

        textcolors = {
            G = { 86 172 91 }
        }
    }
}

namespecifies the name of the font. This gets used for interface elements that use text to signify which font file gets used. This is everything that fonts are used for, with the exception of the map font, which is always tahoma_60. In order to find where exactly a base game's bitmapfont is used, it is best to search every *.gui file in the interface folder using a text editor and check the search results for a complete list.

fontfiles provides the location of each file used in the font, which is the path to the /Hearts of Iron IV/gfx/fonts/*.fnt file without the .fnt extension. The files should have no overlapping characters defined. If a font uses one font file in total, path = "gfx/fonts/my_font" can be used instead.
color defines the colour of the font in hex code of the ARGB format. The first 2 characters after the 0x define the transparency of the font, 00 meaning full transparency and FF meaning full opacity. The latter 6 characters provide the RGB hex code, each colour defined on the scale from 00 to FF.
textcolors provides an override of text colours, allowing to change a particular text colour to give a different colour when used on this font compared to the default value.

Additionally, it is possible to override a bitmapfont to use different settings when the game is set to use a specific language. Such an entry in the /Hearts of Iron IV/interface/*.gfx file looks like the following example:

bitmapfonts = {
    bitmapfont_override = {
        name = "my_font"
        path = "gfx/fonts/my_font_cyrillic"
        languages = { "l_russian" "l_polish" }
    }
}

This is primarily used to make fonts that don't support Cyrillic characters that are used in the Russian language appear as an entirely different font that does support them when the language requires so.