Party Games Box - AI Passport 聚会游戏盒

项目概览

这是一个 AI Passport 二创项目，将 20款聚会小游戏 整合到一个固件中。开机即进入游戏菜单，通过 UP / DOWN / OK 三个按键选择和游玩。所有游戏纯离线运行，不需要网络连接，非常适合朋友聚会线下使用。

项目基于 FoloToy/ai-passport 仓库开发，使用 ESP-IDF v5.5.5 框架，LVGL 9.x 图形库，C 语言编写。支持中文字体显示（子集化方案，仅包含游戏用到的 740 个汉字），每个游戏实现统一的 enter/exit/key 接口，模块化设计便于扩展。

关键数据

游戏列表

操作方式

技术规格

完整构建指南（Windows CMD）

第一步：安装 ESP-IDF 开发环境

1.1 下载并运行官方安装器

1. 访问 ESP-IDF 下载页 下载 Tools Installer
2. 运行安装器，选择 ESP-IDF v5.5.5（或 v5.5.3 亦可）
3. 安装过程中会自动下载 Python、Git、工具链等依赖

1.2 安装过程中子模块更新失败的补救方法

方法 A：手动补拉子模块（推荐）

:: 打开 CMD 后设置 PATH
set PATH=E:\Espressif\Espressif\tools\idf-python\3.11.2;E:\Espressif\Espressif\tools\idf-git\2.44.0\cmd;%PATH%

:: 进入 ESP-IDF 目录补拉子模块
cd C:\Espressif\frameworks\esp-idf-v5.5.5
git submodule update --init --recursive --depth 1

方法 B：配置 Git 代理（需要梯子）

git config --global http.proxy http://127.0.0.1:你的代理端口
git config --global https.proxy http://127.0.0.1:你的代理端口
cd C:\Espressif\frameworks\esp-idf-v5.5.5
git submodule update --init --recursive --depth 1

:: 用完后清除代理
git config --global --unset http.proxy
git config --global --unset https.proxy

方法 C：使用 Espressif 国内镜像

set IDF_GITHUB_ASSETS=https://dl.espressif.com/github_assets
cd C:\Espressif\frameworks\esp-idf-v5.5.5
git submodule update --init --recursive --depth 1

1.3 验证 ESP-IDF 安装

:: 每次打开新 CMD 窗口先初始化环境
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
export.bat

:: 验证
idf.py --version

第二步：克隆 AI Passport 基础仓库

:: 1. 进入 ESP-IDF 目录
cd C:\Espressif\frameworks\esp-idf-v5.5.5

:: 2. 克隆仓库
git clone https://github.com/FoloToy/ai-passport.git

:: 3. 进入仓库目录
cd ai-passport

:: 4. 确保在 main 分支
git checkout main

:: 5. 创建并切换到开发分支
git switch -c feature/party-games

:: 6. 初始化子模块（需要梯子）
git submodule update --init --recursive --depth 1

第三步：中文字体配置（可选，但推荐）

3.1 安装 lv_font_conv 工具

:: 如果 npm 报 404 错误，使用官方源临时安装
npm install -g lv_font_conv --registry https://registry.npmjs.org/

:: 验证安装成功
lv_font_conv --version

3.2 准备中文 TTF 字体文件

推荐字体：思源黑体 (Noto Sans SC)、阿里巴巴普惠体等。将字体文件放到 main/fonts/ 目录。

3.3 提取汉字字符集

cd "项目目录\party-games"
python tools\extract_chars.py

该脚本会扫描所有游戏源文件中的汉字（约740个）+ CJK 标点 + 全角符号。

3.4 生成字体 C 文件（必须用 Python 脚本）

:: 自动查找字体文件并生成
python tools\gen_font_py.py

:: 或指定字体文件路径
python tools\gen_font_py.py "main\fonts\NotoSansCJKsc-Regular.otf"

第四步：复制项目文件到 ai-passport 仓库

:: 复制 main 目录下所有文件
xcopy /E /Y "项目目录\party-games\main\*" "C:\Espressif\frameworks\esp-idf-v5.5.5\ai-passport\main\"

:: 复制配置文件
copy /Y "项目目录\party-games\CMakeLists.txt" "C:\Espressif\frameworks\esp-idf-v5.5.5\ai-passport\"
copy /Y "项目目录\party-games\partitions.csv" "C:\Espressif\frameworks\esp-idf-v5.5.5\ai-passport\"
copy /Y "项目目录\party-games\sdkconfig.defaults" "C:\Espressif\frameworks\esp-idf-v5.5.5\ai-passport\"

第五步：编译

:: 初始化环境（每次开新窗口都要执行！）
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

:: 编译
cd C:\Espressif\frameworks\esp-idf-v5.5.5\ai-passport
idf.py set-target esp32c3
idf.py build

第六步：烧录到设备

方法一：ESP-IDF 命令行烧录

:: COM3 替换为实际端口
idf.py -p COM3 flash

:: 烧录并打开串口监视器
idf.py -p COM3 flash monitor

:: 按 Ctrl+] 退出监视器

方法二：Web Flasher 烧录

1. 编译完成后，固件位于 build/party-games-merged.bin
2. 打开 AI Passport Web Flasher
3. 选择固件文件，浏览器串口连接设备并烧录

方法三：esptool 命令行

esptool.py --chip esp32c3 --port COM3 --baud 460800 write_flash 0x0 party-games-merged.bin

常见问题排查

上传固件到玩法社区

AI Passport 官方玩法社区地址：https://ai-passport.folotoy.cn/plays/

途径一：GitHub 开源分享（推荐）

