v2.0.0 — 批量导入 / 批量删除 + README 精简

新增

批量导入

右上角 + 变成菜单，三种方式：

• 选择文件：可一次选多个，游戏 / BIOS / 金手指 / 存档混着选也行，App 自动归类
• 导入整个文件夹：递归扫描，适合一次拷一堆 ROM 进来（支持 .nes/.fds/.gb/.gbc/.gba/.zip/.7z/.cht/.srm/.sav）
• 从直链 / WebDAV 导入：粘贴链接，或连群晖 / 坚果云 / Nextcloud

批量导入时会显示「正在导入 3/27」进度，结束时按类别汇报：
几款游戏、装了哪些 BIOS、存了哪些金手指、归档了哪些存档。

批量删除

右上角 ⋯ → 批量选择 → 点卡片勾选（支持「全选」）→ 底部删除条。

• 二次确认，明确告诉你删几款
• 每款游戏的 ROM 文件 + 即时存档 + 金手指记录一起清掉
• 批量删除只写一次索引，不会卡

提示

批量操作条下方常驻一句说明（点卡片选择、删除范围、不可恢复）；
空库状态的说明改成「支持哪些格式 + 三种导入方式」清单，不再是干巴巴一句「点 + 导入」。

README

重写为使用说明为主：简介、平台表、安装、使用（导入 / 批量删除 / 游戏内 / 街机 / 手柄）、
版本号规则、构建、许可。构建细节与架构决策挪到 docs/ 下，不再堆在首页。

---

版本号规则（2.0.0 起）

主版本.次版本.修订号：

改动	变哪一位	例子
修 bug、文案、小调整	修订号	2.0.0 → 2.0.1
加功能、较大改动	次版本（修订归零）	2.0.1 → 2.1.0
重构、重大更新	主版本（后两位归零）	2.1.3 → 3.0.0

规则同时写进了 README.md、docs/maintenance.md 和 project.yml 的注释，避免下次又靠记忆。

安装

未签名 ipa，用 Sideloadly / AltStore / 自签证书签名；要求 iOS / iPadOS 17.0+。

完整对比：v1.10...v2.0.0

v1.10 — 全局提示 + 导入自动识别

新增

1. 提示铺满：每个开关都自己解释自己

设置页的每一行控件下面都有一句话说明（快进倍率为什么卡、自动存档什么时候写、摇杆死区多少……），
分组结尾再给一段整体解释；新增「内置资源」分组，一眼看清哪些随包提供。

危险操作全部二次确认：软复位、退出游戏、移除游戏（会连 ROM 与存档一起删）、
恢复默认布局、恢复默认键位——之前点一下就没了。

2. 一键导入自动识别

你选的文件	App 怎么处理
.nes / .fds / .gb / .gbc / .gba	入库并按魔数+扩展名识别平台
.zip	含主机 ROM → 解压分类；街机 romset / 整合包 → 拆包入库
.7z	街机 romset 整包
neogeo.zip / pgm.zip	识别为 BIOS，自动装进 System/
.cht	存进金手指库，游戏内「已导入的金手指文件」一键套用（街机也能用）
.srm / .sav	按同名 ROM 归档到 Saves/<游戏ID>/，兼容 x-1.nes 重名副本

导入结果按类别汇报：几款游戏、装了哪些 BIOS、存了哪些金手指、归档了哪些存档。

关于「内置 FBNeo / BIOS / 内核」

• 四个内核全部内置：fceumm、SameBoy 1.0.4、mGBA 0.10.5、FBNeo 都在 ipa 里，装上就能用，不需要联网下载。
• BIOS 不能内置：neogeo.zip / pgm.zip 里是 IGS / SNK 的版权数据，打包分发属于侵权，
  这和「不内置游戏 ROM」是同一条线。它们本来就躺在你下载的 MAME/FBNeo romset 里，
  拿到后用同一个「+」导入即可，App 会自动装到 System/。
  缺 BIOS 时内核会自己画一张清单页，告诉你差哪几个文件（比如 pgm_p02s.u20）。

