中文字体配置指南

Party Games Box for FoloToy AI Passport

目录

  1. 为什么需要配置中文字体
  2. 方案原理
  3. 第一步：安装 lv_font_conv
  4. 第二步：下载中文字体文件
  5. 第三步：生成字体 C 文件
  6. 第四步：编译烧录
  7. 验证
  8. 常见问题

1为什么需要配置中文字体

LVGL（Light and Versatile Graphics Library）默认只内置 Montserrat 系列字体，这是一种拉丁文字体，只支持英文、数字和基本标点符号。

Party Games Box 的所有游戏界面使用中文文本（游戏名称、题目、提示等）。如果不配置中文字体，屏幕上中文部分会显示为空白或方块。

问题现象

编译烧录后，屏幕上英文/数字部分（如 "PARTY GAMES"、"1/3"、"OK"）正常显示，但所有中文字符（如"骰子比大小"、"真心话大冒险"）显示为空白或方块。

2方案原理

解决方案的核心是：从 TTF 字体文件中提取游戏用到的汉字，生成 LVGL 格式的 C 源文件，编译进固件。

设计理念：自动检测，无缝回退

代码已经做好了统一的字体别名：

  • GAME_FONT_14 — 小号字体（14px），用于提示信息
  • GAME_FONT_20 — 大号字体（20px），用于标题/数字

CMakeLists.txt 会自动检测 main/fonts/font_zh_14.c 和 font_zh_20.c 是否存在：

  • 存在 → 编译中文字体，定义 USE_ZH_FONT，所有中文正常显示
  • 不存在 → 回退到 Montserrat，英文/数字正常，中文为空白

这意味着：你不需要修改任何游戏代码，只需要生成字体文件并放在正确位置。

文件作用
main/font_config.h字体别名定义，根据 USE_ZH_FONT 宏切换
main/CMakeLists.txt自动检测字体文件，条件编译
tools/extract_chars.py扫描所有 .c 文件，提取汉字字符集
tools/gen_font.ps1PowerShell 一键生成字体（Windows）
tools/gen_font.shBash 一键生成字体（Linux/Mac）
main/fonts/font_zh_14.c生成的 14px 中文字体（运行脚本后产生）
main/fonts/font_zh_20.c生成的 20px 中文字体（运行脚本后产生）

3第一步：安装 lv_font_conv

lv_font_conv 是 LVGL 官方的字体转换工具，可以从 TTF/OTF 字体生成 LVGL 格式的 C 源文件。它是一个 Node.js 命令行工具。

1

确认 Node.js 已安装

你的系统已有 Node.js，跳过安装。如果没有：

下载安装 Node.js LTS: https://nodejs.org/

2

安装 lv_font_conv

在 PowerShell 中执行：

PS> npm install -g lv_font_conv

验证安装：

PS> lv_font_conv --version
# 应该输出版本号，如: 1.4.5

4第二步：下载中文字体文件

下载一个支持简体中文的 TTF 或 OTF 字体文件。推荐以下几个免费字体：

字体名称推荐度下载地址
Noto Sans SC 首选 https://github.com/notofonts/noto-cjk/raw/main/Sans/OTF/SimplifiedChinese/NotoSansCJKsc-Regular.otf
思源黑体 SC 推荐 https://mirrors.tuna.tsinghua.edu.cn/osdn/users/8/8592/SourceHanSansSC.zip
文泉驿微米黑 备选（体积小） https://sourceforge.net/projects/wqy/files/wqy-microhei/
1

创建字体目录

PS> mkdir party-games\main\fonts -Force
2

把下载的字体文件放进去

把 TTF/OTF 文件重命名为一个好认的名字，放到 main/fonts/ 目录：

party-games/main/fonts/
└── NotoSansSC-Regular.otf   ← 放这里

提示：字体文件大小

完整的中文字体文件通常 5-20MB。不用担心——我们只提取游戏中用到的几百个汉字，最终生成的 C 文件只有几百 KB。

5第三步：生成字体 C 文件

在 Party Games 项目根目录下执行一键生成脚本：

Windows (PowerShell)

PS C:\...\party-games> .\tools\gen_font.ps1

或者手动指定字体路径：

PS C:\...\party-games> .\tools\gen_font.ps1 -FontPath "C:\downloads\NotoSansSC-Regular.otf"

Linux / macOS (Bash)

$ bash tools/gen_font.sh /path/to/font.otf

脚本执行流程

1

提取汉字 — extract_chars.py 扫描所有 .c 文件，提取所有中文字符

[1/4] Extracting Chinese characters from source files...
  game_dice.c: 45 unique Chinese chars
  game_rps.c: 12 unique Chinese chars
  game_coin.c: 180 unique Chinese chars
  ...
Total unique characters: 520
Chinese characters: 452
2

