Files
NESLite/docs/development_plan_V1.0.md

467 lines
40 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# NESLite V1.0 开发计划
| 项目 | 内容 |
| --- | --- |
| 产品名称 | NESLite |
| 文档版本 | V1.0 |
| 编制日期 | 2026-09-12 |
| 最近修订 | 2026-09-14:按用户确认增加内置内核选择 F15,见第 11 节 |
| 需求依据 | [design.md](../design.md) 及第 11 节用户需求增补 |
| 目标版本 | Android 应用 1.0.0 |
| 首要设备 | 用户的 Honor MagicOS 10 手机+小鸡 X5 Lite 手柄 |
| 当前状态 | 用户确认产品可发布,准备 1.0.0 签名交付至 git.m3frame.com/shen/NESLite;打包入口为打包.cmd,输出统一在 build;历史专项证据与任务勾选状态见 todo.md,不将未执行项自动视为通过 |
本计划将 `design.md` 转化为可执行的任务、阶段依赖、交付物和验收门槛。产品范围以设计文档及明确记录的用户增补为准;工期、实现默认值和测试样本数量属于执行基线,不能代替验收结果。文档版本 V1.0 不代表应用已经达到 1.0.0。
## 1. 开发目标与范围
### 1.1 交付目标
交付一款内置固定版本 FCEUmm 和 Nestopia 内核、自研 Android 前端、原生手柄输入的轻量 NES/FC 模拟器。用户能够完成“导入游戏 → 选择内核 → 连接手柄 → 开始游戏 → 暂停和存档 → 退出 → 恢复进度”,并在目标手机上获得稳定的速度、声音和操作体验。
第一版复用内核的 CPU、PPU、APU 和 Mapper 实现,开发重心为 Android 适配、libretro 宿主、音视频调度、输入和数据可靠性。所有内核能力均需经过前端接入和测试才能算作产品功能。
### 1.2 需求与阶段对应表
下列项目均为 V1.0 范围;“完成阶段”指功能闭环,最终仍须通过 M8 回归。M0~M9 的定义见第 4 节。
| 编号 | 功能与边界 | 完成阶段 | 关键验收 |
| --- | --- | --- | --- |
| F01 | `.nes` 导入,识别 iNES/NES 2.0 文件头;按测试清单声明兼容性 | M2 | 中文名、重复内容、同名不同内容、损坏文件均正确处理 |
| F02 | 游戏列表、搜索、收藏、最近游玩、从列表移除 | M6 | 元数据持久化;移除列表项不误删存档 |
| F03 | 启动、暂停、继续、重置、退出、再次加载 | M2 | 操作顺序完整;失败后仍能回到列表 |
| F04 | 横屏、保持比例、整数缩放、最近邻/线性过滤 | M2 基础,M6 完成 | 画面不拉伸,设置切换和 Surface 重建正常 |
| F05 | 声音、音量、静音、音画同步、音频设备变化 | M3 | 速度正确,无持续爆音或累积性偏移 |
| F06 | X5 Lite 和标准 Android 手柄,默认映射、自定义绑定、A/B 交换 | M4 | 组合输入、多来源输入和配置恢复正确 |
| F07 | 死区、方向冲突处理、A/B 连发、暂停快捷键、手柄导航 | M4;存档导航在 M5 联验 | 不残留按键,主要操作可仅靠手柄完成 |
| F08 | RB 按住快进,可关闭;来自设计文档默认映射 | M3 引擎,M4 绑定 | 松开、暂停或断开后恢复正常速度和声音 |
| F09 | 游戏自身存档、10 个手动即时存档槽、最近 3 份自动恢复点 | M2 基础,M5 完成 | 数据分 ROM 隔离,失败不破坏有效版本 |
| F10 | 存档导入导出、校验、备份、版本检查和失败恢复 | M5 | 导出后可重新导入;默认不包含 ROM |
| F11 | 后台/锁屏暂停、返回导航、界面重建、断柄和异常启动恢复 | M2 基础,M7 完成 | 无后台声音、持续黑屏、输入卡住或崩溃循环 |
| F12 | 虚拟方向键、A/B、Start、Select,基础触屏菜单操作 | M6 | 无手柄可完成基本游戏操作,支持多点触控和取消事件 |
| F13 | 手柄测试、运行状态、错误日志和诊断导出 | M1 基础,M7 完成 | 能定位设备、输入、音频、存档和原生错误 |
| F14 | arm64 发布、4 KB/16 KB 验证、安装升级、源码及许可证交付 | M8~M9 | 发布包、源码、符号、构建记录和验收报告对应 |
| F15 | 内置 FCEUmm/Nestopia 选择,默认值与逐游戏覆盖,独立存档 | XCORE(第 11 节),M8 汇总 | 持久选择、下次加载生效、切回原内核保留存档、同 ROM 对照验证 |
### 1.3 明确不做
V1.0 不做联网对战、云存档、多平台模拟、在线下载游戏、复杂 CRT 滤镜、回溯、run-ahead、用户下载或导入外部内核。内置内核选择按 F15 纳入本轮。FDS、光枪、四人适配器和第二只手柄的完整体验留待 V1.1 之后。
导入器首版仅开放 `.nes`,不扩展到压缩包、UNIF 或固件管理。应用不附带商业游戏 ROM。首版交付以可安装 APK 为准,应用商店上架不计入本轮工期。
## 2. 技术基线与实施决策
### 2.1 工程基线
| 项目 | 计划选择 | 落地要求 |
| --- | --- | --- |
| Android | `minSdk 28`,`compileSdk 36`,`targetSdk 36` | 延续设计目标;实际手机 API、ABI 和页大小在 M1 读取 |
| 应用层 | Kotlin、AndroidX、原生 View | 单一 `app` 模块,按包划分职责;游戏使用独立页面 |
| 数据 | Room+DataStore | Room 管理游戏元数据;DataStore 管理设置和控制器配置 |
| 内核 | 固定提交的 FCEUmm/Nestopia+libretro 接口 | 清单记录完整提交 SHA;默认 FCEUmm,Nestopia 按 F15 接入 |
| 原生层 | C/C++、JNI、Android NDK、CMake | FCEUmm 静态链接进 JNI;Nestopia 使用包内独立共享库;可复现构建并隔离同名符号 |
| 视频 | `GLSurfaceView`+OpenGL ES | 原生帧缓冲交接;不经 Kotlin 每帧搬运图像 |
| 音频 | Oboe | 记录实际流参数,支持请求低延迟失败后的回退 |
| 构建工具 | AGP 8.13.2、Gradle 8.13、JDK 17 | 采用设计给出的兼容组合;M0 在本机完成构建验证 |
| NDK | r28 或更新的稳定版本 | M0 锁定精确版本,不在配置中保留“r28+”或动态版本 |
| ABI | 发布 `arm64-v8a`,测试按需增加 `x86_64` | 测试 ABI 通过不能替代 arm64 发布包的验证 |
| 版本管理 | Git、Gradle Wrapper、依赖版本目录 | 固定 Kotlin、AndroidX、Room、DataStore、Oboe、CMake 等实际版本 |
AGP、Gradle 和 JDK 组合参照 [Android 官方 AGP 8.13 兼容说明](https://developer.android.com/build/releases/agp-8-13-0-release-notes)。本计划不将这些版本称为“最新”;实际依赖锁定及构建成功记录属于 M0 交付物。
NDK r28 起默认采用 16 KB 对齐,但仍需检查全部原生依赖、ELF、APK 打包与运行时行为,并在 16 KB 环境运行。检查依据为 [Android 官方 16 KB 适配指南](https://developer.android.com/guide/practices/page-sizes)。
### 2.2 本计划补充的默认行为
| 决策 | 默认方案 | 确认节点 |
| --- | --- | --- |
| 产品身份 | 显示名称固定为 NESLite;正式 `applicationId` 和签名延续策略在首个长期保留数据的 APK 前确定 | M0 |
| 模拟会话 | 同一时间仅一个 ROM、一个内核实例、一个玩家端口 | M2 |
| 区域时序 | 默认由内核判断,执行频率和采样率读取内核 AV 信息 | M2~M3 |
| 显示 | 默认 4:3 保持比例、最近邻;另设原始像素整数缩放模式 | M2,M6 提供设置 |
| 基础游戏存档 | M2 即接通读取和正常暂停/退出写入,避免原型阶段完全不保存游戏进度 | M2 |
| 快进 | 提供可关闭的按住 2 倍速,期间静音;退出时清空旧音频并重新建立时钟基线 | M3;性能实测后冻结 |
| 自动保存 | 建议变化的游戏存档每 10 秒提交一次,自动即时恢复点每 60 秒生成一次;暂停/退出额外请求提交 | M5 按实测开销冻结 |
| 恢复 | 回到前台、重新接入手柄或发现异常会话时,先处于暂停/恢复选择状态,由用户继续 | M2 基础,M7 完成 |
| 从列表移除 | 默认隐藏游戏条目并保留存档;再次导入同哈希内容时恢复关联 | M6 |
| 工程规模 | 先完成单模块应用,不提前拆分多工程或建设插件平台 | M0 |
2 倍快进是本计划提出的目标,并非性能承诺;若实测不能稳定达到,需调整默认倍率并同步验收清单。存档周期也必须通过帧时间测试后确定。已成功提交的存档应保持有效,突然终止可能丢失最近一次提交之后的进度。
## 3. 架构与模块契约
### 3.1 模块职责
| 模块 | 主要职责 | 边界 |
| --- | --- | --- |
| `ui` | 游戏库、游戏页、暂停菜单、设置、存档和诊断页面 | 展示状态、提交命令,不直接调用内核 |
| `session` | 会话状态、Activity/Surface 绑定、音频焦点及恢复协调 | 不长期持有已销毁的 Activity 或 View |
| `input` | 设备监听、映射、死区、多来源状态合成、菜单导航 | 输出玩家一的按钮快照和单次菜单动作 |
| `storage` | SAF 导入导出、内部 ROM、Room 索引、数据迁移 | 不把 `content://` URI 作为原生文件路径 |
| `jni` | 命令、输入快照、状态和错误通知 | 控制消息低频传递;视频和音频留在原生层 |
| `core_host` | libretro 生命周期、环境回调、内核配置和能力协商 | 不支持的请求返回失败并记录;必要能力缺失时停止加载 |
| `engine` | 模拟线程、命令队列、运行时钟、快进和诊断计数 | 独占内核调用,控制队列有界 |
| `video` | 像素转换、帧缓冲、GL 纹理、比例与过滤 | 处理宽高、`pitch` 和缓冲所有权 |
| `audio` | Oboe 流、重采样、环形缓冲、设备重建和水位 | 回调只消费预分配数据,不等待内核 |
| `state` | 存档快照、元数据、校验、原子提交、备份和恢复 | 模拟线程采集,文件线程提交,成功落盘后才通知“保存成功” |
| `diagnostics` | 版本、设备、输入、帧率、缓冲、错误和导出 | 日志限额轮换,默认不导出 ROM 内容 |
环境回调的语义与初始化流程依据 [libretro 官方接口说明](https://docs.libretro.com/development/cores/developing-cores/);M2 需对照锁定版本实际使用的请求形成支持清单,而不是把所有请求都返回成功。
### 3.2 线程所有权
1. **Android 主线程**处理 UI、输入事件和生命周期,只提交异步命令,不等待模拟线程或文件写入。
2. **模拟线程**串行调用初始化、加载、`retro_run()`、重置、状态序列化、反序列化、卸载和销毁;图像和音频在回调中复制到宿主缓冲,存档内存在保存采集点复制为不可变快照,避免其他线程使用内核临时指针或正在变化的内存。
3. **GL 线程**只显示最近可用的完整帧。过时画面可以丢弃,但不能因此跳过正常模式下应执行的模拟帧。
4. **音频回调线程**只消费环形缓冲,数据不足时补静音并计数;不做文件 I/O、动态分配、睡眠或等待互斥锁。此约束参照 [Oboe 低延迟音频指南](https://developer.android.com/games/sdk/oboe/low-latency-audio)。
5. **文件工作线程**处理不可变快照和导入导出;每个 ROM 的存档写入按序提交,旧任务不得覆盖新任务。
视频采用预分配的双缓冲或三缓冲,交接时明确读写所有权;音频采用有界环形缓冲。重采样和水位控制在非音频回调线程完成。所有队列、日志和历史统计都有容量上限。
### 3.3 会话状态与命令
```text
Idle → Loading → Paused → Running
↑ ↓
└─ Pausing
Paused → Stopping → Idle
加载或运行失败 → Error → 安全清理 → Idle
```
- `Load / Pause / Resume / Reset / Save / LoadState / Stop` 均通过命令队列处理,返回完成或失败结果;输入快照独立更新。
- 加载成功后仅在前台、Surface 可用且资源就绪时首次自动运行;后台恢复和断柄恢复需要用户继续。
- 暂停菜单、失焦、锁屏、断柄及 Surface 丢失先触发暂停和输入清理;音频及时静音。M5 起再纳入完整恢复点提交。
- `Reset`、存档和读档在帧边界执行;读档期间暂停推进,成功或回滚后清空音频、废弃旧待显示帧并重建时间基线。
- 使用会话编号标记异步工作;已经退出的游戏不能被迟到的加载、音频重建或保存通知重新激活。
- Activity 重建只重新连接会话与显示资源,不创建第二个模拟线程;进程重建则从磁盘记录恢复选择,不依赖旧对象。
### 3.4 持久化约定
```text
应用内部 files/
├── roms/<sha256>.nes
├── saves/<sha256>/battery/ 游戏自身存档及有效备份
├── saves/<sha256>/states/ 10 个手动槽位及元数据、缩略图
├── saves/<sha256>/auto/ 最近 3 份自动恢复点
├── saves/cores/nestopia/<sha256>/ Nestopia 独立的 battery、states、auto、recovery 与会话标记
├── system/ 内核需要的稳定系统目录
└── diagnostics/ 限额日志
```
FCEUmm 延续 `saves/<sha256>/`,读档保护副本及会话标记也在各内核、各 ROM 根目录内。Room 数据库和 DataStore 使用各自标准应用目录;数据库记录游戏哈希、显示名、内部文件关联、收藏、最近游玩时间和列表可见状态。哈希按导入文件的完整字节计算,不擅自去头或改写文件;内容不同的版本分别管理。
导入按“读取 URI → 有界流式复制和头部校验 → 计算 SHA-256 → 提交内部正式文件 → 数据库事务登记”执行。取消、空间不足及提交中断必须清理临时文件;数据库和文件系统不能形成单一事务,因此需在启动时对未登记正式文件及缺失文件记录进行核对和恢复。
存档采用“不可变快照 → 同目录临时文件 → 写入并刷新 → 校验 → 原子替换 → 备份轮换”的提交流程。为电池存档与即时存档分别定义格式和兼容检查;即时存档记录 ROM 哈希、内核名称/提交、封装版本、相关配置、时间、长度和校验值。导入的存档包检查路径、条目大小和总大小,不能写出目标存档目录。
## 4. 里程碑、依赖与工期
### 4.1 估算前提
按 **1 名熟悉 Kotlin 和 C/C++ 的开发者全职实施、每周 5 个工作日**估算。开发者承担代码、构建、自动测试和报告整理;设备持有人协助 X5 Lite、MagicOS 10 和实际游玩验收。两种角色可由同一人承担。
基础工作量约 **56~73 人日**,加约 20% 联调和缺陷修复缓冲后约 **67~88 人日,日历约 14~18 周**。此范围不是交付承诺,不包含设备等待、首次学习 Android/NDK 或额外上架工作。兼职按有效投入折算;M1 和 M3 结束后重新估算。
| 阶段 | 应用版本 | 主要目标 | 依赖 | 工作量 | 阶段产物 |
| --- | --- | --- | --- | --- | --- |
| M0 | 工程准备 | 需求、构建、版本、测试资源基线 | 无 | 3~4 人日 | 最小工程、构建记录、锁定清单 |
| M1 | 0.1.x | 原生库与真实手柄诊断 | M0 | 5~7 人日 | 诊断 APK、设备 JSON、键位表 |
| M2 | 0.2.x | 内核、导入、画面和基础操作 | M1 | 7~9 人日 | 无完整音频的运行原型、基础电池存档 |
| M3 | 0.3.x | 正确速度、连续声音和音画同步 | M2 | 8~10 人日 | 首个音画完整可玩版本、性能基线 |
| M4 | 0.4.x | 手柄映射、连发、导航和快捷操作 | M3 | 5~6 人日 | 手柄体验版本、输入回归记录 |
| M5 | 0.5.x | 完整存档、备份、导入导出和恢复 | M3、M4 | 8~10 人日 | 可靠存档版本、格式与故障报告 |
| M6 | 0.6.x | 游戏库、设置、存档 UI 和虚拟按键 | M4、M5 | 6~8 人日 | 日常使用 Beta |
| M7 | 0.7.x | MagicOS 10 和系统行为专项适配 | M6 | 4~6 人日 | 系统兼容报告 |
| M8 | 0.9.x | 全量回归、性能、升级与发布准备 | M1~M7 通过 | 8~10 人日 | 候选发布版 RC |
| M9 | 1.0.0 | 发布验收和归档 | M8 通过 | 2~3 人日 | 正式 APK、对应源码和交付包 |
版本顺序沿用设计文档,0.8.x 不安排独立范围。M0 无需产品级 APK;M1 起每个里程碑必须有可安装 APK、源码提交、构建说明、验收记录和已知问题。
关键路径为 **工程与实机输入 → 内核与画面 → 音频和时钟 → 手柄体验与存档 → 完整界面 → 系统适配 → 回归发布**。不得用后续界面完成度替代前序正确性验收。设备暂不可用时可推进不依赖实机的开发和自动测试,但对应实机门槛仍记为“未验证”。
### 4.2 阶段状态规则
所有下列任务初始状态为“未开始”。跟踪时使用“未开始/进行中/待实机/通过/失败”,不能把待实机标成完成。关键数据损坏、速度错误、崩溃或输入残留未解决时,该阶段不通过。
## 5. 分阶段执行任务
### M0:建立可重复的工程基线
| 任务 | 工作内容 |
| --- | --- |
| M0-01 | 初始化 Git、单 `app` Android 工程、Gradle Wrapper、CMake 和 JNI 空入口;确定应用 ID 与版本命名 |
| M0-02 | 核对本机 JDK/SDK/NDK/CMake,锁定工具及依赖精确版本,记录安装和构建步骤 |
| M0-03 | 选择 FCEUmm 提交,登记 libretro 头文件和 Oboe 来源;统一采用固定提交的依赖引入方式,登记本地补丁 |
| M0-04 | 建立测试 ROM 清单、设备表和验收模板,整理依赖许可证;建立本地构建、检查和测试入口 |
**出口条件:** 从干净检出能按文档生成调试 APK;没有依赖手动复制的未知原生库;代码、依赖和构建版本可追溯。记录未齐备的实机与测试资源,提供取得方法。
### M1/0.1.x:设备与 X5 Lite 诊断
| 版本/任务 | 工作内容 |
| --- | --- |
| 0.1.0/M1-01 | 安装启动、JNI 自检;读取机型、系统 API、ABI、页大小、刷新率和屏幕信息 |
| 0.1.1/M1-02 | 枚举设备名称、描述符、厂商/产品标识、输入源、轴范围和设备连接变化 |
| 0.1.2/M1-03 | 实时展示按钮按下/松开、HAT、摇杆、扳机;保存用于复现的输入事件序列 |
| 0.1.3/M1-04 | 失焦与热插拔状态清理、设备 JSON 导出、X5 Lite 实测键位表和模式说明 |
**出口条件:** 目标手机正常加载原生库;方向+A/B 同时按下可观察;全部松开后状态归零;拔出后无残留、重连后可继续检测。真实按键码来自实测,不由按键字母推断。
按设计使用 X5 Lite 原生安卓模式,核对随设备说明及实际表现;测试前关闭硬件连发。保留厂商模式切换组合,不占用“视图+菜单长按”。本阶段不要求加载 ROM。
### M2/0.2.x:打通内核运行链路
| 版本/任务 | 工作内容 |
| --- | --- |
| 0.2.0/M2-01 | 编译锁定的 FCEUmm;接入 libretro API 版本检查、回调注册、初始化、目录、选项、玩家一端口和卸载 |
| 0.2.1/M2-02 | SAF 导入、文件大小与头部校验、SHA-256 去重、稳定内部副本、最小 Room 索引和错误提示 |
| 0.2.2/M2-03 | 视频回调、协商像素格式、行跨度与重复帧处理;区分纹理宽高与内核基础尺寸,GL 按基础尺寸整数缩放并支持 4:3 适配;空间不足一倍时等比例缩小 |
| 0.2.3/M2-04 | 模拟线程和会话状态机;手柄快照接入;启动、暂停、继续、重置、退出;基础电池存档读写 |
**出口条件:** 至少 3 个有权使用的样本完成加载和运行,其中包含一个电池存档样本;完整操作流程通过;正常退出再加载后游戏自身进度可恢复;损坏文件加载失败不会破坏现有数据。
音频回调在本阶段按接口正确接收并消费数据,暂不输出声音;无音频时按内核时序与单调时钟执行,不能无节制调用 `retro_run()`。后台和 Surface 丢失的基础暂停逻辑同时接入。高级备份与故障保证在 M5 验收前仍标为未完成。
### M3/0.3.x:声音与正确运行速度
| 版本/任务 | 工作内容 |
| --- | --- |
| 0.3.0/M3-01 | Oboe 输出、预分配环形缓冲、欠载补静音与统计;低延迟流失败后按能力回退 |
| 0.3.1/M3-02 | 读取内核与设备采样率,完成重采样、声道/格式适配,记录实际流参数 |
| 0.3.2/M3-03 | 以单调时钟、内核时序及音频消费/水位进行调度;显示节奏独立;缓冲有界且不无限追帧 |
| 0.3.3/M3-04 | 音量、静音、音频焦点、设备重建;音频不可用的时钟回退;快进及回到正常速度 |
**出口条件:** NTSC 与 PAL 样本各连续运行至少 30 分钟;按第 7 节方法验证速度和音频缓冲;暂停后无旧声音继续播放,恢复和设备切换后不累积延迟。快进松开后正常速度恢复,断柄或失焦取消快进。
内核帧率和采样率从返回信息读取;[FCEUmm 官方文档](https://docs.libretro.com/library/fceumm/)给出的 NTSC、PAL/Dendy 时序用于准备测试,不能替代运行时读取。静音时保留正常调度;音频流关闭时显式切换至单调时钟,避免因无音频消费而挂起或加速。
### M4/0.4.x:完成手柄操作体验
| 版本/任务 | 工作内容 |
| --- | --- |
| 0.4.0/M4-01 | 将 M1 实测档案转为默认映射;加入 A/B 交换、自定义绑定、恢复默认和冲突提示 |
| 0.4.1/M4-02 | 按来源维护状态;处理 HAT/按键重复上报、轴阈值滞回、死区和相反方向归零 |
| 0.4.2/M4-03 | A/B 软件连发、暂停菜单、RB 快进绑定;快捷动作按边沿触发,快速读档默认不绑定易误触单键 |
| 0.4.3/M4-04 | 最小游戏列表与菜单的手柄焦点导航、配置持久化、重连后的档案匹配 |
**默认映射:** 十字键为方向,左摇杆可选方向;A/B 对应 NES A/B;X/Y 对应 A/B 连发;菜单键为 Start、视图键为 Select;右摇杆按下打开/关闭暂停菜单;RB 按住快进。实际键码以 M1 记录为准,系统返回和触屏暂停入口始终可用。
**出口条件:** 组合输入、重复轴/按钮事件和失焦清理通过自动回放;20 轮插拔后无残留;仅靠手柄可进入游戏、暂停、继续、重置和退出。存档选择与读档导航依赖 M5,在 M5 完成后补做完整验收,不能在 M4 宣称已通过。
连发周期按模拟时间生成,不能随手机刷新率变化;手柄硬件连发与软件连发分别测试,默认验证时关闭硬件连发。
### M5/0.5.x:可靠存档和恢复
| 版本/任务 | 工作内容 |
| --- | --- |
| 0.5.0/M5-01 | 完善电池存档变化检测、周期提交、暂停/退出提交、按 ROM 隔离、原子替换和有效备份 |
| 0.5.1/M5-02 | 10 个手动即时存档槽、时间、缩略图、校验元数据;存读档在模拟线程安全点执行 |
| 0.5.2/M5-03 | 自动恢复点保留最近 3 份,失败不挤掉有效副本;异常会话标记和恢复选择入口 |
| 0.5.3/M5-04 | SAF 存档包导入导出、版本与配置检查、读档前备份、失败回滚、空间不足和中断恢复 |
**出口条件:** 同一锁定内核下 100 次存读档循环通过;损坏、截断、错误哈希、空间不足和写入中终止均不破坏此前有效提交;存档包导出后重新导入可恢复;仅靠手柄完成选择槽位、存档、读档和退出。
反序列化失败视为内核状态可能已改变:优先恢复读档前快照,回滚失败则安全卸载并重新加载游戏,使用已提交的有效电池存档。不能继续运行未知状态。不同内核提交的即时存档默认拒绝自动恢复,保留原文件并说明原因;跨版本兼容需独立验证。
### M6/0.6.x:完整日常界面
| 版本/任务 | 工作内容 |
| --- | --- |
| 0.6.0/M6-01 | 完善游戏库、搜索、收藏、最近游玩、隐藏列表项和再次导入恢复关联 |
| 0.6.1/M6-02 | 显示比例、缩放、过滤、音量、静音、输入和快进开关;设置持久化 |
| 0.6.2/M6-03 | 存档管理、游戏信息、可理解的错误提示、保存状态和失败重试入口 |
| 0.6.3/M6-04 | 虚拟方向键、A/B、Start、Select、多点触控;首次使用引导和无手柄流程 |
**出口条件:** 首次安装后从导入到保存退出的流程完整;全手柄和纯触屏两条路径均可使用;触屏与手柄同时输入时,松开一个来源不会释放另一个来源仍按住的键。所有页面覆盖空列表、加载中、失败、无手柄和长中文文件名状态。
### M7/0.7.x:MagicOS 10 专项适配
| 任务 | 工作内容 |
| --- | --- |
| M7-01 | 采用 AndroidX 返回处理;游戏返回打开暂停菜单、菜单返回继续、设置返回上级、列表返回退出 |
| M7-02 | 横屏安全区域、挖孔、系统栏、手势边缘及目标设备提供的刷新率模式验证 |
| M7-03 | 后台、锁屏、通知/来电导致的焦点变化、音频路由变化、Surface 和 Activity 重建联调 |
| M7-04 | 进程重建、异常会话恢复、重复崩溃保护;完善状态展示、日志轮换和诊断导出 |
**出口条件:** 20 轮后台/恢复及 20 轮锁屏/解锁后无黑屏、后台声音和卡键;Surface 重建不重复创建内核;同一异常 ROM/状态不会导致启动循环。回前台先恢复资源,再由用户继续。无需关闭系统全部省电策略,不引入后台持续模拟服务。
### M8/0.9.x:发布候选版
| 任务 | 工作内容 |
| --- | --- |
| M8-01 | 冻结功能、依赖和内核版本,完成全部兼容样本、输入、音频、系统及存档回归 |
| M8-02 | 代表游戏长时间运行;收集速度、帧时间、内存、音频欠载和输入延迟,修复崩溃及 ANR |
| M8-03 | 检查全部发布原生库与 APK 的 16 KB 对齐;4 KB 和 16 KB 环境运行;API 28 基线冒烟 |
| M8-04 | 同应用 ID/签名覆盖升级、Room/设置迁移和存档兼容验证;整理发布源码、许可证、符号和已知问题 |
**出口条件:** 第 7 节发布门槛全部通过,无阻断或高优先级缺陷;最终候选包而非仅调试包通过安装、加载、输入、音频、保存恢复及退出冒烟。修复后重跑受影响用例;内核、时钟或存档格式变动在开发时先做局部检查,冻结候选前补齐受影响的完整测试集,按 todo.md 分级规则复用仍有效证据。
### M9/1.0.0:正式交付
| 任务 | 工作内容 |
| --- | --- |
| M9-01 | 核对范围、验收报告与已知问题,确定版本号和递增 `versionCode`,建立发布源码标记 |
| M9-02 | 生成签名 APK、校验和、源码包、依赖与补丁清单、原生符号和使用说明 |
| M9-03 | 对正式交付 APK 做最后冒烟,归档构建环境、验收记录及后续问题清单 |
**出口条件:** 用户可安装并在规定测试范围内完成完整使用流程;产物可以追溯至同一源码版本。签名密钥安全保管,不放入仓库或交付源码包。
## 6. 文档、目录与日常交付
建议延续设计中的单应用目录:
```text
NESLite/
├── design.md
├── app/src/main/
│ ├── java/<package>/{ui,session,input,storage,diagnostics}/
│ ├── cpp/{jni,core_host,engine,video,audio,state}/
│ └── res/
├── app/src/test/ Kotlin 纯逻辑测试
├── app/src/androidTest/ Android 集成测试
├── third_party/{fceumm,libretro,oboe}/
├── tests/{native,input,state,compatibility,lifecycle}/
├── scripts/ 构建、测试、对齐检查和诊断整理
├── docs/
│ ├── development_plan_V1.0.md
│ ├── requirements.md
│ ├── architecture.md
│ ├── build.md
│ ├── controller-x5lite.md
│ ├── save-format.md
│ ├── acceptance.md
│ └── reports/
├── THIRD_PARTY_NOTICES
└── LICENSE
```
此处为待建立的结构,不表示这些文件已存在。M0 建立需求/构建文档,M1 完成设备档案,M2 完成架构和内核支持清单,M5 完成存档格式,M8 汇总验收和发布说明。原生测试需接入独立测试构建;仅放入 `tests/` 不等于已经执行。
每个任务按“实现 → 自动验证 → 必要实机验证 → 更新文档/已知问题 → 提交”完成。M0 建立可本地执行的统一检查入口;如之后配置远程 CI,复用相同入口,不另设只在远程存在的步骤。
每份阶段报告至少记录:应用版本、源码提交、内核提交、设备与系统、ABI/页大小/刷新率、ROM 哈希、配置、测试步骤、预期、实际结果、日志位置及未通过项。尚未执行的测试明确标记“未验证”。
## 7. 测试策略与量化验收
### 7.1 环境与样本
| 测试环境 | 用途 | 限制 |
| --- | --- | --- |
| 目标 MagicOS 10 手机+X5 Lite | 输入、音频、性能、插拔、系统适配的主验收 | 记录真实机型和参数;不由系统名称推断硬件 |
| API 28 的可用测试设备或模拟器 | 最低系统版本的安装、导入、运行和保存冒烟 | 不替代目标手机的性能与手柄测试 |
| 4 KB 与 16 KB 的适配环境 | 原生加载、游戏运行、音频和保存恢复 | 记录实际 ABI;x86_64 的通过不能替代 arm64 原生库检查 |
| 目标手机支持的各刷新率、可用音频路由 | 速度独立性、显示和设备切换 | 没有的硬件条件记录为未覆盖,不虚构结果 |
M0 建立版本化 ROM 清单,只使用自制或有权使用的样本。M2 至少 3 个样本;M8 建议不少于 12 个,覆盖 Mapper 0/1/2/3/4、NTSC/PAL、电池存档,以及 iNES 和 NES 2.0 文件头;多个维度可以由同一 ROM 覆盖。Dendy 时序和更多 Mapper 在有合适样本时扩展,未覆盖项明确记录。
清单记录来源与使用/再分发条件、SHA-256、Mapper、区域、存档类型、预期表现及结果。功能测试 ROM 有自检结果时以其结果验收;游戏样本使用固定操作步骤与观察点。不以“能显示标题画面”认定完整兼容。
### 7.2 自动测试与人工测试分工
| 层次 | 必须覆盖的行为 |
| --- | --- |
| Kotlin 单元测试 | 输入状态合成、方向冲突、死区滞回、去重、映射持久化、会话转换和文件头校验 |
| 原生单元/集成测试 | 有界缓冲、重采样连续性、时钟和快进切换、命令次序、序列化失败回滚 |
| Android 集成测试 | SAF 导入/导出、Room 事务与升级、生命周期、Surface 重建、虚拟按键取消事件 |
| 故障注入 | 截断、错误校验和、错误 ROM/内核版本、写盘不足、提交中终止、重复异步命令 |
| 实机人工验收 | X5 Lite 组合输入与热插拔、手柄焦点导航、听感、系统返回、安全区域、长时间游玩 |
文件写入故障通过可替换的文件接口或测试环境注入;不以填满用户手机全部空间作为常规测试方法。写盘中断测试覆盖临时写入、替换前和替换后等边界,并区分已提交与尚未提交数据。
### 7.3 V1.0 发布指标
以下为目标,均须保存测量记录。增加的测量窗口和采样方法用于使设计中的指标可执行;如需调整,在 M3/M5 实测后更新计划和验收文档,不在发布时临时放宽以掩盖失败。
| 指标 | 目标 | 测量方法 |
| --- | --- | --- |
| 正常模拟速度 | 99.5%~100.5% | NTSC、PAL 各运行至少 30 分钟;计算已执行模拟时间/有效单调时钟时间;检查每个连续 60 秒窗口和全程均值,排除暂停、加载、快进 |
| 长时稳定性 | 代表性样本各 2 小时,无崩溃、ANR、持续内存增长 | 至少选动作/滚屏与电池存档两类;每分钟采集 Java/native 内存与 PSS,检查预热后趋势及往返操作是否泄漏 |
| 输入可靠性 | 组合序列和清理场景无残留、无重复菜单动作 | 自动回放和实机组合输入;统计异常,必须为 0 |
| 软件输入延迟 | 正常负载 P95 不超过 1 个实际模拟帧 | 同一单调时间域记录 Android 事件接收至首次内核采样,目标机采样至少 1,000 次,排除暂停/绑定界面 |
| 存档可靠性 | 100 次存读档全部通过,故障不破坏已提交有效版本 | 比较固定测试状态、游戏进度与校验值;覆盖手动槽、自动轮换、电池存档和导入导出 |
| 手柄热插拔 | 20 轮断开/重连通过 | 方向及 A/B 按住时拔出,检查暂停、清理、配置匹配和重新操作 |
| 后台与锁屏恢复 | 后台 20 轮、锁屏 20 轮通过 | 检查无后台声音、无黑屏/卡键,用户继续后运行正常 |
| 音频稳定性 | 无持续爆音、旧音频积压或累积性音画偏移 | NTSC/PAL 各 30 分钟听感与水位记录;流预热后正常前台段目标欠载为 0,切换段单独统计并确认恢复 |
| 4 KB/16 KB | 原生加载和基本运行通过 | 记录页大小;逐库 ELF 与 APK 对齐检查,并执行运行、声音和保存恢复 |
| 安装升级 | 新装及同签名覆盖升级通过 | 保留至少一个旧测试版本的数据集,验证 ROM 关联、收藏、设置、游戏存档及状态兼容处理 |
软件输入延迟只覆盖“应用收到事件 → 内核采样”,不能作为按键到屏幕总延迟。音频环形缓冲水位也不能代表全部端到端延迟;如报告端到端指标,另附实测方法与证据。
### 7.4 缺陷分级与放行
- **阻断:** 无法安装/启动/运行,已提交存档损坏或串档,启动崩溃循环。必须修复。
- **高优先级:** 可复现崩溃或 ANR、速度错误、后台发声、持续黑屏、卡键、主要手柄操作中断。必须修复。
- **一般:** 不影响核心流程的显示或提示问题,以及测试范围外个别 ROM 的兼容问题。记录复现、影响和绕行方法后逐项决定是否放行。
只对已列明并通过测试的范围声明兼容;不能把规定测试集中的失败通过更改名称或删除记录视作通过。范围调整需同步设计依据、计划及已知问题。
## 8. 风险与处理安排
| 风险 | 最早检查 | 处理方式 |
| --- | --- | --- |
| 实际手机环境或 X5 Lite 键码与设想不同 | M1 | 输出设备和输入档案;以实际事件建立默认映射,保留通用配置 |
| FCEUmm 构建或宿主接口遗漏 | M0~M2 | 固定提交;维护环境请求清单和最小加载测试,局部补丁单独记录 |
| 音频时钟、重采样或缓冲导致变速/延迟累积 | M3 | 先测时序与水位,再调整缓冲;保留音频不可用的时钟回退 |
| Surface、音频流重建与退出发生竞态 | M2~M7 | 单内核线程、会话编号和状态检查,重复调用及迟到结果测试 |
| 存档写入中断或读档失败破坏进度 | M2 基础,M5 完整 | 快照隔离、原子提交、有效备份、故障注入和失败回滚 |
| 内核升级使即时存档失效 | M5/M8 | V1.0 冻结内核;元数据校验、保留旧文件,升级前做兼容测试 |
| 16 KB 检查只覆盖自研库而漏掉依赖 | M0、M8 | 清点最终 APK 内每个原生库,检查对齐并在实际 16 KB 环境运行 |
| 实机或合法测试 ROM 不齐 | M0 | 早建缺口清单;可继续独立开发,但不跳过对应验收 |
| UI 或附加功能挤占可靠性工作 | 全程 | 优先内核、时钟、输入和存档;本轮不加入范围外功能 |
| 源码与发布包、许可证不对应 | M0、M8~M9 | 固定来源,保存补丁/构建选项和符号,发布时逐项核对 |
FCEUmm 上游声明采用 GNU GPL v2,并要求参考源文件头部细节,见 [FCEUmm 上游仓库](https://github.com/libretro/libretro-fceumm)。按设计采用 GPL 兼容的源码交付方案;M0 核对选定提交及全部依赖条款,M8 准备与 APK 对应的完整源码、构建说明、版权和许可证材料。libretro 头文件的许可证不能替代所链接内核的许可证。
## 9. 最终交付清单
- [ ] 签名 `NESLite-1.0.0-arm64-v8a.apk` 及 SHA-256 校验和。
- [ ] 对应源码版本/源码包、锁定依赖、FCEUmm 提交、构建选项和本地补丁。
- [ ] 从干净环境构建的说明、精确工具链版本、原生符号与必要的混淆映射文件。
- [ ] 快速使用说明:游戏导入、手柄模式/映射、暂停、存档、导出和恢复。
- [ ] 设备与 ROM 兼容清单、自动和实机测试报告、性能及 16 KB 检查结果。
- [ ] 存档格式、内核升级兼容策略、升级安装记录和已知问题。
- [ ] `LICENSE`、`THIRD_PARTY_NOTICES` 及对应依赖许可证材料。
只有 F01~F15 在约定范围内完成、发布指标通过且无阻断/高优先级缺陷时,才将应用标记为 1.0.0。
## 10. 首轮启动清单
本节保留初始启动顺序。首轮执行 M0 和 M1,先交付能安装、能加载原生库、能验证真实手柄输入的 0.1.x 诊断版。
1. 建立 Android+JNI 最小工程,锁定工具链,生成首个可安装 APK。
2. 确定应用 ID、依赖提交、基础数据目录及版本管理方式。
3. 读取目标手机系统、ABI、页大小、屏幕和刷新率,导出设备信息。
4. 接入 X5 Lite 设备枚举、按钮/轴展示、组合输入和松开状态。
5. 验证失焦、拔出与重连,形成实测键位表与诊断报告。
6. 完成 M1 出口检查后,进入 M2 的 ROM 导入和 FCEUmm 接入。
首轮以设备与手柄实测为目标。首次音画完整的可玩验收在 M3,可靠日常使用验收在 M6~M7,正式发布在 M8~M9 全部门槛通过后进行。
## 11. F15 增补:内置内核选择(2026-09-14)
用户确认在应用内置的多个内核间切换,并反馈“龙珠英雄”无法打开、黑屏。本增补覆盖原设计中不提供
内核切换的限制;仍不提供外部内核文件、在线下载或自动尝试所有内核。原 M0~M9 编号和已有验收证据
保留,增加 XCORE 实现任务及 GCORE 门槛,纳入 G8 汇总。0.9.16 为开发验证版本,原工期估算不含本增补。
行为契约:初始默认 FCEUmm,可设 Nestopia 为默认;每个 ROM 可覆盖默认或恢复“跟随默认”。选择持久化,
只在下次打开游戏时生效;旧会话先保存/卸载/销毁,再初始化所选内核。单次只运行一个内核实例。
FCEUmm 保留原存档目录,Nestopia 使用独立目录;电池、即时存档、备份和异常恢复计数均隔离,跨内核
状态与存档包拒绝导入。固定提交、具体目录和封装细节以依赖清单及 `docs/save-format.md` 为准。
| 任务 | 交付内容 | 前置 | 最小验收 |
| --- | --- | --- | --- |
| XCORE-01 | 固定 Nestopia 来源并接入双内核宿主、像素格式转换和打包 | 现有可构建的 M2/M3 接口 | L1:arm64 构建、必需入口、局部转换用例、全部库静态对齐 |
| XCORE-02 | 默认和逐游戏选择、持久记录、下次加载生效及当前内核展示 | XCORE-01 | L1:应用编译,默认/覆盖/取消与磁盘重开读取的局部测试 |
| XCORE-03 | 按内核隔离存档与恢复标记,校验存档包身份,保留旧 FCEUmm 数据 | XCORE-01、现有 M5 格式接口 | L1:旧路径、独立路径、包往返、跨内核拒绝、旧包归属 |
| XCORE-04 | 在 Android 验证切换、重启持久化和独立进度 | XCORE-02、XCORE-03 | L2:同进程 FCEUmm→Nestopia→FCEUmm,一份带电池及一份无电池样本的相关分支 |
| XCORE-05 | 定位“龙珠英雄”黑屏,按已确认哈希修正制式选择并记录双内核结果 | XCORE-04、具体 ROM 与目标手机;桌面复现可提前独立完成 | L1:精确匹配及选项隔离;L2:记录哈希/Mapper/区域/包与内核提交,分别验证加载、进入游戏、输入及音画 |
GCORE 为 L3 汇总门槛,依赖 XCORE-01~05;待办条目给出可勾选标准。开发时只运行受影响模块的局部
检查和上述短路径;冻结候选时一次性补受影响内核的兼容集、H-AV、H-SAVE 和 H-NATIVE,已有仍有效证据
按待办第 2 节复用。GCORE 与 G8 引用同一报告,不能各启动一轮重复测试。H-LONG/H-INPUT/H-UPGRADE
保留原发布节点,只有相关证据失效或尚未取得时补齐。桌面测试和静态对齐通过不代替手机加载、16 KB 运行
或具体游戏兼容结果。
接入证据见 [双内核报告](reports/core-selection-0.9.16.md),具体 ROM 的制式修复见
[0.9.17 记录](reports/long-zhu-ying-xiong-0.9.17.md),任务状态只在 [todo.md](../todo.md) 勾选。