Files
NESLite/design.md
T
2026-09-12 11:24:43 +08:00

584 lines
26 KiB
Markdown
Raw 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.
可以。针对你的 **Honor MagicOS 10 手机+小鸡 X5 Lite 手柄**,建议把项目正式定义为:
> **NESLite Android:采用 FCEUmm 模拟内核、自研 Android 前端、原生手柄输入的轻量 NES/FC 模拟器。**
开发路线固定为:
**先验证手机与手柄 → 接通模拟内核 → 完成音画同步 → 完善手柄操作 → 建立可靠存档 → 完善界面与系统适配 → 回归测试和发布。**
荣耀官方资料将 MagicOS 10 列为基于 Android 16,因此首要适配目标按 **Android 16/API 36**设置;具体手机的处理器架构、屏幕刷新率和内存页大小,由首个诊断版本读取,不预先猜测。
下面给出完整的实施计划。**所列版本是开发里程碑,性能和稳定性指标是验收目标,并非已经完成的实测结果。**
---
# 一、先冻结 V1.0 的功能范围
第一版的目标不是做一个功能庞大的“全能模拟器”,而是:
> **在你的手机上,插入 X5 Lite、选择游戏即可稳定游玩,声音正常、操作准确、进度不会轻易丢失。**
## 1. V1.0 必须具备的功能
| 功能领域 | V1.0 范围 |
|---|---|
| 游戏支持 | NES/FC 卡带游戏,优先支持 `.nes` 文件;识别 iNES、NES 2.0 文件头,具体卡带兼容性以内核和测试结果为准 |
| 游戏导入 | 通过 Android 系统文件选择器导入,支持中文文件名和重复文件识别 |
| 游戏管理 | 游戏列表、搜索、最近游玩、收藏、从列表移除 |
| 游戏运行 | 启动、暂停、继续、重置、退出游戏 |
| 图像显示 | 横屏、保持显示比例、整数缩放、最近邻/线性过滤切换 |
| 音频 | 正常声音输出、音量控制、静音、音画同步 |
| 手柄 | X5 Lite 优先适配,兼容 Android 标准手柄输入 |
| 按键设置 | 默认映射、A/B 交换、自定义绑定、摇杆死区、A/B 连发 |
| 存档 | 游戏自身存档、即时存档、自动恢复点、存档导入导出 |
| 系统适配 | 后台暂停、锁屏暂停、手柄断开处理、界面重建和音频设备变化处理 |
| 无手柄操作 | 基础虚拟方向键、A/B、Start、Select |
| 诊断 | 手柄测试、运行状态、错误日志、诊断信息导出 |
FCEUmm 已提供卡带存档、即时存档和多种卡带 Mapper 支持,但**内核支持某项功能,不等于我们编写的 Android 前端已经完成该功能**,仍需要逐项接入和验证。
## 2. V1.0 暂不纳入的功能
暂不做联网对战、云存档、多平台模拟、在线下载游戏、复杂 CRT 滤镜、回溯、提前运行降低延迟(run-ahead),也不在第一版开放用户自行下载和切换内核。
**FDS 磁碟机、光枪、四人适配器以及第二只手柄的完整体验,放到 V1.1 之后。** FDS 还涉及额外固件文件,因此不与普通 `.nes` 卡带游戏混在首版范围中。
---
# 二、技术方案与工程基线
## 1. 推荐技术组合
| 模块 | 建议选择 | 设计目的 |
|---|---|---|
| 应用语言 | Kotlin | 界面、系统交互、文件导入、手柄事件 |
| 界面框架 | AndroidX+原生 View | 首版减少框架复杂度,方便处理游戏界面焦点 |
| 模拟内核 | FCEUmm,固定上游提交版本 | 不从零开发 NES CPU、PPU、APU 和 Mapper |
| 内核接口 | libretro | 将内核与音视频、输入、存档管理分离 |
| 原生运行层 | C/C+++Android NDK | 内核调用、缓冲、时钟和渲染适配 |
| Kotlin/C++ 连接 | JNI | 传递控制命令、输入状态和界面生命周期事件 |
| 图像输出 | `GLSurfaceView`+OpenGL ES | 显示内核输出,完成缩放和比例控制 |
| 音频输出 | Oboe | 低延迟音频与设备差异处理 |
| 游戏索引 | Room | 保存游戏元数据、最近游玩和收藏状态 |
| 应用设置 | DataStore | 保存显示、音频和操作偏好 |
| 构建 | Gradle+CMake/必要的上游构建适配 | 可重复构建,避免手工复制不明来源的 `.so` |
这里采用的是**自己编写轻量 libretro 前端**,不是修改整个 RetroArch 界面。libretro 允许内核以静态库或动态库形式被前端调用,因此首版可把内核固定打包到应用中。
## 2. SDK 和工具链建议
建议采用以下保守起点,而不是为了“最新”频繁更换构建工具:
```text
最低系统:Android 9 / API 28
主要目标:Android 16 / API 36
minSdk:28
compileSdk:36
targetSdk:36
发布架构:arm64-v8a
测试架构:按测试环境增加 x86_64
AGP:8.13.2
Gradle:8.13
JDK:17
NDK:r28 或更新的稳定版本,工程中锁定精确版本
```
AGP 8.13 系列支持 API 36,官方兼容表给出的 Gradle 和 JDK 基线分别为 8.13、17;这里是针对目标系统选择的构建组合,不是在宣称它是当前最新版本。
**NDK 不沿用旧工程里随机留下来的版本。** Android 官方说明,NDK r28 及以上默认采用 16 KB 对齐;同时还需要检查最终 APK 中的原生库打包对齐、第三方依赖和运行时代码。不能只升级 NDK,就认为整个应用已经验证通过。
所有依赖都应锁定具体版本,FCEUmm 额外记录 **Git commit、构建选项和本地补丁**,禁止使用会自动变化的依赖版本。
---
# 三、软件架构:界面与模拟执行严格分开
## 1. 总体结构
```text
NESLite Android
│
├── 应用界面
│ ├── 游戏列表
│ ├── 游戏画面与暂停菜单
│ ├── 按键映射
│ ├── 存档管理
│ └── 设置与诊断
│
├── Android 平台适配
│ ├── 手柄事件与设备监听
│ ├── 系统文件选择器
│ ├── Activity / Surface 生命周期
│ └── 音频焦点与设备变化
│
├── JNI 桥接
│ ├── 加载 / 暂停 / 重置 / 退出命令
│ ├── 输入状态更新
│ └── 错误和运行状态回传
│
├── 原生运行引擎
│ ├── LibretroHost
│ ├── EmulationLoop
│ ├── VideoRenderer
│ ├── AudioEngine
│ ├── InputSnapshot
│ └── SaveStateManager
│
└── 固定版本 FCEUmm
```
## 2. 线程职责
建议从第一版就明确线程所有权,避免后面靠大量锁修补。
| 线程或执行环境 | 允许处理的工作 | 不应处理的工作 |
|---|---|---|
| Android 主线程 | 界面、输入事件、发送控制命令 | 执行模拟、写大文件、等待内核长时间返回 |
| 模拟线程 | 调用内核、读取输入快照、生成图像和声音、取得存档快照 | 操作 Android 界面、直接进行耗时文件写入 |
| GL 渲染线程 | 上传图像、计算显示区域、提交画面 | 修改内核状态 |
| 音频回调线程 | 从音频缓冲读取数据并输出 | 文件操作、等待互斥锁、动态分配大量内存、执行模拟内核 |
| 文件工作线程 | 导入游戏、写存档、导出诊断 | 直接读取正在变化的内核内存 |
**所有改变内核状态的调用统一在模拟线程执行。** 例如,用户点击“读档”,界面只提交命令,由模拟线程在合适的帧边界执行,而不是从主线程直接调用 `retro_unserialize()`。
Oboe 官方特别要求低延迟音频回调避免阻塞、文件读写和内存分配,因此音频线程必须与模拟执行和存档写盘解耦。
---
# 四、分版本开发路线
建议采用 **0.1.x → 0.2.x → … → 0.9.x → 1.0.0** 的递进路线。每个阶段都有可安装 APK 和明确验收结果,不以“代码已经写完”作为完成标准。
## 阶段 0.1.x:工程基线与 X5 Lite 诊断
**目标:先证明手机能稳定加载原生库、接收真实手柄输入。**
| 小版本 | 工作内容 |
|---|---|
| 0.1.0 | 建立 Android+JNI 工程;读取系统版本、ABI、屏幕信息;验证原生库加载 |
| 0.1.1 | 枚举输入设备,显示设备名称、厂商/产品标识、输入源和轴信息 |
| 0.1.2 | 显示所有按钮按下/松开事件、方向键、摇杆和扳机事件 |
| 0.1.3 | 增加热插拔、失焦清理、诊断导出,形成 X5 Lite 初始输入档案 |
**交付物:** 手柄诊断 APK、设备诊断 JSON、X5 Lite 实测键位表。
**验收条件:** 在你的手机上,方向和 A/B 能同时按下;松开后状态归零;拔出手柄不会残留按键;重连后能够继续检测。
这一阶段没有必要先做漂亮的游戏列表,也不需要游戏 ROM。
## 阶段 0.2.x:接通 FCEUmm,形成基础游戏运行链路
**目标:能够导入并运行游戏,看到正确画面,并用手柄操作。**
| 小版本 | 工作内容 |
|---|---|
| 0.2.0 | 固定 FCEUmm 提交版本,完成 NDK 编译和 libretro 接口封装 |
| 0.2.1 | 完成 `.nes` 导入、文件头检查、内部存储和 ROM 加载 |
| 0.2.2 | 接通视频回调、像素格式处理、OpenGL 显示和基础缩放 |
| 0.2.3 | 将 0.1.x 的输入接入内核,实现启动、暂停、重置和退出 |
**交付物:** 基础运行 APK、内核构建记录、首批游戏兼容清单。
**验收条件:** 至少通过一组合法测试 ROM,并能完成“加载—运行—暂停—继续—重置—退出—重新加载”的完整流程。
此时必须接入 libretro 的环境回调、配置选项和目录等必要能力,不能只实现 `retro_run()`,然后把所有其他请求都当作成功。libretro 的环境回调用于内核与前端协商能力,错误的调用顺序也可能导致未定义行为。
## 阶段 0.3.x:声音、帧率和音画同步
**目标:从“游戏能动”提升到“游戏速度正确、声音连续”。**
| 小版本 | 工作内容 |
|---|---|
| 0.3.0 | 接入 Oboe 和音频环形缓冲 |
| 0.3.1 | 实现音频设备实际采样率与内核采样率之间的适配 |
| 0.3.2 | 完成模拟时钟、视频显示节奏、缓冲水位控制 |
| 0.3.3 | 实现静音、音频焦点处理、设备切换和诊断统计 |
**交付物:** 音画完整的可玩 APK、帧时间与音频缓冲统计。
**验收条件:** 连续游玩测试中没有持续爆音、越玩声音越滞后、游戏速度逐渐偏移等问题;暂停后声音停止,恢复后没有旧声音积压播放。
## 阶段 0.4.x:完成 X5 Lite 的实际操作体验
**目标:不只是能接收按键,而是可以只靠手柄完成主要操作。**
| 小版本 | 工作内容 |
|---|---|
| 0.4.0 | 默认映射、A/B 交换、自定义绑定 |
| 0.4.1 | 摇杆死区、方向冲突处理、输入去重 |
| 0.4.2 | A/B 连发、暂停菜单、可配置快捷功能 |
| 0.4.3 | 手柄导航游戏列表和菜单,持久化控制器档案 |
**交付物:** X5 Lite 配置、手柄操作说明、按键回归报告。
**验收条件:** 从游戏列表进入游戏、暂停、选择存档、继续和退出,都能通过手柄完成,不依赖频繁触屏。
## 阶段 0.5.x:可靠存档与恢复
**目标:保护进度,避免“游戏可以玩,但是不敢退出”。**
| 小版本 | 工作内容 |
|---|---|
| 0.5.0 | 游戏自身存档读取、变化检测和安全写盘 |
| 0.5.1 | 即时存档、读档、槽位和缩略图 |
| 0.5.2 | 自动恢复点、备份轮换、损坏检测 |
| 0.5.3 | 存档导入导出、跨版本检查和失败恢复 |
**交付物:** 存档格式说明、故障测试报告、可导出的存档包。
**验收条件:** 正常退出后可恢复;存档文件截断时有明确错误;写盘失败不覆盖最后一个有效存档;不同 ROM 不会互相覆盖进度。
## 阶段 0.6.x:完善日常使用界面
**目标:形成可以长期使用的完整应用。**
| 小版本 | 工作内容 |
|---|---|
| 0.6.0 | 游戏列表、搜索、收藏、最近游玩 |
| 0.6.1 | 显示、音频、手柄设置 |
| 0.6.2 | 存档管理页面、游戏信息和错误提示 |
| 0.6.3 | 基础虚拟按键、首次使用引导和无手柄操作 |
**验收条件:** 首次安装后,用户能够完成“导入游戏—连接手柄—开始游戏—保存—退出”,不需要理解内部目录和 libretro 概念。
## 阶段 0.7.x:MagicOS 10 专项适配
**目标:处理系统行为,而不是只验证应用一直停留在前台的情况。**
主要测试返回手势、横屏安全区域、锁屏与解锁、通知和来电、音频设备变化、应用切换、Surface 重建、不同刷新率,以及手柄接入状态变化。
**交付物:** MagicOS 10 专项兼容报告。
**验收条件:** 不出现后台继续发声、返回键误退出、恢复后黑屏、手柄失效或者输入卡住等问题。
## 阶段 0.9.x:回归、性能和发布准备
完成批量兼容测试、长时间运行测试、原生崩溃定位、16 KB 兼容检查、升级安装测试、许可证整理和发布签名。
**交付物:** 候选发布 APK、对应源码、构建说明、测试报告和已知问题清单。
## 阶段 1.0.0:正式可用版本
只有在前述关键门槛全部通过后,才标记为 1.0.0。
**1.0.0 表示规定范围内可用且经过验证,不表示支持所有历史卡带、所有改版 ROM 或所有安卓设备。**
---
# 五、X5 Lite 适配的具体设计
## 1. 使用原生安卓模式
X5 Lite 应使用 **深蓝色指示灯的安卓模式**。官方说明,“视图+菜单”长按约 2 秒用于切换连接模式,部分手机还需要开启 OTG。
因此本项目明确:
**不依赖 G-Touch 触屏映射,不把“视图+菜单长按”设置成模拟器快捷键,也不把厂商功能键作为唯一的菜单入口。**
## 2. 默认按键映射
下面是应用层的建议映射,实际 Android 键码由 0.1.x 实测后绑定。
| 手柄操作 | 游戏内默认功能 |
|---|---|
| 十字方向键 | NES 上、下、左、右 |
| 左摇杆 | 可选的 NES 方向控制 |
| A | NES A |
| B | NES B |
| X | NES A 连发 |
| Y | NES B 连发 |
| 菜单键 | NES Start |
| 视图键 | NES Select |
| 右摇杆按下 | 打开/关闭暂停菜单 |
| RB | 按住快进,可关闭 |
| 其他肩键/扳机 | 默认保留,允许用户自定义 |
**快速读档默认不绑定一个容易误触的单键。** 读档会改变当前进度,首版更适合放在暂停菜单内,或要求用户主动配置快捷键。
X5 Lite 本身支持连发和按键布局交换,所以适配不能只根据按钮上的字母推断输入;测试时应先关闭手柄硬件连发,避免它与软件连发叠加。
## 3. 输入层必须处理的细节
Android 手柄的按钮和轴分别通过 `KeyEvent`、`MotionEvent` 上报;方向键可能是按键事件,也可能是 HAT 轴,部分扳机还可能同时上报轴和按钮事件。
据此,输入模块按以下规则设计:
**状态而不是点击。** NES 输入保存为“当前哪些按钮被按住”,正确支持方向+跳跃+攻击等组合。
**同一动作去重。** 同一个扳机同时上报轴和按钮时,不能让菜单动作触发两次。
**不同来源分别维护。** 手柄、摇杆和虚拟按键先保存各自状态,再合成为游戏输入,避免松开一个来源时错误释放另一个仍按住的来源。
**方向冲突有确定规则。** 首版建议左右同时按下时横向归零,上下同理;摇杆阈值采用按下/释放不同阈值,减少边界抖动。
**异常状态主动清理。** 手柄断开、应用失去游戏交互状态或进入暂停菜单时,清空相应输入,恢复后重新采样。
**配置与临时设备编号分离。** 控制器配置使用设备特征和实际按键档案匹配,连接时的设备编号只用于当前会话。
---
# 六、几个决定软件质量的实现细节
## 1. 模拟帧率不能写死成手机刷新率
FCEUmm 文档列出的 NTSC 运行频率约为 **60.10 帧/秒**,PAL/Dendy 约为 **50 帧/秒**;实际执行应读取内核返回的时序信息。
因此不能采用:
```text
手机每刷新一次 → 执行一帧游戏
```
也不能简单循环 `sleep(16)`。
建议采用:
```text
模拟线程:按照内核时序和音频缓冲状态执行
渲染线程:按照屏幕显示节奏显示最新可用画面
音频线程:按照音频设备请求消耗声音数据
```
正常模式由音频输出节奏和缓冲水位参与调节;音频不可用、测试模式和快进模式另有明确的时钟策略。
**丢弃过时的待显示画面,不等于跳过内核执行。** 两者必须区分,否则可能改变游戏速度和逻辑。
## 2. 不通过界面层搬运每一帧画面
建议在原生层保存图像缓冲,并交给 GL 线程显示,不要每帧创建新的 `Bitmap`,再通过界面状态更新显示。
视频适配必须处理内核给出的像素格式、宽高和行跨度 `pitch`,不假定每行一定是“宽度×固定字节数”;缓冲交接也不能保存一个已失效的内核临时指针。
显示设置将“4:3 显示”和“原始像素整数缩放”分开,避免为了铺满手机屏幕把画面强行拉宽。
## 3. 音频缓冲需要可测、可调
Oboe 支持请求低延迟和独占模式,但请求不一定能得到满足,程序需要检查实际打开的音频流参数并提供回退。
本项目建议记录:
```text
内核输出采样率
音频设备实际采样率
每次回调请求的帧数
音频缓冲水位
缓冲不足次数
音频流重建次数
```
先实现稳定的默认配置,再增加低延迟配置。不能把“缓冲设得最小”直接当成优化完成,也不能把环形缓冲长度当作全部端到端音频延迟。
## 4. 游戏导入后使用内部稳定副本
Android 系统文件选择器提供的是文档 URI,应该通过相应文件接口读取,不能把 `content://...` 当作普通文件路径交给 C 的文件函数。Storage Access Framework 可以让用户授权访问选定文件,而不要求应用取得整个存储空间的访问权限。
建议导入流程:
```text
用户选择文件
↓
检查大小、文件头和读取结果
↓
复制到应用内部文件目录中的临时文件
↓
计算 SHA-256
↓
校验并提交正式 ROM 文件
↓
建立游戏索引
```
ROM 的身份使用内容哈希,而不是文件名。这样同一游戏改名后可以识别为重复文件,不同游戏即使同名,也不会共用存档。
复制后的正式 ROM 放在应用内部文件目录,**不放在可能被清理的缓存目录**。
## 5. 游戏存档与即时存档分开管理
libretro 分别提供保存内存访问和状态序列化接口;即时存档不是简单复制游戏的电池存档。
建议采用以下数据策略:
| 类型 | 建议策略 |
|---|---|
| 游戏自身存档 | 检查内容变化,周期性提交;暂停和正常退出时补充提交 |
| 手动即时存档 | 10 个槽位,附带时间和缩略图 |
| 自动恢复点 | 独立于手动槽位,保留最近 3 份 |
| 覆盖保护 | 新文件校验成功后再替换,保留上一份有效备份 |
| 导出 | 使用系统文件选择器,默认不把 ROM 混入存档包 |
即时存档元数据至少记录:
```text
ROM 内容哈希
内核名称和提交版本
存档封装格式版本
相关内核配置
创建时间
数据长度
数据校验值
```
**不承诺跨 FCEUmm 版本即时存档自动兼容。** 升级时保留原文件,先验证再恢复;读档失败后,应恢复之前的有效状态或安全重新加载,不能继续运行一个可能已被部分修改的内核状态。
另外,读入较早的即时存档可能回退游戏进度,因此建议在读档前保留当前游戏存档备份。
## 6. 自动保存不等于不会丢失任何进度
设计上可以初步采用“游戏存档变化后周期性提交、即时恢复点定期生成”的策略,但应用被强制停止或进程突然终止时,不应依赖退出回调完成最后一次保存。
验收目标应表述为:
> **最近已经成功提交的存档保持有效;突然终止时可能丢失最后一次提交之后的进度,但不能把此前有效存档也破坏。**
---
# 七、MagicOS 10/Android 16 专项适配
## 1. 16 KB 原生库兼容
需要检查 FCEUmm、JNI 运行层、音频依赖和 C++ 运行库,以及最终 APK 的打包结果。
诊断阶段可通过以下命令读取实际设备页大小:
```bash
adb shell getconf PAGE_SIZE
```
这是 Android 官方给出的检查方式。即使你的手机当前使用 4 KB 页,也应在支持 16 KB 的测试环境中验证原生库,不能由系统名称推断页大小。
## 2. 返回导航与全面屏布局
Android 16 对目标 API 36 的应用启用新的返回导航行为,旧式 `onBackPressed()` 和仅拦截 `KEYCODE_BACK` 的做法不再可靠;同时需要处理全面屏布局,不能依靠旧的退出 edge-to-edge 开关。
本项目建议统一规定:
```text
游戏运行中返回 → 打开暂停菜单
暂停菜单中返回 → 继续游戏
设置页面返回 → 返回上一级
游戏列表中返回 → 正常退出应用
```
游戏画面和菜单分别计算安全区域,避免按钮落在挖孔、系统栏或手势边缘。
## 3. 生命周期与后台行为
首版明确选择:**切到后台就暂停,不做后台继续模拟。**
锁屏、应用切换或失去音频焦点时,按策略暂停内核、停止声音、清空输入,并请求存档提交。回到前台后先恢复画面和音频资源,再由用户继续游戏。
不把“关闭系统所有省电机制”作为正常运行前提,也不为了保活引入与模拟器无关的后台服务。
## 4. 系统回收与异常恢复
启动时检查上一会话是否异常结束。若某 ROM 或即时存档连续导致崩溃,下一次启动不自动重开它,而是进入游戏列表并提示恢复选择,避免形成启动即崩溃的循环。
---
# 八、测试与验收体系
建议把测试分成 **内核接入、手柄、系统、存档和性能** 五类,并保存可复现记录。
| 测试类别 | 重点场景 | 建议验收要求 |
|---|---|---|
| 安装与升级 | 首次安装、覆盖升级、重新启动 | 能安装运行,升级不误删游戏和存档 |
| 文件导入 | 中文名、同名不同内容、重复内容、损坏文件 | 不误覆盖,有清楚的失败提示 |
| 卡带兼容 | 常见 Mapper、不同区域时序、游戏存档 | 通过规定测试集合,记录不支持项 |
| 基础输入 | 方向+A/B、多键同时按、长按 | 无漏释放和重复菜单触发 |
| 热插拔 | 游戏中拔出、重连、待机唤醒 | 自动进入安全状态,重连后可继续 |
| 生命周期 | 锁屏、切后台、返回前台、Surface 重建 | 无持续黑屏、后台声音和输入卡住 |
| 存档 | 保存、读取、覆盖、损坏、磁盘不足 | 失败不破坏最后一份有效文件 |
| 进程终止 | 强制停止后启动 | 可以找到最近已提交的有效恢复点 |
| 音频 | 长时间运行、暂停恢复、设备切换 | 无持续爆音和累积性音画偏移 |
| 显示 | 不同刷新率、不同显示比例 | 游戏速度不随屏幕刷新率改变 |
| 原生兼容 | 4 KB/16 KB 环境 | 原生库正确加载并通过运行测试 |
## 建议的量化目标
这些指标在拿到实机数据后可以调整,但应提前定义测量方法。
| 指标 | 初始目标 |
|---|---|
| 正常速度 | 长时间平均模拟速度保持在目标速度的 99.5%~100.5% |
| 核心稳定性 | 代表性游戏连续运行 2 小时,无崩溃、ANR 和持续内存增长 |
| 输入可靠性 | 自动测试序列和人工组合输入测试中无残留按键 |
| 软件侧输入延迟 | 正常负载下,从应用收到输入到内核采样的 P95 不超过约一个模拟帧 |
| 存档可靠性 | 连续 100 次存读档测试通过;故障注入不损坏已提交备份 |
| 热插拔 | 20 轮断开与重连后仍可正常操作 |
| 后台恢复 | 20 轮切换与恢复后没有声音、画面或输入异常 |
**软件侧输入延迟不等于按键到屏幕的总延迟。** 手柄传输、系统事件分发、游戏自身响应和显示扫描都在完整链路中;端到端延迟应另行实测,不预先宣称“零延迟”。
测试 ROM 只使用自制或有权使用的样本;对需要随源码分发的测试文件,额外核对再分发许可。
---
# 九、项目目录与交付要求
建议仓库保持简单,不在第一版拆出大量独立工程:
```text
NESLite/
├── app/
│ └── src/main/
│ ├── java/.../
│ │ ├── ui/
│ │ ├── input/
│ │ ├── storage/
│ │ └── diagnostics/
│ ├── cpp/
│ │ ├── jni/
│ │ ├── core_host/
│ │ ├── engine/
│ │ ├── video/
│ │ ├── audio/
│ │ └── state/
│ └── res/
├── third_party/
│ ├── fceumm/
│ ├── libretro/
│ └── oboe/
├── tests/
│ ├── input/
│ ├── state/
│ ├── compatibility/
│ └── lifecycle/
├── scripts/
├── docs/
│ ├── requirements.md
│ ├── architecture.md
│ ├── build.md
│ ├── controller-x5lite.md
│ ├── save-format.md
│ └── acceptance.md
└── THIRD_PARTY_NOTICES
```
每个里程碑都应交付 **可安装 APK、对应源码提交、构建说明、验收记录和已知问题**。发布版还应保存原生符号文件,以便定位 C/C++ 崩溃。
FCEUmm 文档和仓库声明使用 GPLv2,因此本计划默认采用 **GPL 兼容的源码交付/发布方式**。对外分发时应处理对应源码、版权和许可证义务;libretro 接口头文件的许可证不会替代 FCEUmm 的许可证。
---
# 十、最先实施的工作
**下一步应直接实施 0.1.x,而不是先编写所有模拟器功能。**
第一轮工程只需要做到:
```text
能安装到你的 MagicOS 10 手机
↓
能加载一个测试原生库
↓
能识别 X5 Lite 并实时显示所有输入
↓
能验证组合键、松开、拔出与重连
↓
能导出设备与按键诊断
```
这一步完成后,就能把目前尚未实测的“应该可以适配”,转化成有依据的 **手机环境基线+X5 Lite 输入规范**。随后在 **0.2.x 接通 FCEUmm、0.3.x 完成声音与正确运行速度**,形成第一版真正可玩的原型;再用 **0.4.x~0.7.x** 把它做成操作顺手、存档可靠、适应 MagicOS 10 系统行为的日常应用。