docs: refactor Components API content

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

@@ -6,50 +6,125 @@
 
 **头文件**: `XCEngine/Components/MeshRendererComponent.h`
 
-**描述**: 保存材质槽、阴影标志和渲染层信息，负责告诉渲染系统“这个 mesh 应该如何被绘制”。
+**描述**: 保存材质槽、阴影开关和渲染层等绘制配置，声明“这个对象上的 Mesh 应该如何被渲染”。
 
-## 概述
+## 角色概述
 
-`MeshRendererComponent` 承担的是“绘制配置”这一半职责：
+`MeshRendererComponent` 负责的是“绘制配置”，不是“几何来源”。
 
-- 材质槽数组
-- 阴影开关
-- 渲染层
+- [MeshFilterComponent](../MeshFilterComponent/MeshFilterComponent.md) 负责网格
+- `MeshRendererComponent` 负责材质槽和渲染附加参数
 
-和 [MeshFilterComponent](../MeshFilterComponent/MeshFilterComponent.md) 配合后，场景提取器就能把几何和材质信息一起整理成 [VisibleRenderObject](../../Rendering/VisibleRenderObject/VisibleRenderObject.md)。
+两者配合后，`RenderSceneExtractor` 才能把场景对象整理成可提交到渲染管线的可见项。
 
-## 当前实现边界
+## 当前实现行为
 
-- 内部同时维护 `m_materials` 和 `m_materialPaths` 两套数组。
-- [SetMaterial](SetMaterial.md) 会在需要时自动扩容材质槽。
-- [SetMaterials](SetMaterials.md) 会整体替换材质数组。
-- [Deserialize](Deserialize.md) 会尝试通过 `ResourceManager` 重新加载材质。
-- 当前 `castShadows`、`receiveShadows` 和 `renderLayer` 还没有真正接入 [RenderSceneExtractor](../../Rendering/RenderSceneExtractor/RenderSceneExtractor.md) 或 [BuiltinForwardPipeline](../../Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)。
+### 1. 同时维护材质 handle 和路径数组
 
-## 公开方法
+内部维护两套并行数组：
 
