游戏引擎 / 系统课时
将 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;正式项目可以将按钮调用替换为游戏菜单事件。
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> 为实际目录:
持久目录: <PATH>
没有有效存档,使用场景初始值第一次保存尚无正式文件,用 File.Move 将完整的 .tmp 移入正式路径;第二次起使用 File.Replace,让旧版进入 .bak,新版成为 .json。若写临时文件时失败,原 .json 不会被直接覆盖。读取时先尝试正式文件,校验失败再回退到备份;残留 .tmp 不自动作为有效进度。

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