NEON RUSH · 体感赛车

项目概览：把 BOX2 变成体感赛车掌机

NEON RUSH 是运行在 ATK-DNESP32S3-BOX2-WIFI 上的单机赛车游戏。左右倾斜设备控制方向，前后倾斜调节速度；240 × 320 竖屏绘制伪 3D 公路、弯道、交通车辆和霓虹仪表，扬声器播放随车速变化的合成引擎声与碰撞音效。固件使用板载传感器和音频芯片，游玩时无需 Wi-Fi 或 TF 卡。

本教程使用 feat/neon-rush-racing-game 分支。当前玩法是容易上手的低难度模式，同时启用两辆障碍车。目标是保持生命值、避让交通车辆并积累里程与分数。

准备硬件与 ESP-IDF 6.0.2

准备项	要求与用途
开发板	ATK-DNESP32S3-BOX2-WIFI，ESP32-S3，16 MB Flash、8 MB OPI PSRAM；工程按此板的引脚与屏幕配置编写。
板载外设	ST7789 240 × 320 屏幕、SC7A20 加速度计、ES8389 音频 Codec、扬声器和 L/Q/M/R 四键。
电脑与连接	Windows、可传输数据的 USB 线，以及可用的 USB 串口；下面以 COM7 为例。
开发环境	Git 与 ESP-IDF 6.0.2。首次构建需要联网下载 `espressif/esp_codec_dev` 1.6.2。

按照乐鑫的ESP-IDF 6.0.2 Windows 官方安装指南安装 ESP-IDF。在 EIM 的自定义安装中明确选择 v6.0.2，因为本工程的依赖清单锁定这一版本。安装后按官方环境激活说明打开对应版本的 IDF PowerShell，在同一窗口中完成后续命令。

idf.py --version
git --version

第一条命令应显示 ESP-IDF v6.0.2。使用不含空格的项目路径，例如 C:\esp，可以避开 ESP-IDF 构建路径限制。

下载分支、编译并烧录

在已激活的 ESP-IDF 6.0.2 PowerShell 中执行以下命令。使用独立目录保存赛车工程，可保留其他 BOX2 项目的构建配置。

New-Item -ItemType Directory -Force C:\esp | Out-Null
Set-Location C:\esp
git clone --branch feat/neon-rush-racing-game --single-branch https://github.com/mlpre/esp32_box2.git box2-neon-rush
Set-Location .\box2-neon-rush
git branch --show-current
idf.py set-target esp32s3
idf.py build

分支检查应输出 feat/neon-rush-racing-game，构建成功后可看到 Project build complete。首次构建会生成 sdkconfig、下载依赖并创建 build 目录。首次克隆后设置目标即可；后续只修改源码时直接运行 idf.py build。

连接开发板，查看串口并烧录。请把命令中的 COM7 换成当前设备实际端口。

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

flash monitor 会写入所需镜像并打开串口日志；退出监视器按 Ctrl+]。完整烧录交给 idf.py 处理，构建产物的对应关系如下。

文件	烧录地址	作用
`build/bootloader/bootloader.bin`	`0x0`	启动加载程序
`build/partition_table/partition-table.bin`	`0x8000`	分区表
`build/esp32_box2.bin`	`0x10000`	赛车应用

首次开机与中位校准

启动时松开全部按键，以平时看屏幕的姿势平稳握住设备。固件先初始化板级外设，再用约 0.5 秒采样标定加速度计中位。
标题页显示 STEERING Y FIXED 后，短按并松开 M 键。
等待 3 秒起跑倒计时，随后用小幅左右倾斜控制赛车。前后轻倾，观察车速变化。
通过顶部 HUD 查看速度、分数、音量、生命值和实时倾斜指示。

串口应出现 NEON RUSH starting、tilt center calibrated 和 steering fixed to BOX2 screen horizontal axis Y+ 等启动信息。转向固定使用 SC7A20 的 Y 轴，无需选择轴向。

中位只在启动时校准。如果平稳握持时赛车仍持续偏向一侧，保持正确握姿后复位重启；Q 键只重开比赛，不重新校准传感器。

完整操作表