安装

未签名 ipa，用 Sideloadly / AltStore / 自签证书签名；要求 iOS / iPadOS 17.0+。

完整对比：v1.9...v1.10

v1.9 — 街机黑屏修复 + 手柄方向 + 远程导入

修复

1. 手柄方向「按一下动一下」

十字键和摇杆共用同一张方向状态表：摇杆每帧回调（停在死区内 = 四个方向全 false），
立刻把十字键按住的方向清掉，所以按住不动也走不动。
现在两个输入源分开记录、取「或」合并（DirectionInputMerger），并补了 4 项单测，
其中一条直接复现旧行为。设置里仍可选 十字键 / 左摇杆 / 两者。

2. 街机导入后打不开（用真实包 kovsh_v13.zip 定位到两个原因）

• 壳包：包里是 kovsh/kovsh.zip + ini + 说明文件。FBNeo 按 romset 文件名认驱动名，
  喂外层壳包必然「no driver」。现在导入会自动拆包（BIOS 装 System/、内层 romset 逐个入库），
  v1.8 已入库的壳包也会在启动扫描时自愈。
• 黑屏根因：FramePipeline 上限写死 512×512，PGM 实际输出 640×480 —— 每一帧都被静默丢弃。
  上限提到 1024×1024，超限改为打日志（静默丢帧这种坑不该再让人猜第二次）。
• 顺带修：statusMessage（加载失败 / 缺 BIOS / 已载入进度）从来没显示过，现在是可点掉的提示条。

实测这台模拟器上：Romset name: kovsh → 640×480 出帧 60fps → FBNeo 自绘错误页
「missing files for THIS VERSION：pgm_t01s.rom / pgm_m01s.rom / pgm_p01s.u20 / pgm_p02s.u20 / ddp3_bios.u37 / bios.u42」。

这个包还缺 PGM BIOS（pgm.zip）。BIOS 属于厂商版权内容，App 不内置也不会内置；
把 pgm.zip 用游戏库「+」导入（自动装到 System/）即可。

3. 远程导入（直链 / WebDAV）

游戏库右上角 🌐：

• 直链：粘贴任意 http(s) 地址，带进度下载后走同一套导入流程
• WebDAV：群晖 / 坚果云 / Nextcloud / InfiniCLOUD 等，可浏览目录、下载后导入
• 密码存钥匙串，服务器与用户名存 UserDefaults；局域网 http 已放行（ATS NSAllowsLocalNetworking）

实测：本地 HTTP 服务器下载 21,158,101 字节 → 导入成功并拆出 kovsh.zip；
WebDAV 列目录 3 项（含中文文件名解码）。

未做（说明）

没有集成 ROM 站点的自动搜索下载。 两个原因：

1. 这些站点分发的是 IGS / SNK 等仍在维权的街机 ROM，做成「搜索即下载」等于把 App 变成分发渠道；
2. store.hzqiangzhi.cn 目前被 Cloudflare 判定为 Suspected Phishing（403 拦截页），
   给 App 接一个自动下载通道到这种域名，风险大于收益。

替代方案：远程导入的「直链」可以下载你自己确认过的任何文件；站点上手动拿到链接后粘贴即可。

安装

未签名 ipa，用 Sideloadly / AltStore / 自签证书签名；要求 iOS / iPadOS 17.0+。

完整对比：v1.8...v1.9

v1.8 — App 图标 + 手柄连接自动隐藏虚拟按键

新增

• App 图标：终于有脸了。米白底 + 红白机手柄正面（朱红机身 / 米白十字键 / 并排双键），
  1024×1024 无 alpha，由 Tools/gen_app_icon.py 程序化生成（改脚本常量即可换配色，见 docs/maintenance.md）。
