游戏引擎 / 系统课时
用稳定 ID 保存物体状态
用稳定 ID 保存物体状态
本课要让宝箱开启、药剂拾取和机关激活在退出游戏、重新加载场景后仍然保持原样。我们会为每个场景实例写入独立且不变的 ID,以它为键保存完成状态,并补上重复 ID 检查,避免玩家反复获得同一份奖励。
学习目标
- 为场景中的持久化对象生成可跨运行匹配的稳定 ID。
- 使用 Unity 6 的 JSON 存档记录和恢复对象完成状态。
- 检测空 ID、重复 ID,并处理对象被移除后的旧存档。
为场景实例确定唯一身份
同一个预制体可以放置多个宝箱,但每个场景实例都必须有自己的 ID。将 32 位十六进制 GUID 保存到组件的序列化字段,并随场景资源提交;后续移动、重命名或调整层级时不要重新生成。GetInstanceID() 只适合运行时引用,物体名称与层级路径也可能变化,都不能充当存档键。
| 场景对象 | 存档状态 | 再次进入场景的效果 |
|---|---|---|
Chest_A |
done = true |
显示开启后的宝箱外观 |
Potion_01 |
done = true |
拾取物不再出现 |
Lever_01 |
done = true |
机关保持激活 |
本例把一个 ID 对应到一个布尔完成状态。对于可反复开关的机关,应把 done 扩展为明确的状态枚举或数值,而不是复用“完成”含义。

