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

状态结构改了旧档怎么办

状态结构改了旧档怎么办

剧情系统一旦上线,玩家手里的存档就会落后于当前代码。解决重点不是“让旧 JSON 勉强读进来”,而是明确存档版本、迁移顺序和缺省规则,把任意受支持的旧结构稳定转换成当前结构,再交给剧情逻辑使用。

学习目标

  • 为存档设计可判定的版本号与当前结构
  • 用连续迁移函数把旧档升级到最新版本
  • 为新增字段设置安全默认值,并验证迁移结果

先把版本号放进存档

版本号应该描述“存档结构版本”,不要直接复用游戏版本号。游戏可能只改了 UI,却没有改存档;也可能一次更新连续修改多次状态结构。把两者绑定会让迁移条件越来越难判断。

下面以一个剧情状态为例。版本 1 只有金币和章节;版本 2 新增 flags;版本 3 把单个章节编号改成更明确的 progress.chapter。下面是结构定义片段,用于明确各版本的数据形状。

ts
type SaveV1 = {
  saveVersion: 1;
  coins: number;
  chapter: number;
};

type SaveV2 = {
  saveVersion: 2;
  coins: number;
  chapter: number;
  flags: Record<string, boolean>;
};

type SaveV3 = {
  saveVersion: 3;
  coins: number;
  flags: Record<string, boolean>;
  progress: {
    chapter: number;
  };
};

这里的关键是:每种历史结构都能被明确识别。不要通过“有没有某个字段”来猜版本,因为字段可能缺失、被手工修改,或者在多个版本中都存在。

迁移要按版本逐级执行

不要直接写大量 if (oldVersion < 7) 修改同一个对象。更稳妥的做法是让每次迁移只负责相邻版本,这样每个函数的输入、输出都清晰,测试也容易覆盖。

存档版本逐级迁移流程

下面的示例可以直接运行,演示如何把 V1 存档升级到 V3。

ts
type SaveV1 = {
  saveVersion: 1;
  coins: number;
  chapter: number;
};

type SaveV2 = {
  saveVersion: 2;
  coins: number;
  chapter: number;
  flags: Record<string, boolean>;
};

type SaveV3 = {
  saveVersion: 3;
  coins: number;
  flags: Record<string, boolean>;
  progress: {
    chapter: number;
  };
};

type AnySave = SaveV1 | SaveV2 | SaveV3;

function migrateV1ToV2(save: SaveV1): SaveV2 {
  return {
    saveVersion: 2,
    coins: save.coins,
    chapter: save.chapter,
    // 新字段必须给出不会误触发剧情的安全默认值
    flags: {}
  };
}

function migrateV2ToV3(save: SaveV2): SaveV3 {
  return {
    saveVersion: 3,
    coins: save.coins,
    flags: save.flags,
    progress: {
      chapter: save.chapter
    }
  };
}

function migrateToLatest(save: AnySave): SaveV3 {
  let current: AnySave = save;

  while (current.saveVersion < 3) {
    if (current.saveVersion === 1) {
      current = migrateV1ToV2(current);
      continue;
    }
    if (current.saveVersion === 2) {
      current = migrateV2ToV3(current);
      continue;
    }
    throw new Error(`Unsupported save version: ${String(current.saveVersion)}`);
  }

  return current as SaveV3;
}

const oldSave: SaveV1 = {
  saveVersion: 1,
  coins: 120,
  chapter: 4
};

console.log(JSON.stringify(migrateToLatest(oldSave)));

预期输出

text
{"saveVersion":3,"coins":120,"flags":{},"progress":{"chapter":4}}

如果实际项目还支持更老版本,只要继续保留对应的相邻迁移函数即可。删除迁移函数前,要先确认产品已经明确停止支持那一代存档。

默认值必须保证剧情安全

新增字段最容易埋坑。比如新增 bossDefeated 时,如果默认值错误地设为 true,旧档一加载就可能跳过整段 Boss 剧情。默认值应该遵循“没有证据就不推进”的原则。

对于集合类字段,通常优先使用空集合;对于是否完成的布尔状态,通常优先 false;对于进度值,则需要根据旧字段推导,而不是机械清零。能从旧数据恢复的信息应迁移,无法恢复的信息才使用默认值。

加载完成后再做结构校验

迁移结束不等于数据一定可用。存档可能被截断、手工修改,或历史版本本身就写入过非法值,因此当前版本仍应做一次最小校验。下面是片段示例,依赖上一段已经定义的 SaveV3 与 migrateToLatest。

ts
function validateSave(save: SaveV3): void {
  if (!Number.isInteger(save.coins) || save.coins < 0) {
    throw new Error("Invalid coins");
  }
  if (!Number.isInteger(save.progress.chapter) || save.progress.chapter < 1) {
    throw new Error("Invalid chapter");
  }
}

const migrated = migrateToLatest({
  saveVersion: 1,
  coins: 120,
  chapter: 4
});

validateSave(migrated);
console.log("save ok");

预期输出

text
save ok

生产环境中还应为失败保留原始存档副本,并记录“原版本、目标版本、失败步骤”,方便恢复和定位。只要坚持“识别版本 → 逐级迁移 → 补安全默认值 → 校验当前结构”这条链路,状态结构升级就不会把旧档变成一次性炸弹。

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

目录与阅读设置

阅读设置

17

记录一个想法

状态结构改了旧档怎么办

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

登录哪都通