游戏引擎 / 系统课时
保存玩家进度与设置
保存玩家进度与设置
玩家通关后,如果只更新内存里的关卡和分数,关闭游戏就会丢失成果。本课在 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 中编写以下组件,挂到当前场景的有效节点上。示例只在教学专用键不存在时建立样本,后续启动读取已有值,不会反复覆盖。
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 解析异常时执行回退。写入方法返回布尔值,便于结算界面在失败时提醒玩家。
运行并验证持久化
- 将
ProgressStoreDemo组件挂到场景节点,在 Cocos Creator 中启动预览。 - 打开控制台,确认首次运行创建并读取教学存档。
- 刷新预览页面,再次检查控制台,确认数据没有因为场景重建而丢失。
- 修改教学键对应的数据,分别验证合法值、无效 JSON 和字段缺失时的行为。
在空存档、且存储正常可写的环境首次预览,预期输出:
关卡=2 分数=1200 音乐=false刷新预览后仍应读取同一结果。手动把该键的内容改成无效 JSON,再运行时会收到读取警告,并恢复到关卡 1、分数 0、音乐开启;这只是运行时回退,示例不会主动覆盖坏档。
把存档接入真实玩法
实际项目在进入游戏时加载一次,把 level 用于选择关卡,把音乐设置交给音频系统;关卡胜利、结算完成或玩家更改设置后,更新数据并调用保存方法。保存的是业务状态快照,而不是整个游戏场景。
建议在玩家完成一个有意义的操作时保存,而不要在每帧 update 中写盘。对于高频变化的分数,可以先更新内存,在检查点、结算或退出流程中持久化,同时考虑异常退出造成的损失范围。
预览、浏览器、原生安装包的本地存储彼此不一定共享,卸载应用或清理站点数据也可能使存档丢失。上线前至少检查首次安装、正常重启、数据损坏与写入失败四条路径;需要跨设备同步时应增加服务端存档。