docs: sync mesh renderer component docs

docs/api/XCEngine/Components/MeshRendererComponent/Deserialize.md

@@ -11,15 +11,44 @@ void Deserialize(std::istream& is) override;
 当前实现会：
 
 1. 先清空材质并重置默认标志。
-2. 解析 `materials`、`castShadows`、`receiveShadows` 和 `renderLayer`。
-3. 对每个非空材质路径调用 `ResourceManager::Get().Load<Resources::Material>()` 尝试重新加载。
+2. 解析 `materialPaths`、`materialRefs`、`castShadows`、`receiveShadows` 和 `renderLayer`。
+3. 兼容读取历史 `materials=` 键，并把它当作 `materialPaths=` 处理。
+4. 让 `m_materials`、`m_materialPaths`、`m_materialRefs`、pending 数组和 async 标记数组在槽位数量上重新对齐。
+
+随后每个槽位按下面的优先级恢复：
+
+1. 如果 `materialRef` 有效，先尝试按 `AssetRef` 恢复。
+2. 如果当前处于 deferred scene load，优先尝试把 `AssetRef` 重新解析回路径，但不立即同步加载材质。
+3. 如果没有有效 `AssetRef`，或者按 `AssetRef` 恢复失败，再退回到路径恢复。
+4. 只有在非 deferred 路径下，才会直接调用 [SetMaterialPath](SetMaterialPath.md) 做同步加载。
+
+这意味着“反序列化完成”并不等于“所有材质句柄都已经可用”。
 
 ## 当前实现说明
 
-- 如果某个材质加载失败，对应路径仍会保留，但句柄可能为空。
 - 默认值是：`castShadows = true`、`receiveShadows = true`、`renderLayer = 0`。
+- 如果某个槽位最终只恢复出了路径或 `AssetRef`，对应 `m_materials[index]` 仍可能为空。
+- 在 deferred scene load 模式下，真正的兑现通常要等首次 [GetMaterial](GetMaterial.md) 或 [GetMaterialHandle](GetMaterialHandle.md) 调用时才会触发。
+
+## 项目资产恢复语义
+
+当前实现特别强调项目资产的稳定恢复：
+
+- 当场景文本里有有效 `materialRef=` 时，组件会尽量依赖它，而不是单纯依赖字符串路径。
+- 如果 `AssetRef` 能解析到当前项目中的材质，路径会被重新规范化回 `Assets/...`。
+- 如果解析失败，仍会回退到文本路径。
+
+这和商业引擎常见的“文本可读路径 + 稳定内部引用”双轨设计一致，优点是既便于调试，也能提高资源重命名后的恢复成功率。
+
+## 兼容性说明
+
+- 仍兼容历史 `materials=` 文本。
+- 新版 [Serialize](Serialize.md) 不再输出 `materials=`。
 
 ## 相关文档
 
 - [返回类型总览](MeshRendererComponent.md)
 - [Serialize](Serialize.md)
+- [GetMaterial](GetMaterial.md)
+- [GetMaterialHandle](GetMaterialHandle.md)
+- [GetMaterialAssetRefs](GetMaterialAssetRefs.md)