# NESLite 存档格式 v1 M5 固定两种二进制格式:即时存档 `.nls`(魔数 `NESLST01`)和独立存档包 `.nsp`(魔数 `NESLPK01`)。所有多字节整数均为无符号小端;时间为 Unix epoch 毫秒。格式解析先检查固定头、版本、 长度上限和精确总长,再分配载荷。 ## 内核与目录 FCEUmm 延用 `files/saves//`,既有存档无需迁移;Nestopia 使用 `files/saves/cores/nestopia//`。下文的相对目录均位于当前内核、当前 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` 区分活动/正常关闭; 再次启动发现活动标记时仅列出校验有效的恢复候选,不自动运行。