# 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-.tmp`。导入过程限制为 64 MiB,校验 iNES/NES 2.0 魔数并计算完整文件 SHA-256;提交文件为 `files/roms/.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/`,导入器遇到相同哈希时恢复关联。显示/音频/输入偏好由独立 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 与覆盖升级仍是独立实机门槛。