游戏引擎 / 系统课时
保存玩家进度与设置
保存玩家进度与设置
玩家离开游戏后,需要保留金币、出生位置和音量设置;直接保存场景组件既难恢复,也容易在更新后失效。本课用轻量 JSON 存档建立运行状态的快照,加入版本检查、缺失字段默认值与错误处理,并在场景对象准备好后恢复状态。
学习目标
- 设计只包含可持久化数值的存档数据结构。
- 使用
JsonUtility和persistentDataPath完成保存、读取与验证。 - 处理旧版本、缺失字段和加载后的状态恢复顺序。
确定哪些数据应该保存
存档不是对整个场景拍照,而是记录重建游戏所必需的最小状态。本例保存三项:玩家金币、世界坐标和主音量。version 说明这些字段属于哪版存档协议,后续增加设置或改变数据含义时才有依据迁移。
| 字段 | 用途 | 恢复到哪里 |
|---|---|---|
coins |
非负整数进度 | 游戏状态字段 |
playerPosition |
单场景内的玩家位置 | 玩家 Transform |
masterVolume |
0~1 的音量设置 | AudioListener.volume |
version |
数据协议版本 | 加载兼容性判断 |
不要直接序列化 GameObject、场景实例引用或临时 UI 状态。JsonUtility 主要处理 Unity 序列化规则支持的字段,不适合作为任意字典或复杂对象图的通用存储器。小型偏好也可使用 PlayerPrefs,但本例将进度和设置放在一个可检查、可迁移的文件中。

实现存取、兼容与异常处理
新建 GameSaveController.cs。其中 SaveData 是纯数据类,不能保存组件引用;GameSaveController 是挂在场景对象上的读写入口。示例采用单场景玩家,并提供 Inspector 右键菜单以便直接测试。
using System;
using System.IO;
using UnityEngine;
[Serializable]
public sealed class SaveData
{
public int version = 2;
public int coins;
public Vector3 playerPosition;
public float masterVolume = 1f;
}
public sealed class GameSaveController : MonoBehaviour
{
[SerializeField] private Transform player;
[SerializeField, Min(0)] private int coins;
[SerializeField, Range(0f, 1f)] private float masterVolume = 1f;
private string FilePath =>
Path.Combine(Application.persistentDataPath, "save.json");
[ContextMenu("Save")]
public void Save()
{
if (player == null)
{
Debug.LogError("未指定玩家");
return;
}
var data = new SaveData
{
version = 2,
coins = Mathf.Max(0, coins),
playerPosition = player.position,
masterVolume = Mathf.Clamp01(masterVolume)
};
try
{
Directory.CreateDirectory(Application.persistentDataPath);
File.WriteAllText(FilePath, JsonUtility.ToJson(data, true));
Debug.Log("保存成功");
}
catch (Exception e)
{
Debug.LogError("保存失败:" + e.Message);
}
}
[ContextMenu("Load")]
public void Load()
{
if (player == null)
{
Debug.LogError("未指定玩家");
return;
}
if (!File.Exists(FilePath))
{
Debug.Log("无存档,沿用默认状态");
return;
}
try
{
// 预填默认值:JSON缺字段时保留当前场景值。
var data = new SaveData
{
version = 1,
coins = 0,
playerPosition = player.position,
masterVolume = masterVolume
};
JsonUtility.FromJsonOverwrite(File.ReadAllText(FilePath), data);
if (data.version < 1 || data.version > 2)
{
Debug.LogWarning("不支持的存档版本");
return;
}
if (data.version == 1)
{
// V1不含音量字段,迁移时使用明确的默认值。
data.masterVolume = 1f;
}
coins = Mathf.Max(0, data.coins);
masterVolume = Mathf.Clamp01(data.masterVolume);
player.position = data.playerPosition;
AudioListener.volume = masterVolume;
Debug.Log("读取成功:金币=" + coins);
}
catch (Exception e)
{
Debug.LogError("读取失败:" + e.Message);
}
}
}Application.persistentDataPath 在不同平台会解析为不同位置,因此用 Path.Combine 拼接文件名,不要硬编码安装目录。FromJsonOverwrite 将 JSON 覆盖到已初始化的数据对象上:缺失字段保持预设值;版本 1 使用默认音量升级到当前含音量字段的版本 2;比当前程序新的版本则拒绝应用,避免错误解释数据。
这里的 version=1 默认值还把没有版本字段的旧文件视为旧格式。若你的项目从未发布过无版本文件,也可以改成明确拒绝;版本迁移规则必须依据实际发布历史制定。
跟做恢复并验证边界情况
- 在空 GameObject 上挂
GameSaveController,将场景中的玩家Transform拖入Player字段。进入 Play 模式,在 Inspector 中把金币设为 3、音量设为 0.6,并把玩家移到(2, 0, 1)。 - 通过组件上下文菜单执行
Save;再把金币改成 0、玩家移到其他位置,执行Load。先改变运行时值,才能确认数据确实来自文件而不是原值。 - 检查玩家回到
(2, 0, 1)、金币恢复为 3,且AudioListener.volume为 0.6。Console 预期输出:
保存成功
读取成功:金币=3再依次验证:删除 save.json 后读取应提示“无存档”且不改状态;将文件改成无效 JSON 时应输出读取失败;将版本改成 3 时应拒绝应用。测试旧版时保留有效位置与金币、设 version 为 1 并删除 masterVolume,读取后音量应变为 1。
把恢复放在正确的生命周期中
本例用手动 Load 保证玩家已存在。正式游戏应先完成场景加载与角色生成,再恢复位置和数值,最后通知 HUD 刷新;不要在玩家尚未实例化的 Awake 中强行恢复。使用 CharacterController 时,必要时先禁用控制器、设置位置再启用,避免与移动控制冲突。
存档的关键不是 JSON 文件本身,而是稳定的数据协议和受控的恢复时机:先读取并验证快照,再把合法数据应用到已经就绪的运行时对象。