XCEngine/docs/api/XCEngine/Scene/Scene/DeserializeFromString.md

Scene::DeserializeFromString

从自定义场景文本重建当前场景内容。

void DeserializeFromString(const std::string& data);

行为说明

当前实现会先清空：

• m_gameObjects
• m_rootGameObjects
• m_gameObjectIDs
• 全局 registry 中属于旧场景的对象

需要注意的是，这个“清空旧场景”过程不会逐个调用 DestroyGameObject，因此不会触发场景销毁事件，也不会为旧组件补发 OnDestroy()。

两阶段重建流程

当前实现按两阶段恢复：

1. 先解析所有对象块，收集 id、uuid、name、tag、active、layer、parent、transform 和组件 payload
2. 再创建全部 GameObject，恢复字段、组件和父子关系

恢复组件时，当前依赖 ComponentFactoryRegistry 通过组件名创建具体实例。

Tag 与 Layer 恢复语义

• tag 通过 GameObject::SetTag() 写回，因此空字符串会回退到 "Untagged"
• layer 在解析阶段先把文本数值限制到 31，然后再通过 SetLayer() 写回

因此按当前实现，场景 round-trip 会保留正确的 tag / layer 语义。

父子关系恢复语义

• parent=INVALID_ID 的对象会进入根列表
• 如果某个对象声明了父 ID，但该父对象最终不存在，它也会回退为根对象
• 父子挂接时调用的是 SetParent(parent, false)，因此恢复层级时不会要求保持世界变换

ID 与 UUID 语义

• 文本里存在的 id 和 uuid 会被尽量保留
• 解析结束后，GameObject::s_nextID 会推进到当前最大 ID 之后

这样可以避免反序列化后继续新建对象时出现 ID 冲突。

当前实现限制

• 不会触发 OnGameObjectCreated
• 不会调用 Awake() / Start()
• 对损坏数字字段抛出的异常当前不会在这里捕获
• 组件恢复成功与否依赖注册表和各组件自身反序列化逻辑

参数

• data - 序列化后的场景文本。

返回值

• 无。

设计提示

这条路径的目标是“尽可能忠实地把场景文本重建回内存状态”，而不是“模拟一次完整运行时创建流程”。这也是它不经过 CreateGameObject()、不补发 Awake() 的根本原因。

相关文档

• Scene
• SerializeToString
• GameObject::Deserialize