• 连接手柄自动隐藏虚拟按键：检测到蓝牙手柄连接就不再渲染屏幕按键，画面完全不被遮挡；
  HUD 右上角图标可临时调回（hand.tap），手柄断开自动恢复。

设置

• 开关位置：设置 → 蓝牙手柄 → 「连接手柄时隐藏虚拟按键」；游戏内菜单 → 显示与操作 同款开关。
• 默认开启。只是不想挡画面时用 HUD 图标临时调回，不用改设置。

调试

• -MRFakeController / -MRNoController 可强制两种连接状态（模拟器会把宿主机手柄透传进来，
  没有这对参数没法做对照验证）。

实测

• connected=1 → hidden=1：画面无按键，HUD 出现 hand.tap 图标
• connected=0 → hidden=0：按键正常显示，位置与间距无变化
• 桌面图标渲染正常（docs/screenshots/17-app-icon.png）

安装

未签名 ipa，用 Sideloadly / AltStore / 自签证书签名后安装；要求 iOS / iPadOS 17.0+。

完整对比：v1.7...v1.8

v1.7 — 街机支持（CPS/Neo Geo/PGM）+ 六项修复

新增

• 街机支持（FBNeo）：CPS1 / CPS2 / Neo Geo / PGM —— 三国战纪、西游释厄传、拳皇等。
  导入整套 romset（.zip/.7z，不要解压）；BIOS neogeo.zip / pgm.zip 用同一个「+」导入，会自动装到 System/。
  街机布局为十字键 + A/B/C/D（2×2）+ SELECT/START。首次构建时自动从上游浅克隆并编译 FBNeo（约 40 分钟）。
• 金手指社区查找：游戏内菜单 → 金手指管理 → 「从社区金手指库查找」。内置 FC/GB/GBC/GBA 共 5231 条游戏索引，
  搜索完全离线，只有选中的代码才联网下载（libretro-database）。
• 快进 16×：倍率补齐 2/3/4/6/8/16×，快进时音频按倍率抽取，不静音也不爆音。
• 进菜单/设置自动暂停：默认开启，关闭菜单后恢复到打开前的运行状态（不会唤醒你手动暂停的游戏）。
• 手柄方向输入可选：十字键 / 左摇杆 / 两者（死区 45%）；键位映射界面保持不变。

修复

• 「每次重启每个 ROM 多出一个文件已损坏条目」
  根因三层：旧索引路径带 ROMs/ 前缀导致校验失败 → 扫描只打标记从不清理 → 删除只删索引不删文件。
  现在启动时自动归一化路径、删除失效条目、合并重复；删除游戏会同时清理文件/存档/金手指。
• 重复导入同一 ROM 不再生成 x-1.nes 副本（按「文件名 + 字节数 + 系统」去重）
• 兼容缺字段的旧 index.json（早期版本写出的索引不会再导致整个库被清空重建）

自测

• ./Tools/run_romlib_test.sh：28 项断言全通过（真实 ROM 识别、导入去重、脏索引自愈两次幂等、街机 zip 入库、金手指解析）
• 模拟器实测：脏索引 4 条 → 重启后 2 条且无损坏标记；游戏 60fps 渲染；菜单打开即暂停

安装

本附件为未签名 ipa，需要自行签名安装：

1. 用 Sideloadly / AltStore / 自签证书 对 MiniRetro-1.7-8-unsigned.ipa 签名
2. 免费 Apple ID 的签名 7 天过期，需重新签名
3. 若签名工具拒绝未签名 ipa，请从源码构建：./Tools/build.sh --adhoc

要求 iOS / iPadOS 17.0+，arm64（真机）。

注意

• 仓库与附件不含任何 ROM / BIOS，请使用你合法拥有的游戏备份
• 街机功能只验证到内核编译与集成（无 romset/BIOS 无法实测运行），有问题请附日志提 issue
• FBNeo 内核禁止商业使用，详见 THIRD-PARTY-NOTICES.md

完整对比：v1.6...v1.7