可以。针对你的 **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 系统行为的日常应用。