Files
NESLite/docs/architecture.md
T

55 lines
3.4 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.
# 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-<uuid>.tmp`。导入过程限制为 64 MiB,校验
iNES/NES 2.0 魔数并计算完整文件 SHA-256;提交文件为 `files/roms/<sha256>.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/<sha256>/battery/battery.sav`。暂停和正常退出时在内核线程
取得保存内存并以临时文件替换提交,状态通知用 `paused_saved`/`stopped_saved` 报告成功。更完整的
备份、故障注入和恢复保证属于 M5,不在此处提前声明。