资料与证据索引

参考任务

本站开发前完整读取了两条 Codex 历史任务：

• 01a00655-ce0c-7753-9b9f-917f8f621b6d — 构建 ESP32 圆屏点击游戏 (2)：网页玩法、美术 v5、圆屏交互与迁移 handoff。
• 01a006c2-9b3f-7670-ba6b-a41e76f2a668 — 迁移游戏至ESP32开发板：硬件锁定、固件、实板性能、RTC/NVS、交互修复与验收。

线程内容被视为历史叙述；可核实数字优先采用仓库中已经落盘的冻结文档、源码、测试输出和 Git 记录。

本地权威文档

路径	用途
docs/game-design-framework.md	初始游戏系统与圆屏设计框架
docs/asset-inventory.md	v5 资产、调色板、字体与质量门
docs/esp32-migration-handoff.md	Web → ESP32 冻结合同与里程碑
docs/v6-oled-device-milestone.md	电量、设置、ambient 与 v6 设备合同
docs/web-v7-interaction-contract.md	v7 三段长按、倾斜与手势合同
docs/esp32-v7-update-handoff.md	v7 固件增量迁移说明（当前工作树）
firmware/docs/hardware-lock.md	BOM、引脚、地址与软件版本
firmware/docs/device-validation.md	v6 实机验证
firmware/docs/device-validation-v7.md	v7 实机、IMU、电源与存档验证（当前工作树）

核心源码

• src/core/：状态、经济、进度、几何、存档与 TypeScript 黄金快照。
• src/ui/：CanvasRenderer、圆屏布局、手势事务、粒子、逐帧 FX、bitmap 字体与设备运行时。
• projects/bit_orbit_minimal_32x32_20260814/：v1–v6 资产源、导出包、接触表与生成规格。
• firmware/pocket-star/main/：C++ 游戏核心、渲染、设备服务与生成资产。
• firmware/tests/：经济、交互、增量画面、OLED、音频、IMU、电源与存档测试。

上游资料

• POCKET STAR / Cookie32 项目 GitHub 仓库 — 本站 Roadmap 中所有提交号均链接到该仓库。
• Waveshare ESP32-S3-Touch-AMOLED-1.75 Wiki
• Waveshare 官方硬件仓库
• Waveshare BSP 3.0.1
• ESP-IDF 编程指南
• VitePress 官方入门
• Fusion Pixel Font 官方仓库 — 标题字体，SIL OFL 1.1。

媒体生成

本站的 12 个 GIF 来自冻结的 fx_tap / fx_grow / fx_loop / core_idle / core_sleep 帧，以及历史圆屏截图的确定性拼接。脚本：

python3 -m pip install -r website/requirements.txt
npm run docs:media

生成结果提交在 public/docs-assets/，VitePress 构建不依赖 Python。标题字体同样自托管，站点离线运行时不会请求第三方 CDN。

证据规则

1. 数值优先源码和验证报告，不从截图估算。
2. 固件 v7 未提交就明确写“工作树”，不填虚假 commit。
3. 自动日志不能替代人眼、手指和人耳证据。
4. 官方板载能力不等于本项目已经使用。
5. 历史 GIF 用于解释行为，不作为新增游戏资产冒充原始版本。