游戏引擎 / 系统课时

定义玩家与关卡存档结构

定义玩家与关卡存档结构

一个可用的关卡存档必须能在重新启动游戏后重建玩家和任务状态。本课使用 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 也不能可靠地跨游戏会话恢复引用关系。

正确做法是在保存时读取组件中的数值,构建不持有场景对象引用的快照;读取存档后,再由加载逻辑把这些数值应用到新场景中的运行时组件。

运行时组件、存档数据对象与 JSON 之间的数据映射

这里还需要明确两个恢复规则: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。以下代码包含全部数据类和测试入口,可直接作为一个脚本编译运行。

csharp
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}"
        );
    }
}

预期输出:

text
场景=Level_Forest 检查点=CP_02 位置X=12 HP=75/100 药剂=3 击败=2

这个示例只验证数据结构和 JSON 转换,并没有将存档写入磁盘,也没有修改真实玩家状态。JsonUtility.ToJson(save, true) 返回格式化的 JSON 字符串;FromJson<GameSaveData>() 则创建新的纯数据对象并填充字段。

在 Unity 编辑器中验证字段完整性

完成脚本后,可以直接在编辑器中验证它是否能够运行。

  1. 在 Hierarchy 中创建空对象,命名为 SaveDemo。
  2. 将 SaveStructureDemo 脚本添加到该对象上,确认 Console 没有编译错误。
  3. 点击 Play,打开 Window > General > Console,检查输出是否与预期一致。
  4. 在 Start() 方法的 JsonUtility.ToJson 调用后设置断点,使用调试器查看 json 字符串,确认包含 schemaVersion、sceneId、player、inventory 和 quests。
  5. 将示例中药剂数量从 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。

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

目录与阅读设置

阅读设置

17

记录一个想法

定义玩家与关卡存档结构

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

登录哪都通