docs: update resources API docs

docs/api/resources/asyncloader/asyncloader.md

@@ -4,6 +4,8 @@
 
 **类型**: `class` (singleton)
 
+**头文件**: `XCEngine/Resources/AsyncLoader.h`
+
 **描述**: 异步资源加载器单例，负责多线程后台资源加载和完成回调调度。
 
 ## 概述
@@ -59,13 +61,25 @@
 | `void CancelAll()` | 取消所有待处理的加载请求 |
 | `void Cancel(Core::uint64 requestId)` | 取消指定 ID 的加载请求 |
 
+### 方法详情
+
+- [Initialize](initialize.md) - 初始化异步加载器
+- [Shutdown](shutdown.md) - 关闭异步加载器
+- [Submit](submit.md) - 提交异步加载请求
+- [Update](update.md) - 更新函数，处理完成的加载请求
+- [IsLoading](isloading.md) - 检查是否有正在加载的资源
+- [GetPendingCount](getpendingcount.md) - 获取待处理加载请求数量
+- [GetProgress](getprogress.md) - 获取整体加载进度
+- [CancelAll](cancelall.md) - 取消所有待处理的加载请求
+- [Cancel](cancel.md) - 取消指定 ID 的加载请求
+
 ## 实现说明
 
 **注意**: 当前 `AsyncLoader` 的实现为部分完成状态（stub）：
 - `Initialize()` 工作线程数参数被忽略
 - `Submit()` 仅将请求加入队列，不进行实际异步加载
 - `Update()` 不执行实际加载，直接调用回调返回成功
-- `QueueCompleted()` 和 `Cancel()` 为空实现
+- `Cancel()` 为空实现
 
 ## 使用示例
 

docs/api/resources/asyncloader/cancel.md

@@ -0,0 +1,27 @@
+# AsyncLoader::Cancel
+
+```cpp
+void Cancel(Core::uint64 requestId)
+```
+
+取消指定 ID 的加载请求。
+
+**参数：**
+- `requestId` - 要取消的请求 ID（由 `LoadRequest::requestId` 提供）
+
+**返回：** 无
+
+**注意：** 当前实现未完成此功能。
+
+**示例：**
+
+```cpp
+LoadRequest req("textures/player.png", ResourceType::Texture,
+    [](LoadResult result) { /* ... */ });
+
+AsyncLoader::Get().Cancel(req.requestId);
+```
+
+## 相关文档
+
+- [AsyncLoader 总览](asyncloader.md) - 返回类总览

docs/api/resources/asyncloader/getpendingcount.md

@@ -0,0 +1,24 @@
+# AsyncLoader::GetPendingCount
+
+```cpp
+Core::uint32 GetPendingCount() const
+```
+
+获取当前待处理的加载请求数量。
+
+**参数：** 无
+
+**返回：** 待处理加载请求数量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Core::uint32 pending = AsyncLoader::Get().GetPendingCount();
+printf("Pending requests: %u\n", pending);
+```
+
+## 相关文档
+
+- [AsyncLoader 总览](asyncloader.md) - 返回类总览

docs/api/resources/asyncloader/initialize.md

@@ -0,0 +1,24 @@
+# AsyncLoader::Initialize
+
+```cpp
+void Initialize(Core::uint32 workerThreadCount = 2)
+```
+
+初始化异步加载器。根据 `workerThreadCount` 参数创建相应数量的工作线程用于后台资源加载。
+
+**参数：**
+- `workerThreadCount` - 工作线程数量，默认为 2
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为创建的工作线程数
+
+**示例：**
+
+```cpp
+AsyncLoader::Get().Initialize(4);
+```
+
+## 相关文档
+
+- [AsyncLoader 总览](asyncloader.md) - 返回类总览

docs/api/resources/asyncloader/isloading.md

@@ -0,0 +1,25 @@
+# AsyncLoader::IsLoading
+
+```cpp
+bool IsLoading() const
+```
+
+检查是否有正在加载的资源。
+
+**参数：** 无
+
+**返回：** 如果有待处理或完成的加载请求返回 `true`，否则返回 `false`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (AsyncLoader::Get().IsLoading()) {
+    printf("Resources are still loading...\n");
+}
+```
+
+## 相关文档
+
+- [AsyncLoader 总览](asyncloader.md) - 返回类总览

docs/api/resources/asyncloader/shutdown.md

@@ -0,0 +1,23 @@
+# AsyncLoader::Shutdown
+
+```cpp
+void Shutdown()
+```
+
+关闭异步加载器。取消所有待处理的加载请求并清理资源。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)
+
+**示例：**
+
+```cpp
+AsyncLoader::Get().Shutdown();
+```
+
+## 相关文档
+
+- [AsyncLoader 总览](asyncloader.md) - 返回类总览

docs/api/resources/asyncloader/submit.md

