bitmap-font-generator

Generate bitmap fonts for Chinese fonts (CJK) with lazy-loaded Unicode subsets.

面向中文字体的位图字体生成工具：把 TTF/OTF 拆成多个 Unicode 子集，生成可按需加载的 BitmapText，适合中文、日文、韩文等大字符集场景。

Demo

Go to Online Demo

Performance Benchmark

Why

在大量文本场景下，PixiJS 的 BitmapText 通常比 Text 更适合长期驻留渲染，因为它能复用图集纹理，减少运行时排版和纹理生成的开销。

但传统位图字体有个明显问题：要先把整套字形全部生成并全部加载。对于 CJK 字体，这通常意味着几千到几万个字符，一次性加载不现实。

这个库的做法是：

构建时把字体拆成多个 Unicode 子集
每个子集单独生成 atlas PNG 和字形信息
运行时先加载 manifest.json
真正显示到页面上的字符，才去加载对应子集

这样同一套字体既保留了位图字体的渲染优势，也避免了首屏就下载整包大字体资源。

体积示例

以下数据来自仓库内的示例字体 HYWenHei-55W.ttf，生成参数为每个字符 32px、resolution: 2：

原始 TTF 文件约 3.1 MB
生成后的 atlas PNG 总计约 2.47 MB
manifest.json gzip 压缩后约 47 KB
单张 atlas 图片大多在 10 KB 到 52 KB 之间

重点不在于把“整套资源的总和”压到极致，而是在于运行时只按需加载少量子集图片。实际页面通常不会一次请求全部 atlas。

安装

npm install bitmap-font-generator

目前主要面向 pixi.js >= 8.0.0。(如果你有 PixiJS v7 的使用需求，可以提 issue，旧版本支持 v7)

用法

1. 构建阶段生成位图字体

import { bitmapFontGenerator } from 'bitmap-font-generator';

await bitmapFontGenerator({
  fontPath: './assets/MyFont.ttf',
  outputDir: './public/fonts/MyFont',
  fontName: 'MyFont',
  fontSize: 32,
  padding: 0,
  resolution: 2,
});

输出目录示例：

public/fonts/MyFont/
  manifest.json
  MyFont_0.png
  MyFont_1.png
  ...

2. 在 PixiJS 中使用

import { BitmapFontManager, LazyBitmapText } from 'bitmap-font-generator/runtime';

await BitmapFontManager.loadFont('/fonts/MyFont/');

const text = new LazyBitmapText({
  text: '你好世界',
  style: {
    fontFamily: 'MyFont',
    fontSize: 24,
    fill: 0xffffff,
    letterSpacing: 2,
    align: 'center',
    wordWrap: true,
    breakWords: true,
    wordWrapWidth: 600,
  },
});

app.stage.addChild(text);

text.text = '新的内容';

BitmapFontManager.loadFont() 会先加载 manifest.json，并立即注册一个空的 BitmapFont。这样 LazyBitmapText 在真实子集尚未下载完成时，也能先用占位字符稳定渲染。

LazyBitmapText 尽量保持和 PixiJS BitmapText 一致的构造方式，常见的 anchor、x、y、rotation、alpha、roundPixels 等字段都可以直接传入。额外限制只有一个：style.fontFamily 必须是单个字符串。

3. 预加载指定文本

await BitmapFontManager.load('MyFont', '关键文字');

如果你希望文本在首次展示前就已经准备好对应字形，可以先手动调用这一步。

API