游戏引擎 / 系统课时

保存玩家进度与设置

保存玩家进度与设置

玩家通关后,如果只更新内存里的关卡和分数,关闭游戏就会丢失成果。本课在 Cocos Creator 3.8 中建立包含关卡、分数与音乐开关的本地存档,完成写入、读取、校验和恢复,让下次启动能接续之前的进度。

学习目标

  • 设计只包含必要字段的版本化存档。
  • 使用 sys.localStorage 持久化并恢复 JSON 数据。
  • 处理首次启动、损坏存档和写入失败。

存档应该保存哪些数据

运行时的节点、组件和动画状态可以重新创建,不应直接序列化到存档。真正需要保存的是无法从配置重算的结果,例如已解锁关卡、累计分数,以及用户主动调整的音量或开关。

本例使用 version 标识数据格式,level 记录下次进入的关卡,score 保存累计分数,settings.musicEnabled 保存音乐开关。关卡从 1 开始,分数不允许为负;存档格式版本号不等于游戏安装版本号。

字段 类型 示例 用途
version number 1 识别存档格式
level number 2 恢复游戏关卡
score number 1200 恢复累计分数
settings.musicEnabled boolean false 恢复音乐开关

本地存档应视为可丢失、可篡改的数据。单机体验可以直接使用它,但联网排行榜、付费权益等权威数据不能只依赖客户端存储。

写入与恢复怎样衔接

保存时先从玩法状态提取普通数据对象,再用 JSON.stringify 转成字符串,通过 sys.localStorage.setItem 写入。恢复时使用 getItem 取得字符串、JSON.parse 还原对象,校验字段后才能把结果交给关卡和 UI 系统。

玩家进度写入与恢复的数据流

读取失败不等于正常得到零值:可能是首次启动没有存档,也可能是 JSON 已损坏,或者平台拒绝访问存储。程序至少要提供默认数据,并防止错误内容直接进入游戏逻辑。

编写可用的存档组件

在 assets/scripts/ProgressStoreDemo.ts 中编写以下组件,挂到当前场景的有效节点上。示例只在教学专用键不存在时建立样本,后续启动读取已有值,不会反复覆盖。

ts
import { _decorator, Component, sys } from 'cc';
const { ccclass } = _decorator;
const KEY = 'tutorial.progress.v1';

type ProgressV1 = {
  version: 1;
  level: number;
  score: number;
  settings: { musicEnabled: boolean };
};

function defaults(): ProgressV1 {
  return { version: 1, level: 1, score: 0, settings: { musicEnabled: true } };
}

function isRecord(v: unknown): v is Record<string, unknown> {
  return v !== null && typeof v === 'object' && !Array.isArray(v);
}

function validProgress(v: unknown): v is ProgressV1 {
  if (!isRecord(v) || !isRecord(v.settings)) return false;
  return v.version === 1 &&
    typeof v.level === 'number' && Number.isInteger(v.level) && v.level >= 1 &&
    typeof v.score === 'number' && Number.isFinite(v.score) && v.score >= 0 &&
    typeof v.settings.musicEnabled === 'boolean';
}

@ccclass('ProgressStoreDemo')
export class ProgressStoreDemo extends Component {
  start(): void {
    try {
      // 仅首次创建教学样本;真实游戏应在结算或设置改变时保存
      if (sys.localStorage.getItem(KEY) === null) {
        const sample: ProgressV1 = {
          version: 1, level: 2, score: 1200,
          settings: { musicEnabled: false }
        };
        if (!this.saveProgress(sample)) return;
      }
      const data = this.loadProgress();
      console.log(`关卡=${data.level} 分数=${data.score} 音乐=${data.settings.musicEnabled}`);
    } catch (error) {
      console.warn('本地存储不可用', error);
    }
  }

  saveProgress(data: ProgressV1): boolean {
    try {
      sys.localStorage.setItem(KEY, JSON.stringify(data));
      return true;
    } catch (error) {
      console.warn('保存失败', error);
      return false;
    }
  }

  loadProgress(): ProgressV1 {
    try {
      const raw = sys.localStorage.getItem(KEY);
      if (raw === null) return defaults();
      const parsed: unknown = JSON.parse(raw);
      // 不信任反序列化结果,坏档使用安全初始值
      if (!validProgress(parsed)) return defaults();
      return parsed;
    } catch (error) {
      console.warn('读取失败,使用初始数据', error);
      return defaults();
    }
  }
}

代码包含三个关键保护:存档不存在时采用初始结构,数据格式不符合约定时拒绝使用,存储访问或 JSON 解析异常时执行回退。写入方法返回布尔值,便于结算界面在失败时提醒玩家。

运行并验证持久化

  1. 将 ProgressStoreDemo 组件挂到场景节点,在 Cocos Creator 中启动预览。
  2. 打开控制台,确认首次运行创建并读取教学存档。
  3. 刷新预览页面,再次检查控制台,确认数据没有因为场景重建而丢失。
  4. 修改教学键对应的数据,分别验证合法值、无效 JSON 和字段缺失时的行为。

在空存档、且存储正常可写的环境首次预览,预期输出:

text
关卡=2 分数=1200 音乐=false

刷新预览后仍应读取同一结果。手动把该键的内容改成无效 JSON,再运行时会收到读取警告,并恢复到关卡 1、分数 0、音乐开启;这只是运行时回退,示例不会主动覆盖坏档。

把存档接入真实玩法

实际项目在进入游戏时加载一次,把 level 用于选择关卡,把音乐设置交给音频系统;关卡胜利、结算完成或玩家更改设置后,更新数据并调用保存方法。保存的是业务状态快照,而不是整个游戏场景。

建议在玩家完成一个有意义的操作时保存,而不要在每帧 update 中写盘。对于高频变化的分数,可以先更新内存,在检查点、结算或退出流程中持久化,同时考虑异常退出造成的损失范围。

预览、浏览器、原生安装包的本地存储彼此不一定共享,卸载应用或清理站点数据也可能使存档丢失。上线前至少检查首次安装、正常重启、数据损坏与写入失败四条路径;需要跨设备同步时应增加服务端存档。

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

目录与阅读设置

阅读设置

17

记录一个想法

保存玩家进度与设置

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

登录哪都通