release: prepare NESLite 1.0.0 with dual cores and signed packaging

This commit is contained in:
2026-09-14 17:30:37 +08:00
parent e3842c21dc
commit fefca3ca68
68 changed files with 1819 additions and 592 deletions
+3 -3
View File
@@ -5,12 +5,12 @@
| 级别 | 用途 | 本地入口/报告 |
| --- | --- | --- |
| L0 | 文档、清单、版本和材料核对 | 人工核对,记录在阶段报告 |
| L1 | 单项逻辑、构建、解析器或映射 | `tools/check.ps1 -Scope Local` 或 `-Scope Module`,按项追加最小用例 |
| L1 | 单项逻辑、构建、解析器或映射 | 构建用 `打包.cmd -NoPause`;局部 Kotlin/CTest 用例按 [构建说明](build.md) 精确选择 |
| L2 | 模块交接、JNI、文件、UI 或设备 | 相邻模块路径;需要设备时记录实机证据 |
| L3 | G0~G7 阶段出口 | `tools/check.ps1 -Scope Stage` 加当阶段指定路径和 H 项 |
| L3 | G0~G7 阶段出口 | 汇总当前构建、受影响模块检查和当阶段指定路径/H 项;有效证据不重复执行 |
| L4 | M8/G8 候选发布 | 冻结兼容集和有效 H 项索引 |
默认命令只做 M0 有界验证;不会启动 ROM 集、30 分钟音画、100 次存读档、20 轮插拔/生命周期、
默认打包只编译选定 APK 并检查静态对齐;不会启动单元测试、ROM 集、30 分钟音画、100 次存读档、20 轮插拔/生命周期、
2 小时长测或 1,000 次延迟采样。
## H 专项编号
+31 -13
View File
@@ -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 字节或文件路径。
+73 -57
View File
@@ -1,82 +1,98 @@
# NESLite 可复现构建说明
# NESLite 构建与打包
本说明对应 0.9.15 候选基线。命令使用系统默认 PowerShell 7.6.6(`pwsh`)从仓库根目录执行;不需要手工复制 `.so`、
FCEUmm 或 Oboe 文件。
项目的 APK 打包入口统一为根目录 `打包.cmd`,项目内的编译产物、缓存、日志和交付文件统一放入
`build/`。当前应用版本为 1.0.0,入口从 APK 构建元数据读取版本,不另写一套版本号。
## 前置条件
## 一键打包
1. 安装或使用 [toolchain.md](toolchain.md) 中的 JDK 17.0.17+10、SDK Platform 36.1、
NDK 28.2.13676358 与 Android CMake 3.22.1。
2. 设置 `JAVA_HOME` 指向 JDK 17;不能用系统默认的 JDK 21。
3. 设置 `ANDROID_HOME`(或在未设置时使用本机记录的 SDK 根目录)。`local.properties` 仅保存
本机 `sdk.dir`,不提交。
4. 首次构建需要访问 Google Maven、Maven Central 与 Gradle 分发服务,以取得已锁定版本。
5. M2~M4 构建原生内核、音频和输入层前,运行:
双击根目录的 **打包.cmd**。成功后窗口显示安装包完整路径,按回车关闭;失败时显示原因和日志位置。
默认生成可直接安装的 arm64 调试版,application ID 为 `org.neslite.app.debug`。
```powershell
.\tools\fetch-third-party.ps1
```
该脚本根据 `third_party/manifest.json` 检出固定提交;M4 构建需要 FCEUmm、libretro headers 与 Oboe。
## 构建调试 APK
也可在 PowerShell 中执行:
```powershell
pwsh -NoProfile -File .\tools\check.ps1 -Scope Build
.\打包.cmd -NoPause
```
产物为 `app/build/outputs/apk/debug/app-debug.apk`,其中只包含 `arm64-v8a` 的
`libneslite_jni.so`。调试包的 application ID 是 `org.neslite.app.debug`。
当前交付文件是 `build/releases/NESLite-1.0.0-debug-arm64-v8a.apk`,旁边的 `.sha256` 保存校验值。
入口检查工具链与固定依赖、编译选定 APK、检查原生库和 APK 的 16 KB 对齐,成功后复制产物。
它不会自动启动单元测试、ROM 遍历、设备测试或发布回归;失败会返回非零退出码,旧交付 APK 不冒充本次成功产物。
## 有界检查入口
| 命令 | 范围 | 不会执行 |
| --- | --- | --- |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Build` | 生成调试 APK | 单元、原生、实机、长测 |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Local` | Kotlin 本地单元测试 | APK、原生、实机、长测 |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Module` | 原生 smoke test 与 Kotlin 本地单测 | APK、实机、长测 |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Stage` | 当前 APK、原生 smoke test 与 Kotlin 本地单测 | 设备、ROM 兼容、耐久、H 专项 |
`Stage` 是本地阶段入口,不是 G1~G9 的替代。实机、ROM、存档、插拔和耐久验收必须在
相应里程碑按 [acceptance.md](acceptance.md) 执行和记录。
## 构建候选交付材料
先提交所有候选源码并保持工作区干净,然后执行:
需要 Release 编译产物时使用同一个入口:
```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\tools\package-rc.ps1
.\打包.cmd release -NoPause
```
脚本重跑 Stage 和 release lint,生成 `org.neslite.app` 的未签名 release APK、完整原生符号、应用及
三个固定第三方依赖的源码包、许可证/说明、静态原生审计、候选清单和 SHA-256。输出位于
`.build/rc-0.9.15/`。静态审计逐个检查 APK 内 `.so` 的 ELF LOAD 段和 APK 16 KB 对齐,并拒绝非
arm64-v8a 库。
该模式使用项目外的正式密钥,生成 `build/releases/NESLite-1.0.0-arm64-v8a.apk`、原生符号、应用和依赖源码 ZIP、发布清单及校验值。
正式打包前必须提交源码并配置签名目录;入口读取 Windows 用户加密的密码,完成签名和签名验证。密钥位置与发布步骤见 [publishing.md](publishing.md)。
一键打包不会运行原 `package-rc.ps1` 的全量 Stage/lint/设备测试包构建,也不表示发布门槛通过。
默认 APK 刻意保持未签名;发布私钥和口令不得传入仓库或写入脚本。获得受保护的发布密钥后,在隔离
环境签名并重新执行对齐/签名/设备检查。未签名包不能用于安装、覆盖升级或 G8 运行验收。
## 工具链
冻结的 12 个 CC0 最小 ROM 冒烟样本可用下列命令在忽略目录重建:
需要 PowerShell 7、JDK 17、SDK Platform 36.1、Build Tools 36.1.0、NDK 28.2.13676358 与 CMake 3.22.1,
版本记录见 [toolchain.md](toolchain.md)。
- JDK 优先使用 `build/toolchains/jdk-17.0.17+10`,没有时使用 `JAVA_HOME`,启动前确认 Java 主版本为 17。
- SDK 依次读取 `local.properties` 的 `sdk.dir`、`ANDROID_HOME`、`ANDROID_SDK_ROOT`,最后尝试
`%LOCALAPPDATA%/Android/Sdk`。SDK 是本机外部依赖,不复制进项目。
- Gradle Wrapper 的 JAR、分发地址与校验值保留在 `gradle/wrapper/`,由新入口直接调用。
全局 Gradle 下载缓存仍使用用户原有配置,项目缓存放入 `build/cache/gradle`。
- `tools/fetch-third-party.ps1` 只负责检出固定依赖,由打包入口调用;已有依赖提交不匹配时停止,不覆盖源码。
首次缺少依赖时需要访问固定 Git 来源、Google Maven、Maven Central 和 Gradle 分发服务。
## 目录约定
| 路径 | 内容 |
| --- | --- |
| `build/app/` | Android 中间文件、原始 APK、测试结果和原生符号 |
| `build/native/app/` | Android CMake/Ninja 编译目录 |
| `build/root/` | 根 Gradle 项目生成文件 |
| `build/cache/` | 项目级 Gradle/Kotlin 缓存 |
| `build/tmp/` | 构建时的临时文件 |
| `build/releases/` | 版本化 APK、校验值、Release 符号和许可证材料 |
| `build/logs/` | 最近一次各模式的打包日志 |
| `build/reports/` | 原生审计与保留的历史诊断记录 |
| `build/toolchains/` | 项目本地 JDK;不是可随意删除的编译缓存 |
模块编译目录与 CMake 编译目录为并列目录,以符合
[AGP 对 CMake staging 目录的要求](https://developer.android.com/reference/tools/gradle-api/8.13/com/android/build/api/dsl/Cmake#buildStagingDirectory)。
Kotlin 的项目缓存通过其
[持久化目录配置](https://kotlinlang.org/docs/gradle-configure-project.html#kotlin-gradle-plugin-data-in-a-project)迁移。
## 按影响选择检查
打包和验收分开执行,按 `todo.md` 选择最小相关范围。需要 Kotlin 局部用例时,可直接调用保留的 Wrapper:
```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\tools\generate-rc-roms.ps1
$env:JAVA_HOME = (Resolve-Path build/toolchains/jdk-17.0.17+10).Path
$env:TEMP = (Resolve-Path build/tmp).Path
$env:TMP = $env:TEMP
$env:JAVA_TOOL_OPTIONS = "-Djava.io.tmpdir=`"$env:TEMP`" -Djdk.net.unixdomain.tmpdir=`"$env:TEMP`""
& "$env:JAVA_HOME/bin/java.exe" -classpath gradle/wrapper/gradle-wrapper.jar org.gradle.wrapper.GradleWrapperMain --project-cache-dir build/cache/gradle :app:testDebugUnitTest --tests org.neslite.app.BuildIdentityTest
```
它们不包含游戏素材,也不能替代音画、滚屏、电池进度和长稳所需的合法代表游戏样本。设备长稳采集
入口为 `tools/collect-h-long.ps1`;默认 120 分钟、60 秒一次,只负责采集,不自动批准内存趋势。
## M1 诊断版安装
连接并授权一台目标手机后执行:
原生测试在 `build/native-tests` 配置后,只构建和运行相关目标,例如显示修复:
```powershell
pwsh -NoProfile -File .\tools\check-m1-device.ps1
$taskCmake = "$env:LOCALAPPDATA/Android/Sdk/cmake/3.22.1/bin"
& "$taskCmake/cmake.exe" -S app/src/main/cpp -B build/native-tests
& "$taskCmake/cmake.exe" --build build/native-tests --config Debug --target neslite_video_viewport_test
& "$taskCmake/ctest.exe" --test-dir build/native-tests -C Debug --output-on-failure -R '^neslite_video_viewport_test$'
```
脚本安装并启动 `0.1.3-debug` 诊断版;手柄操作和导出步骤见
[controller-x5lite.md](controller-x5lite.md)。连接多台设备时传入 `-Serial <adb序列号>`。
单 ROM 桌面诊断见 [探针说明](../tools/rom-probe/README.md)。`tools/check-m1-device.ps1` 只安装和启动已构建
的调试 APK,`tools/check-rc-native.ps1` 只审计现有 APK;它们不是另一个编译入口。ROM 样本生成与长稳采集
脚本的默认输出也已改到 `build/`,专项按 [acceptance.md](acceptance.md) 执行。
## 清理
## 清理与历史记录
只清理本工程生成物时删除 `build/`、`app/build/` 和 `.build/`;不要删除 SDK、NDK、
`.toolchains/` 或用户的签名密钥。上述输出均已被 Git 忽略。
旧的 `tools/check.ps1`、`tools/package-rc.ps1`、`gradlew`、`gradlew.bat` 已由 `打包.cmd` 替代。
旧 `.build/`、`app/build/`、`app/.cxx/`、项目根 `.gradle/`、`.kotlin/` 及重复工具链目录已清理;
保留的本地 JDK 已迁入 `build/toolchains/`。Gradle/CMake 配置、Wrapper JAR 和锁定信息是编译依赖,继续保留。
历史报告中的命令和产物路径记录当时状态,不再作为现行入口。保留的旧日志、审计 JSON 与 ROM 诊断画面
归档在 `build/reports/history/`;历史 APK 和候选发布材料迁入 `build/releases/history/`,可重新生成的旧编译目录已删除。
日常清理可删除 `build/app`、`build/native`、`build/root`、`build/cache`、`build/tmp` 等生成目录;
保留 `build/toolchains` 和需要留存的交付/验收记录。整个 `build/` 不进入 Git;不要删除外部 SDK、签名密钥或 ROM。
+6 -1
View File
@@ -15,9 +15,14 @@ Gradle 版本锁见 [gradle/libs.versions.toml](../gradle/libs.versions.toml)。
| Room | 2.7.2 | Google Maven | Apache-2.0;保留 notices | M2 使用 |
| DataStore Preferences | 1.1.7 | Google Maven | Apache-2.0;保留 notices | M4 使用 |
| FCEUmm | `236ccdfc911e84c60fea6b9d0699c2d440a8de14` | `tools/fetch-third-party.ps1` | GPL-2.0-only;交付完整对应源码、COPYING、修改说明 | M2 使用 |
| Nestopia | `224713b257c8620513c1c9ca28dc7f8dea711e18` | `tools/fetch-third-party.ps1` | GPL-2.0-or-later;内含 nes_ntsc(LGPL-2.1-or-later),保留完整源码、许可及版权 | 0.9.16 内置可选内核 |
| libretro.h | `0c9622896333ee62dc4326bbe8784a210ddeb03c` | `tools/fetch-third-party.ps1` | MIT;保留版权及许可 | M2 使用 |
| Oboe | 1.10.0 / `a81bb9f87d4105b84b682685d3bfbb5beca371d1` | `tools/fetch-third-party.ps1` | Apache-2.0;保留 notices | M3 使用 |
本项目计划静态链接 GPL-2.0-only 的 FCEUmm;因此将应用和可分发的对应源码按
Nestopia 无上游源码补丁;本仓库 CMake 读取固定提交的 `libretro/Makefile.common` 源码列表,使用
`__LIBRETRO__`、`NST_NO_ZLIB`、C++98 和独立共享库。其内置游戏数据库随源码构建,无需用户下载 XML。
上游来源为 [libretro/nestopia](https://github.com/libretro/nestopia/tree/224713b257c8620513c1c9ca28dc7f8dea711e18)。
本项目静态链接 GPL-2.0-only 的 FCEUmm;因此将应用和可分发的对应源码按
GPL-2.0-only 处理。发布前必须由发行负责人核对依赖的实际引入图、完整许可文本、版权声明、
修改源和源码提供义务;M0 的清单不构成法律意见。
+44 -13
View File
@@ -5,18 +5,19 @@
| 产品名称 | NESLite |
| 文档版本 | V1.0 |
| 编制日期 | 2026-09-12 |
| 需求依据 | [design.md](../design.md) |
| 最近修订 | 2026-09-14:按用户确认增加内置内核选择 F15,见第 11 节 |
| 需求依据 | [design.md](../design.md) 及第 11 节用户需求增补 |
| 目标版本 | Android 应用 1.0.0 |
| 首要设备 | 用户的 Honor MagicOS 10 手机+小鸡 X5 Lite 手柄 |
| 当前状态 | 规划完成,开发尚未开始;编制前目录仅有设计文档,尚无 Android 工程,也未初始化 Git 仓库 |
| 当前状态 | 用户确认产品可发布,准备 1.0.0 签名交付至 git.m3frame.com/shen/NESLite;打包入口为打包.cmd,输出统一在 build;历史专项证据与任务勾选状态见 todo.md,不将未执行项自动视为通过 |
本计划将 `design.md` 转化为可执行的任务、阶段依赖、交付物和验收门槛。产品范围以设计文档为准;工期、实现默认值和测试样本数量属于本计划提出的执行基线,尚无实机测试结果。文档版本 V1.0 不代表应用已经达到 1.0.0。
本计划将 `design.md` 转化为可执行的任务、阶段依赖、交付物和验收门槛。产品范围以设计文档及明确记录的用户增补为准;工期、实现默认值和测试样本数量属于执行基线,不能代替验收结果。文档版本 V1.0 不代表应用已经达到 1.0.0。
## 1. 开发目标与范围
### 1.1 交付目标
交付一款采用固定版本 FCEUmm 内核、自研 Android 前端、原生手柄输入的轻量 NES/FC 模拟器。用户能够完成“导入游戏 → 连接手柄 → 开始游戏 → 暂停和存档 → 退出 → 恢复进度”,并在目标手机上获得稳定的速度、声音和操作体验。
交付一款内置固定版本 FCEUmm 和 Nestopia 内核、自研 Android 前端、原生手柄输入的轻量 NES/FC 模拟器。用户能够完成“导入游戏 → 选择内核 → 连接手柄 → 开始游戏 → 暂停和存档 → 退出 → 恢复进度”,并在目标手机上获得稳定的速度、声音和操作体验。
第一版复用内核的 CPU、PPU、APU 和 Mapper 实现,开发重心为 Android 适配、libretro 宿主、音视频调度、输入和数据可靠性。所有内核能力均需经过前端接入和测试才能算作产品功能。
@@ -40,10 +41,11 @@
| F12 | 虚拟方向键、A/B、Start、Select,基础触屏菜单操作 | M6 | 无手柄可完成基本游戏操作,支持多点触控和取消事件 |
| F13 | 手柄测试、运行状态、错误日志和诊断导出 | M1 基础,M7 完成 | 能定位设备、输入、音频、存档和原生错误 |
| F14 | arm64 发布、4 KB/16 KB 验证、安装升级、源码及许可证交付 | M8~M9 | 发布包、源码、符号、构建记录和验收报告对应 |
| F15 | 内置 FCEUmm/Nestopia 选择,默认值与逐游戏覆盖,独立存档 | XCORE(第 11 节),M8 汇总 | 持久选择、下次加载生效、切回原内核保留存档、同 ROM 对照验证 |
### 1.3 明确不做
V1.0 不做联网对战、云存档、多平台模拟、在线下载游戏、复杂 CRT 滤镜、回溯、run-ahead、用户下载或切换内核。FDS、光枪、四人适配器和第二只手柄的完整体验留待 V1.1 之后。
V1.0 不做联网对战、云存档、多平台模拟、在线下载游戏、复杂 CRT 滤镜、回溯、run-ahead、用户下载或导入外部内核。内置内核选择按 F15 纳入本轮。FDS、光枪、四人适配器和第二只手柄的完整体验留待 V1.1 之后。
导入器首版仅开放 `.nes`,不扩展到压缩包、UNIF 或固件管理。应用不附带商业游戏 ROM。首版交付以可安装 APK 为准,应用商店上架不计入本轮工期。
@@ -56,8 +58,8 @@ V1.0 不做联网对战、云存档、多平台模拟、在线下载游戏、复
| Android | `minSdk 28`,`compileSdk 36`,`targetSdk 36` | 延续设计目标;实际手机 API、ABI 和页大小在 M1 读取 |
| 应用层 | Kotlin、AndroidX、原生 View | 单一 `app` 模块,按包划分职责;游戏使用独立页面 |
| 数据 | Room+DataStore | Room 管理游戏元数据;DataStore 管理设置和控制器配置 |
| 内核 | FCEUmm+libretro 接口 | M0 选定完整提交 SHA;M2 编译验证后冻结 |
| 原生层 | C/C++、JNI、Android NDK、CMake | 优先将固定内核静态链接进 JNI 库;上游构建适配保留可复现脚本 |
| 内核 | 固定提交的 FCEUmm/Nestopia+libretro 接口 | 清单记录完整提交 SHA;默认 FCEUmm,Nestopia 按 F15 接入 |
| 原生层 | C/C++、JNI、Android NDK、CMake | FCEUmm 静态链接进 JNI;Nestopia 使用包内独立共享库;可复现构建并隔离同名符号 |
| 视频 | `GLSurfaceView`+OpenGL ES | 原生帧缓冲交接;不经 Kotlin 每帧搬运图像 |
| 音频 | Oboe | 记录实际流参数,支持请求低延迟失败后的回退 |
| 构建工具 | AGP 8.13.2、Gradle 8.13、JDK 17 | 采用设计给出的兼容组合;M0 在本机完成构建验证 |
@@ -141,11 +143,12 @@ Paused → Stopping → Idle
├── saves/<sha256>/battery/ 游戏自身存档及有效备份
├── saves/<sha256>/states/ 10 个手动槽位及元数据、缩略图
├── saves/<sha256>/auto/ 最近 3 份自动恢复点
├── saves/cores/nestopia/<sha256>/ Nestopia 独立的 battery、states、auto、recovery 与会话标记
├── system/ 内核需要的稳定系统目录
└── diagnostics/ 限额日志及会话标记
└── diagnostics/ 限额日志
```
Room 数据库和 DataStore 使用各自标准应用目录;数据库记录游戏哈希、显示名、内部文件关联、收藏、最近游玩时间和列表可见状态。哈希按导入文件的完整字节计算,不擅自去头或改写文件;内容不同的版本分别管理。
FCEUmm 延续 `saves/<sha256>/`,读档保护副本及会话标记也在各内核、各 ROM 根目录内。Room 数据库和 DataStore 使用各自标准应用目录;数据库记录游戏哈希、显示名、内部文件关联、收藏、最近游玩时间和列表可见状态。哈希按导入文件的完整字节计算,不擅自去头或改写文件;内容不同的版本分别管理。
导入按“读取 URI → 有界流式复制和头部校验 → 计算 SHA-256 → 提交内部正式文件 → 数据库事务登记”执行。取消、空间不足及提交中断必须清理临时文件;数据库和文件系统不能形成单一事务,因此需在启动时对未登记正式文件及缺失文件记录进行核对和恢复。
@@ -212,7 +215,7 @@ Room 数据库和 DataStore 使用各自标准应用目录;数据库记录游
| --- | --- |
| 0.2.0/M2-01 | 编译锁定的 FCEUmm;接入 libretro API 版本检查、回调注册、初始化、目录、选项、玩家一端口和卸载 |
| 0.2.1/M2-02 | SAF 导入、文件大小与头部校验、SHA-256 去重、稳定内部副本、最小 Room 索引和错误提示 |
| 0.2.2/M2-03 | 视频回调、协商像素格式、行跨度与重复帧处理;GL 显示、4:3 和整数缩放基础能力 |
| 0.2.2/M2-03 | 视频回调、协商像素格式、行跨度与重复帧处理;区分纹理宽高与内核基础尺寸,GL 按基础尺寸整数缩放并支持 4:3 适配;空间不足一倍时等比例缩小 |
| 0.2.3/M2-04 | 模拟线程和会话状态机;手柄快照接入;启动、暂停、继续、重置、退出;基础电池存档读写 |
**出口条件:** 至少 3 个有权使用的样本完成加载和运行,其中包含一个电池存档样本;完整操作流程通过;正常退出再加载后游戏自身进度可恢复;损坏文件加载失败不会破坏现有数据。
@@ -291,7 +294,7 @@ Room 数据库和 DataStore 使用各自标准应用目录;数据库记录游
| M8-03 | 检查全部发布原生库与 APK 的 16 KB 对齐;4 KB 和 16 KB 环境运行;API 28 基线冒烟 |
| M8-04 | 同应用 ID/签名覆盖升级、Room/设置迁移和存档兼容验证;整理发布源码、许可证、符号和已知问题 |
**出口条件:** 第 7 节发布门槛全部通过,无阻断或高优先级缺陷;最终候选包而非仅调试包通过安装、加载、输入、音频、保存恢复及退出冒烟。修复后重跑受影响用例;内核、时钟或存档格式变动须重跑对应完整测试集。
**出口条件:** 第 7 节发布门槛全部通过,无阻断或高优先级缺陷;最终候选包而非仅调试包通过安装、加载、输入、音频、保存恢复及退出冒烟。修复后重跑受影响用例;内核、时钟或存档格式变动在开发时先做局部检查,冻结候选前补齐受影响的完整测试集,按 todo.md 分级规则复用仍有效证据。
### M9/1.0.0:正式交付
@@ -419,11 +422,11 @@ FCEUmm 上游声明采用 GNU GPL v2,并要求参考源文件头部细节,
- [ ] 存档格式、内核升级兼容策略、升级安装记录和已知问题。
- [ ] `LICENSE`、`THIRD_PARTY_NOTICES` 及对应依赖许可证材料。
只有 F01~F14 在约定范围内完成、发布指标通过且无阻断/高优先级缺陷时,才将应用标记为 1.0.0。
只有 F01~F15 在约定范围内完成、发布指标通过且无阻断/高优先级缺陷时,才将应用标记为 1.0.0。
## 10. 首轮启动清单
首轮执行 M0 和 M1,先交付能安装、能加载原生库、能验证真实手柄输入的 0.1.x 诊断版。
本节保留初始启动顺序。首轮执行 M0 和 M1,先交付能安装、能加载原生库、能验证真实手柄输入的 0.1.x 诊断版。
1. 建立 Android+JNI 最小工程,锁定工具链,生成首个可安装 APK。
2. 确定应用 ID、依赖提交、基础数据目录及版本管理方式。
@@ -433,3 +436,31 @@ FCEUmm 上游声明采用 GNU GPL v2,并要求参考源文件头部细节,
6. 完成 M1 出口检查后,进入 M2 的 ROM 导入和 FCEUmm 接入。
首轮以设备与手柄实测为目标。首次音画完整的可玩验收在 M3,可靠日常使用验收在 M6~M7,正式发布在 M8~M9 全部门槛通过后进行。
## 11. F15 增补:内置内核选择(2026-09-14)
用户确认在应用内置的多个内核间切换,并反馈“龙珠英雄”无法打开、黑屏。本增补覆盖原设计中不提供
内核切换的限制;仍不提供外部内核文件、在线下载或自动尝试所有内核。原 M0~M9 编号和已有验收证据
保留,增加 XCORE 实现任务及 GCORE 门槛,纳入 G8 汇总。0.9.16 为开发验证版本,原工期估算不含本增补。
行为契约:初始默认 FCEUmm,可设 Nestopia 为默认;每个 ROM 可覆盖默认或恢复“跟随默认”。选择持久化,
只在下次打开游戏时生效;旧会话先保存/卸载/销毁,再初始化所选内核。单次只运行一个内核实例。
FCEUmm 保留原存档目录,Nestopia 使用独立目录;电池、即时存档、备份和异常恢复计数均隔离,跨内核
状态与存档包拒绝导入。固定提交、具体目录和封装细节以依赖清单及 `docs/save-format.md` 为准。
| 任务 | 交付内容 | 前置 | 最小验收 |
| --- | --- | --- | --- |
| XCORE-01 | 固定 Nestopia 来源并接入双内核宿主、像素格式转换和打包 | 现有可构建的 M2/M3 接口 | L1:arm64 构建、必需入口、局部转换用例、全部库静态对齐 |
| XCORE-02 | 默认和逐游戏选择、持久记录、下次加载生效及当前内核展示 | XCORE-01 | L1:应用编译,默认/覆盖/取消与磁盘重开读取的局部测试 |
| XCORE-03 | 按内核隔离存档与恢复标记,校验存档包身份,保留旧 FCEUmm 数据 | XCORE-01、现有 M5 格式接口 | L1:旧路径、独立路径、包往返、跨内核拒绝、旧包归属 |
| XCORE-04 | 在 Android 验证切换、重启持久化和独立进度 | XCORE-02、XCORE-03 | L2:同进程 FCEUmm→Nestopia→FCEUmm,一份带电池及一份无电池样本的相关分支 |
| XCORE-05 | 定位“龙珠英雄”黑屏,按已确认哈希修正制式选择并记录双内核结果 | XCORE-04、具体 ROM 与目标手机;桌面复现可提前独立完成 | L1:精确匹配及选项隔离;L2:记录哈希/Mapper/区域/包与内核提交,分别验证加载、进入游戏、输入及音画 |
GCORE 为 L3 汇总门槛,依赖 XCORE-01~05;待办条目给出可勾选标准。开发时只运行受影响模块的局部
检查和上述短路径;冻结候选时一次性补受影响内核的兼容集、H-AV、H-SAVE 和 H-NATIVE,已有仍有效证据
按待办第 2 节复用。GCORE 与 G8 引用同一报告,不能各启动一轮重复测试。H-LONG/H-INPUT/H-UPGRADE
保留原发布节点,只有相关证据失效或尚未取得时补齐。桌面测试和静态对齐通过不代替手机加载、16 KB 运行
或具体游戏兼容结果。
接入证据见 [双内核报告](reports/core-selection-0.9.16.md),具体 ROM 的制式修复见
[0.9.17 记录](reports/long-zhu-ying-xiong-0.9.17.md),任务状态只在 [todo.md](../todo.md) 勾选。
+8 -2
View File
@@ -6,7 +6,7 @@
| --- | --- |
| 显示名称 | `NESLite` |
| 正式 application ID/namespace | `org.neslite.app` |
| 当前候选版本 | `0.9.15`,`versionCode = 9015` |
| 当前发布版本 | `1.0.0`,`versionCode = 1000000` |
| 调试 application ID | `org.neslite.app.debug` |
| 发布 ABI | `arm64-v8a` |
| min/target SDK | 28/36 |
@@ -28,6 +28,10 @@ release keystore;私钥、口令、`*.jks`/`*.keystore` 和 CI 密钥不进
首次发布时记录别名、证书 SHA-256 指纹、有效期和保管责任人到未提交的发布保管记录。之后所有
`org.neslite.app` 更新必须使用同一签名证书;若证书不可恢复,不能以同一 ID 声明无缝升级。
1.0.0 正式签名证书 SHA-256:
`767BDF6D6AB140B336EFCF28C5BAAC7A8515F2D760BC568283BAB4537D319191`。
密钥别名为 `neslite-release`,RSA 3072,有效期至 2054-01-30;私钥与密码仅在维护者本机保存。
## 数据目录约定
应用内部 `files/` 的长期布局如下,正式 ROM 不放在 `cache/`:
@@ -38,10 +42,12 @@ files/
├── saves/<sha256>/battery/
├── saves/<sha256>/states/
├── saves/<sha256>/auto/
├── saves/cores/nestopia/<sha256>/ Nestopia 独立的 battery、states、auto、recovery 与标记
├── system/
└── diagnostics/
```
Room 与 DataStore 使用 Android 标准私有目录。ROM 身份是导入文件完整字节的 SHA-256;同名但
FCEUmm 保持原存档位置;Nestopia 不读取或迁移 FCEUmm 存档。`core_preferences` DataStore 保存默认
内核及按 ROM 哈希覆盖的选择,不改变 Room 身份。Room 与 DataStore 使用 Android 标准私有目录。ROM 身份是导入文件完整字节的 SHA-256;同名但
不同内容必须独立,重新导入相同哈希才重新关联既有存档。目录本身在 M2/M5 实现,本文件只固定
数据兼容约定。
+9 -5
View File
@@ -1,15 +1,19 @@
# 已知问题与候选版限制
# 已知问题与验证记录
本清单对应 0.9.15 候选源码。优先级含义:阻断表示 G8 不可通过;高表示发布前必须处理;中/低需有
明确接受或修复结论。
用户于 2026-09-14 确认产品可发布,并授权准备 1.0.0 源码和签名 APK。下表保留开发期间的
问题与证据缺口;旧优先级对应原 G8 计划,不把用户的发布决定改写成未执行专项已经通过。
本次签名与发布记录见 [发布说明](publishing.md)。
| 编号 | 优先级 | 状态 | 问题与处理条件 |
| --- | --- | --- | --- |
| CORE-H01 | 高 | 已定位/待手机复核 | 用户提供的 ROM 哈希为 `f2fa5c9e40dc68e25fc9d9a4d5f2d5c9179c393d16c0d4e76f843aa17a6df981`,Mapper 4。两个内核按 NTSC 启动均卡死;0.9.17 对该哈希自动选 Dendy,两内核各 1800 帧启动/菜单与一次核心状态往返通过,手机端和完整玩法仍待验证。见 `docs/reports/long-zhu-ying-xiong-0.9.17.md`。 |
| CORE-H02 | 高 | 待实机 | 双内核 APK 已构建并通过局部自动测试及静态对齐检查;Android 动态加载、切换、音画和存档路径尚待 XCORE-04 及 GCORE 验收。 |
| VIDEO-H01 | 高 | 已修复/待手机复核 | Nestopia 扩展纹理被误用为原始像素宽度,导致整数模式横向拉宽。0.9.18 按内核基础尺寸计算倍率,局部尺寸测试和两内核桌面尺寸检查通过;M2-03b 的手机切换复核待完成。见 `docs/reports/integer-scaling-0.9.18.md`。 |
| RC-B01 | 阻断 | 开放 | 荣耀 Magic8 已通过手动安装、JNI 与设备基线并枚举 X5 Lite,但无 ADB,且按键、插拔、ROM 主链、生命周期等 G1~G7/G8 实机证据仍不完整。 |
| RC-B02 | 阻断 | 开放 | 尚无满足动作/滚屏、声音和可观察电池进度要求的合法游戏样本;冻结的 12 个 CC0 最小样本只能用于加载冒烟。 |
| RC-B03 | 阻断 | 开放 | H-LONG、H-INPUT、4 KB/16 KB 运行、API 28 冒烟及 H-UPGRADE 尚未在设备执行。 |
| RC-B04 | 阻断 | 开放 | 尚未提供受保护的发布签名密钥及同 ID/同签名旧版数据集;当前 RC 静态审计包为未签名 APK。 |
| RC-M01 | 中 | 开放 | Debug lint 有 46 个非阻断警告,主要是动态界面文本国际化、依赖版本提示和 Android 16 固定横屏兼容提醒;无 lint 错误。 |
| RC-B04 | 阻断 | 签名已配置/升级证据待补 | 已创建独立正式密钥,打包入口支持签名和验证;首次正式包使用 org.neslite.app,旧调试包为 org.neslite.app.debug。同 ID/同签名旧版数据集和 H-UPGRADE 记录仍未归档。 |
| RC-M01 | 中 | 开放 | 0.9.15 的历史 Debug lint 记录有 46 个非阻断警告,主要是动态界面文本国际化、依赖版本提示和 Android 16 固定横屏兼容提醒;0.9.16~0.9.18 局部修订均未重跑 lint,候选冻结时更新结果。 |
不得通过删除失败 ROM、缩短规定轮数/时长、用 x86_64 替代 arm64,或用桌面原生测试替代 Android
实机运行来关闭阻断项。每项关闭时应在 M8 报告登记设备、包哈希、ROM 哈希、命令、原始日志和结论。
+35
View File
@@ -0,0 +1,35 @@
# NESLite 发布到 Gitea
源码仓库:`http://git.m3frame.com/shen/NESLite.git`;发行页:
[shen/NESLite/releases](http://git.m3frame.com/shen/NESLite/releases)。源码放入 Git,APK、源码归档和符号放入发行附件。
## 正式签名
维护者本机默认目录为 `%USERPROFILE%/NESLite-private/signing`,可用 `NESLITE_SIGNING_DIRECTORY` 覆盖。
目录内使用 `neslite-release.p12`、`password.dpapi`,别名 `neslite-release`。
DPAPI 密码只供当前 Windows 用户解密;换机需从维护者自己的离线恢复材料还原,并重新加密密码。
签名文件、密码和恢复材料均不进入 Git、源码归档或发行附件。
首次生成的本地恢复副本位于 `%USERPROFILE%/NESLite-private/recovery`,包含密钥副本和恢复密码。
维护者应将其复制到受保护的离线存储;本机副本不等于异地备份。后续更新继续使用此密钥。
## 定版与构建
1. 同步应用版本、版本测试、说明和当前发布记录,提交全部源码改动。
2. 运行 `打包.cmd release -NoPause`。正式构建要求干净工作区,固定四项源码依赖,签名并验证 APK。
3. 检查 `build/releases/NESLite-<版本>-release.json` 与 `SHA256SUMS`:提交、版本、APK 和源码附件对应。
4. 将最终提交推送到 `main`,为该提交建立 `v<版本>` 标签并推送。
5. 在 Gitea 创建对应标签的发行草稿,填写 `docs/releases/<版本>.md` 的说明,上传清单中的附件和校验清单。
核对附件后发布。不要上传 `build` 整个目录、游戏 ROM、密钥或历史包。
当前站点的 HTTP Git 访问已核对可用;网页公布的 SSH 地址含 localhost,不能直接用于远程推送。
如以后启用 HTTPS 或配置正确的 SSH 地址,应使用站点确认后的实际地址;凭据由本机 Git 凭据管理器保管。
## 从发行源码构建
可以克隆仓库并双击 `打包.cmd` 构建调试版,固定依赖由脚本取得。
也可解压 NESLite 源码包,将四项依赖源码分别解压至 `third_party/sources/` 对应目录,然后按 `docs/build.md`
中的 Java/Wrapper 调用方式执行 `:app:assembleDebug`。该方式使用随包源码,不要求依赖目录带 Git 元数据。
重新分发改动版时使用自己的签名密钥,不能请求或使用维护者私钥。
1.0.0 发布依据为产品负责人的发布确认;历史计划中未归档的设备专项不自动勾选通过。
+33
View File
@@ -0,0 +1,33 @@
# NESLite 1.0.0
NESLite 的首个正式版本,面向 Android 9 及以上的 arm64 设备。
## 主要功能
- 导入单个 NES 文件或扫描文件夹,支持中文名称、搜索、收藏和游戏库管理。
- 内置 FCEUmm 与 Nestopia,可设置默认内核及逐游戏选择;两个内核独立保存进度。
- 支持 4:3 显示、原始像素整数缩放、最近邻和线性过滤。
- 提供横屏触控按键、外接手柄映射、软件连发和快进。
- 支持电池存档、即时存档、自动恢复点及存档包导入导出。
- 包含已确认“龙珠英雄”ROM 的 Dendy 制式兼容修复,以及 Nestopia 整数缩放比例修复。
## 安装和数据
下载 `NESLite-1.0.0-arm64-v8a.apk`,按 Android 提示允许对应来源安装。
正式包名为 `org.neslite.app`;此前调试包使用 `org.neslite.app.debug`,两个应用可以共存。
请先从调试版导出存档,在正式版导入相同 ROM 和存档包,确认进度后再处理旧应用。不同内核的存档不能互换。
应用不附带游戏 ROM,请自行准备有权使用的文件。当前版本仅提供 arm64-v8a。
## 源码与校验
发行附件包含签名 APK、SHA-256 清单、NESLite 源码、固定版本的 FCEUmm/Nestopia/Oboe/libretro.h
源码,以及原生调试符号、许可证和依赖清单。构建方法见源码中的 `docs/build.md`。
正式签名证书 SHA-256:
`767BDF6D6AB140B336EFCF28C5BAAC7A8515F2D760BC568283BAB4537D319191`。
## 验证范围
产品负责人已确认可发布。本次交付核对正式包身份、签名、arm64 库和 16 KB 静态对齐,并使用局部版本测试。
历史报告未归档的长稳、跨页大小设备运行和升级专项仍保持“未验证”,不将静态检查替代实机结果。
兼容性与问题反馈请同时提供应用版本、当前内核、ROM 哈希和具体表现。
+72
View File
@@ -0,0 +1,72 @@
# NESLite 0.9.16 双内核开发记录
本页保留 0.9.16 当时的证据;后来收到具体 ROM 后的定位与 0.9.17 修复见
[龙珠英雄兼容记录](long-zhu-ying-xiong-0.9.17.md)。通用构建输出路径可能已被新版本覆盖。
日期:2026-09-14。对应 F15/XCORE;应用版本 `0.9.16-debug`、`versionCode 9016`、
ID `org.neslite.app.debug`、ABI `arm64-v8a`。本次基于提交
`e3842c21dcd4c00f34a740da86947c93b5b93afb` 的工作区改动构建,尚未创建新的源码提交。
这是局部开发检查记录,不是 GCORE 或 G8 放行记录。
## 已实现行为
- 保留 FCEUmm `236ccdfc911e84c60fea6b9d0699c2d440a8de14`,新增 Nestopia
`224713b257c8620513c1c9ca28dc7f8dea711e18`,两个内核均随 APK 提供。
- 默认 FCEUmm;设置页可改默认,长按游戏可单独指定或跟随默认。选择写入 DataStore,下一次打开
游戏生效;同一模拟线程先关闭旧会话再打开新会话。状态页和存档管理展示活动内核。
- FCEUmm 的原有存档路径不变,Nestopia 使用独立路径;旧包只归 FCEUmm,新包携带内核 ID/提交,
跨内核包与即时存档拒绝导入。异常恢复计数也按内核分开。
- 宿主支持 XRGB8888、0RGB1555 转 RGB565,保留 pitch 处理和重复帧;清空缓冲后帧序号继续递增。
- 修正无电池内存游戏被读档前保护误拒绝的问题:电池大小为零时保护核心状态即可,实际存在电池
内存时仍要求完整快照;失败后继续执行回滚。模拟线程在全部成员初始化完成后才启动。
## L1 结果
构建环境延用 JDK 17.0.17+10、AGP 8.13.2、Gradle 8.13、NDK 28.2.13676358、CMake 3.22.1。
Windows 本地测试将 Java 临时目录定向到 `.build/java-tmp`;偏好持久化测试使用 DataStore 的 Okio
文件存储以支持 Windows 替换已有文件,并关闭后重开文件验证持久化。Android 生产存储仍使用标准
`preferencesDataStore`。未更改业务依赖版本。
| 检查 | 结果 | 证据/范围 |
| --- | --- | --- |
| arm64 Debug APK | 通过 | `.build/core-selection-build.log`;原生和 Kotlin 编译、链接、打包成功 |
| Kotlin 定向测试 | 6 项通过,0 失败 | CorePreferencesTest 3 项、AppSettingsTest 2 项、BuildIdentityTest 1 项;`app/build/test-results/testDebugUnitTest/` |
| 原生局部测试 | 2 个测试程序通过 | `neslite_core_selection_test`、`neslite_native_smoke_test`;`.build/native-tests/Testing/Temporary/LastTest.log` |
| Nestopia 导出 | 21 个宿主必需入口存在 | APK 解包后检查动态符号表;运行时仍会检查入口和 API 版本 |
| APK 与 ELF 静态对齐 | 通过 | `.build/core-selection-native-audit.json`;全部 3 个原生库 LOAD 段最小对齐 16384,APK 16 KB 对齐合格 |
局部原生用例覆盖内核 ID、旧路径保留、目录与恢复键隔离、包身份及旧包归属、跨内核状态拒绝、
像素通道转换和 pitch 边界、清空后帧序号。原有 smoke 用例复核共享的视频和存档封装/提交行为。
没有将 Android 动态库真正加载、内核运行或无电池游戏的完整读档路径记作自动测试通过。
复跑本轮局部检查(工具链配置见构建说明):
```powershell
.\gradlew.bat :app:assembleDebug :app:testDebugUnitTest --tests org.neslite.app.core.CorePreferencesTest --tests org.neslite.app.settings.AppSettingsTest --tests org.neslite.app.BuildIdentityTest
cmake -S app/src/main/cpp -B .build/native-tests
cmake --build .build/native-tests --config Debug --target neslite_native_smoke_test neslite_core_selection_test
ctest --test-dir .build/native-tests -C Debug -R 'neslite_(native_smoke|core_selection)_test' --output-on-failure
.\tools\check-rc-native.ps1 -ApkPath app/build/outputs/apk/debug/app-debug.apk -OutputPath .build/core-selection-native-audit.json
```
仅文档改动无需复跑以上命令;实现修改按 todo.md 的影响映射选取相关项。本轮未执行 Stage 全量本地
集合、发布 lint、100 次存读档、插拔轮次或 2 小时长稳。
## 构建产物
`app/build/outputs/apk/debug/app-debug.apk`,24,176,631 字节,调试签名,可覆盖同 ID/同调试签名的旧版。
SHA-256:`3BBB41F94F64799DEF49D7A087BB36159E07F1BB6D4F67CFE4D77587E9EF9956`。
APK 原生库为 `libneslite_jni.so`(含 FCEUmm/Oboe)、`libneslite_nestopia.so`、
`libdatastore_shared_counter.so`,均为 arm64-v8a;依赖检查仅出现 Android 系统库,无缺失的第三方共享库。
静态检查通过不能代替 Android 4 KB/16 KB 运行检查。
## 未验证项与最短实测路径
ADB 未发现已连接设备;未取得用户所说“龙珠英雄”的具体 ROM、SHA-256、Mapper 或黑屏日志。
该名称不能唯一确定游戏内容,因此不推断 Mapper,也不宣称新增 Nestopia 已解决黑屏。
先按 XCORE-04 完成 Android 同进程切换、重启选择记录、独立电池与即时存档的短路径,再按 XCORE-05
对同一份“龙珠英雄”分别验证两个内核。Nestopia 也可能不兼容该 ROM;双内核都失败时保留诊断继续定位。
候选冻结时,受影响内核的兼容集、H-AV、H-SAVE、H-NATIVE 按 GCORE/G8 共用证据安排;其余专项仅按
原发布门槛和证据有效性补齐。实机、长测、签名和发布门槛保持未勾选。
+52
View File
@@ -0,0 +1,52 @@
# 原始整数缩放比例修复(0.9.18)
日期:2026-09-14。对应 F04/M2-03a、M2-03b。本次修复用户截图中 Nestopia 游戏画面横向拉宽的
问题,完成 L1 局部验证并提供调试 APK;未连接 Android 设备,M2-03b 的 L2 画面复核仍待完成。
## 原因与改动
固定提交的 Nestopia 默认启用复合视频过滤,视频回调输出为 602×224,
`retro_get_system_av_info` 给出的基础尺寸仍为 256×224。原渲染器直接以纹理宽高计算整数倍率,
把横向扩展的采样宽度当成了 NES 原始像素宽度,因此整幅画面变扁。
- 视频缓冲同时保存纹理尺寸和基础尺寸,像素与基础尺寸在同一帧快照内交接;重复帧保留上一完整快照,
新帧使用当时的基础尺寸,缺失基础尺寸时成对回退为纹理尺寸。
- GL 仍按纹理实际宽高上传;整数显示改按基础宽高选择最大共同整数倍率并居中。空间不足一倍时,
等比例缩小以完整显示。4:3 模式继续按 4:3 适配,暂停时切换模式也重新计算显示区域。
- 沿用内核选项、固定提交、存档配置身份与存档路径;这次只修正前端显示尺寸。
在 1664×1248 的显示区域中,Nestopia 旧算法得到 1204×448;修复后为 1280×1120,即
256×224 的五倍,与同基础尺寸的 FCEUmm 相同。原始整数模式保持基础像素比例,与强制 4:3 显示有区别。
## 分级验证
| 层级/检查 | 结果与范围 |
| --- | --- |
| L1/显示与缓冲 | `neslite_video_viewport_test` 通过:扩展纹理与基础尺寸分离、共同整数倍率、4:3 切换、区域大小变化、重复帧、缓冲清空与新帧尺寸、缺失基础尺寸、刚好一倍和不足一倍边界 |
| L1/共享缓冲回归 | `neslite_core_selection_test` 通过,保留原有格式转换与跨内核帧序号检查 |
| L1/真实内核尺寸 | 对已有本地“龙珠英雄”样本,两内核各采集 60 帧;FCEUmm 为纹理 256×224/基础 256×224,Nestopia 为纹理 602×224/基础 256×224,生产显示算法均计算出 1280×1120,位置 192,64 |
| L1/应用构建 | 最终 `assembleDebug` 通过;`BuildIdentityTest` 1 项和 `AspectRatioFrameLayoutTest` 3 项通过 |
| L1/最终 APK | 3 个 arm64 原生库的 ELF LOAD 段与 APK 16 KB 对齐检查通过,版本 0.9.18-debug/9018 |
| L2/手机画面 | 待复核;ADB 无已连接设备。桌面探针使用真实内核和生产尺寸算法,不启动 Android/GL,也未运行截图中的 Mario ROM |
本次没有运行 Stage 全量、全 ROM 遍历、长稳或重新执行历史专项。桌面探针自带的一次核心状态往返
也返回通过,仅保留在日志中,不作为本次存档验收。尺寸验证使用原样本的字节相同副本,ROM 不进入 APK。
日志:`.build/video-viewport-native-0.9.18.log`、`.build/video-viewport-android-0.9.18.log`、
`.build/video-viewport-final-build-0.9.18.log`、`.build/video-viewport-native-apk-0.9.18.json`;
真实内核尺寸为 `.build/rom-probe/video-fceumm-0.9.18.log` 与 `video-nestopia-0.9.18.log`。
局部原生测试可在构建对应目标后用 CTest 的
`-R '^neslite_(video_viewport|core_selection)_test$'` 选择;真实核心尺寸检查见
[探针说明](../../tools/rom-probe/README.md),传入 60 帧即可。
## 安装包与待复核步骤
- APK:`.build/releases/NESLite-0.9.18-debug-arm64-v8a.apk`,与
`app/build/outputs/apk/debug/app-debug.apk` 字节相同;24,176,631 字节。
- SHA-256:`015D5C76BC8BF0E25549059DE21704470543D0A7170FB5F5D6C0BC6AEC7964E6`。
- application ID:`org.neslite.app.debug`;`versionCode = 9018`。当前工作区构建,未创建 Git 提交。
安装新版后,用 Nestopia 打开原截图中的游戏,在设置中切换“原始整数缩放”和“保持 4:3”,检查人物、
文字与场景不再横向拉宽,整数模式保留居中黑边;暂停时再切换一次确认立即生效。FCEUmm 的同类复核
与 XCORE-04 的切换检查合并完成,不重复跑同一路径;目标手机结果记录后再完成 M2-03b。
@@ -0,0 +1,78 @@
# 龙珠英雄黑屏定位与 0.9.17 修复
日期:2026-09-14。用户提供了项目根目录的 `龙珠英雄.nes`。本次在两个固定内核中复现 NTSC 启动
卡死,并加入按精确文件哈希选择 Dendy 的兼容规则;Android 调试 APK 已构建,手机端仍待复核。
对应计划 F15/XCORE-05,不作为 GCORE 或 G8 的完整放行证据。
## 文件与复现结果
| 项目 | 实际值 |
| --- | --- |
| 文件大小 | 262,160 字节,等于 16 字节头+256 KiB PRG |
| 完整文件 SHA-256 | `f2fa5c9e40dc68e25fc9d9a4d5f2d5c9179c393d16c0d4e76f843aa17a6df981` |
| PRG CRC32 | `20d4221c` |
| iNES 头 | `4e 45 53 1a 10 00 42 00 00 00 00 00 00 00 00 00` |
| 头部声明 | Mapper 4、256 KiB PRG、无 CHR-ROM、带电池,未正确表达此文件所需的 Dendy 制式 |
| 复现平台 | Windows x64、MinGW GCC 16.1.0;同一 libretro 环境选项默认值与输入脚本 |
| FCEUmm 提交 | `236ccdfc911e84c60fea6b9d0699c2d440a8de14` |
| Nestopia 提交 | `224713b257c8620513c1c9ca28dc7f8dea711e18` |
原始默认选项下,两个内核都成功返回加载完成,但持续输出单色画面。FCEUmm 的 600 帧检查仅有
2 次画面变化、非零音频样本计数为 0;Nestopia 为 4 次变化、非零音频计数为 1,并报告 CPU Jam。
临时 CPU 跟踪在 FCEUmm 第 23 帧观察到中断恢复后从错误的程序存储区取指,在 `$9020` 执行停止指令。
该复现在桌面直接取得核心视频回调,不经过 Android 或 GL,因而可以确认黑屏已经发生在游戏执行阶段。
针对启动时序分别检查 PAL 与 Dendy 后,Dendy 在两个内核均能显示中文启动画面并进入菜单;选择
Dendy 作为此文件的兼容制式。Dendy 是核心的 CPU/PPU 时序配置,不是修改手机刷新率;NES 2.0
对该制式有独立定义,见 [NESdev 时序字段](https://www.nesdev.org/wiki/NES_2.0#CPU/PPU_Timing)。
这里只声明已实测的文件,不按中文文件名、Mapper 4 或所有中文游戏泛化此修复。
原始复现日志:`.build/rom-probe/fceumm.log`、`nestopia.log`;临时跟踪记录为
`.build/rom-probe/fceumm-trace.txt`。跟踪只用于定位,最终检查工具和 APK 使用未修改的上游核心源码。
## 应用改动
- `rom_compatibility` 在宿主读入 ROM 后用实际字节计算 SHA-256;仅上述完整哈希命中
`long-zhu-ying-xiong-dendy-v1`,不依赖文件名或 UI 传入的身份字符串。
- 环境回调注册选项时,FCEUmm 使用 `fceumm_region=Dendy`,Nestopia 使用
`nestopia_force_system=dendy`。其余选项、其他 ROM 和两个内核提交保持原值。
- 状态诊断包含 `compatibilityProfile`;卸载时重置,下一款游戏不会继承该规则。
- 原 ROM 字节及其哈希、游戏索引和电池存档位置保留。实际制式进入现有即时存档配置元数据,因此
旧 NTSC 即时存档按原兼容检查拒绝加载且保留文件;本次没有自动删除、改写或迁移用户进度。
- 新增可选 `tools/rom-probe/` 检查工具,明确传入单份本地 ROM 才运行;本地游戏样本加入 Git 忽略,
不进入 APK 或应用源码发布包。
## 局部验证
| 检查 | 结果与边界 |
| --- | --- |
| 兼容规则单测 | `neslite_rom_compatibility_test` 通过;覆盖精确哈希、不同/缺失哈希、两个内核的键名和值、其他选项不受影响 |
| FCEUmm+生产兼容规则 | 1800 帧,约 36 模拟秒;50.007 FPS、91 次画面变化、非零音频计数 1,454,099;一次核心状态往返通过 |
| Nestopia+生产兼容规则 | 1800 帧,约 36 模拟秒;50.007 FPS、92 次画面变化、非零音频计数 1,474,223;一次核心状态往返通过 |
| 画面检查 | 两个内核均看到中文启动、剧情选择和代码输入菜单;固定 Start/A 脚本会改变菜单状态,不再持续黑屏 |
| Android 构建/版本 | `assembleDebug` 通过;BuildIdentityTest 1 项通过,版本 `0.9.17-debug`/9017 |
| 最终 APK 静态原生检查 | 全部 3 个 arm64 库 LOAD 段和 APK 的 16 KB 对齐通过;没有新增共享库依赖 |
| 原文件保护 | 修复后再次计算用户原文件 SHA-256,与输入一致 |
核心状态往返是在 1800 帧后序列化、运行 30 帧、恢复并再运行相同 30 帧,比较画面哈希;每个内核
只做一次,不等同于 Android 存档文件、100 次循环、听感或完整玩法验收。两次 30 帧不计入上表的
1800 帧启动统计。尚未验证 Android 上本次自动规则、完整战斗/通关及长期运行。
验证日志:`.build/rom-probe/verified-fceumm.log`、`verified-nestopia.log`、
`android-build-0.9.17.log`、`android-native-0.9.17.json`;抽样画面为同目录的
`verified-fceumm-179.png`、`verified-fceumm-599.png`、`verified-nestopia-599.png` 等。
复跑单 ROM 检查见 [工具说明](../../tools/rom-probe/README.md);规则单测可用 CTest 精确选择
`^neslite_rom_compatibility_test$`。没有运行 Stage 全量、全库 ROM 遍历、长稳或重复的历史专项。
## 交付与手机复核
版本:`0.9.17-debug`,`versionCode 9017`,ID `org.neslite.app.debug`,arm64-v8a。
源码基于 `e3842c21dcd4c00f34a740da86947c93b5b93afb` 及当前工作区改动,未创建新的 Git 提交。
APK 为 `app/build/outputs/apk/debug/app-debug.apk`,另提供同字节的版本化副本
`.build/releases/NESLite-0.9.17-debug-arm64-v8a.apk`,大小 24,176,631 字节。
SHA-256:`3A08617A13F0EBBD058F3F93AA12F6CB5E65FEC8865124771E9960EA020A8540`。
安装新版后从游戏列表重新打开原有“龙珠英雄”即可命中规则,无需重新导入或改名。FCEUmm 和 Nestopia
均有对应设置;若用户正在旧版会话中,需重新打开游戏。ADB 当前未发现已授权手机,手机加载、输入、
声音和完整玩法需继续按 XCORE-04/05 复核;若仍失败,诊断中的应用版本、内核、ROM 哈希及
`compatibilityProfile` 可用于确认是否实际运行了本次修复。
+2 -1
View File
@@ -2,7 +2,7 @@
本表将设计需求映射到唯一的实现和验收位置,不把规划当成已完成结果。
## F01~F14 映射
## F01~F15 映射
| 需求 | 功能摘要 | 实现位置 | 功能门槛 |
| --- | --- | --- | --- |
@@ -20,6 +20,7 @@
| F12 | 虚拟按键 | M6-04 | G6 |
| F13 | 设备与运行诊断 | M1、M3、M7 | G7 |
| F14 | 原生兼容和交付 | M0、M8、M9 | G8/G9 |
| F15 | 内置内核默认选择、逐游戏覆盖和存档隔离(2026-09-14 用户增补) | XCORE-01~XCORE-05,计划第 11 节 | GCORE/G8 |
## 设备待测参数
+17 -3
View File
@@ -4,6 +4,12 @@ M5 固定两种二进制格式:即时存档 `.nls`(魔数 `NESLST01`)和
`NESLPK01`)。所有多字节整数均为无符号小端;时间为 Unix epoch 毫秒。格式解析先检查固定头、版本、
长度上限和精确总长,再分配载荷。
## 内核与目录
FCEUmm 延用 `files/saves/<romHash>/`,既有存档无需迁移;Nestopia 使用
`files/saves/cores/nestopia/<romHash>/`。下文的相对目录均位于当前内核、当前 ROM 的根目录下。
电池存档、即时存档、恢复副本和异常会话标记均隔离;不自动复制或转换另一内核的数据。
## 即时存档 `.nls`
固定头依次包含格式版本、ROM 哈希/内核名/内核提交/配置文本的长度,缩略图宽、高、行距和
@@ -11,25 +17,33 @@ M5 固定两种二进制格式:即时存档 `.nls`(魔数 `NESLST01`)和
四段 UTF-8 元数据、核心状态和与该状态在同一帧边界取得的原始缩略图。
- 状态最大 64 MiB,缩略图最大 2 MiB,单段文本最大 16 KiB。
- 读档必须匹配完整 ROM SHA-256、`FCEUmm`、固定内核提交和当前核心配置;不同内核提交默认拒绝,
- 读档必须匹配完整 ROM SHA-256、当前内核名称(`FCEUmm` 或 `Nestopia`)、固定提交和当前核心配置;不匹配则拒绝,
原文件不改名、不删除。
- 0.9.17 的已知 ROM 制式兼容规则体现在核心配置元数据中;旧 NTSC 会话的即时存档不会自动读入
Dendy 会话。电池文件、ROM 哈希和各内核的目录保留,不通过修改 ROM 内容或删除旧档来处理黑屏。
- 手动槽为 `states/slot-0.nls` 至 `slot-9.nls`;自动恢复点为 `auto/auto-0.nls` 至
`auto-2.nls`,仅在新文件提交成功后推进轮换。
## 独立存档包 `.nsp`
包头保存格式版本、64 字节 ROM SHA-256 和条目数。每项保存相对路径长度、数据长度、64 字节数据
SHA-256、路径和数据。只允许 `battery/battery.sav`、十个手动槽和三个自动槽;拒绝绝对路径、父目录、
SHA-256、路径和数据。只允许 `core.txt`、`battery/battery.sav`、十个手动槽和三个自动槽;拒绝绝对路径、父目录、
重复路径及任何未列入白名单的名称。单项上限 64 MiB,总数据上限 128 MiB,最多 16 项。包不包含 ROM、
会话标记或读档前保护副本。
0.9.16 起导出的包增加 `core.txt`,内容为 UTF-8 的 `内核 ID\n完整提交\n`,ID 为 `fceumm` 或
`nestopia`。导入时先与当前内核精确匹配,再校验全部存档条目,最后写入;标识本身不落入存档目录。
缺少标识的旧包仅允许在 FCEUmm 下导入,仍检查每个即时存档的内核元数据。新包不能导入尚不识别
`core.txt` 的旧版应用。封装魔数及版本仍为 v1,仅扩充条目白名单;不支持跨内核存档包迁移。
## 提交、备份与恢复
所有文件使用同一安全提交器:不可变快照在文件线程写入目标同目录的带版本临时文件,刷新到存储后
逐字节回读校验;已有目标先以同样流程生成 `.bak`,再原子替换正式文件并同步目录。提交器按 ROM/
目标串行,并拒绝不大于已接收版本的旧任务。替换前失败会清除临时文件,正式文件和有效备份不变。
读档只允许在暂停态的核心线程执行。反序列化前把当前核心状态和电池内存提交到 `recovery/`;失败先
读档只允许在暂停态的核心线程执行。反序列化前把当前核心状态和电池内存提交到 `recovery/`;内核明确
报告电池内存大小为零时只备份核心状态,有电池内存却无法取得完整快照时拒绝读档。失败先
恢复内存快照,回滚也失败则重新载入当前 ROM 并恢复保护的电池内存,无法确定核心状态时进入 Error,
不可继续运行。成功或回滚后均清空旧音视频并重建时钟基线。
+2 -2
View File
@@ -7,8 +7,8 @@
| 项目 | 锁定版本 | 本机位置/状态 | 说明 |
| --- | --- | --- | --- |
| PowerShell | 7.6.6 | 系统默认 `pwsh` | 仅用于运行构建入口;不影响 APK 字节码或原生 ABI。 |
| JDK | Temurin 17.0.17+10 | `E:\\Codex\\NESLite\\.toolchains\\jdk-17.0.17+10` | 供 Gradle/AGP 使用;系统默认 JDK 21 不用于本工程。 |
| PowerShell | 7.6.6 | 系统默认 `pwsh` | 用于运行打包.cmd;不影响 APK 字节码或原生 ABI。 |
| JDK | Temurin 17.0.17+10 | `E:\\Codex\\NESLite\\build\\toolchains\\jdk-17.0.17+10` | 供 Gradle/AGP 使用;系统默认 JDK 21 不用于本工程。 |
| Android SDK Platform | 36.1 | `C:\\Users\\shenw_o246oq4\\AppData\\Local\\Android\\Sdk\\platforms\\android-36.1` | `compileSdk = 36`,AGP 8.13 可支持 API 36.1。 |
| Android Build Tools | 36.1.0 | `C:\\Users\\shenw_o246oq4\\AppData\\Local\\Android\\Sdk\\build-tools\\36.1.0` | 由 AGP 选择,不固定使用系统 `37.0.0`。 |
| NDK | 28.2.13676358 (r28c) | `C:\\Users\\shenw_o246oq4\\AppData\\Local\\Android\\Sdk\\ndk\\28.2.13676358` | `app/build.gradle.kts` 中锁定。 |
+16 -2
View File
@@ -10,18 +10,20 @@
相同内容不会重复。可按名称/哈希搜索、收藏或从列表隐藏。隐藏不删除 ROM 和存档,重新导入相同
内容会恢复关联。
3. 点左上角“列表”图标,在两列或三列网格中点游戏名;加载完成后会自动开始。游戏名可完整换行显示,
长按游戏名可查看详情、收藏或从列表移除。连接外接手柄后仍可按设置选择是否显示
长按游戏名可查看详情、收藏、从列表移除或选择内核。连接外接手柄后仍可按设置选择是否显示
屏幕按键。多点触控支持方向与动作同时按住,滑出、取消、失焦或暂停都会释放输入。
4. 点左上角“设置”图标,在画面与声音、方向与触控、手柄与辅助三个卡片中调整选项,可切换 4:3/整数缩放、最近邻/线性过滤、音量、静音、软件连发和 RB 快进。进入
“手动设置手柄按键、摇杆与功能键”后,可启动逐项向导,也可单独点击动作修改或清除;按下物理键
或推动轴完成捕获,检查无误后点“保存”。冲突会要求确认,设置按设备特征在重启和重连后恢复。
“屏幕方向键与手柄摇杆”可切换四方向/八方向,并循环选择标准、大、特大方向键;两个位置滑块可
调整方向键的水平和垂直位置。默认八方向与大号,A、B 支持两根手指同时按住。
“原始整数缩放”按游戏原始宽高使用同一个整数倍率并居中,保留黑边;空间不足一倍时等比例缩小。
它与“保持 4:3”是两种显示方式,原始模式不强制铺满中央区域。0.9.18 已修正 Nestopia 在此模式下横向拉宽的问题。
5. 游戏中点右侧“暂停”或按手柄右摇杆进入暂停菜单;“重置”需要持续按住约 650 ms,滑出会取消。
“存档管理”显示十个手动槽、三个自动恢复点、
提交时间和缩略图。只有原生层确认安全落盘后才显示保存成功。
6. 存档包通过 Android 系统文件选择器导入导出,默认不含 ROM。导入前先加载对应游戏并暂停;哈希、
内核提交、配置、路径、大小或校验不匹配会被拒绝并保留现有有效存档。
内核名称/提交、配置、路径、大小或校验不匹配会被拒绝并保留现有有效存档。
7. 用“退出游戏”正常结束。上次进程异常终止时,再次加载相同游戏只列出校验有效的自动恢复点,
不会自动运行或覆盖当前进度;同一游戏和恢复点连续异常两次后会返回列表并阻止重复启动,只有
明确点“手动重试”才再次加载。
@@ -30,5 +32,17 @@
9. 切到后台、锁屏、来电/通知失去音频焦点时,应用会清输入、静音并请求暂停保存;回到前台后保持
暂停,由你手动继续。诊断导出会附带限额系统日志和各显示模式的短时运行样本,不包含 ROM。
## 选择 NES 内核
- 设置页底部的“默认 NES 内核”可选择 FCEUmm 或 Nestopia;初始默认仍为 FCEUmm。
- 单个游戏黑屏或无法加载时,在游戏列表长按名称,点“选择内核”,选择另一个内核并保存,然后重新
点开游戏。也可选“跟随默认”取消这个游戏的单独设置。选择会在重启应用后保留。
- 修改选择只影响下次打开游戏;正在运行或暂停的会话继续使用原内核。每个内核分别保存电池进度、
十个手动槽和三个自动恢复点;切回原内核可继续使用它原有的存档。存档管理标题显示当前内核。
- 0.9.17 对已确认内容的“龙珠英雄”(SHA-256 以 `f2fa5c9e40dc` 开头,精确匹配完整哈希)在两个
内核下自动使用 Dendy 制式,无需修改原 ROM 或再次更换内核。其他同名文件不自动套用此规则。
该文件已在桌面内核检查中进入中文启动及剧情选择页面,手机端仍待复核;如仍黑屏,请提供应用
版本、当前内核和导出的诊断信息。
荣耀 Magic8 截图已确认 Android 16、arm64-v8a、120 Hz 显示和 GameSir X5 Lite 枚举正常;新版三栏
布局、实际按键事件、系统手势、文件提供器、生命周期和完整游戏流程仍需在手机上复核。