20款聚会小游戏集成到一个固件 | 三键操作 | 纯离线运行 | 中文字体支持
硬件：ESP32-C3 + LVGL 9.x + ESP-IDF v5.5.5 | 开发工具：TRAE
ps：点击玩法社区安装地址直接安装即可。
ps:着重声明下没搞过这种，所以是纯我提需求trae work执。踩了很多坑经历了上百轮对话才搭建出来的模板后续如果有同学有好的idea可以直接在帖子下面提出来我可以添加模块。后续修改就简单了，如果有同学想要源码或者是踩坑记录可以找我要真是一步一个坑才做出来的。
ESP32-C3 | LVGL 9.x | ESP-IDF v5.5.5 | C语言 | 20款游戏 | 纯离线 | 中文字体子集化
一、我做了个什么
我把 20款聚会小游戏 整合到了一个 AI Passport 固件里，开机即进入游戏菜单，用 UP / DOWN / OK 三个按键选择和游玩。
一句话总结：一台口袋-sized 的聚会游戏机。不需要手机、不需要网络，朋友聚会时掏出来就能玩——骰子比大小、石头剪刀布、谁是卧底、真心话大冒险……20个游戏随你挑。
最特别的地方：所有游戏纯离线运行，20个游戏塞进一个 3MB 的应用分区，还搞定了中文字体显示——通过子集化方案，只把游戏里实际用到的740个汉字打包进固件，14px字体仅202KB、20px仅404KB。
二、它能怎么玩
操作方式
-
UP / DOWN 短按：菜单中翻页选择游戏；游戏中根据提示操作
-
OK 短按：菜单中进入选中的游戏；游戏中确认/掷骰/抽签等
-
OK 长按：任何游戏中随时返回主菜单
20款游戏列表
| 序号 | 名称 | 类型 | 玩法简述 |
|---|---|---|---|
| 1 | 骰子比大小 | 手气 | 轮流掷骰，点数最大赢 |
| 2 | 石头剪刀布 | 对决 | 两人同时出拳，淘汰赛制 |
| 3 | 诚实硬币 | 随机 | 抛硬币，正面真心话反面大冒险 |
| 4 | 猜数字 | 推理 | 1-100猜数，提示大了小了 |
| 5 | 数字炸弹 | 紧张 | 随机炸弹数，踩到出局 |
| 6 | 俄罗斯轮盘 | 手气 | 六格转轮轮流扣扳机 |
| 7 | 真心话大冒险 | 社交 | 转盘选人+随机题目 |
| 8 | 随机惩罚 | 工具 | 30+惩罚任务随机生成 |
| 9 | 我从来没有 | 破冰 | 30+题目，做过的人计数 |
| 10 | 国王游戏 | 社交 | 抽号当国王，指定号码任务 |
| 11 | 反应速度战 | 竞技 | 随机延时后比谁先按 |
| 12 | 两真一假 | 推理 | 三句话猜哪句是假的 |
| 13 | 抽签鬼牌 | 手气 | 轮流抽签，抽到鬼牌受罚 |
| 14 | 二选一 | 讨论 | 25+两难问题轮流选 |
| 15 | 谁最有可能 | 投票 | 25+题目投票指向同一人 |
| 16 | 词语炸弹 | 紧张 | 倒计时传着玩，爆炸出局 |
| 17 | 西蒙说 | 反应 | 西蒙说了才做，没说做了淘汰 |
| 18 | 默契大考验 | 两人 | 两人同题选答案，选一样得默契 |
| 19 | 故事接龙 | 创意 | 随机开头+提示词轮流编故事 |
| 20 | 谁是卧底 | 推理 | 相似词找不同，投票找出卧底 |
适用场景： 朋友聚会、破冰活动、团建、露营、排队等候……任何需要多人互动的场合，掏出 AI Passport 就能开始。
三、它现在长什么样
- AI Passport 屏幕显示游戏菜单的实物图
- 游戏运行中的界面截图（游戏很多我就贴几个意思下）
- 在 TRAE 里编码开发过程的截图。我就不贴对话截图了贴了用量截图 粗略估计小2000积分
技术规格
| 项目 | 规格 |
|---|---|
| 芯片 | ESP32-C3, 8MB Flash, 无 PSRAM |
| 屏幕 | ST7789P3, 240x320, RGB565 |
| 按键 | UP / DOWN / OK (ADC 电阻梯) |
| UI 框架 | LVGL 9.x |
| 开发框架 | ESP-IDF v5.5.5 |
| 语言 | C |
| 应用分区 | 3MB |
| 中文字体 | 子集化方案，740个汉字，14px约202KB，20px约404KB |
文件结构
party-games/
├── main/
│ ├── main.c # 主入口 + 菜单系统
│ ├── games.h # 游戏统一接口声明
│ ├── game_common.h/c # 通用工具
│ ├── font_config.h # 字体别名配置
│ ├── game_dice.c ... game_spy.c # 20个游戏源文件
│ └── fonts/
│ ├── font_zh_14.c # 14px 中文字体（自动生成）
│ └── font_zh_20.c # 20px 中文字体（自动生成）
├── tools/
│ ├── extract_chars.py # 扫描源文件提取汉字字符集
│ ├── gen_font_py.py # Python 字体生成脚本
│ └── full_build.bat # 一键全流程构建
├── CMakeLists.txt
├── partitions.csv
└── sdkconfig.defaults
四、别人怎么体验
ps：点击玩法社区安装地址直接安装即可。
方式一：直接刷入固件
编译完成后，固件位于 build/party-games-merged.bin，可以通过以下方式刷入我的 AI Passport：
bin文件我直接上传了感兴趣的同学可以直接烧机
party-games-merged.zip (513.8 KB)
-
使用 Chrome 或 Edge 浏览器打开 AI Passport Web Flasher（不支持其他浏览器）
-
将 AI Passport 开机，用能传输数据的 Type-C 线连接电脑
-
在网页上点击「安装」或选择自定义固件文件
build/party-games-merged.bin -
浏览器左上角弹窗中选择设备，点击「连接」
-
网页会自动开始安装，保持设备连接，不要拔线或关闭页面
-
等待页面提示安装完成、设备自动重启后即可体验
提示：安装新玩法会覆盖设备当前的全部内容。文件完全在浏览器本地读取，不上传服务器。要恢复默认固件可参考恢复出厂固件教程。
方式二：ESP-IDF 命令行烧录
:: COM3 替换为实际端口，idf.py 会自动找到固件
idf.py -p COM3 flash
:: 烧录并打开串口监视器
idf.py -p COM3 flash monitor
:: 按 Ctrl+] 退出监视器
方式三：esptool 命令行烧录
esptool.py --chip esp32c3 --port COM3 --baud 460800 write_flash 0x0 "C:\Espressif\frameworks\esp-idf-v5.5.5\ai-passport\build\party-games-merged.bin"
COM 端口查不到？ 确认 USB 线是数据线不是充电线，尝试换一个 USB 口，安装 CP210x 或 CH340 驱动，在设备管理器 → 端口 (COM 和 LPT) 中查看。
方式四：自己从源码编译----不建议使用这种，如果是想上手我贴上我的步骤
源码（文件比较大，编译文件我就不放进来了。同学们可以自行根据命令操作，放出源码是可以让同学们进行二次开发的，请勿进行商用。因为上传大小限制如果跑不起来可以帖子下回复我看到会回复的）
这是改动的代码可以根据我下面的指令操作吧代码放到ai-passport的git项目里
party-games.zip (323.4 KB)
第一步要搭建ESP-IDF的环境：这步比较麻烦需要梯子（科学上网）这个教程我就不贴了
ESP-IDF搭建.html (32.9 KB)
第二步涉及中文字体所以我下载了中文字体
中文字体操作步骤.html (18.5 KB)
我的踩坑html(无法上传md文件就生成了个html文件可以看看先)遇到问题的可以先看下
party-games-post.html (52.5 KB)
:: 1. 初始化 ESP-IDF 环境
set PATH=E:\Espressif\Espressif\tools\idf-python\3.11.2;E:\Espressif\Espressif\tools\idf-git\2.44.0\cmd;%PATH%
cd C:\Espressif\frameworks\esp-idf-v5.5.5
call export.bat
:: 2. 克隆 ai-passport 基础仓库
git clone https://github.com/FoloToy/ai-passport.git
cd ai-passport
git switch -c feature/party-games
git submodule update --init --recursive --depth 1
:: 3. 生成中文字体（需要 Node.js + lv_font_conv）
python tools\extract_chars.py
python tools\gen_font_py.py "main\fonts\NotoSansCJKsc-Regular.otf"
:: 4. 复制项目文件、编译、烧录
xcopy /E /Y "party-games\main\*" "ai-passport\main\"
cd C:\Espressif\frameworks\esp-idf-v5.5.5\ai-passport
idf.py set-target esp32c3
idf.py build
idf.py -p COM3 flash
也可以用一键脚本：
tools\full_build.bat自动完成环境初始化→字体生成→复制→编译→烧录全流程。
下一步计划
-
继续添加更多游戏（目标30款+）
-
增加游戏得分记录功能
-
优化菜单界面，增加分类筛选
-
尝试声音反馈（蜂鸣器提示音）
五、开发过程全记录：在 TRAE 里从零到完成的18轮对话
这个项目完全在 TRAE 里通过对话式开发完成。以下是每一轮提问和关键解答的完整记录，展示了从构思到最终成品的全过程。
第1轮：方向探索——寻找新奇不烂大街的二创点子
Q： 根据这个帖子找一个方向给我选择，我确定好了你再开始做。如果我不满意就再找一些点子。我需要新奇的、有意思的、点子不要烂大街的，要实用的。你先思考吧。
A： 分析了 AI Passport 的硬件特性（ESP32-C3、8MB Flash、屏幕+三键），结合"新奇+实用+不烂大街"的要求，提出了多个二创方向，包括电子宠物、迷你合成器、互动小说、聚会游戏盒等。每个方向附带可行性评估和实现难度分析，供用户选择。
第2轮：约束确定——离线运行
Q： 最好是不要用到网络的，你换些提案。
A： 排除了需要联网的方向，聚焦于完全离线的方案。提出了聚会游戏盒方向——把多个线下小游戏集成到一个固件里，开机即玩，三键操作。
第3轮：方向确认——聚会小游戏
Q： 搞成几个朋友聚会可以线下玩的小游戏这种。你找几种小游戏比如狼人杀、石头剪刀布、你说我猜等等。你多找些方向，起码给我50个方向吧，我来选一个。
A： 列出了50个聚会小游戏方向，涵盖手气类、对决类、推理类、社交类、反应类、创意类等多种类型。每个游戏附带玩法简述和适用人数。
第4轮：可行性确认——能否整合多游戏
Q： 可以把这些游戏都做出来吗？然后让用户选择那个游戏。能实现吗？还是只能一个游戏？
A： 确认可行。设计了统一的游戏接口（enter/exit/key），通过菜单系统切换游戏。每个游戏独立实现，主程序通过函数指针调用对应游戏的入口函数。3MB 应用分区足够容纳多个纯文字逻辑游戏。
第5轮：确定20款游戏并开始开发
Q： 需要这么搞，你来找优先级最高的20个游戏吧。后面要是需要我再让你加上。你要能实现出来，然后自己测试下，别到时候有bug。还要能安装进ai passport里面，别安装不了啊。
A： 选择了20款优先级最高的游戏并逐一实现 C 代码，设计统一接口，编写菜单系统，创建 CMakeLists.txt 和分区配置。
第6轮：生成 ESP-IDF 环境安装和编译烧录步骤
Q： 请帮我生成 ESP-IDF 环境安装和编译烧录的详细步骤。
A： 生成了完整的 ESP-IDF-Install-Guide.html，包含：下载安装器、子模块更新失败补救（代理/镜像）、Python 虚拟环境创建、环境验证、克隆仓库、子模块初始化、编译、烧录等全流程步骤。
第7轮：配置中文字体
Q： 请帮我配置中文字体以支持游戏界面。
A： 设计了中文字体子集化方案：创建 font_config.h 定义字体别名、编写 extract_chars.py 扫描源文件提取740个汉字、编写 gen_font_py.py 用 lv_font_conv 生成 LVGL 格式 C 文件、更新 CMakeLists.txt 自动检测字体文件条件编译。
第8轮：更新 README.md 并添加上传方法
Q： 你进行了修改你应该根据这些修改重新更新我的md文件吧。再加上如何把我写的这个固件上传到他们的玩法社区。
A： 更新了 README.md，新增快速/完整重新编译烧录流程章节，添加了上传固件到玩法社区的三种途径：GitHub 开源分享、联系 FoloToy 官方上架、直接分享固件文件。
第9轮：Git 命令顺序确认
Q： 最后这个命名和倒数第二个命令搞反了可以吗？
A： 可以。先 git switch -c 创建开发分支再 git submodule update 拉子模块，更合理。命令顺序已修正。
第10轮：编译报错排查
Q： 这里报错了。
A： 排查了多种编译错误：bsp_pins.h 缺失→子模块更新；COMPILE_DEFINITIONS 不支持→改用 target_compile_definitions；esp_timer.h 缺失→添加 PRIV_REQUIRES esp_timer；&GAME_FONT_14 错误→去掉 &；%d 不匹配 int32_t→改用 %ld；未使用变量警告→加 __attribute__((unused))。
第11轮：ESP-IDF PowerShell 终端在哪
Q： 打开 ESP-IDF PowerShell 终端 这个在哪里？
A： Windows 开始菜单搜索 “ESP-IDF PowerShell” 或 “ESP-IDF CMD”，点击打开即可。这是安装器自动创建的快捷方式。
第12轮：export.bat 闪退
Q： export.bat 打开闪烁下终端就不见了。
A： 不要直接双击 export.bat。先打开 CMD 窗口，设置好 PATH，然后在 CMD 里运行 call export.bat。或直接使用开始菜单快捷方式。
第13轮：验证 ESP-IDF 安装
Q： 是这个吗？怎么看？
A： 运行 idf.py --version，输出版本号说明环境就绪。如果报"不是内部命令"说明环境未初始化。
第14轮：屏幕全是方框
Q： 不行啊，你这个全是方框根本看不了。
A： 中文字体未正确生成或 CMD 编码导致乱码。必须用 python tools\gen_font_py.py 生成字体，避免 CMD 的 set /p 编码问题。
第15轮：第一步无输出
Q： 第一步什么都没有。
A： lv_font_conv 未安装。用 npm install -g lv_font_conv --registry https://registry.npmjs.org/ 安装。
第16轮：部分方框——全局校验
Q： 还是有部分方框。我发现每个游戏里面都有方框，而且外面菜单最上面也是方框。我需要你做全局校验检查，仔细检查。
A： 全局排查发现 LVGL 内部 UI 元素使用默认字体而非中文字体、range.txt 里缺少空格字符、gen_font_py.py 读取时用 .strip() 删除了空格。修复：将 .strip() 改为 .replace('\n', '').replace('\r', '')。
第17轮：空格字符导致方框
Q： 不是空格你也要添加进去啊，我怀疑就是空格导致的方框。
A： 确认是空格字符缺失导致方框。修复 gen_font_py.py 的字符集读取逻辑，确保空格不被删除。JS 代码中也同步修改。重新生成字体后所有方框问题解决。
第18轮：生成社区帖子
Q： 帮我生成帖子，把每一轮的提问以及md都弄进去。
A： 生成了完整的社区帖子，包含项目介绍、20款游戏列表、操作方式、技术规格、构建指南、常见问题排查、上传方法，以及全部18轮开发过程的提问与解答记录。
六、踩坑记录与常见问题
CMD 编码导致中文方框：CMD 的
set /p读取 UTF-8 文件时会把中文当 GBK 解码，导致字体文件里中文全是方块。必须用 Python 脚本gen_font_py.py生成字体，不能用gen_font.bat。
gen_font_py.py旧版用.strip()读取range.txt时删除了空格，导致空格显示为方块。改为.replace('\n', '').replace('\r', '')后修复。
idf_component_register不支持该参数，改用target_compile_definitions方式。
&GAME_FONT_14编译报错：font_config.h里定义的已经是指针(&font_zh_14)，再取&变成指针的指针。去掉&即可。
%d格式不匹配 int32_t：int32_t在 ESP32-C3 上是long int，需要用%ld替代%d。
--registry https://registry.npmjs.org/指定官方源。
git submodule update --init --recursive --depth 1，或用国内镜像set IDF_GITHUB_ASSETS=https://dl.espressif.com/github_assets。
Party Games Box | AI Passport 二创项目
ESP32-C3 + LVGL 9.x + ESP-IDF v5.5.5 | 20款聚会小游戏 | 纯离线运行
本作品完全在 TRAE 中通过对话式开发完成