游戏叙事与剧情 / 系统课时

补齐保存与版本迁移

补齐保存与版本迁移

这一步把综合剧情链从“内存里能跑”补到“退出后还能正确继续”。我们会把剧情状态、一次性触发记录和存档版本一起落盘,并在读档时执行可验证的版本迁移,避免旧存档直接把新逻辑带进错误状态。

学习目标

  • 设计能同时保存剧情状态与重复触发保护信息的存档结构
  • 用显式迁移函数把旧版本存档逐级升级到当前版本
  • 通过原子写入与读档校验降低存档损坏和状态回退风险

存档必须保存哪些状态

剧情存档不能只保存“当前章节”。真正决定后续分支的,通常还有任务完成情况、关键标记、资源数量,以及已经执行过的一次性事件。若漏掉 triggeredEventIds,读档后同一奖励、对白或解锁逻辑就可能再次执行。

下面示例把当前格式定义为版本 2。版本 1 只保存 completedQuests,版本 2 将它迁移为带状态值的 quests,同时补上一套一次性事件记录。

python
import json
import os
import tempfile
from pathlib import Path

CURRENT_VERSION = 2

def migrate_v1_to_v2(data: dict) -> dict:
    completed = data.pop("completedQuests", [])
    data["quests"] = {quest_id: "completed" for quest_id in completed}
    data.setdefault("flags", {})
    data.setdefault("triggeredEventIds", [])
    data["schemaVersion"] = 2
    return data

MIGRATIONS = {
    1: migrate_v1_to_v2,
}

def migrate_to_current(data: dict) -> dict:
    version = data.get("schemaVersion", 1)
    if version > CURRENT_VERSION:
        raise ValueError(f"save version {version} is newer than supported {CURRENT_VERSION}")

    while version < CURRENT_VERSION:
        migration = MIGRATIONS.get(version)
        if migration is None:
            raise ValueError(f"missing migration from version {version}")
        data = migration(data)
        version = data["schemaVersion"]
    return data

def save_game(path: Path, state: dict) -> None:
    payload = dict(state)
    payload["schemaVersion"] = CURRENT_VERSION

    # 先写临时文件并刷盘,再替换正式存档,避免半写入文件被当成有效存档。
    with tempfile.NamedTemporaryFile(
        mode="w", encoding="utf-8", dir=path.parent, delete=False
    ) as fp:
        json.dump(payload, fp, ensure_ascii=False, indent=2)
        fp.flush()
        os.fsync(fp.fileno())
        temp_path = Path(fp.name)

    os.replace(temp_path, path)

def load_game(path: Path) -> dict:
    with path.open("r", encoding="utf-8") as fp:
        data = json.load(fp)
    return migrate_to_current(data)

def trigger_once(state: dict, event_id: str) -> bool:
    triggered = set(state["triggeredEventIds"])
    if event_id in triggered:
        return False

    triggered.add(event_id)
    state["triggeredEventIds"] = sorted(triggered)
    return True

def main() -> None:
    path = Path("savegame.json")

    # 模拟一个历史版本存档。
    path.write_text(
        json.dumps(
            {
                "schemaVersion": 1,
                "chapter": "forest",
                "completedQuests": ["find-key"],
            },
            ensure_ascii=False,
        ),
        encoding="utf-8",
    )

    state = load_game(path)
    print("version:", state["schemaVersion"])
    print("quest:", state["quests"]["find-key"])
    print("first trigger:", trigger_once(state, "reward-find-key"))
    print("second trigger:", trigger_once(state, "reward-find-key"))

    save_game(path, state)
    reloaded = load_game(path)
    print("reloaded events:", reloaded["triggeredEventIds"])

if __name__ == "__main__":
    main()

预期输出:

text
version: 2
quest: completed
first trigger: True
second trigger: False
reloaded events: ['reward-find-key']

第一次触发返回 True,说明事件可以执行;第二次返回 False,说明保护记录已经随状态生效。重新读档后仍能看到同一事件 ID,证明“防重复”不是只存在于当前进程内。

迁移要按版本逐级执行

不要在读档代码里堆一大段“如果缺字段就补字段”。这种写法无法区分字段是旧版本确实没有,还是存档已经损坏。更稳妥的方式是把每次格式变化写成 v1 -> v2、v2 -> v3 的单向迁移,并让加载器逐级执行。

旧存档逐级迁移到当前版本的流程

这样做的另一个好处是迁移函数可以单独测试。发布新版本前,只要准备几个真实旧版本样本,就能验证迁移后的任务、标记和触发记录是否符合预期。

写入时还要防止半个存档

直接打开正式文件并覆盖写入,一旦进程在中途退出,就可能留下截断 JSON。示例中的 save_game 先写同目录临时文件,刷入磁盘后再用 os.replace 替换正式文件;在常见桌面文件系统上,这比直接覆盖更适合作为最小原子写方案。

版本迁移后的验收点

一次完整验收至少要覆盖三件事:旧存档能升级到当前版本;升级后的分支状态与旧版本含义一致;已经执行过的一次性事件在重新加载后仍不会重复触发。只要这三项有一项失败,问题就不是“读档体验不好”,而是剧情状态已经失去可信来源。

版本号、迁移链和重复触发记录应当一起设计:版本号回答“这份数据按什么规则解释”,迁移链负责“把旧含义转换成新含义”,而 triggeredEventIds 保证副作用不会因为重启或读档被无意执行第二次。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

补齐保存与版本迁移

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通