游戏引擎 / 系统课时

保存玩家进度与设置

保存玩家进度与设置

玩家离开游戏后,需要保留金币、出生位置和音量设置;直接保存场景组件既难恢复,也容易在更新后失效。本课用轻量 JSON 存档建立运行状态的快照,加入版本检查、缺失字段默认值与错误处理,并在场景对象准备好后恢复状态。

学习目标

  • 设计只包含可持久化数值的存档数据结构。
  • 使用 JsonUtility 和 persistentDataPath 完成保存、读取与验证。
  • 处理旧版本、缺失字段和加载后的状态恢复顺序。

确定哪些数据应该保存

存档不是对整个场景拍照,而是记录重建游戏所必需的最小状态。本例保存三项:玩家金币、世界坐标和主音量。version 说明这些字段属于哪版存档协议,后续增加设置或改变数据含义时才有依据迁移。

字段 用途 恢复到哪里
coins 非负整数进度 游戏状态字段
playerPosition 单场景内的玩家位置 玩家 Transform
masterVolume 0~1 的音量设置 AudioListener.volume
version 数据协议版本 加载兼容性判断

不要直接序列化 GameObject、场景实例引用或临时 UI 状态。JsonUtility 主要处理 Unity 序列化规则支持的字段,不适合作为任意字典或复杂对象图的通用存储器。小型偏好也可使用 PlayerPrefs,但本例将进度和设置放在一个可检查、可迁移的文件中。

运行时状态经快照写盘再校验恢复

实现存取、兼容与异常处理

新建 GameSaveController.cs。其中 SaveData 是纯数据类,不能保存组件引用;GameSaveController 是挂在场景对象上的读写入口。示例采用单场景玩家,并提供 Inspector 右键菜单以便直接测试。

csharp
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 默认值还把没有版本字段的旧文件视为旧格式。若你的项目从未发布过无版本文件,也可以改成明确拒绝;版本迁移规则必须依据实际发布历史制定。

跟做恢复并验证边界情况

  1. 在空 GameObject 上挂 GameSaveController,将场景中的玩家 Transform 拖入 Player 字段。进入 Play 模式,在 Inspector 中把金币设为 3、音量设为 0.6,并把玩家移到 (2, 0, 1)。
  2. 通过组件上下文菜单执行 Save;再把金币改成 0、玩家移到其他位置,执行 Load。先改变运行时值,才能确认数据确实来自文件而不是原值。
  3. 检查玩家回到 (2, 0, 1)、金币恢复为 3,且 AudioListener.volume 为 0.6。Console 预期输出:
text
保存成功
读取成功:金币=3

再依次验证:删除 save.json 后读取应提示“无存档”且不改状态;将文件改成无效 JSON 时应输出读取失败;将版本改成 3 时应拒绝应用。测试旧版时保留有效位置与金币、设 version 为 1 并删除 masterVolume,读取后音量应变为 1。

把恢复放在正确的生命周期中

本例用手动 Load 保证玩家已存在。正式游戏应先完成场景加载与角色生成,再恢复位置和数值,最后通知 HUD 刷新;不要在玩家尚未实例化的 Awake 中强行恢复。使用 CharacterController 时,必要时先禁用控制器、设置位置再启用,避免与移动控制冲突。

存档的关键不是 JSON 文件本身,而是稳定的数据协议和受控的恢复时机:先读取并验证快照,再把合法数据应用到已经就绪的运行时对象。

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

目录与阅读设置

阅读设置

17

记录一个想法

保存玩家进度与设置

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

登录哪都通