游戏引擎 / 系统课时
定义玩家与关卡存档结构
定义玩家与关卡存档结构
一个可用的关卡存档必须能在重新启动游戏后重建玩家和任务状态。本课使用 Unity 6 的 C# 可序列化类,保存玩家位置、生命值、物品库存、检查点、任务进度和场景标识,并通过 JSON 序列化与反序列化验证数据结构是否完整。
学习目标
- 设计包含玩家、背包、任务与关卡状态的存档数据结构。
- 区分可持久化的纯数据与不能直接持久化的运行时对象引用。
- 使用
JsonUtility完成存档对象的序列化、反序列化与字段验证。
确定存档字段与数据边界
存档应当记录恢复游戏所需的状态,而不是复制整个场景。以第三人称动作关卡为例,假设玩家位于森林关卡,生命值为 75/100,背包中有 3 瓶药剂,已经击败 2 名守卫,并激活了第二个检查点。
可以将这些状态组织为一个根对象 GameSaveData,再按照职责拆分子对象。
| 字段 | 数据类型 | 示例值与用途 |
|---|---|---|
schemaVersion |
int |
1,识别存档结构版本 |
sceneId |
string |
Level_Forest,定位需要加载的场景 |
checkpointId |
string |
CP_02,定位最近激活的检查点 |
player.position |
Vector3 |
(12, 0, 8),保存世界坐标 |
player.currentHp |
int |
75,当前生命值 |
player.maxHp |
int |
100,最大生命值 |
inventory |
List<ItemStackSaveData> |
记录槽位、物品 ID 和堆叠数量 |
quests |
List<QuestSaveData> |
记录任务 ID、当前计数和完成状态 |
其中 sceneId、checkpointId、itemId 和 questId 都应使用项目自行维护的稳定标识。不要将列表索引、临时对象名称或 GetInstanceID() 的结果当作永久 ID,因为它们可能随场景编辑或重新运行发生变化。
背包需要保存实际持有的物品数量,而不必复制物品配置中的名称、图标、描述和基础属性。恢复时通过 itemId 查找对应的 ItemDefinition 配置资产即可。若物品允许多个堆叠,还应保存 slotIndex,避免恢复后槽位顺序丢失。
从运行时组件抽取纯数据
场景中的玩家可能同时具有 Transform、生命值组件、背包组件和任务管理器。这些对象负责运行时行为,但不适合作为存档文件的直接内容。
例如,Transform 是依附于场景对象的组件,物品配置可能是 ScriptableObject,敌人状态也可能由多个 MonoBehaviour 维护。即使 Unity 的序列化器能够记录部分对象引用,其内部实例 ID 也不能可靠地跨游戏会话恢复引用关系。
正确做法是在保存时读取组件中的数值,构建不持有场景对象引用的快照;读取存档后,再由加载逻辑把这些数值应用到新场景中的运行时组件。

