# MeshRendererComponent::SetMaterialPath

按路径设置单个材质槽。

```cpp
void SetMaterialPath(size_t index, const std::string& materialPath);
```

## 当前实现行为

- 调用内部 `EnsureMaterialSlot(index)` 自动扩容槽位数组。
- 清空该槽位旧的 pending async load，并把 `m_asyncMaterialLoadRequested[index]` 复位为 `false`。
- 记录 `m_materialPaths[index] = materialPath`。
- 若路径为空，则同时重置 `m_materials[index]` 和 `m_materialRefs[index]`。
- 若路径非空，则调用 `ResourceManager::Get().Load<Resources::Material>(...)` 尝试加载。
- 然后调用 `TryGetAssetRef(...)` 试着把路径映射成项目资产引用。
- 即使加载失败，路径也会保留。

## 重要语义

- 这是一个同步设置接口，不是“只记录路径、等以后再加载”的接口。
- 虚拟路径或内置路径也允许写入，但通常拿不到有效 `AssetRef`。
- 如果后续重新设置同一槽位，旧的异步状态会被显式丢弃。
- 对项目材质来说，这个 API 写入的是运行时路径缓存；真正序列化时只要能得到有效 `AssetRef`，普通项目路径就不会作为正式场景数据长期保留。

## 使用建议

这比直接设置 handle 更适合：

- 编辑器材质面板
- 运行时或工具侧按路径即时指定材质
- virtual path 资源输入

如果调用方已经手里拿到了一个确定可用的材质句柄，并且希望以运行时对象为主写入，则可以考虑 [SetMaterial](SetMaterial.md)。

## 相关文档

- [返回类型总览](MeshRendererComponent.md)
- [GetMaterialPath](GetMaterialPath.md)
- [GetMaterialAssetRefs](GetMaterialAssetRefs.md)
- [SetMaterial](SetMaterial.md)
- [Serialize](Serialize.md)
- [Deserialize](Deserialize.md)