Files
NESLite/docs/development_plan_V1.0.md

40 KiB
Raw Permalink Blame History

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 线程所有权

  1. Android 主线程处理 UI、输入事件和生命周期,只提交异步命令,不等待模拟线程或文件写入。
  2. 模拟线程串行调用初始化、加载、retro_run()、重置、状态序列化、反序列化、卸载和销毁;图像和音频在回调中复制到宿主缓冲,存档内存在保存采集点复制为不可变快照,避免其他线程使用内核临时指针或正在变化的内存。
  3. GL 线程只显示最近可用的完整帧。过时画面可以丢弃,但不能因此跳过正常模式下应执行的模拟帧。
  4. 音频回调线程只消费环形缓冲,数据不足时补静音并计数;不做文件 I/O、动态分配、睡眠或等待互斥锁。此约束参照 Oboe 低延迟音频指南。
  5. 文件工作线程处理不可变快照和导入导出;每个 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 诊断版。

  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 运行 或具体游戏兼容结果。

接入证据见 双内核报告,具体 ROM 的制式修复见 0.9.17 记录,任务状态只在 todo.md 勾选。