Files
NESLite/docs/architecture.md
T

136 lines
11 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 架构(0.9.6 候选基线)
## 边界与线程
界面层只负责系统文件选择器、游戏列表、控制按钮、手柄事件和 GL Surface。ROM 的 `content://`
地址只在 Kotlin 导入层使用;导入完成后,原生层仅收到应用私有目录中的绝对文件路径。
FCEUmm 由一个原生工作线程独占。JNI 调用只向容量 32 的命令队列写入
`load/run/pause/reset/stop/mute/volume/audio_rebuild/fast`
命令,命令携带单调递增的会话号。旧会话、重复命令和当前状态不允许的命令不会触碰内核,并在
状态快照的完成通知中报告 `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` 调度;M3 在此边界内把核心音频转换并送往输出线程。
## 音频、时钟与快进
固定 Oboe 1.10.0 源码由 `app/src/main/cpp/cmake/oboe.cmake` 引入。打开顺序为独占低延迟、共享低延迟、
共享安全模式;每次都检查实际 float/stereo 格式、采样率、burst 和 callback 参数。全部失败时保持
内核的单调时钟调度,不因没有音频而无限追帧。
FCEUmm 的 int16 stereo 数据先经跨批次连续的线性重采样转成设备实际采样率,再写入 4096 帧 SPSC
环形缓冲。Oboe 回调只操作预分配内存和原子计数:正常取样、应用 0~1 增益,欠载补零,满缓冲丢弃
新数据并计数;不加锁、不分配、不记录文件。暂停、失焦和快进转换均停止输出并清空旧缓冲。
正常速度由 `steady_clock`、核心 FPS 和缓冲水位的 ±2% 有界校正共同调度;音频不可用时只使用单调
时钟;目标水位按设备采样率折算为约一个模拟帧并限制在安全范围。计时器分别累计加载、暂停、正常和快进时间,并保留最多 240 个帧工作耗时样本的平均值与
最大值。按住快进使用 2× 周期并静音;释放时清缓冲、重置重采样和时钟基线,再恢复正常输出。
Android 音频焦点丢失会暂停并清输入,重新获得焦点不会自行继续。音频设备增删或 Oboe
`Disconnected` 由内核线程关闭并按上述回退顺序重建,成功或失败都停在 Paused,防止旧会话回调
复活。状态 JSON 展示核心/设备采样率、callback/burst、缓冲水位、欠载/溢出、重建次数、速度和帧
时间;诊断只存计数与固定窗口。
## 视频、输入和电池存档
视频回调逐行按 pitch 复制到原生 latest-only 缓冲;`data == nullptr` 表示重复帧并保留上一完整帧。
GL 线程只在原生侧读取最新缓冲和上传纹理,不经 JNI 逐帧复制图像。默认 4:3、最近邻显示,可切换
原始像素整数缩放;渲染掉帧不减少内核 `retro_run` 次数。
M4 输入层按物理来源维护状态,来源键包含本次设备 ID、按键/轴/触屏类别、代码和轴方向。多个来源
映射到同一动作时只合成一次;释放一个来源不会清除仍按住的另一个来源。相反方向同时成立时对应轴
归零。轴使用可配置的按下/释放双阈值,跨向时先释放旧方向再按下新方向,避免边界抖动和瞬时冲突。
标准 Android 手柄使用通用映射:方向键/X-Y 轴控制方向,A/B 对应 NES A/B,X/Y 对应 A/B 软件
连发,Start/Select 保持原义,右摇杆按下切换暂停菜单,RB 按住 2× 快进。暂停和快进只按合成动作
边沿发命令,系统重复 KeyEvent 不会重复切换;Guide、Mode、肩键组合和快速读档均不占用。软件连发
在原生核心线程按模拟秒生成 15 Hz 门控,NTSC/PAL 不依赖墙钟频率,离开 Running 即清零。
自定义设置可逐动作捕获按键或轴方向,冲突必须确认替换,并支持取消、恢复默认、A/B 交换及死区
调整。DataStore 以 VID/PID 加 descriptor(不可用时回退规范化名称)的 SHA-256 指纹保存档案,不写入
临时 deviceId;设备重连后按稳定特征恢复。X5 Lite 专属映射注册只接受 M1 实测的完整签名和事件表,
在该证据缺失时保持空表并使用通用档案,防止按名称误套。
运行态输入送入 JNI 的基础掩码和独立连发掩码。暂停菜单、游戏列表及设置均使用可聚焦原生控件;
非运行态不消费方向导航,手柄 B 可从设置返回、从暂停菜单继续。失焦、暂停、断柄和退出同步清除
来源、轴滞回、基础掩码及连发掩码。
存档按 ROM 哈希隔离。核心线程在帧边界取得不可变电池/核心状态/缩略图快照,统一提交器在文件线程
以同目录临时文件、刷新、回读校验、有效备份和原子替换提交,并用单调版本阻止旧任务倒灌。变化电池
每 10 个模拟秒请求,自动恢复点每 60 秒及暂停/退出请求,手动十槽和自动三槽共用带哈希、固定内核
提交、配置、时间、长度和 SHA-256 的 v1 封装,详见 `docs/save-format.md`。
读档只在暂停态核心线程进行并先持久保护当前状态和电池,失败回滚,双重失败安全重载或进入 Error。
活动会话标记只提示校验有效的异常恢复候选,不自动运行。SAF 存档包只允许电池、手动槽和自动槽,
不含 ROM;原生层在写入前完成路径、单项/总大小、格式、哈希、内核提交、配置和每项校验。
## M6 日常界面
Room v2 在 ROM 哈希主键之上保存收藏、隐藏和最近游玩;查询只展示未隐藏项并按收藏、最近、名称排序。
隐藏不操作内部 ROM 或 `saves/<sha256>`,导入器遇到相同哈希时恢复关联。显示/音频/输入偏好由独立
DataStore 保存,渲染线程只读取整数缩放和过滤快照,音频及手柄继续复用原有命令和档案。
存档管理只解析 M5 已提交封装的边界元数据和缩略图,所有修改仍回到核心线程/统一提交器。虚拟手柄
按 pointerId 维护触摸来源并送入与物理手柄相同的 `InputRouter`,因此多来源去重、相反方向和释放规则
一致;取消、滑出、失焦与暂停清空所有虚拟来源。首次使用状态也存于设置 DataStore,不接触用户存档。
0.9.6 将游戏入口收敛为单一横屏主画面:中央 `AspectRatioFrameLayout` 只按 4:3 测量,左右剩余安全
区域绘制虚拟手柄;左侧固定入口打开游戏列表、导入和设置的全屏独立页面。X/Y 复用 M4 的 A/B 软件
连发动作;重置要求持续按住 650 ms。游戏页沉浸式隐藏系统栏,管理页恢复系统栏;页面打开前先等待
运行会话进入暂停态,页面关闭后不自动恢复,避免文件选择或设置过程中游戏在后台继续。
## M7 系统交接与诊断
AndroidX 返回分发先把当前页面和会话状态归一成单一决策:设置/存档页回上级,暂停菜单返回会在
原生层确认后继续,运行中返回会先完成暂停与自动保存;Loading、Pausing、Stopping 或仍有待确认
命令时忽略重复动作。应用内容区合并系统栏、挖孔和强制手势区域的最大边距,横屏画面、菜单与虚拟键
共享同一个可触达安全区域,渲染比例仍由 M2/M6 的视口算法决定。
后台、锁屏和焦点丢失统一清除所有输入、请求暂停保存、放弃音频焦点;回到前台只重建 Surface 与
音频资源,保持 Paused 等待用户继续。路由变化若与暂停或退出交错,会延迟到暂停确认后重建,退出
优先且不会创建第二个核心线程。Activity 进程重建只接回仍存在的原生会话;失效会话直接返回游戏库,
不会凭保存的路径自动加载 ROM。
异常标记按 ROM 哈希和最新有效自动恢复点签名计数;相同组合连续两次异常即安全结束会话并阻止自动
重复进入,用户仍可从列表明确手动重试。系统事件以最多 3 个、每个 256 KiB 的 JSONL 文件轮换。
诊断导出列出应用/设备、输入、可用显示模式及两秒运行样本、帧与音频、存档边界和原生错误,只记录
ROM 哈希,不包含 ROM 字节或文件路径。
## M8 候选可观测性与升级边界
基础输入掩码在 JNI 收到实际变化时记录原生 `steady_clock` 时间,单内核线程在下一次有效帧采样前
计算延迟。固定窗口保留最近 2048 个样本并只导出数量、平均、P95 和最大值,既不在音频回调中工作,
也不保存按键序列。该指标的时间域明确为 JNI 入口到首次核心采样,不宣称是物理按键到屏幕总延迟。
Room v1 和 v2 架构随源码保存,v1→v2 迁移继续显式添加收藏、隐藏和最近游玩字段且默认值为零;Android
迁移测试在设备上验证旧中文名称及行数据保留。release 构建保存 FULL 原生符号但不启用混淆。RC 打包
只接受干净提交,产出未签名 release APK、逐库 16 KB 静态审计、应用/固定第三方源码归档、许可证、
候选清单和校验和;签名、双页大小环境、API 28 与覆盖升级仍是独立实机门槛。