save
game/save 将游戏存档槽以带版本号的 JSON 信封存储在 core.Storage 或本地目录(如 cx.DataDir())中,支持逐版本数据结构迁移与原子备份恢复。
import "github.com/nsgo-dev/game/packages/game/save"
选择存储方式
根据目标平台选择对应的 Store:
NewStorageStore(cx.Storage(), prefix, opts...):将每个槽位存入core.Storage的<prefix>.slot.<slot>与<prefix>.bak.<slot>键下,兼容包括 Web 在内的所有平台。NewFileStore(cx.DataDir(), opts...):将每个槽位保存为目录下的<slot>.json与<slot>.json.bak,适合桌面端和移动端的较大存档(Web 端cx.DataDir()为空,应改用NewStorageStore)。NewStore(backend, opts...):接收任意自定义Backend实现(例如云存档)。
type Progress struct {
Level int `json:"level"`
Coins int `json:"coins"`
Name string `json:"name"`
}
store := save.NewStorageStore(cx.Storage(), "mygame", save.WithVersion(1))
if err := store.Save("slot1", Progress{Level: 3, Coins: 120, Name: "Hero"}); err != nil {
return err
}
var p Progress
if err := store.Load("slot1", &p); errors.Is(err, save.ErrNotFound) {
p = Progress{Level: 1}
} else if err != nil {
return err
}
使用 store.Exists(slot)、store.Slots()(返回有序槽位名列表)和 store.Delete(slot)(同时删除主存档与备份,删除不存在的槽位返回 nil)管理存档槽。
版本信封与数据迁移
每个槽位都以 {"version": N, "data": ...} 信封格式写入。存档结构升级时,提高 WithVersion(N) 并通过 WithMigration、WithMigrations 或 RegisterMigration 注册逐级迁移函数(v -> v+1):
store := save.NewFileStore(cx.DataDir(),
save.WithVersion(2),
save.WithMigration(1, func(raw json.RawMessage) (json.RawMessage, error) {
var v1 struct {
Level int `json:"level"`
Gold int `json:"gold"`
}
if err := json.Unmarshal(raw, &v1); err != nil {
return nil, err
}
return json.Marshal(Progress{
Level: v1.Level,
Coins: v1.Gold, // 字段重命名
Name: "Adventurer",
})
}),
)
Load 读取到旧版本存档时,会按 1 -> 2 -> 3 ... 逐步迁移 JSON,再反序列化到 dst。
可用 errors.Is 判断的哨兵错误:
| 错误 | 含义 |
|---|---|
ErrNotFound |
指定槽位既无主存档也无备份。 |
ErrInvalidSlot |
槽位名为空或包含不安全的路径/键字符。 |
ErrFutureVersion |
存档版本号高于当前 Store.Version。 |
ErrMissingMigration |
缺少升级到 Store.Version 所需的迁移步骤。 |
ErrCorrupt |
存储内容不是合法的存档信封。 |
原子写入与备份恢复
Save 会先完成 JSON 编码再接触底层存储,因此序列化失败不会破坏原有存档。在替换主存档之前,两种内置后端都会先保留上一次有效存档作为备份:
FileBackend:写入同目录临时文件并同步落盘,将原有<slot>.json保存到<slot>.json.bak,再原子重命名临时文件。StorageBackend:先写入备份键再更新主键,即便遇到*core.StorageFullError也能保住上一次完好存档。
调用 Load 时,若主存档缺失、不可读或损坏,会自动回退到备份恢复。但若主存档本身是合法信封且版本号高于 Store.Version,则会直接返回 ErrFutureVersion,不会静默回退到旧版本备份。