1. 将项目推送到 GitHub 仓库
2. 在 README 中写清楚构建步骤和依赖说明
3. 在 Release 页面上传编译好的 .bin 固件文件
4. 其他用户可以用 Web Flasher 或 esptool 刷入固件
5. 可以在 FoloToy/ai-passport 仓库提 Issue 或 PR 告知官方

途径二：联系 FoloToy 官方上架

1. 在 FoloToy 官方 Discord 联系官方团队
2. 提供 GitHub 仓库链接和固件 .bin 文件
3. 说明玩法介绍、操作方式和适用人数
4. 官方审核通过后会上架到玩法社区页面

途径三：直接分享固件文件

1. 编译完成后，固件位于 build/party-games-merged.bin
2. 将 .bin 文件分享给朋友
3. 对方打开 Web Flasher 选择该文件即可安装

文件结构

party-games/
├── CMakeLists.txt              # 顶层 CMake 配置
├── partitions.csv              # Flash 分区表
├── sdkconfig.defaults          # ESP-IDF 配置
├── README.md                   # 项目说明
├── ESP-IDF-Install-Guide.html   # ESP-IDF 环境安装指南
├── Chinese-Font-Setup-Guide.html # 中文字体配置指南
├── main/
│   ├── CMakeLists.txt          # 组件 CMake (自动检测字体文件)
│   ├── font_config.h           # 字体别名配置
│   ├── main.c                  # 主入口 + 菜单系统
│   ├── games.h                 # 游戏统一接口声明
│   ├── game_common.h           # 通用工具头文件
│   ├── game_common.c           # 通用工具实现
│   ├── game_dice.c             # 1. 骰子比大小
│   ├── game_rps.c              # 2. 石头剪刀布
│   ├── game_coin.c             # 3. 诚实硬币
│   ├── game_guess.c            # 4. 猜数字
│   ├── game_bomb.c             # 5. 数字炸弹
│   ├── game_roulette.c         # 6. 俄罗斯轮盘
│   ├── game_truth.c            # 7. 真心话大冒险
│   ├── game_penalty.c          # 8. 随机惩罚
│   ├── game_never.c            # 9. 我从来没有
│   ├── game_king.c             # 10. 国王游戏
│   ├── game_react.c            # 11. 反应速度战
│   ├── game_twotruth.c         # 12. 两真一假
│   ├── game_drawcard.c         # 13. 抽签鬼牌
│   ├── game_picktwo.c          # 14. 二选一
│   ├── game_likely.c           # 15. 谁最有可能
│   ├── game_wordbomb.c         # 16. 词语炸弹
│   ├── game_simon.c            # 17. 西蒙说
│   ├── game_telepathy.c        # 18. 默契大考验
│   ├── game_story.c            # 19. 故事接龙
│   ├── game_spy.c              # 20. 谁是卧底
│   └── fonts/                  # 中文字体文件 (由工具生成)
│       ├── font_zh_14.c        #   14px 中文字体
│       └── font_zh_20.c        #   20px 中文字体
└── tools/                      # 字体生成工具
    ├── extract_chars.py        # 扫描源文件提取汉字字符集
    ├── gen_font_py.py          # Python 字体生成脚本（推荐）
    ├── gen_font.bat            # CMD 字体生成（不推荐，有编码问题）
    ├── gen_font.ps1             # PowerShell 一键生成
    ├── gen_font.sh              # Linux/macOS 一键生成
    ├── build_log.bat            # 编译并保存日志
    ├── full_build.bat           # 一键全流程构建脚本
    ├── chars.txt               # 提取出的字符集
    ├── chars_count.txt         # 字符统计信息
    └── range.txt               # 字符范围参考

开发过程全记录（每轮提问与解答）

以下是整个开发过程中，从构思到完成的每一轮提问与关键解答。记录了从方向选择、游戏选型、代码编写、字体配置、编译烧录到问题排查的完整历程。

README.md 完整内容

以下是项目 README.md 的完整内容备份：

Party Games Box - AI Passport 聚会游戏盒

20款聚会小游戏，集成在一个固件里，开机进菜单选择，三键操作。支持中文字体显示。

操作方式

• UP / DOWN 短按: 菜单中翻页选择；游戏中根据提示操作
• OK 短按: 菜单中进入游戏；游戏中确认/掷骰/抽签等
• OK 长按: 任何游戏中返回主菜单

快速构建（一键脚本）

cd "项目目录\party-games"
tools\full_build.bat

full_build.bat 会自动完成所有步骤：初始化环境 → 生成中文字体 → 复制文件 → 删除缓存 → 编译 → 烧录。每步都有错误检查，失败会提示原因。烧录前会提示输入 COM 端口号。

修改代码后快速重新编译烧录

如果只修改了 party-games\main\ 下的 .c 文件，不需要重新生成字体。每行单独复制粘贴到 CMD 执行：

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
xcopy /E /Y "项目目录\party-games\main\*" "C:\Espressif\frameworks\esp-idf-v5.5.5\ai-passport\main\"
cd C:\Espressif\frameworks\esp-idf-v5.5.5\ai-passport
idf.py build
idf.py -p COM3 flash

注意事项

• 需要基于 FoloToy/ai-passport 仓库的 components/bsp 组件，克隆后需执行 git submodule update --init --recursive
• LVGL 内存池保持 24KB，因为每个游戏的 UI 实际上比原版更简单（纯文本标签，无复杂图形）
• 所有游戏纯离线运行，不需要网络
• 长按 OK 键可从任何游戏返回主菜单
• 固件不经过官方兼容性验证，请先在测试设备上验证
• 中文字体文件未生成时编译仍可成功，但中文会显示空白，仅英文/数字正常
• 框架和工具可能安装在不同盘符（如框架在 C 盘，工具在 E 盘），这是 ESP-IDF 安装器的正常行为