@@ -33,3 +33,4 @@ AsyncLoader::Get().Submit("textures/player.png", ResourceType::Texture,
 ## 相关文档
 
 - [AsyncLoader 总览](asyncloader.md) - 返回类总览
+- [Cancel](cancel.md) - 取消指定请求

docs/api/resources/audio-loader/canload.md

@@ -0,0 +1,36 @@
+# AudioLoader::CanLoad
+
+## 方法签名
+
+```cpp
+bool CanLoad(const Containers::String& path) const override;
+```
+
+## 详细描述
+
+根据文件扩展名判断此加载器是否能处理指定路径的资源。检测时先提取路径扩展名（小写），再与支持列表逐一比对。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `path` | `const Containers::String&` | 资源文件的完整或相对路径 |
+
+## 返回值
+
+`bool` - 如果扩展名在支持列表中返回 `true`，否则返回 `false`。
+
+## 示例
+
+```cpp
+AudioLoader loader;
+
+// 正确识别支持的格式
+bool canLoad1 = loader.CanLoad("assets/audio/bgm.ogg");     // true
+bool canLoad2 = loader.CanLoad("sound_effect.wav");        // true
+bool canLoad3 = loader.CanLoad("music.mp3");               // true
+
+// 识别不支持的格式
+bool canLoad4 = loader.CanLoad("video.avi");               // false
+bool canLoad5 = loader.CanLoad("document.pdf");            // false
+```

docs/api/resources/audio-loader/getdefaultsettings.md

@@ -0,0 +1,27 @@
+# AudioLoader::GetDefaultSettings
+
+## 方法签名
+
+```cpp
+ImportSettings* GetDefaultSettings() const override;
+```
+
+## 详细描述
+
+返回音频资源的默认导入设置。当前版本音频加载器不使用导入设置，始终返回 `nullptr`。
+
+## 返回值
+
+`ImportSettings*` - 始终返回 `nullptr`。
+
+## 示例
+
+```cpp
+AudioLoader loader;
+ImportSettings* settings = loader.GetDefaultSettings();
+
+// 始终为 nullptr
+if (settings == nullptr) {
+    printf("No default settings for AudioLoader\n");
+}
+```

docs/api/resources/audio-loader/getsupportedextensions.md

@@ -0,0 +1,38 @@
+# AudioLoader::GetSupportedExtensions
+
+## 方法签名
+
+```cpp
+Containers::Array<Containers::String> GetSupportedExtensions() const override;
+```
+
+## 详细描述
+
+返回此加载器支持的所有音频文件扩展名。扩展名列表用于 `ResourceManager` 确定给定文件应由哪个加载器处理。
+
+## 返回值
+
+返回 `Containers::Array<Containers::String>`，包含所有支持的扩展名小写形式。
+
+**支持的格式：**
+
+| 扩展名 | 格式 |
+|--------|------|
+| `wav` | WAV (Waveform Audio File Format) |
+| `ogg` | OGG (Ogg Vorbis) |
+| `mp3` | MP3 (MPEG-1 Audio Layer III) |
+| `flac` | FLAC (Free Lossless Audio Codec) |
+| `aiff` | AIFF (Audio Interchange File Format) |
+| `aif` | AIFF (旧版扩展名) |
+
+## 示例
+
+```cpp
+AudioLoader loader;
+Array<String> extensions = loader.GetSupportedExtensions();
+
+for (const auto& ext : extensions) {
+    printf("Supported: %s\n", ext.CStr());
+}
+// 输出: wav, ogg, mp3, flac, aiff, aif
+```

docs/api/resources/audio-loader/index.md

@@ -0,0 +1,56 @@
+# AudioLoader
+
+## 命名空间
+
+`XCEngine::Resources`
+
+## 类型
+
+类 (Class)
+
+## 描述
+
+音频资源加载器，负责从文件系统加载音频文件并转换为 `AudioClip` 资源。支持 WAV、OGG、MP3、FLAC、AIFF 等常见音频格式。
+
+## 概述
+
+`AudioLoader` 继承自 `IResourceLoader` 接口，实现音频资源的异步加载与格式解析。内部通过文件扩展名和文件头数据双重检测确定音频格式，确保加载结果的准确性。
+
+## 公共方法表格
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| `AudioLoader()` | - | 构造函数 |
+| `~AudioLoader()` | - | 析构函数 |
+| `GetResourceType()` | `ResourceType` | 返回资源类型 `AudioClip` |
+| `GetSupportedExtensions()` | `Array<String>` | 获取支持的扩展名列表 |
+| `CanLoad(path)` | `bool` | 检查是否能够加载指定路径的资源 |
+| `Load(path, settings)` | `LoadResult` | 加载音频资源 |
+| `GetDefaultSettings()` | `ImportSettings*` | 获取默认导入设置 |
+
+## 使用示例
+
+```cpp
+#include "Resources/AudioLoader.h"
+#include "Resources/ResourceManager.h"
+
+using namespace XCEngine::Resources;
+
+// 通过 ResourceManager 加载音频
+ResourceGUID guid = ResourceGUID::Generate("assets/audio/bgm_music.ogg");
+LoadResult result = ResourceManager::Get().Load(guid, "assets/audio/bgm_music.ogg");
+
+if (result.IsSuccess()) {
+    AudioClip* clip = result.GetResource<AudioClip>();
+    // 使用音频片段
+}
+```
+
+## 相关文档
+
+- [GetSupportedExtensions](getsupportedextensions.md) - 获取支持的音频格式
+- [CanLoad](canload.md) - 检查资源可加载性
+- [Load](load.md) - 加载音频资源
+- [GetDefaultSettings](getdefaultsettings.md) - 获取默认导入设置
+- [IResourceLoader](../resource-loader/resource-loader.md) - 资源加载器基类
+- [AudioClip](../audioclip/audio-clip.md) - 音频资源类型

docs/api/resources/audio-loader/load.md

@@ -0,0 +1,58 @@
+# AudioLoader::Load
+
+## 方法签名
+
+```cpp
+LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override;
+```
+
+## 详细描述
+
+从指定路径加载音频文件，读取文件数据后自动检测音频格式，并创建包含完整音频数据的 `AudioClip` 对象。
+
+**加载流程：**
+
+1. 调用 `ReadFileData(path)` 读取文件数据
+2. 若读取失败，返回包含错误信息的 `LoadResult`
+3. 调用 `DetectAudioFormat()` 检测音频格式
+4. 创建 `AudioClip` 对象并设置路径、名称、GUID
+5. 调用 `SetAudioFormat()` 和 `SetAudioData()` 设置音频属性
+6. 计算内存占用并返回成功结果
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `path` | `const Containers::String&` | 音频文件的完整或相对路径 |
+| `settings` | `const ImportSettings*` | 导入设置（当前版本未使用，始终为 `nullptr`） |
+
+## 返回值
+
+`LoadResult` - 成功时包含 `AudioClip*` 指针，失败时包含错误信息字符串。
+
+## 示例
+
+```cpp
+#include "Resources/AudioLoader.h"
+#include "Resources/ResourceManager.h"
+
+using namespace XCEngine::Resources;
+
+AudioLoader loader;
+LoadResult result = loader.Load("assets/audio/bgm_music.ogg");
+
+if (result.IsSuccess()) {
+    AudioClip* audioClip = result.GetResource<AudioClip>();
+    
+    printf("Loaded: %s\n", audioClip->m_name.CStr());
+    printf("Format: %d\n", static_cast<int>(audioClip->GetAudioFormat()));
+    printf("Size: %zu bytes\n", audioClip->m_memorySize);
+} else {
+    printf("Error: %s\n", result.GetError().CStr());
+}
+```
+
+## 注意事项
+
+- 当前实现 `ParseWAVData()` 方法为空，WAV 格式解析逻辑尚未完成
+- `settings` 参数当前版本未使用，保留接口兼容性

docs/api/resources/audioclip/audio-clip.md

@@ -0,0 +1,89 @@
+# AudioClip
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class`
+
+**描述**: 音频片段资源类，管理音频样本数据、格式信息和播放参数。
+
+## 概述
+
+`AudioClip` 是 XCEngine 中的音频资源类，继承自 `IResource`。它管理音频的原始样本数据、采样率、通道数、位深度、时长、格式类型和播放参数。AudioClip 支持 WAV、OGG、MP3、FLAC 等多种音频格式，可用于音效、音乐、语音和环境音等不同用途。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [`AudioClip`](audio-clip.md) | 构造函数 |
+| [`~AudioClip`](dtor.md) | 析构函数 |
+| [`GetType`](get-type.md) | 获取资源类型 |
+| [`GetName`](get-name.md) | 获取音频名称 |
+| [`GetPath`](get-path.md) | 获取音频路径 |
+| [`GetGUID`](get-guid.md) | 获取全局唯一标识符 |
+| [`IsValid`](is-valid.md) | 检查音频是否有效 |
+| [`GetMemorySize`](get-memory-size.md) | 获取内存大小 |
+| [`Release`](release.md) | 释放音频资源 |
+| [`SetAudioData`](setaudiodata.md) | 设置音频数据 |
+| [`GetAudioData`](get-audio-data.md) | 获取音频数据 |
+| [`SetSampleRate`](set-sample-rate.md) | 设置采样率 |
+| [`GetSampleRate`](get-sample-rate.md) | 获取采样率 |
+| [`SetChannels`](set-channels.md) | 设置通道数 |
+| [`GetChannels`](get-channels.md) | 获取通道数 |
+| [`SetBitsPerSample`](set-bits-per-sample.md) | 设置位深度 |
+| [`GetBitsPerSample`](get-bits-per-sample.md) | 获取位深度 |
+| [`SetDuration`](set-duration.md) | 设置时长 |
+| [`GetDuration`](get-duration.md) | 获取时长 |
+| [`SetAudioFormat`](set-audio-format.md) | 设置音频格式 |
+| [`GetAudioFormat`](get-audio-format.md) | 获取音频格式 |
+| [`SetAudioType`](set-audio-type.md) | 设置音频类型 |
+| [`GetAudioType`](get-audio-type.md) | 获取音频类型 |
+| [`SetIs3D`](set-is-3d.md) | 设置是否为 3D 音频 |
+| [`Is3D`](is-3d.md) | 检查是否为 3D 音频 |
+| [`SetLoop`](set-loop.md) | 设置是否循环播放 |
+| [`IsLoop`](is-loop.md) | 检查是否循环播放 |
+| [`GetRHIResource`](get-rhi-resource.md) | 获取 RHI 音频缓冲区 |
+| [`SetRHIResource`](set-rhi-resource.md) | 设置 RHI 音频缓冲区 |
+
+## 使用示例
+
+```cpp
+#include "Resources/AudioClip.h"
+#include "Resources/ResourceManager.h"
+#include "Resources/ResourceFileSystem.h"
+
+using namespace XCEngine::Resources;
+
+AudioClip* CreateExplosionSound() {
+    AudioClip* clip = new AudioClip();
+    
+    auto wavData = ResourceFileSystem::Get().ReadResource("sounds/explosion.wav");
+    clip->SetAudioData(wavData);
+    clip->SetSampleRate(44100);
+    clip->SetChannels(2);
+    clip->SetBitsPerSample(16);
+    clip->SetDuration(1.5f);
+    clip->SetAudioFormat(AudioFormat::WAV);
+    clip->SetAudioType(AudioType::SoundEffect);
+    clip->SetLoop(false);
+    clip->SetIs3D(false);
+    
+    return clip;
+}
+
+void PlaySoundEffect() {
+    ResourceHandle<AudioClip> sfx = ResourceManager::Get().Load<AudioClip>("sounds/explosion.wav");
+    
+    if (sfx->IsValid()) {
+        uint32_t sampleRate = sfx->GetSampleRate();
+        float duration = sfx->GetDuration();
+        bool loop = sfx->IsLoop();
+        AudioFormat format = sfx->GetAudioFormat();
+        AudioType type = sfx->GetAudioType();
+    }
+}
+```
+
+## 相关文档
+
+- [IResource](../iresource/iresource.md) - 资源基类
+- [Resources](../resources.md) - 资源模块总览

docs/api/resources/audioclip/audioclip.md

@@ -4,6 +4,8 @@
 
 **类型**: `class`
 
+**头文件**: `XCEngine/Resources/AudioClip.h`
+
 **描述**: 音频片段资源类，管理音频样本数据、格式信息和播放参数。
 
 ## 概述
@@ -13,7 +15,7 @@
 ## 头文件
 
 ```cpp
-#include <XCEngine/Resources/AudioClip.h>
+#include "Resources/AudioClip.h"
 ```
 
 ## 枚举类型
@@ -59,7 +61,7 @@
 
 | 方法 | 描述 |
 |------|------|
-| `void SetAudioData(const Containers::Array<Core::uint8>& data)` | 设置音频数据（根据采样率、通道数、位深度自动计算时长） |
+| `void SetAudioData(const Containers::Array<Core::uint8>& data)` | 设置音频数据（需先设置采样率、通道数、位深度，自动计算时长） |
 | `const Containers::Array<Core::uint8>& GetAudioData() const` | 获取音频数据指针 |
 
 ## 实现说明

docs/api/resources/audioclip/ctor.md

@@ -0,0 +1,23 @@
+# AudioClip::AudioClip
+
+```cpp
+AudioClip()
+```
+
+构造一个新的 `AudioClip` 实例。
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+#include "Resources/AudioClip.h"
+
+using namespace XCEngine::Resources;
+
+AudioClip* clip = new AudioClip();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览

docs/api/resources/audioclip/dtor.md

@@ -0,0 +1,26 @@
+# AudioClip::~AudioClip
+
+```cpp
+virtual ~AudioClip() override
+```
+
+销毁 `AudioClip` 实例并释放相关资源。
+
+**线程安全：** ❌ （不应在多线程中同时访问正在销毁的对象）
+
+**示例：**
+
+```cpp
+#include "Resources/AudioClip.h"
+
+using namespace XCEngine::Resources;
+
+{
+    AudioClip clip;
+    clip.SetAudioFormat(AudioFormat::WAV);
+}
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览

docs/api/resources/audioclip/get-audio-data.md

@@ -0,0 +1,29 @@
+# AudioClip::GetAudioData
+
+```cpp
+const Containers::Array<Core::uint8>& GetAudioData() const
+```
+
+获取音频的原始样本数据。
+
+**返回：** 音频数据字节数组的常量引用
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+auto wavData = ResourceFileSystem::Get().ReadResource("sounds/explosion.wav");
+clip.SetAudioData(wavData);
+
+const Containers::Array<Core::uint8>& data = clip.GetAudioData();
+size_t dataSize = data.Size();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [SetAudioData](setaudiodata.md) - 设置音频数据

docs/api/resources/audioclip/get-audio-format.md

@@ -0,0 +1,26 @@
+# AudioClip::GetAudioFormat
+
+```cpp
+AudioFormat GetAudioFormat() const
+```
+
+获取音频的格式。
+
+**返回：** `AudioFormat` 枚举值
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetAudioFormat(AudioFormat::OGG);
+AudioFormat format = clip.GetAudioFormat();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [SetAudioFormat](set-audio-format.md) - 设置音频格式

docs/api/resources/audioclip/get-audio-type.md

@@ -0,0 +1,26 @@
+# AudioClip::GetAudioType
+
+```cpp
+AudioType GetAudioType() const
+```
+
+获取音频的类型。
+
+**返回：** `AudioType` 枚举值
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetAudioType(AudioType::Voice);
+AudioType type = clip.GetAudioType();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [SetAudioType](set-audio-type.md) - 设置音频类型

docs/api/resources/audioclip/get-bits-per-sample.md

@@ -0,0 +1,26 @@
+# AudioClip::GetBitsPerSample
+
+```cpp
+Core::uint32 GetBitsPerSample() const
+```
+
+获取音频的位深度。
+
+**返回：** 位深度（8、16、24、32）
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetBitsPerSample(16);
+uint32_t bits = clip.GetBitsPerSample();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [SetBitsPerSample](set-bits-per-sample.md) - 设置位深度

docs/api/resources/audioclip/get-channels.md

@@ -0,0 +1,26 @@
+# AudioClip::GetChannels
+
+```cpp
+Core::uint32 GetChannels() const
+```
+
+获取音频的通道数。
+
+**返回：** 通道数（1=单声道，2=立体声）
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetChannels(2);
+uint32_t channels = clip.GetChannels();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [SetChannels](set-channels.md) - 设置通道数

docs/api/resources/audioclip/get-duration.md

@@ -0,0 +1,26 @@
+# AudioClip::GetDuration
+
+```cpp
+float GetDuration() const
+```
+
+获取音频的时长。
+
+**返回：** 时长（秒）
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetDuration(3.0f);
+float duration = clip.GetDuration();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [SetDuration](set-duration.md) - 设置时长

docs/api/resources/audioclip/get-guid.md

@@ -0,0 +1,25 @@
+# AudioClip::GetGUID
+
+```cpp
+ResourceGUID GetGUID() const override
+```
+
+获取音频资源的全局唯一标识符。
+
+**返回：** 资源 GUID
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+ResourceGUID guid = clip.GetGUID();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [IResource](../iresource/iresource.md) - 资源基类

docs/api/resources/audioclip/get-memory-size.md

@@ -0,0 +1,25 @@
+# AudioClip::GetMemorySize
+
+```cpp
+size_t GetMemorySize() const override
+```
+
+获取音频资源占用的内存大小。
+
+**返回：** 内存大小（字节）
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+size_t memSize = clip.GetMemorySize();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [IResource](../iresource/iresource.md) - 资源基类

docs/api/resources/audioclip/get-name.md

@@ -0,0 +1,25 @@
+# AudioClip::GetName
+
+```cpp
+const Containers::String& GetName() const override
+```
+
+获取音频资源的名称。
+
+**返回：** 音频名称的常量引用
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+Containers::String name = clip.GetName();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [IResource](../iresource/iresource.md) - 资源基类

docs/api/resources/audioclip/get-path.md

@@ -0,0 +1,25 @@
+# AudioClip::GetPath
+
+```cpp
+const Containers::String& GetPath() const override
+```
+
+获取音频资源的路径。
+
+**返回：** 音频路径的常量引用
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+Containers::String path = clip.GetPath();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [IResource](../iresource/iresource.md) - 资源基类

docs/api/resources/audioclip/get-rhi-resource.md

@@ -0,0 +1,27 @@
+# AudioClip::GetRHIResource
+
+```cpp
+class IRHIAudioBuffer* GetRHIResource() const
+```
+
+获取 RHI 音频缓冲区资源指针。
+
+**返回：** `IRHIAudioBuffer` 指针，如果未设置则返回 `nullptr`
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+IRHIAudioBuffer* rhi = clip.GetRHIResource();
+if (rhi != nullptr) {
+}
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [SetRHIResource](set-rhi-resource.md) - 设置 RHI 音频缓冲区

docs/api/resources/audioclip/get-sample-rate.md

@@ -0,0 +1,26 @@
+# AudioClip::GetSampleRate
+
+```cpp
+Core::uint32 GetSampleRate() const
+```
+
+获取音频的采样率。
+
+**返回：** 采样率（Hz）
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetSampleRate(48000);
+uint32_t rate = clip.GetSampleRate();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [SetSampleRate](set-sample-rate.md) - 设置采样率

docs/api/resources/audioclip/get-type.md

@@ -0,0 +1,25 @@
+# AudioClip::GetType
+
+```cpp
+ResourceType GetType() const override
+```
+
+返回资源的类型标识符。
+
+**返回：** `ResourceType::AudioClip`
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+ResourceType type = clip.GetType();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [IResource](../iresource/iresource.md) - 资源基类

docs/api/resources/audioclip/is-3d.md

@@ -0,0 +1,26 @@
+# AudioClip::Is3D
+
+```cpp
+bool Is3D() const
+```
+
+检查音频是否为 3D 音频。
+
+**返回：** 如果是 3D 音频返回 `true`，否则返回 `false`
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetIs3D(false);
+bool is3D = clip.Is3D();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [SetIs3D](set-is-3d.md) - 设置是否为 3D 音频

docs/api/resources/audioclip/is-loop.md

@@ -0,0 +1,26 @@
+# AudioClip::IsLoop
+
+```cpp
+bool IsLoop() const
+```
+
+检查音频是否循环播放。
+
+**返回：** 如果循环播放返回 `true`，否则返回 `false`
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetLoop(false);
+bool loop = clip.IsLoop();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [SetLoop](set-loop.md) - 设置是否循环播放

docs/api/resources/audioclip/is-valid.md

@@ -0,0 +1,25 @@
+# AudioClip::IsValid
+
+```cpp
+bool IsValid() const override
+```
+
+检查音频资源是否有效。
+
+**返回：** 如果资源有效返回 `true`，否则返回 `false`
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+bool valid = clip.IsValid();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [IResource](../iresource/iresource.md) - 资源基类

docs/api/resources/audioclip/release.md

@@ -0,0 +1,36 @@
+# AudioClip::Release
+
+```cpp
+void Release()
+```
+
+释放音频资源，释放存储的音频数据并清除 RHI 资源引用。
+
+## 详细描述
+
+调用此方法后：
+1. 清除音频数据（调用 `m_audioData.Clear()`）
+2. 将 RHI 资源引用置为 `nullptr`
+3. 将 `m_isValid` 标记为 `false`
+
+## 参数
+
+无
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+ResourceHandle<AudioClip> sfx = ResourceManager::Get().Load<AudioClip>("sounds/explosion.wav");
+sfx->Release();
+if (!sfx->IsValid()) {
+    // 音频已释放
+}
+```
+
+## 相关文档
+
+- [AudioClip 总览](audioclip.md) - 返回类总览

docs/api/resources/audioclip/set-audio-format.md

@@ -0,0 +1,27 @@
+# AudioClip::SetAudioFormat
+
+```cpp
+void SetAudioFormat(AudioFormat format)
+```
+
+设置音频的格式。
+
+**参数：**
+- `format` - 音频格式（`AudioFormat::Unknown`、`AudioFormat::WAV`、`AudioFormat::OGG`、`AudioFormat::MP3`、`AudioFormat::FLAC`）
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetAudioFormat(AudioFormat::WAV);
+AudioFormat format = clip.GetAudioFormat();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [GetAudioFormat](get-audio-format.md) - 获取音频格式

docs/api/resources/audioclip/set-audio-type.md

@@ -0,0 +1,27 @@
+# AudioClip::SetAudioType
+
+```cpp
+void SetAudioType(AudioType type)
+```
+
+设置音频的类型。
+
+**参数：**
+- `type` - 音频类型（`AudioType::SoundEffect`、`AudioType::Music`、`AudioType::Voice`、`AudioType::Ambient`）
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetAudioType(AudioType::Music);
+AudioType type = clip.GetAudioType();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [GetAudioType](get-audio-type.md) - 获取音频类型

docs/api/resources/audioclip/set-bits-per-sample.md

@@ -0,0 +1,27 @@
+# AudioClip::SetBitsPerSample
+
+```cpp
+void SetBitsPerSample(Core::uint32 bits)
+```
+
+设置音频的位深度。
+
+**参数：**
+- `bits` - 位深度（8、16、24、32）
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetBitsPerSample(16);
+uint32_t bits = clip.GetBitsPerSample();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [GetBitsPerSample](get-bits-per-sample.md) - 获取位深度

docs/api/resources/audioclip/set-channels.md

@@ -0,0 +1,27 @@
+# AudioClip::SetChannels
+
+```cpp
+void SetChannels(Core::uint32 channels)
+```
+
+设置音频的通道数。
+
+**参数：**
+- `channels` - 通道数（1=单声道，2=立体声）
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetChannels(2);
+uint32_t channels = clip.GetChannels();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [GetChannels](get-channels.md) - 获取通道数

docs/api/resources/audioclip/set-duration.md

@@ -0,0 +1,27 @@
+# AudioClip::SetDuration
+
+```cpp
+void SetDuration(float seconds)
+```
+
+设置音频的时长。
+
+**参数：**
+- `seconds` - 时长（秒）
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetDuration(2.5f);
+float duration = clip.GetDuration();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [GetDuration](get-duration.md) - 获取时长

docs/api/resources/audioclip/set-is-3d.md

@@ -0,0 +1,27 @@
+# AudioClip::SetIs3D
+
+```cpp
+void SetIs3D(bool is3D)
+```
+
+设置音频是否为 3D 音频。
+
+**参数：**
+- `is3D` - 是否为 3D 音频
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetIs3D(true);
+bool is3D = clip.Is3D();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [Is3D](is-3d.md) - 检查是否为 3D 音频

docs/api/resources/audioclip/set-loop.md

@@ -0,0 +1,27 @@
+# AudioClip::SetLoop
+
+```cpp
+void SetLoop(bool loop)
+```
+
+设置音频是否循环播放。
+
+**参数：**
+- `loop` - 是否循环播放
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetLoop(true);
+bool loop = clip.IsLoop();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [IsLoop](is-loop.md) - 检查是否循环播放

docs/api/resources/audioclip/set-rhi-resource.md

@@ -0,0 +1,28 @@
+# AudioClip::SetRHIResource
+
+```cpp
+void SetRHIResource(class IRHIAudioBuffer* resource)
+```
+
+设置 RHI 音频缓冲区资源。
+
+**参数：**
+- `resource` - `IRHIAudioBuffer` 指针
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+IRHIAudioBuffer* rhiBuffer = CreateRHIBuffer();
+clip.SetRHIResource(rhiBuffer);
+IRHIAudioBuffer* rhi = clip.GetRHIResource();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [GetRHIResource](get-rhi-resource.md) - 获取 RHI 音频缓冲区

docs/api/resources/audioclip/set-sample-rate.md

@@ -0,0 +1,27 @@
+# AudioClip::SetSampleRate
+
+```cpp
+void SetSampleRate(Core::uint32 rate)
+```
+
+设置音频的采样率。
+
+**参数：**
+- `rate` - 采样率（Hz），常用值为 44100、48000 等
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+using namespace XCEngine::Resources;
+
+AudioClip clip;
+clip.SetSampleRate(44100);
+uint32_t rate = clip.GetSampleRate();
+```
+
+## 相关文档
+
+- [AudioClip 总览](audio-clip.md) - 返回类总览
+- [GetSampleRate](get-sample-rate.md) - 获取采样率

docs/api/resources/dependencygraph/dependencygraph.md

@@ -4,6 +4,8 @@
 
 **类型**: `class`
 
+**头文件**: `XCEngine/Resources/DependencyGraph.h`
+
 **描述**: 资源依赖图管理器，负责跟踪资源之间的依赖关系、引用计数和拓扑排序。
 
 ## 概述

docs/api/resources/filearchive/close.md

@@ -0,0 +1,22 @@
+# FileArchive::Close
+
+关闭归档。
+
+## 方法签名
+
+```cpp
+void Close() override;
+```
+
+## 详细描述
+
+关闭归档并重置内部状态。清空归档路径并标记为无效状态。
+
+## 示例
+
+```cpp
+FileArchive archive;
+archive.Open("resources/textures/");
+// 使用归档...
+archive.Close();
+```

docs/api/resources/filearchive/enumerate.md

@@ -0,0 +1,31 @@
+# FileArchive::Enumerate
+
+枚举匹配的文件。
+
+## 方法签名
+
+```cpp
+void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const override;
+```
+
+## 详细描述
+
+枚举归档目录中与指定模式匹配的文件。当前实现为 stub，仅清空输出数组，未实现实际的模式匹配功能。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `pattern` | `const Containers::String&` | 文件匹配模式（如 `*.png`、`textures/*.jpg`） |
+| `outFiles` | `Containers::Array<Containers::String>&` | 输出容器，接收匹配的文件路径列表 |
+
+## 示例
+
+```cpp
+FileArchive archive;
+archive.Open("resources/");
+
+Containers::Array<Containers::String> files;
+archive.Enumerate("*.png", files);
+// 注意：当前实现返回空数组
+```

docs/api/resources/filearchive/exists.md

@@ -0,0 +1,36 @@
+# FileArchive::Exists
+
+检查文件是否存在。
+
+## 方法签名
+
+```cpp
+bool Exists(const Containers::String& fileName) const override;
+```
+
+## 详细描述
+
+检查归档内是否存在指定文件。文件路径是相对于归档目录的路径。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `fileName` | `const Containers::String&` | 要检查的文件名（相对于归档路径） |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `bool` | 文件存在返回 `true`，否则返回 `false` |
+
+## 示例
+
+```cpp
+FileArchive archive;
+archive.Open("resources/");
+
+if (archive.Exists("textures/player.png")) {
+    // 文件存在
+}
+```

docs/api/resources/filearchive/filearchive.md

@@ -2,19 +2,17 @@
 
 **命名空间**: `XCEngine::Resources`
 
-**类型**: `class` (extends IArchive)
+**类型**: `class`
 
-**描述**: 文件归档封装类，用于读取归档包（如 .pak、.zip）中的资源文件。
+**头文件**: `XCEngine/Resources/FileArchive.h`
+
+**继承自**: `IArchive`
+
+**描述**: 文件归档读取器，将文件系统目录作为虚拟归档进行访问。
 
 ## 概述
 
-`FileArchive` 实现了 `IArchive` 接口，提供从单个归档包文件中读取资源的功能。它维护已打开归档的路径和有效性状态。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Resources/FileArchive.h>
-```
+`FileArchive` 实现了 `IArchive` 接口，用于将文件系统目录作为虚拟归档进行访问。它维护已打开目录的路径和有效性状态，支持读取文件、检查存在性、获取文件大小等操作。
 
 ## 继承关系
 
@@ -25,60 +23,53 @@ IArchive
 
 ## 公共方法
 
-### 构造与析构
-
 | 方法 | 描述 |
 |------|------|
-| `FileArchive()` | 默认构造 |
-| `~FileArchive()` | 析构函数，关闭归档 |
-
-### IArchive 接口实现
-
-| 方法 | 描述 |
-|------|------|
-| `bool Open(const Containers::String& path) override` | 打开归档文件 |
-| `void Close() override` | 关闭归档文件 |
-| `bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const override` | 从归档中读取文件数据 |
-| `size_t GetSize(const Containers::String& fileName) const override` | 获取归档内文件大小 |
-| `bool Exists(const Containers::String& fileName) const override` | 检查文件是否存在于归档中 |
-| `void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const override` | 枚举归档内匹配的文件（当前为 stub） |
-| `bool IsValid() const override` | 检查归档是否有效 |
-
-## 实现说明
-
-**注意**: `Enumerate()` 当前为 stub，仅清空输出数组。
-
-### 访问器
-
-| 方法 | 描述 |
-|------|------|
-| `const Containers::String& GetPath() const` | 获取归档文件路径 |
+| [`FileArchive()`](filearchive.md) | 默认构造 |
+| [`~FileArchive()`](filearchive.md) | 析构函数，自动关闭归档 |
+| [`Open(...)`](open.md) | 打开归档目录 |
+| [`Close()`](close.md) | 关闭归档 |
+| [`Read(...)`](read.md) | 读取文件数据 |
+| [`GetSize(...)`](getsize.md) | 获取文件大小 |
+| [`Exists(...)`](exists.md) | 检查文件是否存在 |
+| [`Enumerate(...)`](enumerate.md) | 枚举匹配的文件（暂未实现） |
+| [`IsValid()`](filearchive.md) | 检查归档是否有效 |
+| [`GetPath()`](filearchive.md) | 获取归档路径 |
 
 ## 使用示例
 
 ```cpp
+#include <XCEngine/Resources/FileArchive.h>
+
+// 创建并打开归档
 FileArchive archive;
-if (archive.Open("data/resources.pak")) {
+if (archive.Open("resources/textures/")) {
     // 检查文件是否存在
-    if (archive.Exists("textures/player.png")) {
+    if (archive.Exists("player.png")) {
         // 获取文件大小
-        size_t size = archive.GetSize("textures/player.png");
+        size_t size = archive.GetSize("player.png");
         
         // 读取文件内容
         Containers::Array<Core::uint8> buffer(size);
-        archive.Read("textures/player.png", buffer.Data(), size, 0);
+        if (archive.Read("player.png", buffer.Data(), size, 0)) {
+            // 处理文件数据
+        }
     }
     
-    // 枚举文件
+    // 枚举匹配的文件
     Containers::Array<Containers::String> files;
-    archive.Enumerate("textures/*.png", files);
+    archive.Enumerate("*.png", files);
     
     archive.Close();
 }
 ```
 
+## 实现说明
+
+- `Enumerate()` 当前为 stub，仅清空输出数组，未实现模式匹配功能。
+
 ## 相关文档
 
-- [IArchive](../filesystem/filesystem.md) - 归档接口
-- [ResourceFileSystem](../filesystem/filesystem.md) - 资源文件系统
-- [Resources 总览](../resources.md) - 返回模块总览
+- [Resources 模块总览](../resources.md) - 返回模块总览
+- [IArchive](../resourcefilesystem/resourcefilesystem.md) - 归档接口定义
+- [ResourceFileSystem](../resourcefilesystem/resourcefilesystem.md) - 资源文件系统

docs/api/resources/filearchive/getsize.md

@@ -0,0 +1,37 @@
+# FileArchive::GetSize
+
+获取文件大小。
+
+## 方法签名
+
+```cpp
+size_t GetSize(const Containers::String& fileName) const override;
+```
+
+## 详细描述
+
+获取归档内指定文件的字节大小。文件路径是相对于归档目录的路径。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `fileName` | `const Containers::String&` | 要查询的文件名（相对于归档路径） |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `size_t` | 文件字节大小，文件不存在或归档无效时返回 0 |
+
+## 示例
+
+```cpp
+FileArchive archive;
+archive.Open("resources/");
+
+size_t size = archive.GetSize("textures/player.png");
+if (size > 0) {
+    // 文件存在，准备读取
+}
+```

docs/api/resources/filearchive/open.md

@@ -0,0 +1,34 @@
+# FileArchive::Open
+
+打开归档目录。
+
+## 方法签名
+
+```cpp
+bool Open(const Containers::String& path) override;
+```
+
+## 详细描述
+
+打开指定路径的目录作为归档。归档路径可以是绝对路径或相对路径。方法会设置内部路径并标记归档为有效状态。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `path` | `const Containers::String&` | 归档目录路径 |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `bool` | 始终返回 `true`。当前实现不验证路径是否真实存在。 |
+
+## 示例
+
+```cpp
+FileArchive archive;
+if (archive.Open("resources/textures/")) {
+    // 归档已打开
+}
+```

docs/api/resources/filearchive/read.md

@@ -0,0 +1,42 @@
+# FileArchive::Read
+
+读取文件数据。
+
+## 方法签名
+
+```cpp
+bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const override;
+```
+
+## 详细描述
+
+从归档中读取指定文件的全部或部分内容。文件路径是相对于归档目录的路径。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `fileName` | `const Containers::String&` | 要读取的文件名（相对于归档路径） |
+| `buffer` | `void*` | 读取数据的目标缓冲区 |
+| `size` | `size_t` | 要读取的字节数 |
+| `offset` | `size_t` | 文件内起始偏移位置 |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `bool` | 读取成功返回 `true`，失败返回 `false` |
+
+## 示例
+
+```cpp
+FileArchive archive;
+archive.Open("resources/");
+
+size_t fileSize = archive.GetSize("textures/player.png");
+Containers::Array<Core::uint8> buffer(fileSize);
+
+if (archive.Read("textures/player.png", buffer.Data(), fileSize, 0)) {
+    // 文件读取成功
+}
+```

docs/api/resources/filesystem/filesystem.md

@@ -4,6 +4,8 @@
 
 **类型**: `class`
 
+**头文件**: `XCEngine/Resources/FileSystem.h`
+
 **描述**: 资源文件系统，负责资源文件的查找、读取和虚拟文件系统（支持目录和归档包）管理。
 
 ## 概述
@@ -46,16 +48,16 @@
 
 | 方法 | 描述 |
 |------|------|
-| `void Initialize(const Containers::String& rootPath)` | 初始化，设置资源根目录 |
-| `void Shutdown()` | 关闭，释放所有归档 |
-| `bool AddArchive(const Containers::String& archivePath)` | 添加归档包（优先查找） |
-| `bool AddDirectory(const Containers::String& directoryPath)` | 添加资源目录 |
-| `void RemoveArchive(const Containers::String& archivePath)` | 移除归档包 |
-| `bool FindResource(const Containers::String& relativePath, Containers::String& outAbsolutePath) const` | 查找资源的绝对路径 |
-| `bool Exists(const Containers::String& relativePath) const` | 检查资源是否存在 |
-| `Containers::Array<Core::uint8> ReadResource(const Containers::String& relativePath) const` | 读取资源文件内容（字节数组） |
-| `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const` | 获取资源信息（部分字段可能未填充） |
-| `void EnumerateResources(const Containers::String& pattern, Containers::Array<ResourceInfo>& outResources) const` | 枚举匹配的资源（当前为 stub，仅清空输出） |
+| `Initialize()` | 初始化，设置资源根目录 |
+| `Shutdown()` | 关闭，释放所有归档 |
+| [`AddArchive`](addarchive.md) | 添加归档包（优先查找） |
+| [`AddDirectory`](adddirectory.md) | 添加资源目录 |
+| [`RemoveArchive`](removearchive.md) | 移除归档包 |
+| [`FindResource`](findresource.md) | 查找资源的绝对路径 |
+| [`Exists`](exists.md) | 检查资源是否存在 |
+| [`ReadResource`](readresource.md) | 读取资源文件内容（字节数组） |
+| [`GetResourceInfo`](getresourceinfo.md) | 获取资源信息 |
+| [`EnumerateResources`](enumerateresources.md) | 枚举匹配的资源 |
 
 ## 实现说明
 

docs/api/resources/iloader/getresourcetype.md

@@ -0,0 +1,23 @@
+# IResourceLoader::GetResourceType
+
+```cpp
+virtual ResourceType GetResourceType() const = 0
+```
+
+获取此加载器所支持的资源类型。纯虚方法，子类必须实现。
+
+**参数：** 无
+
+**返回：** `ResourceType` 枚举值，标识资源类型（如 `ResourceType::Texture`、`ResourceType::Mesh` 等）
+
+**示例：**
+
+```cpp
+ResourceType TextureLoader::GetResourceType() const {
+    return ResourceType::Texture;
+}
+```
+
+## 相关文档
+
+- [IResourceLoader 总览](iloader.md) - 返回类总览

docs/api/resources/iloader/iloader.md

@@ -4,6 +4,8 @@
 
 **类型**: `class` (abstract)
 
+**头文件**: `XCEngine/Resources/ILoader.h`
+
 **描述**: 资源加载器抽象接口，定义了资源加载的标准协议。每个资源类型需要提供对应的加载器实现。
 
 ## 概述
@@ -34,22 +36,22 @@ struct LoadResult {
 
 | 方法 | 描述 |
 |------|------|
-| `ResourceType GetResourceType() const` | 获取此加载器支持的资源类型 |
-| `Containers::Array<Containers::String> GetSupportedExtensions() const` | 获取支持的文件扩展名列表 |
-| `bool CanLoad(const Containers::String& path) const` | 检查此加载器是否能加载指定路径 |
-| `ImportSettings* GetDefaultSettings() const` | 获取默认导入设置 |
+| [`GetResourceType`](getresourcetype.md) | 获取此加载器支持的资源类型 |
+| [`GetSupportedExtensions`](getsupportedextensions.md) | 获取支持的文件扩展名列表 |
+| [`CanLoad`](canload.md) | 检查此加载器是否能加载指定路径 |
+| [`GetDefaultSettings`](getdefaultsettings.md) | 获取默认导入设置 |
 
 ### 同步加载
 
 | 方法 | 描述 |
 |------|------|
-| `LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr)` | 同步加载资源 |
+| [`Load`](load.md) | 同步加载资源 |
 
 ### 异步加载
 
 | 方法 | 描述 |
 |------|------|
-| `void LoadAsync(const Containers::String& path, const ImportSettings* settings, std::function<void(LoadResult)> callback)` | 异步加载资源（内部默认实现调用同步 Load） |
+| [`LoadAsync`](loadasync.md) | 异步加载资源（带默认实现，子类可重写） |
 
 ### 辅助方法（受保护）
 

docs/api/resources/iresource/getguid.md

@@ -0,0 +1,29 @@
+# IResource::GetGUID
+
+```cpp
+virtual ResourceGUID GetGUID() const = 0
+```
+
+获取全局唯一标识符。纯虚方法，由具体资源类实现，返回资源的唯一 GUID。
+
+**参数：** 无
+
+**返回：** `ResourceGUID` - 资源的全局唯一标识符
+
+**异常：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/player.mat");
+ResourceGUID guid = mat->GetGUID();
+// guid 是根据路径生成的唯一标识符
+```
+
+## 相关文档
+
+- [IResource 总览](iresource.md) - 返回类总览

docs/api/resources/iresource/getmemorysize.md

@@ -0,0 +1,29 @@
+# IResource::GetMemorySize
+
+```cpp
+virtual size_t GetMemorySize() const = 0
+```
+
+获取资源占用的内存大小。纯虚方法，由具体资源类实现，返回资源在内存中的字节数。
+
+**参数：** 无
+
+**返回：** `size_t` - 资源占用的内存大小（字节）
+
+**异常：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
+size_t size = mesh->GetMemorySize();
+// size == 内存占用字节数
+```
+
+## 相关文档
+
+- [IResource 总览](iresource.md) - 返回类总览

docs/api/resources/iresource/getname.md

@@ -0,0 +1,29 @@
+# IResource::GetName
+
+```cpp
+virtual const Containers::String& GetName() const = 0
+```
+
+获取资源名称。纯虚方法，由具体资源类实现，返回资源的显示名称。
+
+**参数：** 无
+
+**返回：** `const Containers::String&` - 资源名称的常量引用
+
+**异常：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
+const Containers::String& name = mesh->GetName();
+// name == "player"
+```
+
+## 相关文档
+
+- [IResource 总览](iresource.md) - 返回类总览

docs/api/resources/iresource/getpath.md

@@ -0,0 +1,29 @@
+# IResource::GetPath
+
+```cpp
+virtual const Containers::String& GetPath() const = 0
+```
+
+获取资源路径。纯虚方法，由具体资源类实现，返回资源在文件系统中的相对路径。
+
+**参数：** 无
+
+**返回：** `const Containers::String&` - 资源路径的常量引用
+
+**异常：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+const Containers::String& path = tex->GetPath();
+// path == "textures/player.png"
+```
+
+## 相关文档
+
+- [IResource 总览](iresource.md) - 返回类总览

docs/api/resources/iresource/gettype.md

@@ -0,0 +1,30 @@
+# IResource::GetType
+
+```cpp
+virtual ResourceType GetType() const = 0
+```
+
+获取资源类型。纯虚方法，由具体资源类实现，返回该资源所属的类型枚举值。
+
+**参数：** 无
+
+**返回：** `ResourceType` - 资源类型枚举
+
+**异常：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+ResourceType type = tex->GetType();
+// type == ResourceType::Texture
+```
+
+## 相关文档
+
+- [IResource 总览](iresource.md) - 返回类总览
+- [ResourceTypes](../resourcetypes/resourcetypes.md) - 资源类型定义

docs/api/resources/iresource/initialize.md

@@ -11,6 +11,10 @@ void Initialize(const ConstructParams& params)
 
 **返回：** 无
 
+**异常：** 无
+
+**线程安全：** ❌
+
 **复杂度：** O(1)
 
 **示例：**

docs/api/resources/iresource/iresource.md

@@ -4,6 +4,8 @@
 
 **类型**: `class` (abstract)
 
+**头文件**: `XCEngine/Resources/IResource.h`
+
 **描述**: 资源基类接口，所有具体资源类型（Texture、Mesh、Material 等）都必须继承自此类。
 
 ## 概述
@@ -14,25 +16,24 @@
 
 | 方法 | 描述 |
 |------|------|
-| `ResourceType GetType() const` | 获取资源类型 |
-| `const Containers::String& GetName() const` | 获取资源名称 |
-| `const Containers::String& GetPath() const` | 获取资源路径 |
-| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
-| `bool IsValid() const` | 检查资源是否有效 |
-| `size_t GetMemorySize() const` | 获取资源占用的内存大小（字节） |
-| `void Release()` | 释放资源引用 |
-| `void Initialize(const ConstructParams& params)` | 使用构造参数初始化资源 |
-| `void SetInvalid()` | 将资源标记为无效 |
+| [`GetType()`](gettype.md) | 获取资源类型 |
+| [`GetName()`](getname.md) | 获取资源名称 |
+| [`GetPath()`](getpath.md) | 获取资源路径 |
+| [`GetGUID()`](getguid.md) | 获取全局唯一标识符 |
+| [`IsValid()`](isvalid.md) | 检查资源是否有效 |
+| [`GetMemorySize()`](getmemorysize.md) | 获取资源占用的内存大小（字节） |
+| [`Release()`](release.md) | 释放资源引用 |
+| [`Initialize()`](initialize.md) | 使用构造参数初始化资源 |
+| [`SetInvalid()`](setinvalid.md) | 将资源标记为无效 |
 
-### 构造参数
+### 构造参数结构体 `ConstructParams`
 
 | 成员 | 类型 | 描述 |
 |------|------|------|
-| `m_name` | `Containers::String` | 资源名称 |
-| `m_path` | `Containers::String` | 资源路径 |
-| `m_guid` | `ResourceGUID` | 全局唯一标识符 |
-| `m_isValid` | `bool` | 资源是否有效 |
-| `m_memorySize` | `size_t` | 内存占用大小 |
+| `name` | `Containers::String` | 资源名称 |
+| `path` | `Containers::String` | 资源路径 |
+| `guid` | `ResourceGUID` | 全局唯一标识符 |
+| `memorySize` | `size_t` | 内存占用大小（字节），默认 0 |
 
 ## 使用示例
 
@@ -51,7 +52,4 @@ public:
 
 ## 相关文档
 
-- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄
-- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
-- [ResourceTypes](../resourcetypes/resourcetypes.md) - 资源类型定义
 - [Resources 总览](../resources.md) - 返回模块总览

docs/api/resources/iresource/isvalid.md

@@ -0,0 +1,33 @@
+# IResource::IsValid
+
+```cpp
+virtual bool IsValid() const = 0
+```
+
+检查资源是否有效。纯虚方法，由具体资源类实现，返回资源当前的有效状态。
+
+**参数：** 无
+
+**返回：** `bool` - 资源有效返回 `true`，无效返回 `false`
+
+**异常：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+if (tex->IsValid()) {
+    // 资源加载成功，可以使用
+} else {
+    // 资源加载失败或已被释放
+}
+```
+
+## 相关文档
+
+- [IResource 总览](iresource.md) - 返回类总览
+- [SetInvalid](setinvalid.md) - 将资源标记为无效

docs/api/resources/iresource/release.md

@@ -10,6 +10,10 @@ virtual void Release() = 0
 
 **返回：** 无
 
+**异常：** 无
+
+**线程安全：** ❌
+
 **复杂度：** O(1) 或 O(n)，取决于具体实现
 
 **示例：**

docs/api/resources/iresource/setinvalid.md

@@ -10,6 +10,10 @@ void SetInvalid()
 
 **返回：** 无
 
+**异常：** 无
+
+**线程安全：** ❌
+
 **复杂度：** O(1)
 
 **示例：**

docs/api/resources/material-loader/index.md

@@ -0,0 +1,59 @@
+# MaterialLoader
+
+## 命名空间
+
+`XCEngine::Resources`
+
+## 类型
+
+类 (Class)
+
+## 描述
+
+材质资源加载器，负责从磁盘加载 `.mat`、`.material` 和 `.json` 格式的材质资源文件。
+
+## 概述
+
+`MaterialLoader` 继承自 `IResourceLoader`，实现了材质资源的加载功能。它支持多种材质文件格式，能够解析材质文件中的 shader 引用并自动加载对应的 Shader 资源。加载过程中会提取材质的基本属性信息并创建 `Material` 对象。
+
+## 公共方法
+
+| 方法 | 签名 | 描述 |
+|------|------|------|
+| [MaterialLoader](methods/material-loader-constructor.md) | `MaterialLoader()` | 默认构造函数 |
+| [~MaterialLoader](methods/material-loader-destructor.md) | `virtual ~MaterialLoader()` | 析构函数 |
+| [GetResourceType](methods/get-resource-type.md) | `ResourceType GetResourceType() const` | 返回资源类型为 Material |
+| [GetSupportedExtensions](methods/get-supported-extensions.md) | `Array<String> GetSupportedExtensions() const` | 返回支持的扩展名列表 |
+| [CanLoad](methods/can-load.md) | `bool CanLoad(const String& path) const` | 检查给定路径是否可被加载 |
+| [Load](methods/load.md) | `LoadResult Load(const String& path, const ImportSettings* settings = nullptr)` | 加载指定路径的材质资源 |
+| [GetDefaultSettings](methods/get-default-settings.md) | `ImportSettings* GetDefaultSettings() const` | 返回默认导入设置 |
+
+## 使用示例
+
+```cpp
+#include "Resources/MaterialLoader.h"
+#include "Resources/ResourceManager.h"
+
+using namespace XCEngine::Resources;
+
+// 通过 ResourceManager 加载材质
+auto materialHandle = ResourceManager::Get().Load<Material>("assets/materials/wood.mat");
+if (materialHandle.IsValid()) {
+    Material* material = materialHandle.Get();
+    // 使用材质...
+}
+
+// 直接使用 MaterialLoader
+MaterialLoader loader;
+LoadResult result = loader.Load("assets/materials/wood.material");
+if (result.IsSuccess()) {
+    Material* material = static_cast<Material*>(result.GetResource());
+    // 使用材质...
+}
+```
+
+## 相关文档
+
+- [Material](../material/material.md)
+- [IResourceLoader](../iloader/iloader.md)
+- [ResourceManager](../resource-manager/resource-manager.md)

docs/api/resources/material-loader/methods/can-load.md

@@ -0,0 +1,31 @@
+# MaterialLoader::CanLoad
+
+## 方法签名
+
+```cpp
+bool CanLoad(const Containers::String& path) const override;
+```
+
+## 详细描述
+
+检查给定路径的文件是否可以被该加载器加载。通过提取文件扩展名并与支持列表进行比较来判断。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| path | `const Containers::String&` | 待检查的文件路径 |
+
+## 返回值
+
+`bool` - 如果文件扩展名在支持列表中返回 `true`，否则返回 `false`
+
+## 示例
+
+```cpp
+MaterialLoader loader;
+bool canLoad1 = loader.CanLoad("assets/materials/wood.mat");      // true
+bool canLoad2 = loader.CanLoad("assets/materials/wood.material"); // true
+bool canLoad3 = loader.CanLoad("assets/materials/wood.json");     // true
+bool canLoad4 = loader.CanLoad("assets/materials/wood.png");      // false
+```

docs/api/resources/material-loader/methods/get-default-settings.md

@@ -0,0 +1,27 @@
+# MaterialLoader::GetDefaultSettings
+
+## 方法签名
+
+```cpp
+ImportSettings* GetDefaultSettings() const override;
+```
+
+## 详细描述
+
+返回材质加载器的默认导入设置。当前实现返回 `nullptr`，表示材质加载不使用特殊的导入设置。
+
+## 参数
+
+无
+
+## 返回值
+
+`ImportSettings*` - 始终返回 `nullptr`
+
+## 示例
+
+```cpp
+MaterialLoader loader;
+ImportSettings* settings = loader.GetDefaultSettings();
+// settings == nullptr
+```

docs/api/resources/material-loader/methods/get-resource-type.md

@@ -0,0 +1,27 @@
+# MaterialLoader::GetResourceType
+
+## 方法签名
+
+```cpp
+ResourceType GetResourceType() const override;
+```
+
+## 详细描述
+
+返回该加载器管理的资源类型，固定为 `ResourceType::Material`。此方法继承自 `IResourceLoader` 接口，用于资源管理器识别加载器类型。
+
+## 参数
+
+无
+
+## 返回值
+
+`ResourceType` - 资源类型枚举值，始终返回 `ResourceType::Material`
+
+## 示例
+
+```cpp
+MaterialLoader loader;
+ResourceType type = loader.GetResourceType();
+// type == ResourceType::Material
+```

docs/api/resources/material-loader/methods/get-supported-extensions.md

@@ -0,0 +1,36 @@
+# MaterialLoader::GetSupportedExtensions
+
+## 方法签名
+
+```cpp
+Containers::Array<Containers::String> GetSupportedExtensions() const override;
+```
+
+## 详细描述
+
+返回该加载器支持的文件扩展名列表。`MaterialLoader` 支持三种材质文件格式：
+- `.mat` - 材质文件
+- `.material` - 材质文件（完整格式）
+- `.json` - JSON 格式的材质描述文件
+
+## 参数
+
+无
+
+## 返回值
+
+`Containers::Array<Containers::String>` - 支持的扩展名数组
+
+## 示例
+
+```cpp
+MaterialLoader loader;
+auto extensions = loader.GetSupportedExtensions();
+for (const auto& ext : extensions) {
+    printf("Supported extension: %s\n", ext.CStr());
+}
+// Output:
+// Supported extension: mat
+// Supported extension: material
+// Supported extension: json
+```

docs/api/resources/material-loader/methods/load.md

@@ -0,0 +1,62 @@
+# MaterialLoader::Load
+
+## 方法签名
+
+```cpp
+LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override;
+```
+
+## 详细描述
+
+加载指定路径的材质资源文件。加载过程包括：
+1. 读取文件数据
+2. 创建 `Material` 对象并设置基本信息（路径、名称、GUID）
+3. 解析 JSON 格式内容，提取 shader 路径
+4. 加载引用的 Shader 资源
+5. 设置材质的有效性标志和内存占用
+
+当前实现仅支持解析 JSON 中的 `"shader"` 字段并加载对应的 Shader 资源。
+
+## 参数
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| path | `const Containers::String&` | - | 材质文件路径 |
+| settings | `const ImportSettings*` | `nullptr` | 导入设置（当前未使用） |
+
+## 返回值
+
+`LoadResult` - 加载结果对象，包含成功加载的 `Material` 指针或错误信息
+
+## 示例
+
+```cpp
+#include "Resources/MaterialLoader.h"
+
+using namespace XCEngine::Resources;
+
+MaterialLoader loader;
+LoadResult result = loader.Load("assets/materials/pbr.metallic");
+
+if (result.IsSuccess()) {
+    Material* material = static_cast<Material*>(result.GetResource());
+    printf("Loaded material: %s, GUID: %s\n", 
+           material->m_name.CStr(), 
+           material->m_guid.ToString().CStr());
+} else {
+    printf("Failed to load material: %s\n", result.GetError().CStr());
+}
+```
+
+### JSON 材质文件格式
+
+```json
+{
+    "shader": "shaders/pbr.glsl",
+    "properties": {
+        "albedo": [1.0, 1.0, 1.0, 1.0],
+        "metallic": 0.0,
+        "roughness": 0.5
+    }
+}
+```

docs/api/resources/material-loader/methods/material-loader-constructor.md

@@ -0,0 +1,29 @@
+# MaterialLoader::MaterialLoader
+
+## 方法签名
+
+```cpp
+MaterialLoader();
+```
+
+## 详细描述
+
+`MaterialLoader` 类的默认构造函数，使用默认方式构造一个 `MaterialLoader` 实例。
+
+## 参数
+
+无
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+#include "Resources/MaterialLoader.h"
+
+using namespace XCEngine::Resources;
+
+MaterialLoader loader;
+```

docs/api/resources/material-loader/methods/material-loader-destructor.md

@@ -0,0 +1,28 @@
+# MaterialLoader::~MaterialLoader
+
+## 方法签名
+
+```cpp
+virtual ~MaterialLoader() override;
+```
+
+## 详细描述
+
+`MaterialLoader` 类的析构函数，用于清理 `MaterialLoader` 实例占用的资源。当前实现为默认析构函数。
+
+## 参数
+
+无
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+{
+    MaterialLoader loader;
+    // 使用 loader...
+} // loader 在此自动销毁
+```

docs/api/resources/material/clear-all-properties.md

@@ -0,0 +1,21 @@
+# Material::ClearAllProperties
+
+```cpp
+void ClearAllProperties();
+```
+
+清空所有属性和纹理绑定。
+
+**线程安全：** ❌
+
+**复杂度：** O(n)
+
+**示例：**
+
+```cpp
+mat->ClearAllProperties();
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-bool.md

@@ -0,0 +1,26 @@
+# Material::GetBool
+
+```cpp
+bool GetBool(const Containers::String& name) const;
+```
+
+获取布尔属性值。如果属性不存在则返回 false。
+
+**参数：**
+- `name` - 属性名称
+
+**返回：** 布尔属性值，不存在则返回 false
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+bool receiveShadow = mat->GetBool("receiveShadow");
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-constant-buffer-data.md

@@ -0,0 +1,25 @@
+# Material::GetConstantBufferData
+
+```cpp
+const Containers::Array<Core::uint8>& GetConstantBufferData() const;
+```
+
+获取常量缓冲区原始数据。数据由 UpdateConstantBuffer() 更新。
+
+**返回：** 常量缓冲区数据数组的引用
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+mat->UpdateConstantBuffer();
+const auto& cbData = mat->GetConstantBufferData();
+// 将 cbData 上传到 GPU
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-float.md

@@ -0,0 +1,26 @@
+# Material::GetFloat
+
+```cpp
+float GetFloat(const Containers::String& name) const;
+```
+
+获取浮点属性值。如果属性不存在则返回 0.0f。
+
+**参数：**
+- `name` - 属性名称
+
+**返回：** 浮点属性值，不存在则返回 0.0f
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+float roughness = mat->GetFloat("roughness");
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-float2.md

@@ -0,0 +1,26 @@
+# Material::GetFloat2
+
+```cpp
+Math::Vector2 GetFloat2(const Containers::String& name) const;
+```
+
+获取二维向量属性值。如果属性不存在则返回零向量。
+
+**参数：**
+- `name` - 属性名称
+
+**返回：** 二维向量属性值
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Math::Vector2 uvScale = mat->GetFloat2("uvScale");
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-float3.md

@@ -0,0 +1,26 @@
+# Material::GetFloat3
+
+```cpp
+Math::Vector3 GetFloat3(const Containers::String& name) const;
+```
+
+获取三维向量属性值。如果属性不存在则返回零向量。
+
+**参数：**
+- `name` - 属性名称
+
+**返回：** 三维向量属性值
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Math::Vector3 albedo = mat->GetFloat3("albedo");
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-float4.md

@@ -0,0 +1,26 @@
+# Material::GetFloat4
+
+```cpp
+Math::Vector4 GetFloat4(const Containers::String& name) const;
+```
+
+获取四维向量属性值。如果属性不存在则返回零向量。
+
+**参数：**
+- `name` - 属性名称
+
+**返回：** 四维向量属性值
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Math::Vector4 plane = mat->GetFloat4("planeEquation");
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-guid.md

@@ -0,0 +1,24 @@
+# Material::GetGUID
+
+```cpp
+ResourceGUID GetGUID() const override;
+```
+
+获取材质的全局唯一标识符。
+
+**返回：** 资源 GUID
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/pbr.mat");
+ResourceGUID guid = mat->GetGUID();
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-int.md

@@ -0,0 +1,26 @@
+# Material::GetInt
+
+```cpp
+Core::int32 GetInt(const Containers::String& name) const;
+```
+
+获取整数属性值。如果属性不存在则返回 0。
+
+**参数：**
+- `name` - 属性名称
+
+**返回：** 整数属性值，不存在则返回 0
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+int32 normalScale = mat->GetInt("normalScale");
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-memory-size.md

@@ -0,0 +1,24 @@
+# Material::GetMemorySize
+
+```cpp
+size_t GetMemorySize() const override;
+```
+
+获取材质占用的内存大小。
+
+**返回：** 内存大小（字节）
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/pbr.mat");
+size_t memSize = mat->GetMemorySize();
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-name.md

@@ -0,0 +1,24 @@
+# Material::GetName
+
+```cpp
+const Containers::String& GetName() const override;
+```
+
+获取材质的名称。
+
+**返回：** 材质名称字符串的引用
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/pbr.mat");
+const String& name = mat->GetName();
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-path.md

@@ -0,0 +1,24 @@
+# Material::GetPath
+
+```cpp
+const Containers::String& GetPath() const override;
+```
+
+获取材质资源的路径。
+
+**返回：** 资源路径字符串的引用
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/pbr.mat");
+const String& path = mat->GetPath();
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-shader.md

@@ -0,0 +1,26 @@
+# Material::GetShader
+
+```cpp
+class Shader* GetShader() const;
+```
+
+获取材质关联的着色器指针。
+
+**返回：** 着色器指针，如果未设置则返回 nullptr
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Shader* shader = mat->GetShader();
+if (shader != nullptr) {
+    // 使用着色器
+}
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-texture.md

@@ -0,0 +1,26 @@
+# Material::GetTexture
+
+```cpp
+ResourceHandle<Texture> GetTexture(const Containers::String& name) const;
+```
+
+获取纹理属性句柄。
+
+**参数：**
+- `name` - 属性名称
+
+**返回：** 纹理资源句柄
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Texture> albedoMap = mat->GetTexture("albedoMap");
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/get-type.md

@@ -0,0 +1,26 @@
+# Material::GetType
+
+```cpp
+ResourceType GetType() const override;
+```
+
+返回材质的资源类型，标识该资源为 Material 类型。
+
+**返回：** `ResourceType::Material`
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/pbr.mat");
+if (mat->GetType() == ResourceType::Material) {
+    // 这是一个材质资源
+}
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/has-property.md

@@ -0,0 +1,28 @@
+# Material::HasProperty
+
+```cpp
+bool HasProperty(const Containers::String& name) const;
+```
+
+检查指定属性是否存在。
+
+**参数：**
+- `name` - 属性名称
+
+**返回：** 属性存在返回 true，否则返回 false
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (mat->HasProperty("roughness")) {
+    float roughness = mat->GetFloat("roughness");
+}
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/is-valid.md

@@ -0,0 +1,26 @@
+# Material::IsValid
+
+```cpp
+bool IsValid() const override;
+```
+
+检查材质是否有效且已正确加载。
+
+**返回：** 材质有效返回 true，否则返回 false
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/pbr.mat");
+if (mat->IsValid()) {
+    // 材质已成功加载
+}
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/material.md

@@ -4,11 +4,13 @@
 
 **类型**: `class`
 
+**头文件**: `XCEngine/Resources/Material.h`
+
 **描述**: 材质资源类，管理渲染所需的着色器和属性参数。
 
 ## 概述
 
-`Material` 是 XCEngine 中的材质资源类，继承自 `IResource`。它管理材质关联的着色器和各种属性参数（浮点数、向量、纹理等），并支持将属性数据打包到常量缓冲区。
+`Material` 是 XCEngine 中的材质资源类，继承自 `IResource`。它管理材质关联的着色器和各种属性参数（浮点数、向量、整数、布尔值、纹理等），并支持将属性数据打包到常量缓冲区供 GPU 着色器使用。
 
 ## 头文件
 
@@ -20,7 +22,7 @@
 
 ### MaterialPropertyType
 
-材质属性类型枚举。
+材质属性类型枚举，定义材质支持的属性数据类型。
 
 | 值 | 描述 |
 |----|------|
@@ -28,124 +30,135 @@
 | `Float2` | 二维浮点向量 |
 | `Float3` | 三维浮点向量 |
 | `Float4` | 四维浮点向量 |
-| `Int` | 整数 |
+| `Int` | 32位整数 |
 | `Int2` | 二维整数向量 |
 | `Int3` | 三维整数向量 |
 | `Int4` | 四维整数向量 |
 | `Bool` | 布尔值 |
-| `Texture` | 纹理资源 |
+| `Texture` | 二维纹理资源 |
 | `Cubemap` | 立方体贴图资源 |
 
 ## 结构体
 
 ### MaterialProperty
 
-材质属性结构体。
+材质属性结构体，存储单个属性的名称、类型和值。
 
 | 成员 | 类型 | 描述 |
 |------|------|------|
-| `name` | `Containers::String` | 属性名称 |
-| `type` | `MaterialPropertyType` | 属性类型 |
-| `value` | `union` | 属性值（float/int/bool） |
+| `name` | `Containers::String` | 属性名称标识符 |
+| `type` | `MaterialPropertyType` | 属性数据类型 |
+| `value` | `union Value` | 属性值联合体，支持 float[4]、int[4]、bool |
 | `refCount` | `Core::uint32` | 引用计数 |
 
-## 公共方法
+## 公共方法表格
 
-### 基础属性
+### 资源基类方法
 
 | 方法 | 描述 |
 |------|------|
-| `ResourceType GetType() const` | 返回 `ResourceType::Material` |
-| `const Containers::String& GetName() const` | 获取材质名称 |
-| `const Containers::String& GetPath() const` | 获取材质路径 |
-| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
-| `bool IsValid() const` | 检查材质是否有效 |
-| `size_t GetMemorySize() const` | 获取内存大小 |
-| `void Release()` | 释放材质引用 |
+| `GetType()` | 返回 `ResourceType::Material` |
+| `GetName()` | 获取材质名称 |
+| `GetPath()` | 获取材质资源路径 |
+| `GetGUID()` | 获取全局唯一标识符 |
+| `IsValid()` | 检查材质是否有效且已加载 |
+| `GetMemorySize()` | 获取材质占用的内存大小 |
+| `Release()` | 释放材质所有引用和资源 |
 
 ### 着色器管理
 
 | 方法 | 描述 |
 |------|------|
-| `void SetShader(const ResourceHandle<Shader>& shader)` | 设置材质着色器 |
-| `Shader* GetShader() const` | 获取材质着色器 |
+| [`SetShader`](set-shader.md) | 设置材质使用的着色器 |
+| [`GetShader`](get-shader.md) | 获取材质关联的着色器指针 |
 
-### 属性设置
+### 属性设置方法
 
 | 方法 | 描述 |
 |------|------|
-| `void SetFloat(const Containers::String& name, float value)` | 设置浮点属性 |
-| `void SetFloat2(const Containers::String& name, const Math::Vector2& value)` | 设置 Vector2 属性 |
-| `void SetFloat3(const Containers::String& name, const Math::Vector3& value)` | 设置 Vector3 属性 |
-| `void SetFloat4(const Containers::String& name, const Math::Vector4& value)` | 设置 Vector4 属性 |
-| `void SetInt(const Containers::String& name, Core::int32 value)` | 设置整数属性 |
-| `void SetBool(const Containers::String& name, bool value)` | 设置布尔属性 |
-| `void SetTexture(const Containers::String& name, const ResourceHandle<Texture>& texture)` | 设置纹理属性 |
+| [`SetFloat`](set-float.md) | 设置浮点属性 |
+| [`SetFloat2`](set-float2.md) | 设置二维向量属性 |
+| [`SetFloat3`](set-float3.md) | 设置三维向量属性 |
+| [`SetFloat4`](set-float4.md) | 设置四维向量属性 |
+| [`SetInt`](set-int.md) | 设置整数属性 |
+| [`SetBool`](set-bool.md) | 设置布尔属性 |
+| [`SetTexture`](set-texture.md) | 设置纹理属性 |
 
-### 属性获取
+### 属性获取方法
 
 | 方法 | 描述 |
 |------|------|
-| `float GetFloat(const Containers::String& name) const` | 获取浮点属性 |
-| `Math::Vector2 GetFloat2(const Containers::String& name) const` | 获取 Vector2 属性 |
-| `Math::Vector3 GetFloat3(const Containers::String& name) const` | 获取 Vector3 属性 |
-| `Math::Vector4 GetFloat4(const Containers::String& name) const` | 获取 Vector4 属性 |
-| `Core::int32 GetInt(const Containers::String& name) const` | 获取整数属性 |
-| `bool GetBool(const Containers::String& name) const` | 获取布尔属性 |
-| `ResourceHandle<Texture> GetTexture(const Containers::String& name) const` | 获取纹理属性 |
+| [`GetFloat`](get-float.md) | 获取浮点属性值，不存在返回 0.0f |
+| [`GetFloat2`](get-float2.md) | 获取二维向量属性值 |
+| [`GetFloat3`](get-float3.md) | 获取三维向量属性值 |
+| [`GetFloat4`](get-float4.md) | 获取四维向量属性值 |
+| [`GetInt`](get-int.md) | 获取整数属性值，不存在返回 0 |
+| [`GetBool`](get-bool.md) | 获取布尔属性值，不存在返回 false |
+| [`GetTexture`](get-texture.md) | 获取纹理属性句柄 |
 
 ### 常量缓冲区
 
 | 方法 | 描述 |
 |------|------|
-| `const Containers::Array<Core::uint8>& GetConstantBufferData() const` | 获取常量缓冲区数据 |
-| `void UpdateConstantBuffer()` | 更新常量缓冲区数据 |
+| [`GetConstantBufferData`](get-constant-buffer-data.md) | 获取常量缓冲区原始数据 |
+| [`UpdateConstantBuffer`](update-constant-buffer.md) | 更新常量缓冲区数据 |
 
-### 属性管理
+### 属性查询与管理
 
 | 方法 | 描述 |
 |------|------|
-| `bool HasProperty(const Containers::String& name) const` | 检查属性是否存在 |
-| `void RemoveProperty(const Containers::String& name)` | 移除属性 |
-| `void ClearAllProperties()` | 清空所有属性 |
-
-## 实现说明
-
-**注意**: `MaterialLoader::ParseMaterialData()` 为 stub，始终返回 true。`MaterialLoader::Load()` 仅为示例实现，未解析材质属性。
+| [`HasProperty`](has-property.md) | 检查指定属性是否存在 |
+| [`RemoveProperty`](remove-property.md) | 移除指定属性 |
+| [`ClearAllProperties`](clear-all-properties.md) | 清空所有属性和纹理绑定 |
 
 ## 使用示例
 
 ```cpp
-// 加载材质
+// 通过资源管理器加载材质
 ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/player.mat");
 
 // 设置着色器
-mat->SetShader(shaderHandle);
+ResourceHandle<Shader> shader = ResourceManager::Get().Load<Shader>("shaders/pbr.shader");
+mat->SetShader(shader);
 
-// 设置各种属性
+// 设置材质属性
 mat->SetFloat("roughness", 0.5f);
+mat->SetFloat("metallic", 0.0f);
 mat->SetFloat3("albedo", Math::Vector3(1.0f, 0.8f, 0.6f));
+mat->SetFloat4("emission", Math::Vector4(1.0f, 0.5f, 0.2f, 2.0f));
+mat->SetInt("normalScale", 1);
+mat->SetBool("receiveShadow", true);
+
+// 设置纹理
+ResourceHandle<Texture> albedoTex = ResourceManager::Get().Load<Texture>("textures/albedo.png");
+ResourceHandle<Texture> normalTex = ResourceManager::Get().Load<Texture>("textures/normal.png");
+ResourceHandle<Texture> roughnessTex = ResourceManager::Get().Load<Texture>("textures/roughness.png");
 mat->SetTexture("albedoMap", albedoTex);
 mat->SetTexture("normalMap", normalTex);
-mat->SetInt("normalScale", 1);
+mat->SetTexture("roughnessMap", roughnessTex);
 
 // 获取属性
 float roughness = mat->GetFloat("roughness");
 Math::Vector3 albedo = mat->GetFloat3("albedo");
+Shader* shader = mat->GetShader();
 
-// 检查属性
+// 属性查询
 if (mat->HasProperty("metallic")) {
     float metallic = mat->GetFloat("metallic");
 }
 
-// 更新常量缓冲区
+// 更新常量缓冲区供 GPU 使用
 mat->UpdateConstantBuffer();
-auto cbData = mat->GetConstantBufferData();
+const auto& cbData = mat->GetConstantBufferData();
+
+// 释放材质
+mat->Release();
 ```
 
 ## 相关文档
 
-- [IResource](../iresource/iresource.md) - 资源基类
+- [IResource](../iresource/iresource.md) - 资源基类接口
 - [Shader](../shader/shader.md) - 着色器资源
 - [Texture](../texture/texture.md) - 纹理资源
-- [Resources 总览](../resources.md) - 返回模块总览
+- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄
+- [Resources 模块总览](../resources.md) - 返回模块总览

docs/api/resources/material/release.md

@@ -0,0 +1,26 @@
+# Material::Release
+
+**方法签名**:
+```cpp
+void Release() override
+```
+
+**详细描述**: 释放材质的所有引用和资源。调用后着色器引用、属性映射、纹理绑定和常量缓冲区数据都将被清空，材质变为无效状态。
+
+**参数**: 无
+
+**返回值**: 无
+
+**复杂度**: O(n)，n 为属性和纹理绑定数量
+
+**示例**:
+
+```cpp
+mat->Release();
+// 调用后 mat->IsValid() 返回 false
+```
+
+## 相关文档
+
+- [Material 总览](material.md) - 返回类总览
+- [IResource::Release](../iresource/iresource.md) - 资源基类接口

docs/api/resources/material/remove-property.md

@@ -0,0 +1,24 @@
+# Material::RemoveProperty
+
+```cpp
+void RemoveProperty(const Containers::String& name);
+```
+
+移除指定属性。
+
+**参数：**
+- `name` - 属性名称
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+mat->RemoveProperty("roughness");
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/set-bool.md

@@ -0,0 +1,26 @@
+# Material::SetBool
+
+```cpp
+void SetBool(const Containers::String& name, bool value);
+```
+
+设置布尔属性值。
+
+**参数：**
+- `name` - 属性名称
+- `value` - 布尔值
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+mat->SetBool("receiveShadow", true);
+mat->SetBool("castShadow", false);
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/set-float.md

@@ -0,0 +1,26 @@
+# Material::SetFloat
+
+```cpp
+void SetFloat(const Containers::String& name, float value);
+```
+
+设置浮点属性值。如果属性不存在则创建，存在则更新。
+
+**参数：**
+- `name` - 属性名称
+- `value` - 浮点数值
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+mat->SetFloat("roughness", 0.5f);
+mat->SetFloat("metallic", 0.8f);
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/set-float2.md

@@ -0,0 +1,25 @@
+# Material::SetFloat2
+
+```cpp
+void SetFloat2(const Containers::String& name, const Math::Vector2& value);
+```
+
+设置二维向量属性值。
+
+**参数：**
+- `name` - 属性名称
+- `value` - 二维向量值
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+mat->SetFloat2("uvScale", Math::Vector2(2.0f, 2.0f));
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/set-float3.md

@@ -0,0 +1,26 @@
+# Material::SetFloat3
+
+```cpp
+void SetFloat3(const Containers::String& name, const Math::Vector3& value);
+```
+
+设置三维向量属性值，常用于颜色、法线缩放等。
+
+**参数：**
+- `name` - 属性名称
+- `value` - 三维向量值
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+mat->SetFloat3("albedo", Math::Vector3(1.0f, 0.8f, 0.6f));
+mat->SetFloat3("emission", Math::Vector3(0.5f, 0.5f, 0.5f));
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/set-float4.md

@@ -0,0 +1,25 @@
+# Material::SetFloat4
+
+```cpp
+void SetFloat4(const Containers::String& name, const Math::Vector4& value);
+```
+
+设置四维向量属性值。
+
+**参数：**
+- `name` - 属性名称
+- `value` - 四维向量值
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+mat->SetFloat4("planeEquation", Math::Vector4(0.0f, 1.0f, 0.0f, 0.0f));
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/set-int.md

@@ -0,0 +1,26 @@
+# Material::SetInt
+
+```cpp
+void SetInt(const Containers::String& name, Core::int32 value);
+```
+
+设置整数属性值。
+
+**参数：**
+- `name` - 属性名称
+- `value` - 整数值
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+mat->SetInt("normalScale", 1);
+mat->SetInt("uSampleCount", 4);
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/set-shader.md

@@ -0,0 +1,25 @@
+# Material::SetShader
+
+```cpp
+void SetShader(const ResourceHandle<class Shader>& shader);
+```
+
+设置材质使用的着色器。
+
+**参数：**
+- `shader` - 着色器资源句柄
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Shader> shader = ResourceManager::Get().Load<Shader>("shaders/pbr.shader");
+mat->SetShader(shader);
+```
+
+## 相关文档
+
+- [Material](material.md) - 返回类总览

docs/api/resources/material/set-texture.md

@@ -1,16 +1,16 @@
 # Material::SetTexture
 
 ```cpp
-void SetTexture(const Containers::String& name, const ResourceHandle<Texture>& texture)
+void SetTexture(const Containers::String& name, const ResourceHandle<Texture>& texture);
 ```
 
-设置材质纹理属性。
+设置纹理属性。
 
 **参数：**
 - `name` - 属性名称
 - `texture` - 纹理资源句柄
 
-**返回：** 无
+**线程安全：** ❌
 
 **复杂度：** O(1)
 
@@ -25,4 +25,4 @@ mat->SetTexture("normalMap", normalTex);
 
 ## 相关文档
 
-- [Material 总览](material.md) - 返回类总览
+- [Material](material.md) - 返回类总览

docs/api/resources/material/setfloat.md

@@ -1,27 +0,0 @@
-# Material::SetFloat
-
-```cpp
-void SetFloat(const Containers::String& name, float value)
-```
-
-设置材质浮点属性。
-
-**参数：**
-- `name` - 属性名称
-- `value` - 属性值
-
-**返回：** 无
-
-**复杂度：** O(1)
-
-**示例：**
-
-```cpp
-mat->SetFloat("roughness", 0.5f);
-mat->SetFloat("metallic", 0.0f);
-mat->SetFloat("emissionStrength", 2.0f);
-```
-
-## 相关文档
-
-- [Material 总览](material.md) - 返回类总览