release: prepare NESLite 1.0.0 with dual cores and signed packaging
This commit is contained in:
+31
-13
@@ -1,11 +1,11 @@
|
||||
# NESLite 架构(0.9.15 候选基线)
|
||||
# NESLite 架构(1.0.0)
|
||||
|
||||
## 边界与线程
|
||||
|
||||
界面层只负责系统文件选择器、游戏列表、控制按钮、手柄事件和 GL Surface。ROM 的 `content://`
|
||||
地址只在 Kotlin 导入层使用;导入完成后,原生层仅收到应用私有目录中的绝对文件路径。
|
||||
|
||||
FCEUmm 由一个原生工作线程独占。JNI 调用只向容量 32 的命令队列写入
|
||||
当前选中的 FCEUmm 或 Nestopia 由一个原生工作线程独占。JNI 调用只向容量 32 的命令队列写入
|
||||
`load/run/pause/reset/stop/mute/volume/audio_rebuild/fast`
|
||||
命令,命令携带单调递增的会话号。旧会话、重复命令和当前状态不允许的命令不会触碰内核,并在
|
||||
状态快照的完成通知中报告 `stale` 或 `ignored`。状态集合固定为 Idle、Loading、Paused、
|
||||
@@ -21,20 +21,28 @@ iNES/NES 2.0 魔数并计算完整文件 SHA-256;提交文件为 `files/roms/<
|
||||
|
||||
## libretro 宿主
|
||||
|
||||
固定 FCEUmm 提交见 `third_party/manifest.json`,构建定义在 `app/src/main/cpp/cmake/fceumm.cmake`。
|
||||
固定内核提交见 `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 与重复帧;其他像素格式拒绝 |
|
||||
| 视频 | 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。当前固定 FCEUmm 不把上述
|
||||
明确不支持的请求作为加载必要条件。
|
||||
宿主在加载前核对 libretro API 版本和私有目录;必要能力缺失进入 Error。具体 ROM 是否可运行仍需按
|
||||
各内核分别验证,不能以 API 入口存在代替兼容性结果。
|
||||
|
||||
加载、`retro_run`、重置、卸载和保存内存访问均在内核线程执行。时序来自
|
||||
`retro_get_system_av_info`,以 `steady_clock` 调度;M3 在此边界内把核心音频转换并送往输出线程。
|
||||
@@ -45,7 +53,7 @@ iNES/NES 2.0 魔数并计算完整文件 SHA-256;提交文件为 `files/roms/<
|
||||
共享安全模式;每次都检查实际 float/stereo 格式、采样率、burst 和 callback 参数。全部失败时保持
|
||||
内核的单调时钟调度,不因没有音频而无限追帧。
|
||||
|
||||
FCEUmm 的 int16 stereo 数据先经跨批次连续的线性重采样转成设备实际采样率,再写入 4096 帧 SPSC
|
||||
内核的 int16 stereo 数据先经跨批次连续的线性重采样转成设备实际采样率,再写入 4096 帧 SPSC
|
||||
环形缓冲。Oboe 回调只操作预分配内存和原子计数:正常取样、应用 0~1 增益,欠载补零,满缓冲丢弃
|
||||
新数据并计数;不加锁、不分配、不记录文件。暂停、失焦和快进转换均停止输出并清空旧缓冲。
|
||||
|
||||
@@ -60,9 +68,15 @@ Android 音频焦点丢失会暂停并清输入,重新获得焦点不会自行
|
||||
|
||||
## 视频、输入和电池存档
|
||||
|
||||
视频回调逐行按 pitch 复制到原生 latest-only 缓冲;`data == nullptr` 表示重复帧并保留上一完整帧。
|
||||
GL 线程只在原生侧读取最新缓冲和上传纹理,不经 JNI 逐帧复制图像。默认 4:3、最近邻显示,可切换
|
||||
原始像素整数缩放;渲染掉帧不减少内核 `retro_run` 次数。
|
||||
视频回调逐行按 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、按键/轴/触屏类别、代码和轴方向。多个来源
|
||||
映射到同一动作时只合成一次;释放一个来源不会清除仍按住的另一个来源。相反方向同时成立时对应轴
|
||||
@@ -82,17 +96,21 @@ M4 输入层按物理来源维护状态,来源键包含本次设备 ID、按
|
||||
非运行态不消费方向导航,手柄 B 可从设置返回、从暂停菜单继续。失焦、暂停、断柄和退出同步清除
|
||||
来源、轴滞回、基础掩码及连发掩码。
|
||||
|
||||
存档按 ROM 哈希隔离。核心线程在帧边界取得不可变电池/核心状态/缩略图快照,统一提交器在文件线程
|
||||
存档按内核及 ROM 哈希隔离,FCEUmm 保留原目录,Nestopia 使用独立子目录。核心线程在帧边界取得不可变电池/核心状态/缩略图快照,统一提交器在文件线程
|
||||
以同目录临时文件、刷新、回读校验、有效备份和原子替换提交,并用单调版本阻止旧任务倒灌。变化电池
|
||||
每 10 个模拟秒请求,自动恢复点每 60 秒及暂停/退出请求,手动十槽和自动三槽共用带哈希、固定内核
|
||||
提交、配置、时间、长度和 SHA-256 的 v1 封装,详见 `docs/save-format.md`。
|
||||
|
||||
读档只在暂停态核心线程进行并先持久保护当前状态和电池,失败回滚,双重失败安全重载或进入 Error。
|
||||
活动会话标记只提示校验有效的异常恢复候选,不自动运行。SAF 存档包只允许电池、手动槽和自动槽,
|
||||
活动会话标记只提示校验有效的异常恢复候选,不自动运行。SAF 存档包只允许内核标识、电池、手动槽和自动槽,
|
||||
不含 ROM;原生层在写入前完成路径、单项/总大小、格式、哈希、内核提交、配置和每项校验。
|
||||
|
||||
## M6 日常界面
|
||||
|
||||
独立的 `core_preferences` DataStore 保存默认内核和每 ROM 的覆盖项。设置与长按游戏菜单提供选择,
|
||||
写入成功后才更新界面;完成初始读取前阻止加载,防止错误使用默认值。加载命令固定本次内核,运行中
|
||||
更改偏好只影响下次加载。存档管理使用活动会话的内核和哈希,丢弃旧会话迟到的目录扫描结果。
|
||||
|
||||
Room v2 在 ROM 哈希主键之上保存收藏、隐藏和最近游玩;查询只展示未隐藏项并按收藏、最近、名称排序。
|
||||
隐藏不操作内部 ROM 或 `saves/<sha256>`,导入器遇到相同哈希时恢复关联。显示/音频/输入偏好由独立
|
||||
DataStore 保存,渲染线程只读取整数缩放和过滤快照,音频及手柄继续复用原有命令和档案。
|
||||
@@ -141,7 +159,7 @@ AndroidX 返回分发先把当前页面和会话状态归一成单一决策:
|
||||
优先且不会创建第二个核心线程。Activity 进程重建只接回仍存在的原生会话;失效会话直接返回游戏库,
|
||||
不会凭保存的路径自动加载 ROM。
|
||||
|
||||
异常标记按 ROM 哈希和最新有效自动恢复点签名计数;相同组合连续两次异常即安全结束会话并阻止自动
|
||||
异常标记按内核、ROM 哈希和最新有效自动恢复点签名计数;相同组合连续两次异常即安全结束会话并阻止自动
|
||||
重复进入,用户仍可从列表明确手动重试。系统事件以最多 3 个、每个 256 KiB 的 JSONL 文件轮换。
|
||||
诊断导出列出应用/设备、输入、可用显示模式及两秒运行样本、帧与音频、存档边界和原生错误,只记录
|
||||
ROM 哈希,不包含 ROM 字节或文件路径。
|
||||
|
||||
Reference in New Issue
Block a user