PokeTrail · 宝可旅途

带着伙伴走路，遇见宝可梦，用节奏对战和投球完成捕捉。
运行在 M5Stack StopWatch（C152）圆屏上的离线步行探险。

圆屏首页：妙蛙种子站在森林路线上，标注携带中，下方为今日 4 步。主机 Runtime/M5GFX 渲染，不是实机拍摄。

开始使用 · 构建和烧录 · 开发指南 · 验证说明

_{开发中的非官方爱好项目 · 画面为主机 Runtime/M5GFX 渲染，不是实机拍摄}

玩法

走路探险：森林、海边、洞窟三条路线，遭遇池各不相同。每走 200–500 步（随机）产生一次遭遇。
节奏对战与捕捉：按节拍攻击或躲避，胜利后最多投两球；精灵球不限量。成功捕获后该种永久退出遭遇池。
伙伴培养：一次携带一只，只有携带者获得培养步，达到条件后手动进化。
图鉴：自由浏览关都与城都 1～251，动画为《黑／白》像素素材。

_{节奏对战 · 蓄力投球 · 图鉴}

_{森林 · 海边 · 洞窟}

概率、进化费用、按键和存档规则见使用指南。账户与迁移见玩法契约。

画面来源

全部画面是 2026-10-29 在当前代码上用主机 Runtime/M5GFX 离屏渲染的截图，不是 C152 实机拍摄，也不能当作实机帧率、观感或验收结果。点图片打开 468×468 原文件。物理圆屏为 466×466，当前 M5GFX 驱动报告 468×468；PNG 只保留圆屏内像素，圆外透明。

画面	渲染套件	截图
首屏首页	`test_home_render`	`home-today-complete-live`：今日 4 步来自测试中的模拟走路
森林、海边、洞窟	`test_home_render`	`home-scene-0`～`home-scene-2`：未校时，所以今日显示 --
节奏对战、蓄力投球	`test_adventure_render`	`battle`、`throw-active`：海边路线，对手为玛瑙水母
图鉴	`test_adventure_render`	`viewer-entry`：测试档中的初始伙伴

电量处的 -- 是因为渲染时没有电池读数。重新生成：

rtk proxy mise exec -- python3 scripts/run_render_tests.py \
  test_home_render test_adventure_render

开始使用

使用项目烧录脚本后，设备会同步烧录电脑的当前时间。存储可用后选择妙蛙种子、小火龙或杰尼龟作为初始伙伴。也可以在设备上手动校时，或暂不校时：累计步数与探索照常增加，未知日期期间的步数不会补填到今日。

首页点按任一侧键或轻触屏幕进入菜单。30 秒无操作后熄屏，计步和保存继续；按键或触摸先点亮屏幕。页面操作见使用指南。

构建和烧录

使用 mise 管理开发环境，命令通过 RTK 执行。主机回归还需系统 C/C++ 编译器，渲染回归需 SDL2 及 sdl2-config。当前验证环境为 macOS；Linux 和 Windows 尚未实跑。

rtk proxy mise trust
rtk proxy mise install
rtk proxy mise exec -- python3 -m pip install -r requirements-dev.txt
rtk proxy mise run build

仓库包含完整生成的固件数据，普通构建无需重新下载宝可梦素材。PlatformIO 首次构建需要联网获取固定版本的工具链和库。素材更新、测试命令和代码归属见开发指南。

烧录前确认目标设备，首次覆盖出厂固件前备份整片 Flash：

rtk proxy mise exec -- python3 scripts/detect_port.py
rtk proxy mise exec -- ./scripts/backup.sh /dev/cu.usbmodemXXXX
rtk proxy mise exec -- ./scripts/flash.sh /dev/cu.usbmodemXXXX
rtk proxy mise exec -- pio device monitor -p /dev/cu.usbmodemXXXX --baud 115200

以上端口是 macOS 示例，应替换为实际目标；自动探测仅支持 macOS USB 串口，多个设备时请显式指定。备份脚本读取设备当前内容，刷入自定义固件后再备份不会得到出厂镜像。已有出厂备份请长期保留。

烧录脚本构建并写入 bootloader、分区表和应用，不写入文件系统镜像。应用启动后，脚本通过 USB 串口发送电脑当前时间，设备按现有校时事务写入 RTC 和存档，再回读确认。已校准设备保留原时区，首次校准采用电脑当前时区偏移；电脑时间须正确。普通重启沿用 RTC，不重复设置日期。仅使用 PlatformIO 或 esptool 写入固件不会执行这一步。

校时失败时脚本会说明固件已经写入，并以非零状态退出。测试模式、设备忙或存储故障会阻止自动校时。固件要求 spiffs 分区已有可挂载的 LittleFS；当前没有首次格式化入口。新设备若显示“存储未初始化”，图鉴仍可浏览，步行玩法不可用。请保留原 Flash，在确认备份和分区用途后另行初始化；不要用自动格式化绕过挂载错误。