40 KiB
NESLite V1.0 开发计划
| 项目 | 内容 |
|---|---|
| 产品名称 | NESLite |
| 文档版本 | V1.0 |
| 编制日期 | 2026-09-12 |
| 最近修订 | 2026-09-14:按用户确认增加内置内核选择 F15,见第 11 节 |
| 需求依据 | 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 兼容说明。本计划不将这些版本称为“最新”;实际依赖锁定及构建成功记录属于 M0 交付物。
NDK r28 起默认采用 16 KB 对齐,但仍需检查全部原生依赖、ELF、APK 打包与运行时行为,并在 16 KB 环境运行。检查依据为 Android 官方 16 KB 适配指南。
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 官方接口说明;M2 需对照锁定版本实际使用的请求形成支持清单,而不是把所有请求都返回成功。
3.2 线程所有权
- Android 主线程处理 UI、输入事件和生命周期,只提交异步命令,不等待模拟线程或文件写入。
- 模拟线程串行调用初始化、加载、
retro_run()、重置、状态序列化、反序列化、卸载和销毁;图像和音频在回调中复制到宿主缓冲,存档内存在保存采集点复制为不可变快照,避免其他线程使用内核临时指针或正在变化的内存。 - GL 线程只显示最近可用的完整帧。过时画面可以丢弃,但不能因此跳过正常模式下应执行的模拟帧。
- 音频回调线程只消费环形缓冲,数据不足时补静音并计数;不做文件 I/O、动态分配、睡眠或等待互斥锁。此约束参照 Oboe 低延迟音频指南。
- 文件工作线程处理不可变快照和导入导出;每个 ROM 的存档写入按序提交,旧任务不得覆盖新任务。
视频采用预分配的双缓冲或三缓冲,交接时明确读写所有权;音频采用有界环形缓冲。重采样和水位控制在非音频回调线程完成。所有队列、日志和历史统计都有容量上限。
3.3 会话状态与命令
Idle → Loading → Paused → Running
↑ ↓
└─ Pausing
Paused → Stopping → Idle
加载或运行失败 → Error → 安全清理 → Idle
Load / Pause / Resume / Reset / Save / LoadState / Stop均通过命令队列处理,返回完成或失败结果;输入快照独立更新。- 加载成功后仅在前台、Surface 可用且资源就绪时首次自动运行;后台恢复和断柄恢复需要用户继续。
- 暂停菜单、失焦、锁屏、断柄及 Surface 丢失先触发暂停和输入清理;音频及时静音。M5 起再纳入完整恢复点提交。
Reset、存档和读档在帧边界执行;读档期间暂停推进,成功或回滚后清空音频、废弃旧待显示帧并重建时间基线。- 使用会话编号标记异步工作;已经退出的游戏不能被迟到的加载、音频重建或保存通知重新激活。
- Activity 重建只重新连接会话与显示资源,不创建第二个模拟线程;进程重建则从磁盘记录恢复选择,不依赖旧对象。
3.4 持久化约定
应用内部 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 官方文档给出的 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. 文档、目录与日常交付
建议延续设计中的单应用目录:
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 上游仓库。按设计采用 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 诊断版。
- 建立 Android+JNI 最小工程,锁定工具链,生成首个可安装 APK。
- 确定应用 ID、依赖提交、基础数据目录及版本管理方式。
- 读取目标手机系统、ABI、页大小、屏幕和刷新率,导出设备信息。
- 接入 X5 Lite 设备枚举、按钮/轴展示、组合输入和松开状态。
- 验证失焦、拔出与重连,形成实测键位表与诊断报告。
- 完成 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 运行 或具体游戏兼容结果。