-| 方法 | 说明 |
-|------|------|
-| [GetName](GetName.md) | 返回组件名字。 |
-| [GetMaterialCount](GetMaterialCount.md) | 获取材质槽数量。 |
-| [GetMaterial](GetMaterial.md) | 获取指定槽位材质。 |
-| [GetMaterialHandle](GetMaterialHandle.md) | 获取指定槽位材质句柄。 |
-| [GetMaterialPaths](GetMaterialPaths.md) | 获取序列化路径数组。 |
-| [SetMaterial](SetMaterial.md) | 设置单个材质槽。 |
-| [SetMaterials](SetMaterials.md) | 批量设置材质槽。 |
-| [ClearMaterials](ClearMaterials.md) | 清空所有材质槽。 |
-| [GetCastShadows](GetCastShadows.md) | 查询投射阴影标志。 |
-| [SetCastShadows](SetCastShadows.md) | 设置投射阴影标志。 |
-| [GetReceiveShadows](GetReceiveShadows.md) | 查询接收阴影标志。 |
-| [SetReceiveShadows](SetReceiveShadows.md) | 设置接收阴影标志。 |
-| [GetRenderLayer](GetRenderLayer.md) | 获取渲染层。 |
-| [SetRenderLayer](SetRenderLayer.md) | 设置渲染层。 |
-| [Serialize](Serialize.md) | 序列化材质路径与标志位。 |
-| [Deserialize](Deserialize.md) | 反序列化材质路径与标志位。 |
+- `m_materials`
+- `m_materialPaths`
+
+这和 `MeshFilterComponent` 的思路一致，目的是同时满足：
+
+- 运行时快速拿资源
+- 序列化时稳定写路径
+
+### 2. 材质槽会按需自动扩容
+
+`SetMaterialPath()` 和 `SetMaterial()` 在写入指定槽位前，都会先调用内部 `EnsureMaterialSlot(index)`。
+
+因此：
+
+- 可以直接写入一个较大的槽位索引
+- 中间缺失槽位会被自动补成空材质
+
+`tests/Components/test_mesh_render_components.cpp` 已覆盖这一行为。
+
+### 3. 越界读取是“安全空值”语义
+
+按当前实现：
+
+- `GetMaterial(index)` 越界时返回 `nullptr`
+- `GetMaterialHandle(index)` 越界时返回静态空 handle
+- `GetMaterialPath(index)` 越界时返回静态空字符串
+
+这让上层调用少了很多显式边界判断，但也意味着调用者不能把空返回值误读成“这个槽位一定存在但内容为空”。
+
+### 4. 反序列化按路径重建槽位
+
+`Deserialize()` 会：
+
+- 先清空旧材质与标记
+- 解析 `materials=` 字段
+- 用 `|` 分隔多材质路径
+- 对每个槽位调用 `SetMaterialPath()` 尝试重新加载
+
+即使资源此刻没有加载成功，路径数组也会被保留下来。这一点同样有测试覆盖。
+
+## 阴影和渲染层的现实状态
+
+当前组件公开了：
+
+- `GetCastShadows()` / `SetCastShadows()`
+- `GetReceiveShadows()` / `SetReceiveShadows()`
+- `GetRenderLayer()` / `SetRenderLayer()`
+
+但按当前 [RenderSceneExtractor](../../Rendering/RenderSceneExtractor/RenderSceneExtractor.md) 实现，场景提取时还没有看到这些字段被真正消费。也就是说：
+
+- 这些字段当前可以保存
+- 也可以被序列化
+- 但它们还没有完整接入当前已取证的渲染提取路径
+
+文档必须把这一点说清楚，避免用户把“字段存在”误解成“功能已完整生效”。
+
+## 序列化语义
+
+当前写出：
+
+- `materials`，多个路径用 `|` 分隔
+- `castShadows`
+- `receiveShadows`
+- `renderLayer`
+
+测试还覆盖了“末尾空材质槽”会被保留的情况，这对编辑器材质槽 UI 很重要。
+
+## 线程语义
+
+- 当前实现没有内部加锁。
+- 资源路径解析和材质切换默认按主线程配置路径使用。
+
+## 当前实现限制
+
+- 当前文档目录原先缺少 `GetMaterialPath()` 和 `SetMaterialPath()` 独立方法页，本轮已补齐。
+- `castShadows`、`receiveShadows` 和 `renderLayer` 还没有完整接入当前已取证的场景提取逻辑。
+- 它只负责声明绘制配置，不等于完整 renderer feature 集合。
+
+## 相关方法
+
+- [GetMaterialCount](GetMaterialCount.md)
+- [GetMaterial](GetMaterial.md)
+- [GetMaterialHandle](GetMaterialHandle.md)
+- [GetMaterialPath](GetMaterialPath.md)
+- [GetMaterialPaths](GetMaterialPaths.md)
+- [SetMaterial](SetMaterial.md)
+- [SetMaterialPath](SetMaterialPath.md)
+- [SetMaterials](SetMaterials.md)
+- [ClearMaterials](ClearMaterials.md)
+- [GetCastShadows](GetCastShadows.md)
+- [SetCastShadows](SetCastShadows.md)
+- [GetReceiveShadows](GetReceiveShadows.md)
+- [SetReceiveShadows](SetReceiveShadows.md)
+- [GetRenderLayer](GetRenderLayer.md)
+- [SetRenderLayer](SetRenderLayer.md)
+- [Serialize](Serialize.md)
+- [Deserialize](Deserialize.md)
 
 ## 相关文档
 
-- [Components](../Components.md)
+- [当前模块](../Components.md)
 - [MeshFilterComponent](../MeshFilterComponent/MeshFilterComponent.md)
 - [RenderSceneExtractor](../../Rendering/RenderSceneExtractor/RenderSceneExtractor.md)
 - [BuiltinForwardPipeline](../../Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
+- [API 总索引](../../../main.md)