只因你太美 · 体感投篮

项目概览：轻晃一下，顶球进篮

「只因你太美」是 ATK-DNESP32S3-BOX2-WIFI 上的单动作体感投篮小游戏。轻晃开发板，屏幕中的真人背身角色就会顶出篮球；每次进篮加 2 分，球回到待发位置后可以继续。游戏开机直接进入灰色练习室场景，画面包含篮板、篮网、角色和计分区域。

本教程使用 feat/zhiyin-taimei-game 分支，以该分支的 GAME.md 和游戏源码为准。默认构建的就是游戏。仓库 README 后半部分保留了通用驱动与硬件测试说明，其中的色条、Wi-Fi 扫描、麦克风电平和 TF 卡读写流程属于可选硬件测试。

角色图片和录音已经随源码内置。背景是 4.28 秒的副歌口号循环，每五个进球播放一次 1.20 秒的「你干嘛」录音短句；游戏运行无需 TF 卡或 Wi-Fi。

准备开发板与 ESP-IDF 6.0.2

准备项	要求与用途
开发板	ATK-DNESP32S3-BOX2-WIFI，ESP32-S3，16 MB Flash 与 8 MB OPI PSRAM。
板载外设	240 × 320 ST7789 屏幕、SC7A20 加速度计、ES8389 音频 Codec、扬声器和 L/Q/M/R 四键。
电脑与 USB 线	Windows 和可传输数据的 USB 线；本教程用 COM7 演示，实际端口以电脑识别结果为准。
构建工具	Git、ESP-IDF 6.0.2。首次构建需联网下载 `espressif/esp_codec_dev` 1.6.2。

按乐鑫的ESP-IDF 6.0.2 Windows 官方安装指南安装工具，在 EIM 自定义安装中选择 v6.0.2。本工程的依赖清单明确锁定这一版本。安装完成后参考官方环境激活步骤，打开此版本的 IDF PowerShell。

idf.py --version
git --version

确认版本输出为 ESP-IDF v6.0.2。下文使用不含空格的 C:\esp 作为工作目录；ESP-IDF 与工程目录都应避免空格。

克隆游戏分支并构建固件

在已激活环境的 PowerShell 中执行。篮球使用独立目录 box2-zhiyin-basketball，方便与其他 BOX2 分支分开维护。

New-Item -ItemType Directory -Force C:\esp | Out-Null
Set-Location C:\esp
git clone --branch feat/zhiyin-taimei-game --single-branch https://github.com/mlpre/esp32_box2.git box2-zhiyin-basketball
Set-Location .\box2-zhiyin-basketball
git branch --show-current
idf.py build

分支检查应输出 feat/zhiyin-taimei-game。该分支的 sdkconfig.defaults 已设置 ESP32-S3 目标、16 MB Flash 和 OPI PSRAM，干净克隆后可直接构建。构建会下载组件、生成配置，并把启动加载程序、分区表和应用镜像输出到 build；完成标志是 Project build complete。

如果这个目录此前启用过硬件测试，先明确切回游戏再构建：

idf.py -DBOX2_HARDWARE_TEST=OFF reconfigure build

确认开发板端口，然后完整烧录并查看启动日志：

Get-PnpDevice -Class Ports | Format-Table Status,FriendlyName
idf.py -p COM7 flash monitor

将 COM7 换成实际端口。使用 idf.py flash 会一起烧录 bootloader、分区表和 build/esp32_box2.bin，也会采用此分支的自定义分区配置。退出串口监视器按 Ctrl+]。

上电后确认游戏启动

复位或重新上电时松开四个按键，让板级驱动读取正常空闲电平。
启动自检完成后，屏幕直接进入练习室，显示角色、篮球、篮筐、当前分数和操作提示。
轻晃一次设备，或短按 M，确认角色顶球、篮球飞入篮筐、当前分数增加 2 分。
等篮球回到待发位置，再触发下一球。按 R 可以测试音量切换。

正常启动日志包含 BUMP SELFTEST PASS。传感器和音频都初始化成功时，可看到类似下面的信息：

BACK-BUMP GAME READY | sensor=1 audio=1 music=4.28s voice=1.20s
BUMP: energy=...
BASKET! count=1 score=2

该游戏无需菜单选择、握姿校准或起跑倒计时。体感检测适应任意握姿；启动时的按键空闲电平检测与体感握姿校准是两回事。

操作与投篮规则

动作或按键	效果	注意事项
轻晃设备	触发一次顶球	可以使用任意握姿；轻晃后让设备稍微稳定，再进行下一次动作。
M 或 L	触发一次顶球	按下后经防抖确认即生效，传感器不可用时仍可用按键玩。
Q	清零当前得分与进球数，重新开始	同时把球恢复到待发位置；已保存的历史最高分不随此操作清零。
R	循环音量	开机为 55%，按键依次切换至 75%、静音、35%，再回到 55%。

