https://github.com/yuuenn/unity-bmfontimporter

A Unity script that imports custom bitmap fonts from AngelCode BMFont files, enabling efficient support for large character sets (e.g., CJK fonts). It extends the Unity Default Font system by pre-generating bitmap data, overcoming the performance and memory limitations of dynamic fonts.
https://github.com/yuuenn/unity-bmfontimporter

bitmapfont char-importing cjk-characters unity unity5-6-4f1

Last synced: about 1 month ago
JSON representation

A Unity script that imports custom bitmap fonts from AngelCode BMFont files, enabling efficient support for large character sets (e.g., CJK fonts). It extends the Unity Default Font system by pre-generating bitmap data, overcoming the performance and memory limitations of dynamic fonts.

• Host: GitHub
• URL: https://github.com/yuuenn/unity-bmfontimporter
• Owner: Yuuenn
• License: mit
• Created: 2025-02-14T18:21:02.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2025-02-23T21:37:39.000Z (over 1 year ago)
• Last Synced: 2025-02-24T20:07:32.650Z (over 1 year ago)
• Topics: bitmapfont, char-importing, cjk-characters, unity, unity5-6-4f1
• Language: C#
• Homepage:
• Size: 170 KB
• Stars: 3
• Watchers: 1
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# 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](docs/README.ja.md)

- Simplified Chinese: [docs/README.zh-CN.md](docs/README.zh-CN.md)

## Repository Layout

```text

/

├─ 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](src/BMFontImporter.cs): the script that imports BMFont data into a Unity `Custom Font`

- [config/CustomFontConfig.bmfc](config/CustomFontConfig.bmfc): the BMFont configuration file included with this repository

- [characters/Characters_BOM.txt](characters/Characters_BOM.txt): a sample character list for BMFont’s `Edit -> Select Chars From File`

## About `Characters_BOM.txt`

[characters/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](https://www.angelcode.com/products/bmfont/).

2. An installed Unity Editor.

3. [src/BMFontImporter.cs](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](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](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](https://github.com/Perfare/AssetStudio/) or another updated branch such as [zhangjiequan/AssetStudio](https://github.com/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](https://github.com/nesrak1/UABEA) 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](https://www.angelcode.com/products/bmfont/).

6. Download [config/CustomFontConfig.bmfc](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](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](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.