3.9 KiB
NESLite 存档格式 v1
M5 固定两种二进制格式:即时存档 .nls(魔数 NESLST01)和独立存档包 .nsp(魔数
NESLPK01)。所有多字节整数均为无符号小端;时间为 Unix epoch 毫秒。格式解析先检查固定头、版本、
长度上限和精确总长,再分配载荷。
内核与目录
FCEUmm 延用 files/saves/<romHash>/,既有存档无需迁移;Nestopia 使用
files/saves/cores/nestopia/<romHash>/。下文的相对目录均位于当前内核、当前 ROM 的根目录下。
电池存档、即时存档、恢复副本和异常会话标记均隔离;不自动复制或转换另一内核的数据。
即时存档 .nls
固定头依次包含格式版本、ROM 哈希/内核名/内核提交/配置文本的长度,缩略图宽、高、行距和 像素格式,创建时间、状态长度、缩略图长度,以及 64 字节小写十六进制状态 SHA-256。随后依次保存 四段 UTF-8 元数据、核心状态和与该状态在同一帧边界取得的原始缩略图。
- 状态最大 64 MiB,缩略图最大 2 MiB,单段文本最大 16 KiB。
- 读档必须匹配完整 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、路径和数据。只允许 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/;内核明确
报告电池内存大小为零时只备份核心状态,有电池内存却无法取得完整快照时拒绝读档。失败先
恢复内存快照,回滚也失败则重新载入当前 ROM 并恢复保护的电池内存,无法确定核心状态时进入 Error,
不可继续运行。成功或回滚后均清空旧音视频并重建时钟基线。
电池内容变化后每 10 个模拟秒请求提交;自动恢复点每 60 个模拟秒请求,暂停和正常退出额外请求。
无变化的电池不重复写入,只有正式文件提交成功才报告保存成功。session.marker 区分活动/正常关闭;
再次启动发现活动标记时仅列出校验有效的恢复候选,不自动运行。