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

26 KiB
Raw Blame History

可以。针对你的 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 和工具链建议

建议采用以下保守起点,而不是为了“最新”频繁更换构建工具:

最低系统: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. 总体结构

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 帧/秒;实际执行应读取内核返回的时序信息。

因此不能采用:

手机每刷新一次 → 执行一帧游戏

也不能简单循环 sleep(16)。

建议采用:

模拟线程:按照内核时序和音频缓冲状态执行
渲染线程:按照屏幕显示节奏显示最新可用画面
音频线程:按照音频设备请求消耗声音数据

正常模式由音频输出节奏和缓冲水位参与调节;音频不可用、测试模式和快进模式另有明确的时钟策略。

丢弃过时的待显示画面,不等于跳过内核执行。 两者必须区分,否则可能改变游戏速度和逻辑。

2. 不通过界面层搬运每一帧画面

建议在原生层保存图像缓冲,并交给 GL 线程显示,不要每帧创建新的 Bitmap,再通过界面状态更新显示。

视频适配必须处理内核给出的像素格式、宽高和行跨度 pitch,不假定每行一定是“宽度×固定字节数”;缓冲交接也不能保存一个已失效的内核临时指针。

显示设置将“4:3 显示”和“原始像素整数缩放”分开,避免为了铺满手机屏幕把画面强行拉宽。

3. 音频缓冲需要可测、可调

Oboe 支持请求低延迟和独占模式,但请求不一定能得到满足,程序需要检查实际打开的音频流参数并提供回退。

本项目建议记录:

内核输出采样率
音频设备实际采样率
每次回调请求的帧数
音频缓冲水位
缓冲不足次数
音频流重建次数

先实现稳定的默认配置,再增加低延迟配置。不能把“缓冲设得最小”直接当成优化完成,也不能把环形缓冲长度当作全部端到端音频延迟。

4. 游戏导入后使用内部稳定副本

Android 系统文件选择器提供的是文档 URI,应该通过相应文件接口读取,不能把 content://... 当作普通文件路径交给 C 的文件函数。Storage Access Framework 可以让用户授权访问选定文件,而不要求应用取得整个存储空间的访问权限。

建议导入流程:

用户选择文件
    ↓
检查大小、文件头和读取结果
    ↓
复制到应用内部文件目录中的临时文件
    ↓
计算 SHA-256
    ↓
校验并提交正式 ROM 文件
    ↓
建立游戏索引

ROM 的身份使用内容哈希,而不是文件名。这样同一游戏改名后可以识别为重复文件,不同游戏即使同名,也不会共用存档。

复制后的正式 ROM 放在应用内部文件目录,不放在可能被清理的缓存目录。

5. 游戏存档与即时存档分开管理

libretro 分别提供保存内存访问和状态序列化接口;即时存档不是简单复制游戏的电池存档。

建议采用以下数据策略:

类型 建议策略
游戏自身存档 检查内容变化,周期性提交;暂停和正常退出时补充提交
手动即时存档 10 个槽位,附带时间和缩略图
自动恢复点 独立于手动槽位,保留最近 3 份
覆盖保护 新文件校验成功后再替换,保留上一份有效备份
导出 使用系统文件选择器,默认不把 ROM 混入存档包

即时存档元数据至少记录:

ROM 内容哈希
内核名称和提交版本
存档封装格式版本
相关内核配置
创建时间
数据长度
数据校验值

不承诺跨 FCEUmm 版本即时存档自动兼容。 升级时保留原文件,先验证再恢复;读档失败后,应恢复之前的有效状态或安全重新加载,不能继续运行一个可能已被部分修改的内核状态。

另外,读入较早的即时存档可能回退游戏进度,因此建议在读档前保留当前游戏存档备份。

6. 自动保存不等于不会丢失任何进度

设计上可以初步采用“游戏存档变化后周期性提交、即时恢复点定期生成”的策略,但应用被强制停止或进程突然终止时,不应依赖退出回调完成最后一次保存。

验收目标应表述为:

最近已经成功提交的存档保持有效;突然终止时可能丢失最后一次提交之后的进度,但不能把此前有效存档也破坏。


七、MagicOS 10/Android 16 专项适配

1. 16 KB 原生库兼容

需要检查 FCEUmm、JNI 运行层、音频依赖和 C++ 运行库,以及最终 APK 的打包结果。

诊断阶段可通过以下命令读取实际设备页大小:

adb shell getconf PAGE_SIZE

