# NESLite 架构(M2 基线) ## 边界与线程 界面层只负责系统文件选择器、游戏列表、控制按钮、手柄事件和 GL Surface。ROM 的 `content://` 地址只在 Kotlin 导入层使用;导入完成后,原生层仅收到应用私有目录中的绝对文件路径。 FCEUmm 由一个原生工作线程独占。JNI 调用只向容量 32 的命令队列写入 `load/run/pause/reset/stop` 命令,命令携带单调递增的会话号。旧会话、重复命令和当前状态不允许的命令不会触碰内核,并在 状态快照的完成通知中报告 `stale` 或 `ignored`。状态集合固定为 Idle、Loading、Paused、 Running、Pausing、Stopping 和 Error。 ## ROM 和索引 系统文件选择器的输入流先写入 `files/roms/.import-.tmp`。导入过程限制为 64 MiB,校验 iNES/NES 2.0 魔数并计算完整文件 SHA-256;提交文件为 `files/roms/.nes`。Room 以哈希 作为主键,因此相同内容去重、同名不同内容分别登记。写文件后、写数据库前中断留下的有效正式 文件会在下次启动恢复为索引项;残留导入临时文件会清除;索引缺少文件时标记为 `MISSING`,重新 导入相同内容可恢复文件和状态。 ## libretro 宿主 固定 FCEUmm 提交见 `third_party/manifest.json`,构建定义在 `app/src/main/cpp/cmake/fceumm.cmake`。 环境协商清单如下;不在清单中的请求统一返回 `false`。 | 类别 | 处理 | | --- | --- | | 私有目录 | system、save、content,必须可建立,否则阻止加载 | | 视频 | 固定核心使用的 RGB565 与重复帧;其他像素格式拒绝 | | 选项 | core-options version 0 与 `SET_VARIABLES/GET_VARIABLE` 默认值 | | 输入 | player 1 joypad、bitmask、输入/控制器描述 | | 前端信息 | 日志、英语、60 Hz/48 kHz 目标、动态 geometry/AV、消息接口 v1、性能级别、内存映射、成就/内容声明 | | 明确不支持 | VFS、扩展 game-info、硬件渲染以及未列出的请求 | 宿主在加载前核对 libretro API 版本和私有目录;必要能力缺失进入 Error。当前固定 FCEUmm 不把上述 明确不支持的请求作为加载必要条件。 加载、`retro_run`、重置、卸载和保存内存访问均在内核线程执行。时序来自 `retro_get_system_av_info`,以 `steady_clock` 调度;M2 完整消费音频回调并返回已消费帧数,但按阶段 要求暂不发声。 ## 视频、输入和电池存档 视频回调逐行按 pitch 复制到原生 latest-only 缓冲;`data == nullptr` 表示重复帧并保留上一完整帧。 GL 线程只在原生侧读取最新缓冲和上传纹理,不经 JNI 逐帧复制图像。默认 4:3、最近邻显示,可切换 原始像素整数缩放;渲染掉帧不减少内核 `retro_run` 次数。 手柄状态在 Android 事件侧合成为 libretro joypad 位掩码,内核每帧按状态采样。后台、失焦和断柄 会清零并请求暂停。M1 的 X5 Lite 实测键码仍须在 G1 回填,因此当前只包含 Android 标准按键及 HAT/主方向轴映射。 电池存档按 ROM 哈希隔离为 `files/saves//battery/battery.sav`。暂停和正常退出时在内核线程 取得保存内存并以临时文件替换提交,状态通知用 `paused_saved`/`stopped_saved` 报告成功。更完整的 备份、故障注入和恢复保证属于 M5,不在此处提前声明。