Unity BMFont Importer

Unity BMFont Importer is a Unity script that imports custom bitmap fonts from AngelCode BMFont .fnt files. It is especially useful for fonts with a large number of characters, such as CJK fonts, and works as an extension to the Unity Default Font workflow. By using pre-generated bitmap font data, it helps reduce the performance and memory pressure that dynamic fonts can create when handling very large character sets. In Unity 5.6.4f1, the script parses external BMFont data, calculates UV coordinates, offsets, and baseline corrections for each character, and writes the result into the Character Rects field of a Custom Font, greatly reducing manual setup work.

This guide is written mainly for localization workers who may use Unity for workflow purposes without being full-time Unity developers.

If you plan to replace fonts in a released game, for example for third-party localization or authorized localization work, please read the “Replacing Fonts in Released Games” section below first.

This Project Is Mainly Intended For

1. Third-party localization for older Unity games.
2. Authorized localization for older Unity games.
3. Introducing broader CJK support into older projects in a relatively non-destructive and lower-cost way.

What Problem This Project Solves

• Older Unity projects may use bitmap-based Unity Default Font fonts, so replacing only the TTF may not work.
• Manually managing large CJK character sets is expensive and tedious.
• Localization projects often need to preserve the original asset structure while expanding character coverage.
• Authorized localization work may also need a safer and lower-cost way to improve CJK support.

Languages

• English: this file
• Japanese: docs/README.ja.md
• Simplified Chinese: docs/README.zh-CN.md

Repository Layout

/
├─ README.md
├─ LICENSE
├─ .gitignore
├─ src/
│  └─ BMFontImporter.cs
├─ config/
│  └─ CustomFontConfig.bmfc
├─ characters/
│  └─ Characters_BOM.txt
└─ docs/
   ├─ README.ja.md
   └─ README.zh-CN.md

Included Files

• src/BMFontImporter.cs: the script that imports BMFont data into a Unity Custom Font
• config/CustomFontConfig.bmfc: the BMFont configuration file included with this repository
• characters/Characters_BOM.txt: a sample character list for BMFont’s Edit -> Select Chars From File

About Characters_BOM.txt

characters/Characters_BOM.txt is not meant to be a complete or universal CJK character set. It is a practical starting point.

Its purpose is to:

• provide a BOM-encoded text file that BMFont can import reliably
• include not only common characters, but also some less common CJK characters and symbols
• better fit projects such as rhythm games, music games, or other titles that often use unusual strings, decorative symbols, or non-standard text fragments

In practice, you should still trim or expand it based on the game script, UI text, localization plan, and QA findings.

Requirements

1. A bitmap texture file, usually .dds or .png, and an AngelCode BMFont index file generated by tools such as Bitmap Font Generator.
2. An installed Unity Editor.
3. src/BMFontImporter.cs from this repository.

Final Product

A custom Unity Default Font bitmap font that can be used in the Unity Editor.

Steps to Use

1. Create a Project and Import Assets

1. Create and open a Unity project.
2. Import src/BMFontImporter.cs, the generated .fnt file, and the matching texture file into the Assets folder.
3. In the Assets folder, right-click and choose Create → Custom Font to create a new Custom Font, then name it.
4. In the Assets folder, right-click and choose Create → Material to create a new Material.
5. In the Hierarchy, choose Create → Create Empty to create an empty GameObject. A recommended name is FontManager. Then add src/BMFontImporter.cs through Add Component or drag and drop.
6. In the Hierarchy, choose Create → 3D Object → 3D Text to create a 3D Text object.

2. Adjust Asset Properties

1. Texture settings
   • In the Assets folder, select the texture file and check the following in the Inspector
   • Read/Write Enabled → turned on. This is important for font replacement and for reusing the texture inside Unity
   • Wrap Mode → set to Clamp, or match the original file
   • Filter Mode → set to Bilinear, or match the original file
   • After checking the settings, click Apply.
2. Material settings
   • Select the created Material and set the following in the Inspector
   • Shader → choose Unlit/Transparent
   • Bind the texture file to the Material’s texture slot. In most cases, this means dragging it into the box currently labeled None (Texture).
3. Font settings
   • Select the created Custom Font and set the following in the Inspector
   • Line Spacing → set it to the desired font size, or match the original file
   • Bind the created Material to the font.
4. Text object settings
   • Select the created 3D Text object in the Hierarchy and in the Inspector:
   • Set the Rect Transform Height to the intended font size so you can check text position
   • Enter a test string in the Text component. Including CJK characters is recommended
   • Assign the Custom Font to the Font field of the Text component.
5. BMFontImporter script settings
   • Select the FontManager GameObject in the Hierarchy and in the Inspector assign:
   • the Custom Font to Custom Font
   • the texture file to Font Texture
   • the .fnt file to Fnt File.

3. Apply the Script

1. Press Ctrl+P or click the Play button to run the scene. The script will parse the .fnt file and write the character data into the Character Rects field of the Custom Font.
2. If the test string appears in the new font in the Scene view, the import succeeded.