这里还需要明确两个恢复规则:player.position 表示保存瞬间的位置,checkpointId 表示已经激活的复活点。正常读取有效存档时优先恢复保存位置;玩家死亡或存档位置不可用时,再考虑使用检查点位置。两者承担不同职责,不应相互覆盖。
编写可序列化的存档对象
Unity 6 内置的 JsonUtility 使用 Unity 序列化规则。普通数据类需要添加 [Serializable],需要持久化的字段可以使用公开实例字段。Vector3、int、bool、string 和受支持的 List<T> 都适合这里的存档结构。
不要把关键数据仅写成 C# 自动属性,例如 public int CurrentHp { get; set; },因为 JsonUtility 不会按普通属性进行序列化。Dictionary<TKey, TValue> 也不能直接依赖 Unity 内置序列化器保存,本例使用列表存放物品和任务记录。
在 Unity 6 项目中创建 Assets/Scripts/Save/SaveStructureDemo.cs。以下代码包含全部数据类和测试入口,可直接作为一个脚本编译运行。
using System;
using System.Collections.Generic;
using UnityEngine;
[Serializable]
public class PlayerSaveData
{
public Vector3 position;
public int currentHp;
public int maxHp;
}
[Serializable]
public class ItemStackSaveData
{
public int slotIndex;
public string itemId;
public int count;
}
[Serializable]
public class QuestSaveData
{
public string questId;
public int currentCount;
public bool completed;
}
[Serializable]
public class GameSaveData
{
public int schemaVersion = 1;
public string sceneId;
public string checkpointId;
public PlayerSaveData player = new PlayerSaveData();
public List<ItemStackSaveData> inventory = new List<ItemStackSaveData>();
public List<QuestSaveData> quests = new List<QuestSaveData>();
}
public class SaveStructureDemo : MonoBehaviour
{
private void Start()
{
// 用固定测试值模拟从运行时组件采集的状态快照。
GameSaveData save = new GameSaveData
{
sceneId = "Level_Forest",
checkpointId = "CP_02",
player = new PlayerSaveData
{
position = new Vector3(12f, 0f, 8f),
currentHp = 75,
maxHp = 100
},
inventory = new List<ItemStackSaveData>
{
new ItemStackSaveData
{
slotIndex = 0,
itemId = "potion_small",
count = 3
}
},
quests = new List<QuestSaveData>
{
new QuestSaveData
{
questId = "defeat_guards",
currentCount = 2,
completed = false
}
}
};
// JSON只保存数据字段,不包含场景组件引用。
string json = JsonUtility.ToJson(save, true);
GameSaveData restored = JsonUtility.FromJson<GameSaveData>(json);
// 验证多层嵌套数据在序列化往返后没有丢失。
Debug.Log(
$"场景={restored.sceneId} 检查点={restored.checkpointId} " +
$"位置X={restored.player.position.x:0} " +
$"HP={restored.player.currentHp}/{restored.player.maxHp} " +
$"药剂={restored.inventory[0].count} " +
$"击败={restored.quests[0].currentCount}"
);
}
}预期输出:
场景=Level_Forest 检查点=CP_02 位置X=12 HP=75/100 药剂=3 击败=2这个示例只验证数据结构和 JSON 转换,并没有将存档写入磁盘,也没有修改真实玩家状态。JsonUtility.ToJson(save, true) 返回格式化的 JSON 字符串;FromJson<GameSaveData>() 则创建新的纯数据对象并填充字段。
在 Unity 编辑器中验证字段完整性
完成脚本后,可以直接在编辑器中验证它是否能够运行。
- 在 Hierarchy 中创建空对象,命名为
SaveDemo。 - 将
SaveStructureDemo脚本添加到该对象上,确认 Console 没有编译错误。 - 点击 Play,打开
Window > General > Console,检查输出是否与预期一致。 - 在
Start()方法的JsonUtility.ToJson调用后设置断点,使用调试器查看json字符串,确认包含schemaVersion、sceneId、player、inventory和quests。 - 将示例中药剂数量从
3改为5,重新运行,确认输出中的药剂数量同步变为5。
还可以检查 JSON 中的 position 是否保存为包含 x、y、z 的对象,以及 inventory 和 quests 是否分别表现为 JSON 数组。这些检查可以确认嵌套结构没有被意外忽略。
读取存档前需要检查的边界
成功反序列化只意味着 JSON 可以转换成数据对象,不代表其中的数据一定有效。正式读取时,应当先校验,再修改玩家或关卡状态。
| 检查项目 | 具体规则 | 失败处理 |
|---|---|---|
| 存档版本 | schemaVersion == 1 |
不支持的版本拒绝加载或先执行迁移 |
| 场景标识 | sceneId 必须对应项目允许加载的场景 |
停止恢复并提示存档场景无效 |
| 生命值 | maxHp > 0,currentHp 在 0 到 maxHp 之间 |
对越界生命值进行修正或拒绝异常存档 |
| 库存数量 | count > 0,slotIndex 在背包容量内且不冲突 |
拒绝无效槽位,避免重复覆盖 |
| 物品与任务 ID | 必须能在当前配置表中找到 | 按项目迁移规则处理缺失记录 |
| 检查点与位置 | 检查点 ID 可解析,玩家位置符合恢复规则 | 使用有效检查点或场景默认出生点 |
例如,一个容量为 20 格的背包,只允许槽位索引 0 到 19。如果存档包含 slotIndex = 25,就不应该直接将其应用到运行时背包。两个记录使用相同槽位索引也需要作为冲突处理,而不是让后一个记录悄悄覆盖前一个。
任务数据还应由当前任务配置确定完成条件。对于目标为击败 3 名守卫的任务,currentCount = 2 且 completed = false 是合理状态;但若存档出现计数为 2、完成标记却为 true,就要根据任务规则校验或迁移,不能直接信任两个字段。
真正回填场景时,应先使用 sceneId 加载目标场景,等待运行时对象初始化,再通过稳定 ID 定位对应的检查点、物品配置和任务。最后按照验证后的数据设置玩家位置、生命值、库存和任务状态。不要在目标场景尚未加载时,就尝试访问旧场景中的 Transform 或 MonoBehaviour。
这份结构还预留了 schemaVersion,便于以后新增字段或调整库存规则时识别旧存档。需要扩展的数据应继续放在纯数据容器中,而不是将场景实例、组件引用或配置资产直接塞入 JSON。