Files

53 lines
3.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 区分活动/正常关闭;
再次启动发现活动标记时仅列出校验有效的恢复候选,不自动运行。