动作或按键	效果	使用提示
左右倾斜设备	左右转向	转向死区约 20 mg，轻微倾斜就会产生明显响应。
前后倾斜设备	调节车速	以启动时的握姿为基准，小幅调整即可。
M 短按	标题页开始；比赛中暂停；暂停后继续；结束后再来一局	短按操作在松开时触发；起跑倒计时期间不切换暂停。
M 长按 2 秒	关机	显示关机画面、停止音频并释放 `SYS_POW` 电源锁存。
L	音量降低 10%	最低为 0%，即静音。
R	音量提高 10%	最高为 100%，开机默认 50%。
Q	重开比赛	重置本局分数和生命值，重新进入 3 秒倒计时。

如果 USB 仍供电，长按 M 后设备会进入深度睡眠；重新上电或按复位键可再次启动。

怎样玩好第一局

起跑后先让赛车保持在道路中部，使用短促、轻微的倾斜避让车辆。转向灵敏度较高，持续大幅倾斜容易开到路肩；驶离道路中央区域会降低目标速度。引擎音调会随速度变化，可以和 HUD 一起帮助判断当前状态。

当前规则按行驶距离每米累计 2 分，交通车辆经过并被回收时增加 100 分。碰撞会扣除 12 点生命值并明显减速，随后有约 2.2 秒保护时间，减少连续碰撞伤害。初始生命值为 100，耗尽后进入结束画面。

结束时可查看本次运行中的最高分，按 M 或 Q 开始下一局。该分支的最高分保存在内存里，复位或断电后会重置。暂停期间可调整握姿，但若改变了舒适的中位角度，重新启动并校准会更合适。

常见问题与排查

现象	检查与处理
`idf.py` 无法识别，或依赖版本不匹配	重新打开已激活的 ESP-IDF 6.0.2 PowerShell，先运行 `idf.py --version`。首次构建需要可访问组件下载服务。
构建目标或 PSRAM 初始化异常	确认开发板为 ESP32-S3 N16R8，对照工程的 `sdkconfig.defaults`。在独立工程目录执行 `idf.py set-target esp32s3` 后重新构建；该命令会重新初始化构建配置。
找不到串口、端口被占用或连接超时	检查数据线与实际 COM 端口，关闭其他串口软件。需要手动下载时，按住 BOOT、短按 RESET、松开 BOOT，再重试烧录；进入下载模式后端口可能变化。
赛车自动偏转或手感过于灵敏	松开按键、保持正常握姿后复位，等中位校准完成再开始。用小幅倾斜操作，Q 不会重新标定中位。
画面正常但没有声音	先按 R 调高音量。查看串口是否提示 `audio unavailable; game will continue silently`；该提示表示音频初始化失败，游戏仍可无声运行。
开始后画面更新但赛车不前进	检查串口中的 SC7A20/I2C 错误与启动校准信息。游戏运行更新依赖有效体感读数；确认硬件型号和传感器连接正常。
关机后 USB 仍连接，设备没有完全断电	这是外部 USB 继续供电时的深度睡眠行为；按复位键或重新上电启动。

源码结构与可修改位置

文件	职责
`main/main.c`	标题、倒计时、运行、暂停、结束与关机状态；体感中位、转向、障碍车、碰撞、计分。
`main/box2_lcd.c`	透视赛道、场景、车辆、HUD 和菜单绘制。
`main/box2_audio.c`	独立音频播放、实时引擎音效与音量控制。
`main/box2_motion.c`	SC7A20 初始化与加速度 mg 数值读取。
`main/box2_board.c`	TCA9555、按键、板级初始化与电源控制。
`main/box2_config.h`、`sdkconfig.defaults`	引脚映射以及 Flash、OPI PSRAM、CPU 和 USB 控制台配置。

想调整难度，可以从 main/main.c 中的 EASY_TRAFFIC_COUNT、转向死区、碰撞伤害和保护时间入手，每次只改变一项并重新烧录体验。该分支的渲染循环按约 50 ms 间隔安排刷新；实际帧率应以实机测量为准。

源码与参考资料

教程按提交 e0764001471e526162963abc33f785a60e853e85 的说明与源码核对。分支后续可能更新，可通过 git rev-parse HEAD 查看自己下载的版本。

所有项目下一篇：BOX-2 网络收音机