Files
NESLite/docs/architecture.md

177 lines
15 KiB
Markdown
Raw Permalink 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 架构(1.0.0)
## 边界与线程
界面层只负责系统文件选择器、游戏列表、控制按钮、手柄事件和 GL Surface。ROM 的 `content://`
地址只在 Kotlin 导入层使用;导入完成后,原生层仅收到应用私有目录中的绝对文件路径。
当前选中的 FCEUmm 或 Nestopia 由一个原生工作线程独占。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 宿主
固定内核提交见 `third_party/manifest.json`,构建定义在 `app/src/main/cpp/cmake/`。
FCEUmm 静态链接进 JNI 库;Nestopia 构建为 APK 内置的 `libneslite_nestopia.so`,以固定库名加载。
`CoreApi` 只绑定已登记内核的 libretro 函数,检查必需入口及 API 版本;Nestopia 使用上游导出表与
`-Bsymbolic` 隔离同名符号。库句柄保留至进程退出,每次换游戏仍执行旧内核卸载/销毁,再初始化新内核。
所有内核调用均在同一模拟线程完成,不接受下载或外部路径。每次加载前重置选项与像素协商状态。
`rom_compatibility` 对读取到的 ROM 字节计算完整 SHA-256 后匹配已验证规则,不按文件名推断硬件。
0.9.17 的唯一特例是指定“龙珠英雄”哈希:注册默认选项时将 FCEUmm 的 `fceumm_region` 设为 `Dendy`,
或将 Nestopia 的 `nestopia_force_system` 设为 `dendy`。其余选项和 ROM 均维持上游默认;原文件及
数据库身份不变。诊断 JSON 的 `compatibilityProfile` 记录规则 ID,卸载时清回默认。
环境协商清单如下;不在清单中的请求统一返回 `false`。
| 类别 | 处理 |
| --- | --- |
| 私有目录 | system、save、content,必须可建立,否则阻止加载 |
| 视频 | RGB565、XRGB8888、0RGB1555 与重复帧;后两种转换为 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。具体 ROM 是否可运行仍需按
各内核分别验证,不能以 API 入口存在代替兼容性结果。
加载、`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 参数。全部失败时保持
内核的单调时钟调度,不因没有音频而无限追帧。
内核的 int16 stereo 数据先经跨批次连续的线性重采样转成设备实际采样率,再写入 4096 帧 SPSC
环形缓冲。Oboe 回调只操作预分配内存和原子计数:正常取样、应用 0~1 增益,欠载补零,满缓冲丢弃
新数据并计数;不加锁、不分配、不记录文件。暂停、失焦和快进转换均停止输出并清空旧缓冲。
正常速度由 `steady_clock`、核心 FPS 和缓冲水位的 ±2% 有界校正共同调度;音频不可用时只使用单调
时钟;目标水位按设备采样率折算为约一个模拟帧并限制在安全范围。计时器分别累计加载、暂停、正常和快进时间,并保留最多 240 个帧工作耗时样本的平均值与
最大值。按住快进使用 2× 周期并静音;释放时清缓冲、重置重采样和时钟基线,再恢复正常输出。
Android 音频焦点丢失会暂停并清输入,重新获得焦点不会自行继续。音频设备增删或 Oboe
`Disconnected` 由内核线程关闭并按上述回退顺序重建,成功或失败都停在 Paused,防止旧会话回调
复活。状态 JSON 展示核心/设备采样率、callback/burst、缓冲水位、欠载/溢出、重建次数、速度和帧
时间;诊断只存计数与固定窗口。
## 视频、输入和电池存档
视频回调逐行按 pitch 复制到原生 latest-only 缓冲,同时保存该帧对应的内核基础尺寸
`geometry.base_width/base_height`;纹理宽高独立保留用于上传。缺失基础尺寸时成对回退为纹理宽高。
`data == nullptr` 表示重复帧并保留上一完整帧及其尺寸。
帧序号跨缓冲清空单调递增,切换内核后不会因序号重复而跳过新帧上传。GL 线程只在原生侧读取最新缓冲
和上传纹理,不经 JNI 逐帧复制图像。默认 4:3、最近邻显示,可切换
原始像素整数缩放。整数模式按基础宽高选择能完整放入 Surface 的最大共同整数倍率并居中,
放不下一倍时等比例缩小;4:3 模式等比例适配 Surface。Nestopia 默认复合视频输出可能为
602×224,但基础尺寸为 256×224,不能按 602 计算原始整数倍率。尺寸计算由 `video_viewport`
提供,GL 每次绘制均应用当前模式和 Surface 尺寸,暂停时切换也生效;渲染掉帧不减少内核 `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 哈希隔离,FCEUmm 保留原目录,Nestopia 使用独立子目录。核心线程在帧边界取得不可变电池/核心状态/缩略图快照,统一提交器在文件线程
以同目录临时文件、刷新、回读校验、有效备份和原子替换提交,并用单调版本阻止旧任务倒灌。变化电池
每 10 个模拟秒请求,自动恢复点每 60 秒及暂停/退出请求,手动十槽和自动三槽共用带哈希、固定内核
提交、配置、时间、长度和 SHA-256 的 v1 封装,详见 `docs/save-format.md`。
读档只在暂停态核心线程进行并先持久保护当前状态和电池,失败回滚,双重失败安全重载或进入 Error。
活动会话标记只提示校验有效的异常恢复候选,不自动运行。SAF 存档包只允许内核标识、电池、手动槽和自动槽,
不含 ROM;原生层在写入前完成路径、单项/总大小、格式、哈希、内核提交、配置和每项校验。
## M6 日常界面
独立的 `core_preferences` DataStore 保存默认内核和每 ROM 的覆盖项。设置与长按游戏菜单提供选择,
写入成功后才更新界面;完成初始读取前阻止加载,防止错误使用默认值。加载命令固定本次内核,运行中
更改偏好只影响下次加载。存档管理使用活动会话的内核和哈希,丢弃旧会话迟到的目录扫描结果。
Room v2 在 ROM 哈希主键之上保存收藏、隐藏和最近游玩;查询只展示未隐藏项并按收藏、最近、名称排序。
隐藏不操作内部 ROM 或 `saves/<sha256>`,导入器遇到相同哈希时恢复关联。显示/音频/输入偏好由独立
DataStore 保存,渲染线程只读取整数缩放和过滤快照,音频及手柄继续复用原有命令和档案。
存档管理只解析 M5 已提交封装的边界元数据和缩略图,所有修改仍回到核心线程/统一提交器。虚拟手柄
按 pointerId 维护触摸来源并送入与物理手柄相同的 `InputRouter`,因此多来源去重、相反方向和释放规则
一致;取消、滑出、失焦与暂停清空所有虚拟来源。首次使用状态也存于设置 DataStore,不接触用户存档。
0.9.15 将游戏入口收敛为单一横屏主画面:中央 `AspectRatioFrameLayout` 只按 4:3 测量,左右剩余安全
区域绘制虚拟手柄;左上角横排图标入口独立于游戏安全内边距,打开游戏列表、导入和设置的全屏页面。
方向键与 ABXY 的半径为原布局的 1.5 倍,Select、Start、暂停和重置为原布局的 1.3 倍。Magic8 横屏
安全区允许时,方向键、Select、4:3 画面、Start、暂停和重置整体左移一个 A 键直径,右侧扩展空间用于
拉开 ABXY 菱形的横向间距;X/Y 复用 M4 的 A/B 软件
连发动作;重置要求持续按住 650 ms。游戏页沉浸式隐藏系统栏,管理页恢复系统栏;页面打开前先等待
运行会话进入暂停态,页面关闭后不自动恢复,避免文件选择或设置过程中游戏在后台继续。
屏幕方向键使用单一圆形触控域和互斥方向扇区,不再由四个重叠圆形命中区判定。中心 15% 为中立区,
有效触控半径比可见十字键大 30%,当前方向获得 25% 的切换迟滞,并在方向首次按下或切换时反馈。
八方向模式允许一个触点同时持有横向和纵向,四方向模式保留最近明确输入的主轴;同一策略在统一
`InputRouter` 中约束物理摇杆。多触点状态以动作集合保存,因此 A 与 B 可以同时按住。方向键大小、
水平与垂直偏移存入 AppSettings DataStore。
横屏翻转时挖孔和返回手势保护值会交换左右两侧。游戏画面与虚拟按键只用两侧共有的保护值计算尺寸;
左侧额外保护值转为游戏画面及按键的整体右移,并在右边缘裁切前限制位移。因此两种横屏方向的按键
保持同样的 1.5/1.3 倍大小,但中央画面位置可以不同。基础半径还受屏幕高度上限约束,避免翻转时
侧栏可用宽度变化导致第二方向过分放大或 ABXY 菱形相对间距改变。左上角列表、导入、设置入口不参与右移。
管理页面不使用左右防误触边距,只保留已显示顶部和底部系统栏所需空间。游戏库按可用横向宽度显示
两列或三列完整、可换行的游戏名,长按条目才显示详情、收藏和移除操作。
设置页按画面与声音、方向与触控、手柄与辅助分成横屏卡片。ROM 导入页同时提供单文件选择与 SAF
文件夹选择;文件夹导入递归扫描子文件夹的 `.nes` 文件,沿用流式校验与 SHA-256 去重,不保留目录权限。
手柄设置支持逐项向导和单项修改/清除。捕获目标动作后,物理 KeyEvent 或超过按下阈值的轴方向成为
该动作的唯一绑定;冲突必须由用户确认替换。轴捕获后必须先回到释放阈值内才进入下一项,防止同一
持续轴值误绑多个动作。草稿与正在使用的档案分离,仅保存成功后替换运行档案并按设备指纹持久化。
## M7 系统交接与诊断
AndroidX 返回分发先把当前页面和会话状态归一成单一决策:设置/存档页回上级,暂停菜单返回会在
原生层确认后继续,运行中返回会先完成暂停与自动保存;Loading、Pausing、Stopping 或仍有待确认
命令时忽略重复动作。游戏页只在左右合并显示挖孔和系统返回手势边距,顶部与底部不为已隐藏的系统栏
留白;管理页独立合并系统栏、挖孔和系统手势的四边安全区。系统栏状态变化后会再次请求 Insets 并重算
两套边距,渲染比例仍由 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 与覆盖升级仍是独立实机门槛。