游戏引擎 / 系统课时

将 JSON 存档写入持久目录

将 JSON 存档写入持久目录

这节把关卡编号、玩家生命值和位置保存为 JSON,写入 Unity 6 的持久目录,并在重新运行时恢复。实现时先写临时文件,再替换正式存档并保留上一版备份,避免写入失败直接破坏已有进度。

学习目标

  • 使用 JsonUtility 将可序列化状态写入 Application.persistentDataPath。
  • 区分首次保存和覆盖保存,利用临时文件与备份降低中断风险。
  • 验证重启后的数据一致性,并处理损坏存档与平台差异。

选定存档字段与文件位置

示例限定为 Unity 6(6000.x)桌面端:保存 schemaVersion=1、关卡编号、生命值和世界坐标。它们都是可恢复的值,不保存 Transform、GameObject 等场景对象引用。JsonUtility 要求普通数据类标记 [Serializable],并使用受 Unity 序列化器支持的字段;顶层数组应包进数据类。

存档路径通过 Path.Combine(Application.persistentDataPath, "savegame.json") 取得。不要写到 Assets、Application.dataPath 或 StreamingAssets:这些位置不适合用作已发布游戏的用户存档。持久目录会随系统、公司名及产品名变化,实际位置应从 Console 输出确认。

编写可保存、可恢复的组件

在 Assets/Scripts 中新建 JsonSaveDemo.cs,填入以下完整代码。示例用 OnGUI 绘制两个测试按钮,无须先配置输入动作或 UI Toolkit;正式项目可以将按钮调用替换为游戏菜单事件。

csharp
using System;
using System.IO;
using System.Text;
using UnityEngine;

[Serializable]
public sealed class GameSaveData
{
    public int schemaVersion;
    public int level;
    public int health;
    public Vector3 playerPosition;
}

public sealed class JsonSaveDemo : MonoBehaviour
{
    [SerializeField] private Transform player;
    [SerializeField] private int level = 1;
    [SerializeField] private int health = 100;

    private string SavePath =>
        Path.Combine(Application.persistentDataPath, "savegame.json");

    private void Start()
    {
        if (player == null || string.IsNullOrEmpty(Application.persistentDataPath))
        {
            Debug.LogError("未绑定玩家,或当前平台没有可用持久目录");
            enabled = false;
            return;
        }

        Debug.Log("持久目录: " + Application.persistentDataPath);
        Load();
    }

    private void OnGUI()
    {
        if (GUI.Button(new Rect(20, 20, 140, 40), "Save")) Save();
        if (GUI.Button(new Rect(20, 70, 140, 40), "Load")) Load();
    }

    private void Save()
    {
        var data = new GameSaveData
        {
            schemaVersion = 1,
            level = level,
            health = health,
            playerPosition = player.position
        };

        string path = SavePath;
        string temp = path + ".tmp";
        string backup = path + ".bak";

        try
        {
            Directory.CreateDirectory(Application.persistentDataPath);
            // 先完成临时文件写入,不直接截断现有正式存档。
            File.WriteAllText(temp, JsonUtility.ToJson(data, true),
                new UTF8Encoding(false));

            // 覆盖时备份旧版;首次保存则移动临时文件。
            if (File.Exists(path))
                File.Replace(temp, path, backup);
            else
                File.Move(temp, path);

            Debug.Log($"保存成功: 关卡={level}, 生命={health}");
        }
        catch (Exception e)
        {
            Debug.LogError("保存失败: " + e.Message);
        }
    }

    private void Load()
    {
        string source = SavePath;
        if (!TryRead(source, out GameSaveData data))
        {
            source = SavePath + ".bak";
            if (!TryRead(source, out data))
            {
                Debug.Log("没有有效存档,使用场景初始值");
                return;
            }
        }

        level = data.level;
        health = data.health;
        player.position = data.playerPosition;
        Debug.Log($"读取成功: 关卡={level}, 生命={health}, 来源={Path.GetFileName(source)}");
    }

