游戏叙事与剧情 / 系统课时
补齐保存与版本迁移
补齐保存与版本迁移
这一步把综合剧情链从“内存里能跑”补到“退出后还能正确继续”。我们会把剧情状态、一次性触发记录和存档版本一起落盘,并在读档时执行可验证的版本迁移,避免旧存档直接把新逻辑带进错误状态。
学习目标
- 设计能同时保存剧情状态与重复触发保护信息的存档结构
- 用显式迁移函数把旧版本存档逐级升级到当前版本
- 通过原子写入与读档校验降低存档损坏和状态回退风险
存档必须保存哪些状态
剧情存档不能只保存“当前章节”。真正决定后续分支的,通常还有任务完成情况、关键标记、资源数量,以及已经执行过的一次性事件。若漏掉 triggeredEventIds,读档后同一奖励、对白或解锁逻辑就可能再次执行。
下面示例把当前格式定义为版本 2。版本 1 只保存 completedQuests,版本 2 将它迁移为带状态值的 quests,同时补上一套一次性事件记录。
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()预期输出:
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 保证副作用不会因为重启或读档被无意执行第二次。