# 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/.nes ├── saves//battery/ 游戏自身存档及有效备份 ├── saves//states/ 10 个手动槽位及元数据、缩略图 ├── saves//auto/ 最近 3 份自动恢复点 ├── saves/cores/nestopia// Nestopia 独立的 battery、states、auto、recovery 与会话标记 ├── system/ 内核需要的稳定系统目录 └── diagnostics/ 限额日志 ``` FCEUmm 延续 `saves//`,读档保护副本及会话标记也在各内核、各 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//{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) 勾选。