Defold 游戏存档与序列化：数据建模、加密校验与版本迁移

游戏运行时：玩家对象在内存（关卡、金币、技能、背包）
存档：把这些「关键状态」落盘 → 下次启动恢复

- 存「角色到了第 3 关」，不存「角色像素坐标 123,456」
- 存「拥有剑与护甲」，不存「当前装备渲染对象」
- 推导成本高的数据才存，可推导的不存

-- 存档结构（示意）
local save = {
    version = 5,                    -- 存档格式版本
    meta = {                        -- 元信息
        created = 1700000000,
        updated = 1700001000,
    },
    progress = {                    -- 进度层
        level = 3,
        checkpoints = {2, 5},
        unlocked = {"map_1", "map_2"},
    },
    player = {                      -- 角色层
        gold = 1250,
        level = 8,
        skills = {"sword_master", "dash"},
        inventory = {items = {...}},
    },
    settings = {                    -- 设置层
        volume = 0.8,
        quality = "high",
        language = "zh",
    },
}

- 各层独立演进（settings 层升级不影响 progress 层）
- 部分层可不同步（云存档只同步进度，不同步设置）
- 校验/加密按层区分（设置可明文、进度要校验）

- 用「稳定的键名」：改名 = 破坏老存档（用 version 迁移兜底）
- 数值用整数/字符串（浮点精度跨平台不稳）
- 布尔/枚举用固定字符串（别用数字魔法值）
- 大型数据（地图/自定义）→ 单独文件，不塞主存档

-- JSON（需要第三方库）
local json = require("modules.json")
local str = json.encode(save_data)

-- msgpack（Lua 生态成熟）
local msgpack = require("modules.msgpack")
local blob = msgpack.pack(save_data)

-- 注意：函数/协程/userdata 不可序列化
-- 存档里只放「纯数据」（table/字符串/数值/布尔）

- 存档小（<几十 KB）→ JSON 足够，调试最爽
- 存档大/频繁读写 → msgpack（体积速度双赢）
- 跨端（云端/网页端）→ 优先 JSON（通用解析）
- 存档要「可手工编辑」？→ 人类可读格式

- table 键必须是「字符串/数值」（否则序列化失败）
- 循环引用 → 序列化崩溃（存档数据别建环）
- 浮点数跨平台精度 → 存整数/字符串
- 数值索引的数组 vs 哈希表 → 序列化库要能区分

-- 写存档（data 是二进制字符串）
sys.save("/save/slot1.data", data)

-- 读存档
local ok, data = sys.load("/save/slot1.data")
if ok then
    local save = msgpack.unpack(data)
end

-- 删除
os.remove("/save/slot1.data")     -- 或 sys 提供的方法

- "/save/..." 是 Defold 的「用户数据」虚拟路径
  → 自动映射到各平台的安全目录
- 目录不存在要自己创建（io.mkdir 或 ensure）
- 路径规范：/save/slot1.data、/save/settings.json

-- 槽位管理
local SLOTS = {"/save/slot1.data", "/save/slot2.data", "/save/slot3.data"}

function write_slot(self, idx, data)
    sys.save(SLOTS[idx], data)
end

- 原子写入：先写临时文件再改名（防中途崩溃坏档）
- 写盘完成确认（sys.save 同步/异步差异）
- 空间不足/写入失败 → 捕获并提示玩家
- 别在「游戏帧中」频繁大写入（卡顿）

-- HMAC 校验：存档数据 + 秘密密钥 → 摘要
local hmac = require("modules.hmac")
local key = "app_secret_key"          -- 藏于二进制（对抗玩家）
local data = msgpack.pack(save_body)

-- 写入
local checksum = hmac.hmac_sha256(key, data)
sys.save("/save/slot1.data", data .. checksum)

-- 读取
local loaded = sys.load("/save/slot1.data")
local body, sum = string.sub(loaded, 1, -33), string.sub(loaded, -32)
if hmac.hmac_sha256(key, body) ~= sum then
    -- 存档被篡改或损坏 → 提示/丢弃/救档
else
    local save = msgpack.unpack(body)
end

- 完整性校验（HMAC）：防篡改、防损坏 → 必须
- 加密（AES）：防「读取明文」→ 一般存档不需要
  （玩家总能用内存工具读出值，加密只防「文本编辑」）
- 真正要防的是「数值被改」→ 校验 > 加密

- 密钥不硬编码成明文（拆散/混淆）
- 服务器权威存档（数值只在服务端可信）
- 校验「数值合法性」（金币非负、等级在范围内）

-- 迁移管线：把老版本存档升级到当前版本
local migrations = {
    -- [1] → [2]：金币字段改名 gold → currency
    function(save)
        save.currency = save.gold
        save.gold = nil
        return save
    end,
    -- [2] → [3]：新增技能树（默认值）
    function(save)
        save.skills = save.skills or {}
        return save
    end,
}

function load_save(raw)
    local save = msgpack.unpack(raw)
    local v = save.version or 1
    for i = v, #migrations do
        save = migrations[i](save)      -- 逐步升级
    end
    save.version = #migrations          -- 打上新版本
    return save
end

- 迁移「只增不改」：老字段保留读取兼容，新字段给默认值
- 逐版本顺序迁移（不跳步）→ 逻辑清晰
- 迁移失败 → 保留原始存档（可回滚/救档）
- 测试矩阵：每个历史版本 → 迁移 → 当前版本 都能跑

- 损坏存档：尝试恢复部分数据（能救的救）
- 迁移失败：保留原档 + 提示「已备份」
- 备份方案：每次覆盖前存一份 .bak
- 坏档检测到 → 别直接删，先备份再处理

自动存档点：
  - 关卡过关 / 检查点到达
  - 关键事件（Boss 战前、重大选择）
  - 应用切后台 / 退出时
  - 定时（每 N 分钟）
  
不要每帧存：频繁写盘卡顿 + 磨损存储

- 检查点：轻量「重生点」数据（关卡内位置）
- 全量存档：完整进度（跨关卡）
- 组合：检查点快速恢复 + 全量存档定期落盘

-- 自动存档（事件触发）
function on_checkpoint(self, data)
    self:write_slot(data)          -- 检查点即时存
end

function on_message(self, message_id, ...)
    if message_id == hash("app_pause") then   -- 切后台
        self:write_slot()                      -- 兜底存档
    end
end

- 存盘点图标/音效反馈（玩家知道「存过了」）
- 自动存档不阻塞（异步/后台写）
- 「死亡惩罚」平衡：检查点太远 = 挫败、太近 = 无压力

- 平台云存档：iCloud / Google Play Games（平台内建）
- 自建后端：服务器权威存档 + 客户端读写
- 混合：本地为主 + 云端同步（离线可用）

冲突场景：设备 A、B 各玩一段 → 同步时谁的档有效？

策略：
  1. 时间戳胜出：最新修改者覆盖（简单，但丢进度）
  2. 分字段合并：进度层取最新、设置层按设备（复杂）
  3. 服务器权威 + 版本号：冲突则玩家选（体验折衷）

- 本地「缓存 + 后台同步」：弱网可玩
- 同步前先「版本戳」比较，避免回退
- 同步后校验（HMAC）防串档
- 首次登录关联：老档上传 / 云端档下载 的选择 UI

- 云端多槽位 → 每槽独立版本戳
- 槽位上限（如 3 个）→ 超出提示清理
- 云端删除要二次确认（不可逆）