Replacing Fonts in Released Games

This section is intended for the following situations:

1. The font you need to replace is a bitmap-based Unity Default Font.
2. Replacing the TrueType font file is ineffective, or there is no TrueType font file at all, or AssetStudio shows a texture-backed font that does not match TextMeshPro characteristics, for example it does not have the expected MonoBehaviour. In such cases, this workflow may be more suitable.
3. In that situation, this project’s method can be used to generate the required font and create the corresponding files for replacing assets in a released game.
4. The general workflow is: extract information from the original font, choose a similar font with matching properties, import it into a temporary Unity project, process the assets there, and then export the result back into the target game.

Requirements

1. The TrueType font file you want to introduce into the game.
2. Use AssetStudio or another updated branch such as zhangjiequan/AssetStudio to inspect the original Texture2D and record:
   • Format
   • Filter Mode
   • Wrap Mode
   • Channels
3. Confirm the color style of the original font texture:
   • white text on opaque black background
   • black text on opaque white background
   • white text on transparent background
   • black text on transparent background
4. Use tools such as UABEAvalonia to export the original Font and Texture text files using Export Dump. If you export multiple fonts, it is helpful to separate them by font name.
5. Download Bitmap Font Generator.
6. Download config/CustomFontConfig.bmfc from this repository.
7. Optional: if you only want to generate part of the TrueType font, for example common Chinese characters, prepare a text file containing the desired characters in UTF-8 BOM or UTF-16 BOM. You can also start from characters/Characters_BOM.txt.

Steps

1. Install the font file
   Install the target TrueType font on your computer. If multiple font weights are installed, temporarily remove the ones you do not need and keep only the required weight so that BMFont can recognize it correctly.
2. Load the configuration
   Open Bitmap Font Generator, then choose Options → Load Configuration, and load config/CustomFontConfig.bmfc.
3. Set font parameters
   Open Options → Font Settings and confirm or adjust the following:
   • Font → change it to the target font
   • Size (px) → change it to the target size in pixels
   • Match char height → keeping it enabled is recommended
   • Super sampling → keep it enabled and set level to 4
   • Leave other settings at default unless your project needs something different, then click OK to save.
4. Set export options
   Open Options → Export Options and confirm the following:
   • Padding is set to 2. Increase it only if edge noise appears
   • Width and Height should be adjusted based on your needs. In older Unity versions such as Unity 5, the practical maximum is often around 8192×8192
   • Bit depth should remain 32 unless you have a specific reason to change it
   • Adjust the channel preset based on the original file:
     • white text on transparent background → White text with alpha
     • black text on transparent background → Black text with alpha
     • white text on opaque black background → White text on black (no alpha)
     • black text on opaque white background → Black text on white (no alpha)
   • Set File/Font to Text
   • Set Textures and Compression according to the original Format. For example, if the format is DXT1, choose dds and DXT1. Then click OK to save.
5. Optional: import partial characters
   If you only want a partial character set, use Edit → Select Chars From File to import a text file containing the target characters. The file should be UTF-8 BOM or UTF-16 BOM encoded.
6. Preview the font
   In Bitmap Font Generator, use the Unicode view on the left and the selection panel on the right to inspect the font. When everything looks correct, click Options → Visualize to preview the texture.

   The preview title should read Preview: 1/1, which means all characters fit in one texture. If multiple textures are generated, a single texture is not enough, so you need to increase the texture size or reduce the number of characters.

7. Save the generated font
   Close the preview window and click Options → Save bitmap font as... to save the generated texture file and .fnt font index file.
8. Adjust the baseline
   To ensure correct display, open the generated .fnt file in a text editor and change the value after base= to an integer.

   In practice, a useful starting point is often around 0.2 × lineHeight, or a nearby rounded value.

9. After these steps, you should have the required texture file and .fnt configuration file. Review the “Requirements” section above and continue to the next stage.

Testing the Font, Building a Temporary Game, and Exporting the Font

Final Product

The new font’s Font and Texture text files exported through Export Dump.

1. Check the text position inside the Text object

1. In the Hierarchy, select the created 3D Text object and check whether the test text is positioned correctly relative to the Text component. It should stay inside the gray boundary, meaning inside the Rect Transform, and the distance to the top and bottom edges should be as even as possible.
2. If the characters appear too high, reduce the base= value in the .fnt file. If they appear too low, increase it.
3. For more precise adjustment, zoom in on the Scene view, measure the visible offset, and correct it gradually.

2. Save the project and build a temporary game

1. First, save the current project with Ctrl+S or File → Save Project, and make sure all changes are stored.
2. Then open File → Build Settings and choose the target platform, for example PC, Mac & Linux Standalone.
3. Click Add Open Scenes to add the current scene to the build list.
4. Finally, click Build, choose a save location, and build the temporary game.

3. Export the created font

1. Open the built game’s GameName_Data folder.
2. Use tools such as UABEAvalonia to open the resources.assets file from the temporary game.
3. Export the newly created font’s Font and Texture text files using Export Dump, and be careful not to confuse them with the original font files.