写入完成状态并在加载时恢复
在 Unity 6(6000.x)项目中创建 Assets/Scripts/PersistentSceneFlag.cs。以下是完整的单文件示例:组件负责将场景实例与 ID 关联,SceneFlagStore 负责序列化、落盘和读取。JsonUtility 使用可序列化的 List 而不是直接序列化 Dictionary;文件保存在 Application.persistentDataPath 下。
using System;
using System.Collections.Generic;
using System.IO;
using UnityEngine;
public sealed class PersistentSceneFlag : MonoBehaviour
{
[SerializeField] private string stableId;
[SerializeField] private GameObject beforeDone;
[SerializeField] private GameObject afterDone;
[SerializeField] private bool hideRootWhenDone;
public string StableId => stableId;
private void Awake()
{
if (string.IsNullOrWhiteSpace(stableId))
{
Debug.LogError("Missing stable ID", this);
enabled = false;
return;
}
Apply(SceneFlagStore.IsDone(stableId));
}
[ContextMenu("Complete (Play Mode)")]
public void Complete()
{
if (!Application.isPlaying || string.IsNullOrWhiteSpace(stableId)) return;
// 写入成功后才隐藏物体,避免存盘失败造成道具丢失。
if (SceneFlagStore.TrySetDone(stableId)) Apply(true);
}
private void Apply(bool done)
{
if (beforeDone != null) beforeDone.SetActive(!done);
if (afterDone != null) afterDone.SetActive(done);
if (hideRootWhenDone && done) gameObject.SetActive(false);
}
#if UNITY_EDITOR
[ContextMenu("Generate New Stable ID")]
private void GenerateId()
{
// ID 只能写到场景实例,不能写到共享的 Prefab Asset。
if (UnityEditor.PrefabUtility.IsPartOfPrefabAsset(gameObject) ||
UnityEditor.SceneManagement.PrefabStageUtility.GetCurrentPrefabStage() != null)
{
Debug.LogError("Generate ID on a scene instance only", this);
return;
}
UnityEditor.Undo.RecordObject(this, "Generate stable ID");
stableId = Guid.NewGuid().ToString("N");
UnityEditor.PrefabUtility.RecordPrefabInstancePropertyModifications(this);
UnityEditor.EditorUtility.SetDirty(this);
}
#endif
}
internal static class SceneFlagStore
{
[Serializable]
private sealed class Entry
{
public string id;
public bool done;
}
[Serializable]
private sealed class SaveData
{
public int version = 1;
public List<Entry> items = new List<Entry>();
}
private static SaveData cache;
private static string SavePath =>
Path.Combine(Application.persistentDataPath, "scene-state.json");
// 兼容编辑器关闭 Domain Reload 后的重复 Play 测试。
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
private static void ResetCache() => cache = null;
private static SaveData Load()
{
if (cache != null) return cache;
cache = new SaveData();
if (!File.Exists(SavePath)) return cache;
try
{
var loaded = JsonUtility.FromJson<SaveData>(File.ReadAllText(SavePath));
if (loaded != null && loaded.items != null) cache = loaded;
}
catch (Exception e)
{
Debug.LogError($"Save load failed: {e.Message}");
}
return cache;
}
public static bool IsDone(string id) =>
Load().items.Exists(item => item.id == id && item.done);
public static bool TrySetDone(string id)
{
if (IsDone(id)) return true; // 重复交互不写入第二条记录。
var items = Load().items;
items.Add(new Entry { id = id, done = true });
try
{
File.WriteAllText(SavePath, JsonUtility.ToJson(cache, true));
Debug.Log($"Saved completed state for {id}");
return true;
}
catch (Exception e)
{
items.RemoveAt(items.Count - 1);
Debug.LogError($"Save write failed: {e.Message}");
return false;
}
}
}首次完成交互后的预期输出(<ID> 是当前实例真实生成的标识,实际值不同):
Saved completed state for <ID>此时文件 scene-state.json 中的 items 增加一条对应 ID、done 为 true 的记录。场景再次载入时,组件在 Awake 中按相同 ID 查询并执行 Apply(true);不能在拾取时直接 Destroy 对象后再依赖场景扫描存档,因为销毁的对象已无法被枚举。本例在状态变化时立即落盘,适合少量静态对象;大量频繁变更的状态应批量写入并采用临时文件替换与备份策略。
检查空 ID 和复制导致的冲突
复制场景物体会连同序列化字段一起复制,因此两个实例可能携带相同 ID。创建 Assets/Editor/StableIdValidator.cs,通过菜单扫描当前已加载场景中的所有 PersistentSceneFlag,包含未激活的对象。
using System;
using System.Collections.Generic;
using UnityEditor;
using UnityEngine;
using UnityEngine.SceneManagement;
public static class StableIdValidator
{
[MenuItem("Tools/Save/Validate Stable IDs")]
private static void Validate()
{
var seen = new Dictionary<string, PersistentSceneFlag>();
int errors = 0;
for (int i = 0; i < SceneManager.sceneCount; i++)
{
var scene = SceneManager.GetSceneAt(i);
if (!scene.isLoaded) continue;
foreach (var root in scene.GetRootGameObjects())
foreach (var item in root.GetComponentsInChildren<PersistentSceneFlag>(true))
{
string id = item.StableId;
if (string.IsNullOrWhiteSpace(id) ||
!Guid.TryParseExact(id, "N", out _))
{
Debug.LogError("Missing or invalid stable ID", item);
errors++;
}
else if (seen.TryGetValue(id, out var first))
{
Debug.LogError($"Duplicate ID: {id}; first: {first.name}", item);
errors++;
}
else seen.Add(id, item);
}
}
Debug.Log($"Stable ID validation: {errors} issue(s)");
}
}选择 Tools > Save > Validate Stable IDs,无异常时预期输出:
Stable ID validation: 0 issue(s)若复制对象后出现 Duplicate ID,只为新复制出的实例执行 Generate New Stable ID,不要给已有存档的原实例重新编号。跨多个关卡保存时,应将相关场景一起加载检查,或在构建校验中逐个汇总 ID;这个菜单只扫描目前加载的场景,不代表项目所有场景均无冲突。
接入宝箱、拾取物和机关
- 在 Hierarchy 中选中宝箱的场景实例,添加
PersistentSceneFlag,从组件右上角菜单执行Generate New Stable ID;记录生成的stableId并保存场景。Prefab Asset 上不生成实例 ID。 - 宝箱将关闭外观子物体拖入
Before Done,开启外观子物体拖入After Done,取消Hide Root When Done。机关也这样绑定未激活与激活两套子物体。 - 药剂拾取物勾选
Hide Root When Done,两个外观引用可留空;它再次加载时会在Awake中隐藏自身。 - 将既有交互成功回调连接到该组件的
Complete()。对于拾取物,先确认库存添加成功,再调用它;若仅拿到输入就标记完成,背包容量不足时也会误删道具。 - 运行前执行 ID 检查并保存场景。进入 Play 模式,也可直接用组件菜单的
Complete (Play Mode)测试一次状态保存。
这里的 Complete() 只做持久化与外观切换,宝箱发奖励、药剂入库、机关开门仍由原有交互逻辑负责。对于同一个可领取奖励,逻辑层还应在发奖励前检查是否已领取;仅在 UI 中隐藏物体不能代替防重复发放校验。
重载验收与旧存档处理
建议按以下顺序验收:先在测试存档里完成一个宝箱和一瓶药剂;退出 Play 后再进入,同一宝箱应保持开启、药剂不应重现;再次进入也不应多出第二条相同 ID。随后移动宝箱、修改其名称并保存场景,验证仍可恢复。最后复制一个未完成机关,运行检查器确认报告冲突,修复新实例的 ID 后再次得到零错误。
scene-state.json 位于 Application.persistentDataPath,首次测试前应备份或清理这份测试文件,否则以前的完成状态会影响结果;删除 PlayerPrefs 不会清除此 JSON。部署版本中应为存档增加备份和写入完整性保护,不要把本示例的直接覆盖写入当作抗断电方案。
如果开发时从场景中删除了一个已持久化对象,旧存档里的 ID 可以暂时留存,不要依据“本次加载没找到对象”就自动删记录:物体也可能只是在另一场景或暂时未加载。若要替换对象又继承原进度,应在设计上保留原 ID,或提供带版本号的旧 ID 到新 ID 迁移表;新添加的对象必须拿到新 ID。这样改关卡布局不会让玩家重新领取已经消耗的拾取物。