这是 Android 官方给出的检查方式。即使你的手机当前使用 4 KB 页,也应在支持 16 KB 的测试环境中验证原生库,不能由系统名称推断页大小。

2. 返回导航与全面屏布局

Android 16 对目标 API 36 的应用启用新的返回导航行为,旧式 onBackPressed() 和仅拦截 KEYCODE_BACK 的做法不再可靠;同时需要处理全面屏布局,不能依靠旧的退出 edge-to-edge 开关。

本项目建议统一规定:

游戏运行中返回 → 打开暂停菜单
暂停菜单中返回 → 继续游戏
设置页面返回   → 返回上一级
游戏列表中返回 → 正常退出应用

游戏画面和菜单分别计算安全区域,避免按钮落在挖孔、系统栏或手势边缘。

3. 生命周期与后台行为

首版明确选择:切到后台就暂停,不做后台继续模拟。

锁屏、应用切换或失去音频焦点时,按策略暂停内核、停止声音、清空输入,并请求存档提交。回到前台后先恢复画面和音频资源,再由用户继续游戏。

不把“关闭系统所有省电机制”作为正常运行前提,也不为了保活引入与模拟器无关的后台服务。

4. 系统回收与异常恢复

启动时检查上一会话是否异常结束。若某 ROM 或即时存档连续导致崩溃,下一次启动不自动重开它,而是进入游戏列表并提示恢复选择,避免形成启动即崩溃的循环。


八、测试与验收体系

建议把测试分成 内核接入、手柄、系统、存档和性能 五类,并保存可复现记录。

测试类别 重点场景 建议验收要求
安装与升级 首次安装、覆盖升级、重新启动 能安装运行,升级不误删游戏和存档
文件导入 中文名、同名不同内容、重复内容、损坏文件 不误覆盖,有清楚的失败提示
卡带兼容 常见 Mapper、不同区域时序、游戏存档 通过规定测试集合,记录不支持项
基础输入 方向+A/B、多键同时按、长按 无漏释放和重复菜单触发
热插拔 游戏中拔出、重连、待机唤醒 自动进入安全状态,重连后可继续
生命周期 锁屏、切后台、返回前台、Surface 重建 无持续黑屏、后台声音和输入卡住
存档 保存、读取、覆盖、损坏、磁盘不足 失败不破坏最后一份有效文件
进程终止 强制停止后启动 可以找到最近已提交的有效恢复点
音频 长时间运行、暂停恢复、设备切换 无持续爆音和累积性音画偏移
显示 不同刷新率、不同显示比例 游戏速度不随屏幕刷新率改变
原生兼容 4 KB/16 KB 环境 原生库正确加载并通过运行测试

建议的量化目标

这些指标在拿到实机数据后可以调整,但应提前定义测量方法。

指标 初始目标
正常速度 长时间平均模拟速度保持在目标速度的 99.5%~100.5%
核心稳定性 代表性游戏连续运行 2 小时,无崩溃、ANR 和持续内存增长
输入可靠性 自动测试序列和人工组合输入测试中无残留按键
软件侧输入延迟 正常负载下,从应用收到输入到内核采样的 P95 不超过约一个模拟帧
存档可靠性 连续 100 次存读档测试通过;故障注入不损坏已提交备份
热插拔 20 轮断开与重连后仍可正常操作
后台恢复 20 轮切换与恢复后没有声音、画面或输入异常

软件侧输入延迟不等于按键到屏幕的总延迟。 手柄传输、系统事件分发、游戏自身响应和显示扫描都在完整链路中;端到端延迟应另行实测,不预先宣称“零延迟”。

测试 ROM 只使用自制或有权使用的样本;对需要随源码分发的测试文件,额外核对再分发许可。


九、项目目录与交付要求

建议仓库保持简单,不在第一版拆出大量独立工程:

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,而不是先编写所有模拟器功能。

第一轮工程只需要做到:

能安装到你的 MagicOS 10 手机
        ↓
能加载一个测试原生库
        ↓
能识别 X5 Lite 并实时显示所有输入
        ↓
能验证组合键、松开、拔出与重连
        ↓
能导出设备与按键诊断

这一步完成后,就能把目前尚未实测的“应该可以适配”,转化成有依据的 手机环境基线+X5 Lite 输入规范。随后在 0.2.x 接通 FCEUmm、0.3.x 完成声音与正确运行速度,形成第一版真正可玩的原型;再用 0.4.x~0.7.x 把它做成操作顺手、存档可靠、适应 MagicOS 10 系统行为的日常应用。