一次有效触发会让篮球按设定的抛物线飞向篮筐。约 1.1 秒时过篮计分，每球只记一次；约 1.65 秒完成整个动作并补球。在篮球飞行或下落过程中继续晃动、按 M 或 L，都不会重复发射。

体感检测需要先回到较平稳的状态才能再次触发，因此「轻晃一下、等球回来、再轻晃」比连续猛晃更容易操作。它采用单动作玩法，无需跟节拍，也无需组合动作或调整投篮角度。

程序把历史最高分保存在 kun_basket NVS 命名空间。球回到待发位置后才保存新的纪录，避开飞行期间的 Flash 写入。Q 重开只清理本局；正常重启后可继续读取已保存的纪录。

画面、音频与运行节奏

角色由两帧真人背面透明图片组成，顶肩时切换姿势；篮球经过篮筐时，篮网与前沿按前后关系遮挡球体。背景口号持续循环，每五个进球叠加一次短句，顶球与进篮也有合成反馈音。

图片与 PCM 录音已经编入固件，不必另拷素材到 TF 卡。素材来源、原始文件名和处理方式记录在 main/assets/SOURCES.md；这些音频是已有录音片段。

主循环按 20 ms 周期采样体感和处理按键，显示任务按 33 ms 周期安排刷新，音频使用独立任务。约 30 FPS 是显示任务的设计目标，不代表已测得的实体屏幕帧率。

常见问题与排查

现象	检查与处理
`idf.py` 无法使用或组件版本报错	切到 ESP-IDF 6.0.2 的已激活 PowerShell，检查 `idf.py --version`，并确认首次构建可以联网下载组件。
启动后出现色条和硬件状态面板	目录缓存了硬件测试构建开关。执行 `idf.py -DBOX2_HARDWARE_TEST=OFF reconfigure build`，再完整烧录。
按 M 能玩，晃动无反应	先等球回到待发位置，稳定一下再轻晃。检查 `sensor=1`；若日志出现 `Sensor unavailable; M still works`，检查 SC7A20 与 I2C，修复后重启。
连续晃动或连按没有连续出球	这是防重复触发规则；一球完成约需 1.65 秒，等补球后再操作。
按键反应不对	复位时松开 L/Q/M/R。板级驱动会在初始化时学习按键空闲电平，按住启动可能影响判断。
没有声音	按 R 离开静音档，查看日志中的 `audio=1`。如出现 `Audio stopped`，检查音频/I2S 错误和硬件连接后重启。
串口无法连接或烧录超时	使用数据线，重新确认 COM 端口，关闭占用端口的软件。自动下载失败时按住 BOOT、短按 RESET、松开 BOOT，再确认端口并重试。
断电后新纪录未保存	进球后等待篮球回到待发位置，再断电。串口若出现 `Record save failed`，需要继续检查 NVS 写入错误。

只有需要单独排查硬件时，才切到保留的硬件测试应用。以下两组命令分别进入测试和恢复游戏，每次切换后都要重新烧录；日常游玩无需执行。

# 可选：构建并烧录硬件测试
idf.py -DBOX2_HARDWARE_TEST=ON reconfigure build
idf.py -p COM7 flash monitor

# 退出监视器后，恢复游戏并重新烧录
idf.py -DBOX2_HARDWARE_TEST=OFF reconfigure build
idf.py -p COM7 flash monitor

源码结构与可选桌面预览

文件或目录	职责
`main/game_main.c`	默认游戏入口、体感采样、按键防抖、显示和音频任务、NVS 纪录保存。
`main/game.c`、`main/game.h`	单动作检测、防重复触发、抛物线、计分、重置及飞行时间常量。
`main/game_render.c`	练习室、角色、篮球、篮网遮挡与中文界面绘制。
`main/game_selftest.c`	板上与桌面共用自检，覆盖轨迹、单次计分、防重复、重置与任意握姿检测。
`main/assets/`	透明 PNG、PCM 录音、素材来源与许可证文件。
`driver/`	可复用的板级、屏幕、体感、音频和存储驱动。
`main/CMakeLists.txt`	通过 `BOX2_HARDWARE_TEST` 选择游戏或硬件测试入口。
`partitions.csv`、`sdkconfig.defaults`	分区表、ESP32-S3 目标及 Flash/PSRAM 默认配置。

想修改素材或检查绘图，可选用桌面预览工具。它需要本机安装 VS 2022 Build Tools；字体生成使用 Windows 微软雅黑与 Consolas。普通固件构建已经有随源码提交的资源，无需先运行这些脚本。

.\tools\generate_game_sprites.ps1
.\tools\generate_game_font.ps1
cmd.exe /c tools\preview_game.cmd
.\tools\preview_to_png.ps1

桌面程序会使用同一套游戏逻辑和绘图代码执行自检，输出待发、顶肩、飞行和进篮四个状态，合图位于 build/game_preview.png。

源码与参考资料

教程按提交 878a393656086935fc293b28f2be67d05054ce0d 的 GAME.md 和源码核对。使用 git rev-parse HEAD 可以检查自己的源码版本。

所有项目下一篇：Wi-Fi 扩展屏