Files
NESLite/docs/save-format.md
T

39 lines
2.7 KiB
Markdown

# NESLite 存档格式 v1
M5 固定两种二进制格式:即时存档 `.nls`(魔数 `NESLST01`)和独立存档包 `.nsp`(魔数
`NESLPK01`)。所有多字节整数均为无符号小端;时间为 Unix epoch 毫秒。格式解析先检查固定头、版本、
长度上限和精确总长,再分配载荷。
## 即时存档 `.nls`
固定头依次包含格式版本、ROM 哈希/内核名/内核提交/配置文本的长度,缩略图宽、高、行距和
像素格式,创建时间、状态长度、缩略图长度,以及 64 字节小写十六进制状态 SHA-256。随后依次保存
四段 UTF-8 元数据、核心状态和与该状态在同一帧边界取得的原始缩略图。
- 状态最大 64 MiB,缩略图最大 2 MiB,单段文本最大 16 KiB。
- 读档必须匹配完整 ROM SHA-256、`FCEUmm`、固定内核提交和当前核心配置;不同内核提交默认拒绝,
原文件不改名、不删除。
- 手动槽为 `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`、十个手动槽和三个自动槽;拒绝绝对路径、父目录、
重复路径及任何未列入白名单的名称。单项上限 64 MiB,总数据上限 128 MiB,最多 16 项。包不包含 ROM、
会话标记或读档前保护副本。
## 提交、备份与恢复
所有文件使用同一安全提交器:不可变快照在文件线程写入目标同目录的带版本临时文件,刷新到存储后
逐字节回读校验;已有目标先以同样流程生成 `.bak`,再原子替换正式文件并同步目录。提交器按 ROM/
目标串行,并拒绝不大于已接收版本的旧任务。替换前失败会清除临时文件,正式文件和有效备份不变。
读档只允许在暂停态的核心线程执行。反序列化前把当前核心状态和电池内存提交到 `recovery/`;失败先
恢复内存快照,回滚也失败则重新载入当前 ROM 并恢复保护的电池内存,无法确定核心状态时进入 Error,
不可继续运行。成功或回滚后均清空旧音视频并重建时钟基线。
电池内容变化后每 10 个模拟秒请求提交;自动恢复点每 60 个模拟秒请求,暂停和正常退出额外请求。
无变化的电池不重复写入,只有正式文件提交成功才报告保存成功。`session.marker` 区分活动/正常关闭;
再次启动发现活动标记时仅列出校验有效的恢复候选,不自动运行。