    private static bool TryRead(string path, out GameSaveData data)
    {
        data = null;
        if (!File.Exists(path)) return false;

        try
        {
            var value = JsonUtility.FromJson<GameSaveData>(
                File.ReadAllText(path, Encoding.UTF8));
            // 版本与范围校验可阻止部分缺字段或错误存档被应用。
            if (value == null || value.schemaVersion != 1 ||
                value.level < 1 || value.health < 0 || value.health > 100)
                return false;

            data = value;
            return true;
        }
        catch (Exception e)
        {
            Debug.LogWarning("读取失败: " + e.Message);
            return false;
        }
    }
}

预期输出:首次进入 Play 模式且尚无有效存档时,Console 显示以下内容,<PATH> 为实际目录:

text
持久目录: <PATH>
没有有效存档,使用场景初始值

第一次保存尚无正式文件,用 File.Move 将完整的 .tmp 移入正式路径;第二次起使用 File.Replace,让旧版进入 .bak,新版成为 .json。若写临时文件时失败,原 .json 不会被直接覆盖。读取时先尝试正式文件,校验失败再回退到备份;残留 .tmp 不自动作为有效进度。

临时写入、替换备份及读取回退的数据流

在编辑器与重启后验收

  1. 新建空物体 SaveController,挂载 JsonSaveDemo,把场景中玩家根节点的 Transform 拖入 Player 字段。
  2. 进入 Play 模式。在 Inspector 中将 Level 改为 2、Health 改为 75,暂时禁用会移动角色的控制脚本,将玩家位置设为 (2, 1, 3);点击游戏画面左上角 Save。
  3. 检查 Console 的持久目录,打开其中的 savegame.json,确认 schemaVersion 为 1、level 为 2、health 为 75,位置的 x/y/z 对应 2/1/3。
  4. 退出 Play 模式并再次进入。Start 会自动读取存档;观察 Inspector 数值和玩家位置,再点击 Load 复核。此处的 level 仅为示例状态,不会自动切换 Unity 场景;正式项目应在目标场景及角色初始化后恢复坐标。

上述操作的预期结果(路径因平台而不同):

text
持久目录: <PATH>
保存成功: 关卡=2, 生命=75
读取成功: 关卡=2, 生命=75, 来源=savegame.json

首次保存后应有 savegame.json;再修改生命值为 60 并保存一次,应出现 savegame.json.bak,其中保留上一次的生命值 75。在测试副本中故意将正式文件改成无效 JSON,再点击 Load,应从备份恢复 75,日志来源变为 savegame.json.bak。动态目录 <PATH> 请以实际 Console 输出为准。

处理文件损坏和平台限制

现象 判断与处理
Console 显示“保存失败” 查看异常详情,排查目录权限、磁盘空间和占用文件;保留旧 .json,不要改成直接覆盖写入。
主文件损坏但 .bak 完好 通过 TryRead 校验后回退旧版;备份可能落后一次保存,这是有意取舍。
留下 .tmp 说明某次保存未走完;本例忽略临时文件,以主文件或备份为准。
主文件与备份都无效 不套用不可信坐标或生命值,保留场景初始值,并提示玩家重新开始。

File.Replace 依赖目标运行环境的文件系统与运行时实现,不能据此承诺断电时绝对原子或所有平台都支持。示例适用于使用常规文件系统的桌面端验证;迁移到 Android、iOS 等目标平台时,应在真机测试替换、权限和异常恢复。WebGL 的持久目录对应浏览器存储机制,tvOS 不提供 persistentDataPath,不能直接假定本方案的桌面行为。

正式上线还要限制单次存档并发、为不同槽位使用独立文件名,并针对新增字段制定版本迁移规则。本例保留 schemaVersion,遇到未知版本拒绝加载。版本和数值范围校验无法发现所有合法 JSON 中的缺字段或篡改,正式存档可再增加完整性校验与字段迁移。API 细节可查阅 Unity 持久目录文档、JsonUtility 文档 与 .NET File.Replace 文档。

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

目录与阅读设置

阅读设置

17

记录一个想法

将 JSON 存档写入持久目录

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

登录哪都通