检查 lv_font_conv — 如果没安装会自动安装

[2/4] Checking lv_font_conv...
lv_font_conv is available.
3

生成 14px 字体

[3/4] Generating 14px font...
Generated: main/fonts/font_zh_14.c
4

生成 20px 字体

[4/4] Generating 20px font...
Generated: main/fonts/font_zh_20.c

生成成功

两个字体文件会出现在 main/fonts/ 目录：

party-games/main/fonts/
├── font_zh_14.c   ← 14px 中文字体（约 200-400KB）
└── font_zh_20.c   ← 20px 中文字体（约 400-800KB）

手动执行（如果脚本失败）

如果一键脚本不工作，可以分步手动执行：

# 1. 提取汉字
python tools/extract_chars.py

# 2. 生成 14px 字体
lv_font_conv \
  --font main/fonts/NotoSansSC-Regular.otf \
  --bpp 4 \
  --size 14 \
  --format lvgl \
  --force-fast-kernfmt local \
  --no-compress \
  --symbols "$(cat tools/range.txt)" \
  --output main/fonts/font_zh_14.c

# 3. 生成 20px 字体
lv_font_conv \
  --font main/fonts/NotoSansSC-Regular.otf \
  --bpp 4 \
  --size 20 \
  --format lvgl \
  --force-fast-kernfmt local \
  --no-compress \
  --symbols "$(cat tools/range.txt)" \
  --output main/fonts/font_zh_20.c

6第四步：编译烧录

字体文件生成后，按正常流程编译烧录即可。CMakeLists.txt 会自动检测到字体文件并启用中文字体支持。

1

把字体文件复制到 ai-passport 仓库

# 如果你在 ai-passport 仓库里开发：
Copy-Item "party-games\main\fonts\*" "C:\Espressif\ai-passport\main\fonts\" -Recurse -Force
2

编译时你会看到确认信息

PS> idf.py build

-- Processing 1 dependencies:
-- Configuring done
-- Chinese font files found - enabling USE_ZH_FONT   ← 看到这行说明字体已启用
-- Generating done
-- Build files have been written to...
3

烧录

PS> idf.py -p COM3 flash

7验证

烧录重启后检查：

检查项预期
菜单标题显示 "PARTY GAMES"（英文，本来就是正常的）
游戏名称显示中文："骰子比大小"、"石头剪刀布"等
游戏内提示显示中文："OK掷骰"、"长按返回"、"玩家1的回合"等
题目内容显示中文题目："你最害怕什么?"、"学鸡叫三声"等
数字正常显示数字：1/3、50、GO! 等

8常见问题

Q: 脚本报 "Font file not found"

A: 你需要先下载 TTF/OTF 字体文件放到 main/fonts/ 目录，或者用 -FontPath 参数指定路径。

Q: lv_font_conv 报错 "Cannot find module"

A: 全局安装可能没成功。尝试本地安装：

cd party-games
npm init -y
npm install lv_font_conv
npx lv_font_conv --version

然后用 npx lv_font_conv 替代 lv_font_conv 执行。

Q: 生成的字体文件太大，Flash 放不下

A: 减小 bpp（每像素位数）或减少字符数。

# 用 --bpp 1 (1bit灰度) 代替 --bpp 4 (4bit灰度)
lv_font_conv --font ... --bpp 1 --size 14 ...

--bpp 1 字体体积约为 --bpp 4 的 1/4，但渲染质量较差。对于 240x320 的小屏幕，1bpp 基本够用。

Q: 编译报 "font_zh_14.c: No such file"

A: 字体文件没生成或路径不对。确认文件在 main/fonts/font_zh_14.c。如果不需要中文，删除 CMakeLists.txt 中对字体文件的引用即可（CMakeLists.txt 已做了自动检测，不应该出现这个错误）。

Q: 中文字符显示为方块/问号

A: 字体文件中缺少某些字符。extract_chars.py 可能漏掉了某些字符。检查 tools/range.txt 是否包含所有需要的汉字，必要时手动补充。

Q: 添加了新游戏后中文不显示

A: 新游戏可能引入了 extract_chars.py 运行时不存在的汉字。重新运行：

python tools/extract_chars.py
.\tools\gen_font.ps1

重新生成字体文件即可。

Q: lv_font_conv 在 PowerShell 中 --symbols 参数有问题

A: PowerShell 对特殊字符处理不同。改用 Bash 脚本 gen_font.sh（需要 Git Bash），或手动把字符列表写入文件后用管道传递：

lv_font_conv --font font.otf --bpp 4 --size 14 --format lvgl --no-compress --symbols "$(Get-Content tools\range.txt -Raw)" --output main\fonts\font_zh_14.c
Party Games Box | Chinese Font Configuration Guide
Generated on 2026-09-15