msdf-bmfont-xml

🇺🇸 English Doc

GitHub Actions npm version npm

将 .ttf 字体文件转换为多通道有符号距离场（MSDF），并输出打包的精灵图和 AngelCode BMFont 格式的 xml(.fnt) / txt(.fnt) 或 json 字体数据。

有符号距离场是一种通过纹理重现矢量图形的方法，详见 Valve 的论文。本工具使用 Chlumsky/msdfgen 生成多通道距离场以保留字体边角。距离场由矢量字体生成，并渲染到纹理页。BMFont 对象用于字符排版。（参考 BMFont 格式）

预览图

支持平台

使用 pixi.js 在浏览器预览 MSDF 字体

npm install & npm run render

作为 CLI 安装

npm install msdf-bmfont-xml -g

msdfgen 多平台可执行程序

本工具的字符生成msdf贴图依赖于 msdfgen 目前已经支持最新版本(1.12.1)的多平台可执行程序

✨ 更新：所有支持平台的 msdfgen 二进制文件现已预置在仓库并通过 npm 分发，避免 GitHub 流量限制和下载失败。安装时不会自动下载。 如需要手动下载更新，请参阅 MSDFGEN_INSTALL.md。

在 macOS 上，安装器会自动处理安全限制（移除隔离属性、代码签名等) 详见 MACOS_SECURITY.md。

安装完成后，直接在控制台运行 msdf-bmfont 生成字体文件。 输入 msdf-bmfont --help 查看详细用法。

控制台演示

用法

Usage: msdf-bmfont [options] <font-file>

Creates a BMFont compatible bitmap font of signed distance fields from a font file

Options:
  -V, --version                 输出版本号
  -f, --output-type <format>    字体文件格式: xml(默认) | json | txt (默认: "xml")
  -o, --filename <atlas_path>   字体纹理文件名（默认: 字体名称）
                                字体文件名始终设为字体名称
  -s, --font-size <fontSize>    生成纹理的字体大小（默认: 42）
  -i, --charset-file <charset>  从文本文件指定字符集
  -m, --texture-size <w,h>      输出纹理图集大小（默认: [2048,2048]）
  -p, --texture-padding <n>     字形间距（默认: 1）
  -b, --border <n>              字形与边缘的空间（默认: 0）
  -r, --distance-range <n>      SDF 距离范围（默认: 4）
  -t, --field-type <type>       msdf(默认) | sdf | psdf (默认: "msdf")
  -d, --round-decimal <digit>   输出字体文件的小数位数（默认: 0）
  -v, --vector                  生成 SVG 矢量文件用于调试
  -u, --reuse [file.cfg]        保存/创建配置文件以复用设置（默认: false）
      --smart-size              图集自动缩小为最小正方形
      --pot                     图集尺寸为 2 的幂
      --square                  图集尺寸为正方形
      --rot                     打包时允许 90 度旋转
      --rtl                     使用 RTL（阿拉伯/波斯语）字符修正
  -h, --help                    输出帮助信息

CLI 示例

生成带 ASCII 字符集、字体大小 42、spread 3、最大纹理尺寸 512x256、间距 1，并保存配置文件的多通道距离场字体图集：

msdf-bmfont --reuse -o path/to/atlas.png -m 512,256 -s 42 -r 3 -p 1 -t msdf path/to/font.ttf

将生成三个文件：atlas.0.png atlas.0.cfg 和 font.fnt，如下为最小 pot 尺寸（256x256）的图集：

Atlas0

如需用旧配置但更换字体，并生成单通道距离场及 SVG 图集：

msdf-bmfont -v -u path/to/atlas.0.cfg -t sdf -p 0 -r 8 path/to/anotherfont.ttf

将得到新的 atlas.0.png，追加了新字体：

Atlas1

不满意风格？SVG 图集也可用！

svg

还可以用图形编辑器为输出图集添加特效：

final

作为模块安装

npm install msdf-bmfont-xml

模块用法示例

将距离场和字体数据写入磁盘：

const generateBMFont = require('msdf-bmfont-xml');
const fs = require('fs');

generateBMFont('Some-Font.ttf', (error, textures, font) => {
  if (error) throw error;
  textures.forEach((texture, index) => {
    fs.writeFile(texture.filename, texture.texture, (err) => {
      if (err) throw err;
    });
  });
  fs.writeFile(font.filename, font.data, (err) => {
    if (err) throw err;
  });
});

自定义字符集生成单通道距离场：

const generateBMFont = require('msdf-bmfont');

const opt = {
  charset: 'ABC.ez_as-123!',
  fieldType: 'sdf'
};
generateBMFont('Some-Font.ttf', opt, (error, textures, font) => {
  ...
});

API

generateBMFont(fontPath | fontBuffer, [opt], callback)

根据 fontPath 或 fontBuffer 指定的字体渲染位图字体，可选参数 opt，完成后触发 callback。

参数说明：

callback 参数为 (error, textures, font)：

opt 可选，第二参数可直接传 callback。

License

MIT，详见 LICENSE.md。

This site is open source. Improve this page.