docs: 重构 API 文档 - components 和 scene 模块

- components: 修复英文标题为中文，添加缺失组件文档 - 新增 camera-component, light-component, audio-source-component, audio-listener-component 类总览 - 修复 get-position.md 格式 - 更新 components.md 模块总览 - scene: 修复方法文档格式，新增缺失方法 - 修复 find.md, create-game-object.md 英文标题 - 新增 FindByID, SerializeToString, DeserializeFromString 方法文档 - 更新 scene.md 类总览方法列表
2026-03-26 01:50:27 +08:00
parent 7c3f304688
commit f5a34f8adc
46 changed files with 781 additions and 157 deletions
--- a/docs/api/audio/windows-audio-backend/windows-audio-backend.md
+++ b/docs/api/audio/windows-audio-backend/windows-audio-backend.md
@@ -0,0 +1,69 @@
+# WindowsAudioBackend
+
+**命名空间**: `XCEngine::Audio::WASAPI`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Audio/WindowsAudioBackend.h`
+
+**描述**: Windows 平台音频后端实现，使用 Windows MultiMedia API (waveXxx 函数)。
+
+## 概述
+
+WindowsAudioBackend 是基于 Windows MultiMedia API 的音频后端实现，通过 waveXxx 函数提供音频输出能力。它运行在单独的音频线程上，使用双缓冲区交换机制实现流畅的音频播放，支持设备枚举、音量控制和静音管理。
+
+该后端与 WASAPIBackend 类似，但使用更底层的 waveOut API 而非 WASAPI COM 接口，具有更好的兼容性和更低的依赖要求。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `WindowsAudioBackend` | 构造函数 |
+| `~WindowsAudioBackend` | 析构函数，关闭音频设备并清理资源 |
+| `Initialize` | 初始化音频后端和设备 |
+| `Shutdown` | 关闭音频后端并释放资源 |
+| `GetDeviceName` | 获取当前音频设备名称 |
+| `GetAvailableDevices` | 获取系统可用音频设备列表 |
+| `SetDevice` | 设置音频输出设备 |
+| `GetMasterVolume` | 获取主音量（0.0-1.0） |
+| `SetMasterVolume` | 设置主音量（0.0-1.0） |
+| `IsMuted` | 检查静音状态 |
+| `SetMuted` | 设置静音状态 |
+| `Start` | 启动音频处理线程 |
+| `Stop` | 停止音频处理线程 |
+| `Suspend` | 暂停音频处理 |
+| `Resume` | 恢复音频处理 |
+| `ProcessAudio` | 处理音频数据到输出缓冲区 |
+| `IsRunning` | 检查音频线程是否正在运行 |
+| `GetConfig` | 获取当前音频配置 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Audio/AudioSystem.h>
+#include <XCEngine/Audio/WindowsAudioBackend.h>
+
+using namespace XCEngine::Audio;
+
+void SetupAudioWithWindowsBackend() {
+    // 创建 Windows 音频后端
+    auto backend = std::make_unique<WASAPI::WindowsAudioBackend>();
+
+    // 设置到音频系统
+    AudioSystem::Get().SetBackend(std::move(backend));
+
+    // 初始化配置
+    AudioConfig config;
+    config.sampleRate = 48000;
+    config.channels = 2;
+    config.bufferSize = 512;
+
+    AudioSystem::Get().Initialize(config);
+}
+```
+
+## 相关文档
+
+- [Audio 模块总览](../audio.md) - Audio 模块总览
+- [IAudioBackend](../i-audio-backend/i-audio-backend.md) - 音频后端接口
+- [WASAPIBackend](../wasapi-backend/wasapi-backend.md) - WASAPI 后端实现
--- a/docs/api/components/audio-listener-component/audio-listener-component.md
+++ b/docs/api/components/audio-listener-component/audio-listener-component.md
@@ -0,0 +1,86 @@
+# AudioListenerComponent
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Components/AudioListenerComponent.h`
+
+**描述**: 音频监听组件，接收声音并处理多普勒效应、混响和音量控制。
+
+## 概述
+
+AudioListenerComponent 是 XCEngine ECS 系统中的音频监听组件，通常附加到相机或玩家对象上。它负责接收场景中所有 AudioSourceComponent 发出的声音，并进行多普勒效应、混响和音量控制处理。每个场景通常只有一个 AudioListenerComponent。
+
+## 公共方法
+
+### 音量控制
+
+| 方法 | 描述 |
+|------|------|
+| [`SetMasterVolume`](../../audio/audio-system/set-master-volume.md) | 设置主音量 |
+| [`GetMasterVolume`](../../audio/audio-system/get-master-volume.md) | 获取主音量 |
+
+### 静音控制
+
+| 方法 | 描述 |
+|------|------|
+| [`SetMute`](../../audio/audio-mixer/set-mute.md) | 设置静音状态 |
+| [`IsMute`](is-mute.md) | 检查是否静音 |
+
+### 多普勒效应
+
+| 方法 | 描述 |
+|------|------|
+| [`SetDopplerLevel`](set-doppler-level.md) | 设置多普勒效应等级 |
+| [`GetDopplerLevel`](get-doppler-level.md) | 获取多普勒效应等级 |
+| [`SetSpeedOfSound`](set-speed-of-sound.md) | 设置声速（米/秒） |
+| [`GetSpeedOfSound`](get-speed-of-sound.md) | 获取声速 |
+
+### 混响
+
+| 方法 | 描述 |
+|------|------|
+| [`SetReverbLevel`](set-reverb-level.md) | 设置混响等级 |
+| [`GetReverbLevel`](get-reverb-level.md) | 获取混响等级 |
+| [`SetReverb`](set-reverb.md) | 设置混响效果器 |
+| [`GetReverb`](get-reverb.md) | 获取混响效果器 |
+
+### 频谱分析
+
+| 方法 | 描述 |
+|------|------|
+| [`GetEnergy`](get-energy.md) | 获取当前能量值 |
+| [`GetFrequencyData`](get-frequency-data.md) | 获取频谱数据 |
+| [`GetFrequencyDataSize`](get-frequency-data-size.md) | 获取频谱数据大小 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Components/AudioListenerComponent.h>
+#include <XCEngine/Components/GameObject.h>
+
+using namespace XCEngine::Components;
+
+void SetupAudioListener(GameObject* listenerObject) {
+    auto listener = listenerObject->AddComponent<AudioListenerComponent>();
+    
+    listener->SetMasterVolume(1.0f);
+    listener->SetDopplerLevel(1.0f);
+    listener->SetSpeedOfSound(343.0f);
+    listener->SetReverbLevel(0.5f);
+}
+
+void AdjustVolume(GameObject* listenerObject, float volume) {
+    auto listener = listenerObject->GetComponent<AudioListenerComponent>();
+    if (listener) {
+        listener->SetMasterVolume(volume);
+    }
+}
+```
+
+## 相关文档
+
+- [Components 模块总览](../components.md) - Components 模块总览
+- [Component](../component/component.md) - 组件基类
+- [AudioSourceComponent](../audio-source-component/audio-source-component.md) - 音频源组件
--- a/docs/api/components/audio-source-component/audio-source-component.md
+++ b/docs/api/components/audio-source-component/audio-source-component.md
@@ -0,0 +1,121 @@
+# AudioSourceComponent
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Components/AudioSourceComponent.h`
+
+**描述**: 音频源组件，负责声音播放、3D 空间化、衰减和多普勒效应。
+
+## 概述
+
+AudioSourceComponent 是 XCEngine ECS 系统中的音频源组件，用于在场景中播放声音。它支持 3D 空间化、声音衰减、多普勒效应、混响区域混合等功能。该组件需要配合 AudioListenerComponent 使用来接收声音并进行音频处理。
+
+## 公共方法
+
+### 播放控制
+
+| 方法 | 描述 |
+|------|------|
+| [`Play`](play.md) | 开始播放音频 |
+| [`Pause`](pause.md) | 暂停播放 |
+| [`Stop`](stop.md) | 停止播放 |
+| [`IsPlaying`](is-playing.md) | 检查是否正在播放 |
+| [`IsPaused`](is-paused.md) | 检查是否已暂停 |
+
+### 音频剪辑
+
+| 方法 | 描述 |
+|------|------|
+| [`SetClip`](set-clip.md) | 设置音频剪辑 |
+| [`GetClip`](get-clip.md) | 获取当前音频剪辑 |
+
+### 音频属性
+
+| 方法 | 描述 |
+|------|------|
+| [`SetVolume`](../../audio/audio-mixer/set-volume.md) | 设置音量 |
+| [`GetVolume`](get-volume.md) | 获取音量 |
+| [`SetPitch`](set-pitch.md) | 设置音调 |
+| [`GetPitch`](get-pitch.md) | 获取音调 |
+| [`SetPan`](set-pan.md) | 设置平移 |
+| [`GetPan`](get-pan.md) | 获取平移 |
+| [`SetLooping`](set-looping.md) | 设置循环播放 |
+| [`IsLooping`](is-looping.md) | 检查是否循环播放 |
+
+### 3D 空间化
+
+| 方法 | 描述 |
+|------|------|
+| [`SetSpatialize`](set-spatialize.md) | 设置是否启用 3D 空间化 |
+| [`IsSpatialize`](is-spatialize.md) | 检查是否启用 3D 空间化 |
+| [`Set3DParams`](../../audio/audio-mixer/set-3d-params.md) | 设置 3D 音频参数 |
+| [`Get3DParams`](get-3d-params.md) | 获取 3D 音频参数 |
+| [`SetDopplerLevel`](set-doppler-level.md) | 设置多普勒效应等级 |
+| [`GetDopplerLevel`](get-doppler-level.md) | 获取多普勒效应等级 |
+| [`SetSpread`](set-spread.md) | 设置扩散角度 |
+| [`GetSpread`](get-spread.md) | 获取扩散角度 |
+| [`SetReverbZoneMix`](set-reverb-zone-mix.md) | 设置混响区域混合 |
+| [`GetReverbZoneMix`](get-reverb-zone-mix.md) | 获取混响区域混合 |
+
+### 输出混音器
+
+| 方法 | 描述 |
+|------|------|
+| [`SetOutputMixer`](../../audio/audio-mixer/set-output-mixer.md) | 设置输出混音器 |
+| [`GetOutputMixer`](get-output-mixer.md) | 获取输出混音器 |
+
+### 播放时间
+
+| 方法 | 描述 |
+|------|------|
+| [`SetTime`](set-time.md) | 设置播放位置 |
+| [`GetTime`](get-time.md) | 获取当前播放位置 |
+| [`GetDuration`](../../resources/audioclip/get-duration.md) | 获取音频总时长 |
+
+### 能量检测
+
+| 方法 | 描述 |
+|------|------|
+| [`GetEnergy`](get-energy.md) | 获取当前能量值 |
+| [`StartEnergyDetect`](start-energy-detect.md) | 开始能量检测 |
+| [`StopEnergyDetect`](stop-energy-detect.md) | 停止能量检测 |
+| [`IsEnergyDetecting`](is-energy-detecting.md) | 检查是否正在能量检测 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Components/AudioSourceComponent.h>
+#include <XCEngine/Components/GameObject.h>
+#include <XCEngine/Resources/AudioClip/AudioClip.h>
+
+using namespace XCEngine::Components;
+
+void PlaySound(GameObject* audioObject) {
+    auto audioSource = audioObject->AddComponent<AudioSourceComponent>();
+    
+    audioSource->SetVolume(0.8f);
+    audioSource->SetPitch(1.0f);
+    audioSource->SetLooping(false);
+    audioSource->SetSpatialize(true);
+    
+    audioSource->Play();
+}
+
+void Setup3DAudio(GameObject* audioObject) {
+    auto audioSource = audioObject->AddComponent<AudioSourceComponent>();
+    
+    Audio::Audio3DParams params;
+    params.dopplerLevel = 1.0f;
+    params.spread = 0.0f;
+    params.reverbZoneMix = 1.0f;
+    audioSource->Set3DParams(params);
+}
+```
+
+## 相关文档
+
+- [Components 模块总览](../components.md) - Components 模块总览
+- [Component](../component/component.md) - 组件基类
+- [AudioListenerComponent](../audio-listener-component/audio-listener-component.md) - 音频监听组件
--- a/docs/api/components/camera-component/camera-component.md
+++ b/docs/api/components/camera-component/camera-component.md
@@ -0,0 +1,80 @@
+# CameraComponent
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Components/CameraComponent.h`
+
+**描述**: 相机组件，定义视图和投影参数，支持透视和正交两种投影模式。
+
+## 概述
+
+CameraComponent 是 XCEngine ECS 系统中的相机组件，用于定义场景的观察视角。它支持透视投影（Perspective）和正交投影（Orthographic）两种模式，可以设置视场角、近裁剪面、远裁剪面、深度值和清除颜色等参数。
+
+## 枚举
+
+### CameraProjectionType
+
+| 枚举值 | 描述 |
+|--------|------|
+| `Perspective` | 透视投影，符合人眼观察习惯 |
+| `Orthographic` | 正交投影，保持物体真实大小 |
+
+## 公共方法
+
+### 投影设置
+
+| 方法 | 描述 |
+|------|------|
+| [`GetProjectionType`](get-projection-type.md) | 获取投影类型 |
+| [`SetProjectionType`](set-projection-type.md) | 设置投影类型 |
+| [`GetFieldOfView`](get-field-of-view.md) | 获取视场角（透视投影） |
+| [`SetFieldOfView`](set-field-of-view.md) | 设置视场角 |
+| [`GetOrthographicSize`](get-orthographic-size.md) | 获取正交投影大小 |
+| [`SetOrthographicSize`](set-orthographic-size.md) | 设置正交投影大小 |
+
+### 裁剪平面
+
+| 方法 | 描述 |
+|------|------|
+| [`GetNearClipPlane`](get-near-clip-plane.md) | 获取近裁剪面距离 |
+| [`SetNearClipPlane`](set-near-clip-plane.md) | 设置近裁剪面距离 |
+| [`GetFarClipPlane`](get-far-clip-plane.md) | 获取远裁剪面距离 |
+| [`SetFarClipPlane`](set-far-clip-plane.md) | 设置远裁剪面距离 |
+
+### 相机属性
+
+| 方法 | 描述 |
+|------|------|
+| [`GetDepth`](../../rhi/texture/get-depth.md) | 获取深度值 |
+| [`SetDepth`](set-depth.md) | 设置深度值 |
+| [`IsPrimary`](is-primary.md) | 检查是否为主相机 |
+| [`SetPrimary`](set-primary.md) | 设置为主相机 |
+| [`GetClearColor`](get-clear-color.md) | 获取清除颜色 |
+| [`SetClearColor`](../../rhi/opengl/pipeline-state/set-clear-color.md) | 设置清除颜色 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Components/CameraComponent.h>
+#include <XCEngine/Components/GameObject.h>
+
+using namespace XCEngine::Components;
+
+void SetupCamera(GameObject* cameraObject) {
+    auto camera = cameraObject->AddComponent<CameraComponent>();
+    
+    camera->SetProjectionType(CameraProjectionType::Perspective);
+    camera->SetFieldOfView(60.0f);
+    camera->SetNearClipPlane(0.1f);
+    camera->SetFarClipPlane(1000.0f);
+    camera->SetPrimary(true);
+}
+```
+
+## 相关文档
+
+- [Components 模块总览](../components.md) - Components 模块总览
+- [Component](../component/component.md) - 组件基类
+- [TransformComponent](../transform-component/transform-component.md) - 变换组件
--- a/docs/api/components/component/component.md
+++ b/docs/api/components/component/component.md
@@ -63,5 +63,5 @@ public:
 ## 相关文档

 - [Components 模块总览](../components.md) - Components 模块总览
- [GameObject](game-object/game-object.md) - 游戏对象
- [TransformComponent](transform-component/transform-component.md) - 变换组件
+- [GameObject](../game-object/game-object.md) - 游戏对象
+- [TransformComponent](../transform-component/transform-component.md) - 变换组件
--- a/docs/api/components/component/get-scene.md
+++ b/docs/api/components/component/get-scene.md
@@ -11,4 +11,4 @@ Scene* GetScene() const;
 ## 相关文档

 - [Component 总览](component.md)
- [Scene](../scene/scene/scene.md)
+- [Scene](../../scene/scene.md)
--- a/docs/api/components/component/transform.md
+++ b/docs/api/components/component/transform.md
@@ -13,4 +13,4 @@ TransformComponent& transform() const;
 ## 相关文档

 - [Component 总览](component.md)
- [TransformComponent](transform-component/transform-component.md)
+- [TransformComponent](../transform-component/transform-component.md)
--- a/docs/api/components/components.md
+++ b/docs/api/components/components.md
@@ -25,6 +25,20 @@ Components 模块是 XCEngine ECS 架构中的组件层，提供各种游戏对
 |------|------|------|
 | [TransformComponent](transform-component/transform-component.md) | `TransformComponent.h` | 变换组件，包含位置、旋转、缩放 |

+### 渲染组件
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [CameraComponent](camera-component/camera-component.md) | `CameraComponent.h` | 相机组件，定义视图和投影参数 |
+| [LightComponent](light-component/light-component.md) | `LightComponent.h` | 光源组件，支持方向光、点光、聚光灯 |
+
+### 音频组件
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [AudioSourceComponent](audio-source-component/audio-source-component.md) | `AudioSourceComponent.h` | 音频源组件，负责声音播放和3D音效 |
+| [AudioListenerComponent](audio-listener-component/audio-listener-component.md) | `AudioListenerComponent.h` | 音频监听组件，接收声音并处理多普勒效应和混响 |
+
 ## 使用示例

 ```cpp
--- a/docs/api/components/game-object/add-component.md
+++ b/docs/api/components/game-object/add-component.md
@@ -20,4 +20,4 @@ T* AddComponent(Args&&... args);
 ## 相关文档

 - [GameObject 总览](game-object.md)
- [Component](component/component.md)
+- [Component](../component/component.md)
--- a/docs/api/components/game-object/game-object.md
+++ b/docs/api/components/game-object/game-object.md
@@ -113,6 +113,6 @@ void FindAndOperate() {
 ## 相关文档

 - [Components 模块总览](../components.md) - Components 模块总览
- [Component](component/component.md) - 组件基类
- [TransformComponent](transform-component/transform-component.md) - 变换组件
- [Scene](../scene/scene/scene.md) - 场景
+- [Component](../component/component.md) - 组件基类
+- [TransformComponent](../transform-component/transform-component.md) - 变换组件
+- [Scene](../../scene/scene.md) - 场景
--- a/docs/api/components/game-object/get-scene.md
+++ b/docs/api/components/game-object/get-scene.md
@@ -11,4 +11,4 @@ Scene* GetScene() const;
 ## 相关文档

 - [GameObject 总览](game-object.md)
- [Scene](../scene/scene/scene.md)
+- [Scene](../../scene/scene.md)
--- a/docs/api/components/game-object/get-transform.md
+++ b/docs/api/components/game-object/get-transform.md
@@ -12,4 +12,4 @@ const TransformComponent* GetTransform() const;
 ## 相关文档

 - [GameObject 总览](game-object.md)
- [TransformComponent](transform-component/transform-component.md)
+- [TransformComponent](../transform-component/transform-component.md)
--- a/docs/api/components/light-component/light-component.md
+++ b/docs/api/components/light-component/light-component.md
@@ -0,0 +1,90 @@
+# LightComponent
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Components/LightComponent.h`
+
+**描述**: 光源组件，支持方向光、点光、聚光灯三种类型，可设置颜色、强度和阴影。
+
+## 概述
+
+LightComponent 是 XCEngine ECS 系统中的光源组件，支持三种光源类型：方向光（Directional）、点光（Point）和聚光灯（Spot）。方向光从无穷远处照射，模拟太阳光；点光从一个点向所有方向照射；聚光灯沿一个锥形方向照射。光源组件可以设置颜色、强度、作用范围和是否投射阴影。
+
+## 枚举
+
+### LightType
+
+| 枚举值 | 描述 |
+|--------|------|
+| `Directional` | 方向光，从无穷远处照射 |
+| `Point` | 点光，从一个点向所有方向照射 |
+| `Spot` | 聚光灯，沿锥形方向照射 |
+
+## 公共方法
+
+### 光源类型
+
+| 方法 | 描述 |
+|------|------|
+| [`GetLightType`](get-light-type.md) | 获取光源类型 |
+| [`SetLightType`](set-light-type.md) | 设置光源类型 |
+
+### 光源属性
+
+| 方法 | 描述 |
+|------|------|
+| [`GetColor`](get-color.md) | 获取光源颜色 |
+| [`SetColor`](set-color.md) | 设置光源颜色 |
+| [`GetIntensity`](get-intensity.md) | 获取光源强度 |
+| [`SetIntensity`](set-intensity.md) | 设置光源强度 |
+| [`GetRange`](get-range.md) | 获取作用范围（点光/聚光灯） |
+| [`SetRange`](set-range.md) | 设置作用范围 |
+
+### 聚光灯属性
+
+| 方法 | 描述 |
+|------|------|
+| [`GetSpotAngle`](get-spot-angle.md) | 获取聚光灯角度 |
+| [`SetSpotAngle`](set-spot-angle.md) | 设置聚光灯角度 |
+
+### 阴影
+
+| 方法 | 描述 |
+|------|------|
+| [`GetCastsShadows`](get-casts-shadows.md) | 检查是否投射阴影 |
+| [`SetCastsShadows`](set-casts-shadows.md) | 设置是否投射阴影 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Components/LightComponent.h>
+#include <XCEngine/Components/GameObject.h>
+
+using namespace XCEngine::Components;
+
+void SetupLighting(GameObject* lightObject) {
+    auto light = lightObject->AddComponent<LightComponent>();
+    
+    light->SetLightType(LightType::Directional);
+    light->SetColor(Math::Color::White());
+    light->SetIntensity(1.0f);
+    light->SetCastsShadows(true);
+}
+
+void SetupPointLight(GameObject* pointLightObject) {
+    auto pointLight = pointLightObject->AddComponent<LightComponent>();
+    
+    pointLight->SetLightType(LightType::Point);
+    pointLight->SetColor(Math::Color(1.0f, 0.8f, 0.6f, 1.0f));
+    pointLight->SetIntensity(2.0f);
+    pointLight->SetRange(10.0f);
+}
+```
+
+## 相关文档
+
+- [Components 模块总览](../components.md) - Components 模块总览
+- [Component](../component/component.md) - 组件基类
+- [TransformComponent](../transform-component/transform-component.md) - 变换组件
--- a/docs/api/components/transform-component/get-position.md
+++ b/docs/api/components/transform-component/get-position.md
@@ -1,33 +1,34 @@
-# GetPosition
+# TransformComponent::GetPosition

-Get the world position of this transform.
-
-## Syntax
+获取变换的世界空间位置。

 ```cpp
 Math::Vector3 GetPosition() const;
 ```

-## Returns
+返回变换的世界空间位置。如果变换有父对象，世界位置由局部位置与父对象世界位置组合计算得出。

-Returns the world position as a `Math::Vector3`.
+**返回：** `Math::Vector3` - 世界空间位置向量

-## Remarks
+**线程安全：** ✅ (只读操作)

-Returns the world-space position of this transform. If this transform has a parent, the world position is computed by combining the local position with the parent's world position.
-
-## See Also
-
- [GetLocalPosition](get-local-position)
- [SetLocalPosition](set-local-position)
- [SetPosition](set-position)
-
-## Examples
+**示例：**

 ```cpp
+#include <XCEngine/Components/TransformComponent.h>
+
+using namespace XCEngine::Components;
+
 void Example(TransformComponent* transform) {
    Math::Vector3 worldPos = transform->GetPosition();
-    XC_LOG_INFO("World position: ({}, {}, {})", 
+    printf("World position: (%f, %f, %f)\n", 
        worldPos.x, worldPos.y, worldPos.z);
 }
 ```
+
+## 相关文档
+
+- [TransformComponent 总览](transform-component.md) - 返回类总览
+- [GetLocalPosition](get-local-position.md) - 获取局部位置
+- [SetPosition](set-position.md) - 设置世界位置
+- [SetLocalPosition](set-local-position.md) - 设置局部位置
--- a/docs/api/components/transform-component/transform-component.md
+++ b/docs/api/components/transform-component/transform-component.md
@@ -122,5 +122,5 @@ void TransformExample(TransformComponent* transform) {
 ## 相关文档

 - [Components 模块总览](../components.md) - Components 模块总览
- [Component](component/component.md) - 组件基类
- [GameObject](game-object/game-object.md) - 游戏对象
+- [Component](../component/component.md) - 组件基类
+- [GameObject](../game-object/game-object.md) - 游戏对象
--- a/docs/api/main.md
+++ b/docs/api/main.md
@@ -9,8 +9,8 @@
 | 模块 | 文档目录 | 描述 |
 |------|----------|------|
 | **RHI** | [rhi/](rhi/rhi.md) | 渲染硬件接口抽象层 |
-| **D3D12** | [rhi/d3d12/](rhi/opengl/overview.md) | DirectX 12 后端实现 |
-| **OpenGL** | [rhi/opengl/](rhi/opengl/overview.md) | OpenGL 后端实现 |
+| **D3D12** | [rhi/d3d12/](rhi/d3d12/d3d12.md) | DirectX 12 后端实现 |
+| **OpenGL** | [rhi/opengl/](rhi/opengl/opengl.md) | OpenGL 后端实现 |
 | **Containers** | [containers/](containers/containers.md) | 容器数据结构 |
 | **Memory** | [memory/](memory/memory.md) | 内存管理 |
 | **Threading** | [threading/](threading/threading.md) | 多线程和任务系统 |
--- a/docs/api/math/aabb/aabb.md
+++ b/docs/api/math/aabb/aabb.md
@@ -1,47 +1,62 @@
-# AABB / OBB
+# OBB

 **命名空间**: `XCEngine::Math`

 **类型**: `struct`

-**头文件**: `XCEngine/Math/AABB.h`
+**头文件**: `XCEngine/Core/Math/AABB.h`

-**描述**: 轴对齐包围盒 (AABB) 和有向包围盒 (OBB)
+**描述**: 有向包围盒（Oriented Bounding Box），支持任意方向旋转的盒状包围体

 ## 概述

-`AABB` 在 Math 库中通过 `Bounds` 类型实现。OBB 是可以任意方向旋转的包围盒。
+OBB（Oriented Bounding Box）是一种包围盒类型，与轴对齐包围盒（AABB）不同，OBB 可以任意旋转，因此能够更紧凑地包围复杂形状的对象。OBB 由一个中心点、半长向量（extents）和一个变换矩阵组成，变换矩阵定义了盒子的朝向。

-## AABB
-
-`AABB` 在 Math 库中通过 `Bounds` 类型实现，参见 [./bounds/bounds.md](../bounds/bounds.md)。
-
-## OBB - 有向包围盒
-
-OBB 是可以任意方向旋转的包围盒。
+OBB 常用于碰撞检测、剔除运算和物理模拟等场景。

 ## 结构体成员

 | 成员 | 类型 | 描述 |
 |------|------|------|
 | `center` | `Vector3` | OBB 中心点 |
-| `extents` | `Vector3` | 从中心到每个面的距离 |
-| `transform` | `Matrix4` | 变换矩阵 |
+| `extents` | `Vector3` | 从中心到每个面的距离（半长） |
+| `transform` | `Matrix4x4` | 变换矩阵，定义盒子朝向 |

 ## 公共方法

 | 方法 | 描述 |
 |------|------|
-| `OBB()` | 默认构造 |
-| `OBB(const Vector3& center, const Vector3& extents)` | 从中心和半长构造 |
-| [GetAxis](obb-getaxis.md) | 获取局部轴 |
-| [GetMin](obb-getmin.md) | 局部空间最小点 |
-| [GetMax](obb-getmax.md) | 局部空间最大点 |
-| [Contains](obb-contains.md) | 点是否在 OBB 内 |
-| [Intersects(OBB)](intersects-obb.md) | 与另一个 OBB 相交 |
-| [Intersects(Sphere)](intersects-sphere.md) | 与球体相交 |
+| `GetAxis(int index)` | 获取指定索引处的局部轴方向 |
+| `GetMin()` | 获取局部空间最小顶点 |
+| `GetMax()` | 获取局部空间最大顶点 |
+| `Contains(const Vector3& point)` | 检测点是否在 OBB 内 |
+| `Intersects(const OBB& other)` | 检测与另一个 OBB 是否相交 |
+| `Intersects(const Sphere& sphere)` | 检测与球体是否相交 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Math/AABB.h>
+#include <XCEngine/Core/Math/Vector3.h>
+#include <XCEngine/Core/Math/Matrix4.h>
+
+using namespace XCEngine::Math;
+
+OBB obb(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.5f, 1.0f));
+
+Vector3 point(0.5f, 0.25f, 0.5f);
+if (obb.Contains(point)) {
+    // 点在 OBB 内
+}
+
+Vector3 axis = obb.GetAxis(0);
+Vector3 min = obb.GetMin();
+Vector3 max = obb.GetMax();
+```

 ## 相关文档

- [Bounds](../bounds/bounds.md) - 轴对齐包围盒
- [Math 模块总览](../math.md)
+- [Bounds](bounds/bounds.md) - 轴对齐包围盒
+- [Vector3](vector3/vector3.md) - 三维向量
+- [Matrix4](matrix4/matrix4.md) - 4x4 变换矩阵
+- [Sphere](sphere/sphere.md) - 球体
--- a/docs/api/math/bounds/bounds.md
+++ b/docs/api/math/bounds/bounds.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Bounds.h`
+**头文件**: `XCEngine/Core/Math/Bounds.h`

 **描述**: 轴对齐包围盒，用于场景管理中的快速剔除

@@ -37,8 +37,8 @@ Bounds 表示一个轴对齐包围盒（AABB），使用中心点 `center` 和
 ## 使用示例

 ```cpp
-#include <XCEngine/Math/Bounds.h>
-#include <XCEngine/Math/Vector3.h>
+#include <XCEngine/Core/Math/Bounds.h>
+#include <XCEngine/Core/Math/Vector3.h>

 using namespace XCEngine::Math;

--- a/docs/api/math/box/box.md
+++ b/docs/api/math/box/box.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Box.h`
+**头文件**: `XCEngine/Core/Math/Box.h`

 **描述**: 轴对齐盒体，用于碰撞检测和视锥体裁剪

@@ -41,9 +41,9 @@
 ## 使用示例

 ```cpp
-#include <XCEngine/Math/Box.h>
-#include <XCEngine/Math/Vector3.h>
-#include <XCEngine/Math/Sphere.h>
+#include <XCEngine/Core/Math/Box.h>
+#include <XCEngine/Core/Math/Vector3.h>
+#include <XCEngine/Core/Math/Sphere.h>

 using namespace XCEngine::Math;

--- a/docs/api/math/color/color.md
+++ b/docs/api/math/color/color.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Color.h`
+**头文件**: `XCEngine/Core/Math/Color.h`

 **描述**: 颜色结构体，支持 RGBA 浮点分量，用于图形渲染

@@ -79,7 +79,7 @@ Color halfAlpha(0.5f, 0.5f, 0.5f);  // a = 1.0f
 ## 使用示例

 ```cpp
-#include <XCEngine/Math/Color.h>
+#include <XCEngine/Core/Math/Color.h>

 using namespace XCEngine::Math;

--- a/docs/api/math/frustum/frustum.md
+++ b/docs/api/math/frustum/frustum.md
@@ -4,7 +4,7 @@

 **类型**: `class`

-**头文件**: `XCEngine/Math/Frustum.h`
+**头文件**: `XCEngine/Core/Math/Frustum.h`

 **描述**: 视锥体，用于 3D 裁剪和可见性判断

--- a/docs/api/math/math.md
+++ b/docs/api/math/math.md
@@ -43,8 +43,7 @@ Math 模块提供了一套完整的图形数学库，包括向量、矩阵、四
 | [Plane](plane/plane.md) | `Plane.h` | 平面 |
 | [Sphere](sphere/sphere.md) | `Sphere.h` | 球体 |
 | [Box](box/box.md) | `Box.h` | 盒子 |
-| [Bounds](bounds/bounds.md) | `Bounds.h` | 包围盒 |
-| [AABB](aabb/aabb.md) | `AABB.h` | 轴对齐包围盒 |
+| [Bounds](bounds/bounds.md) | `Bounds.h` | 轴对齐包围盒 |
 | [Frustum](frustum/frustum.md) | `Frustum.h` | 视锥体 |
 | [Rect](rect/rect.md) | `Rect.h` | 二维矩形 |

@@ -72,10 +71,10 @@ Math 模块提供了一套完整的图形数学库，包括向量、矩阵、四
 ## 使用示例

 ```cpp
-#include <XCEngine/Math/Math.h>
-#include <XCEngine/Math/Vector3.h>
-#include <XCEngine/Math/Matrix4.h>
-#include <XCEngine/Math/Quaternion.h>
+#include <XCEngine/Core/Math/Math.h>
+#include <XCEngine/Core/Math/Vector3.h>
+#include <XCEngine/Core/Math/Matrix4.h>
+#include <XCEngine/Core/Math/Quaternion.h>

 using namespace XCEngine::Math;

--- a/docs/api/math/matrix3/matrix3.md
+++ b/docs/api/math/matrix3/matrix3.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Matrix3.h`
+**头文件**: `XCEngine/Core/Math/Matrix3.h`

 **描述**: 3x3 矩阵，用于旋转变换和线性代数运算。

@@ -56,8 +56,8 @@ using Matrix3 = Matrix3x3;
 ## 使用示例

 ```cpp
-#include <XCEngine/Math/Matrix3.h>
-#include <XCEngine/Math/Vector3.h>
+#include <XCEngine/Core/Math/Matrix3.h>
+#include <XCEngine/Core/Math/Vector3.h>

 using namespace XCEngine::Math;

--- a/docs/api/math/matrix4/matrix4.md
+++ b/docs/api/math/matrix4/matrix4.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Matrix4.h`
+**头文件**: `XCEngine/Core/Math/Matrix4.h`

 **描述**: 4x4 矩阵，用于 3D 变换（平移、旋转、缩放）、视图和投影计算

@@ -49,9 +49,9 @@
 ## 使用示例

 ```cpp
-#include "XCEngine/Math/Matrix4.h"
-#include "XCEngine/Math/Vector3.h"
-#include "XCEngine/Math/Quaternion.h"
+#include "XCEngine/Core/Math/Matrix4.h"
+#include "XCEngine/Core/Math/Vector3.h"
+#include "XCEngine/Core/Math/Quaternion.h"

 using namespace XCEngine::Math;

--- a/docs/api/math/plane/plane.md
+++ b/docs/api/math/plane/plane.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Plane.h`
+**头文件**: `XCEngine/Core/Math/Plane.h`

 **描述**: 平面，用于 3D 空间中的平面表示和相交测试

@@ -36,9 +36,9 @@
 ## 使用示例

 ```cpp
-#include <XCEngine/Math/Plane.h>
-#include <XCEngine/Math/Vector3.h>
-#include <XCEngine/Math/Sphere.h>
+#include <XCEngine/Core/Math/Plane.h>
+#include <XCEngine/Core/Math/Vector3.h>
+#include <XCEngine/Core/Math/Sphere.h>

 using namespace XCEngine::Math;

--- a/docs/api/math/quaternion/quaternion.md
+++ b/docs/api/math/quaternion/quaternion.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Quaternion.h`
+**头文件**: `XCEngine/Core/Math/Quaternion.h`

 **描述**: 四元数，用于表示三维旋转

@@ -43,9 +43,9 @@ Quaternion 提供了一套完整的三维旋转表示和操作方法。四元数
 ## 使用示例

 ```cpp
-#include <XCEngine/Math/Quaternion.h>
-#include <XCEngine/Math/Vector3.h>
-#include <XCEngine/Math/Math.h>
+#include <XCEngine/Core/Math/Quaternion.h>
+#include <XCEngine/Core/Math/Vector3.h>
+#include <XCEngine/Core/Math/Math.h>

 using namespace XCEngine::Math;

--- a/docs/api/math/ray/ray.md
+++ b/docs/api/math/ray/ray.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Ray.h`
+**头文件**: `XCEngine/Core/Math/Ray.h`

 **描述**: 射线，用于 3D 拾取和光线追踪

@@ -35,9 +35,9 @@
 ## 使用示例

 ```cpp
-#include <XCEngine/Math/Ray.h>
-#include <XCEngine/Math/Vector3.h>
-#include <XCEngine/Math/Sphere.h>
+#include <XCEngine/Core/Math/Ray.h>
+#include <XCEngine/Core/Math/Vector3.h>
+#include <XCEngine/Core/Math/Sphere.h>

 using namespace XCEngine::Math;

--- a/docs/api/math/rect/rect.md
+++ b/docs/api/math/rect/rect.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Rect.h`
+**头文件**: `XCEngine/Core/Math/Rect.h`

 **描述**: 二维矩形，用于表示平面上的矩形区域

@@ -42,8 +42,8 @@ Rect 结构体表示一个二维矩形，由位置 `(x, y)` 和尺寸 `(width, h
 ## 使用示例

 ```cpp
-#include "XCEngine/Math/Rect.h"
-#include "XCEngine/Math/Vector2.h"
+#include "XCEngine/Core/Math/Rect.h"
+#include "XCEngine/Core/Math/Vector2.h"
 #include <iostream>

 using namespace XCEngine::Math;
--- a/docs/api/math/sphere/sphere.md
+++ b/docs/api/math/sphere/sphere.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Sphere.h`
+**头文件**: `XCEngine/Core/Math/Sphere.h`

 **描述**: 球体，用于碰撞检测和范围查询

@@ -31,8 +31,8 @@
 ## 使用示例

 ```cpp
-#include <XCEngine/Math/Sphere.h>
-#include <XCEngine/Math/Vector3.h>
+#include <XCEngine/Core/Math/Sphere.h>
+#include <XCEngine/Core/Math/Vector3.h>

 using namespace XCEngine::Math;

--- a/docs/api/math/transform/transform.md
+++ b/docs/api/math/transform/transform.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Transform.h`
+**头文件**: `XCEngine/Core/Math/Transform.h`

 **描述**: 变换组件，包含位置、旋转和缩放，用于层级变换计算

@@ -43,9 +43,9 @@
 ## 使用示例

 ```cpp
-#include "XCEngine/Math/Transform.h"
-#include "XCEngine/Math/Vector3.h"
-#include "XCEngine/Math/Quaternion.h"
+#include "XCEngine/Core/Math/Transform.h"
+#include "XCEngine/Core/Math/Vector3.h"
+#include "XCEngine/Core/Math/Quaternion.h"

 using namespace XCEngine::Math;

--- a/docs/api/math/vector2/vector2.md
+++ b/docs/api/math/vector2/vector2.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Vector2.h`
+**头文件**: `XCEngine/Core/Math/Vector2.h`

 **描述**: 二维向量，支持 2D 游戏开发和图形计算

@@ -51,7 +51,7 @@ Vector2 是 XCEngine 中的二维向量结构体，用于表示 2D 空间中的
 ## 使用示例

 ```cpp
-#include "XCEngine/Math/Vector2.h"
+#include "XCEngine/Core/Math/Vector2.h"

 using namespace XCEngine::Math;

--- a/docs/api/math/vector3/vector3.md
+++ b/docs/api/math/vector3/vector3.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Vector3.h`
+**头文件**: `XCEngine/Core/Math/Vector3.h`

 **描述**: 三维向量，用于 3D 图形和游戏开发中的位置、方向和缩放计算

@@ -68,7 +68,7 @@ Vector3 是 XCEngine 中用于表示三维向量的核心类型，支持常见
 ## 使用示例

 ```cpp
-#include "XCEngine/Math/Vector3.h"
+#include "XCEngine/Core/Math/Vector3.h"
 #include <iostream>

 using namespace XCEngine::Math;
--- a/docs/api/math/vector4/vector4.md
+++ b/docs/api/math/vector4/vector4.md
@@ -4,7 +4,7 @@

 **类型**: `struct`

-**头文件**: `XCEngine/Math/Vector4.h`
+**头文件**: `XCEngine/Core/Math/Vector4.h`

 **描述**: 四维向量，用于齐次坐标变换和四元数相关计算

@@ -47,8 +47,8 @@ Vector4 是四维向量结构体，常用于：
 ## 使用示例

 ```cpp
-#include <XCEngine/Math/Vector4.h>
-#include <XCEngine/Math/Vector3.h>
+#include <XCEngine/Core/Math/Vector4.h>
+#include <XCEngine/Core/Math/Vector3.h>
 #include <cstdio>

 int main() {
--- a/docs/api/math/viewport/viewport.md
+++ b/docs/api/math/viewport/viewport.md
@@ -2,7 +2,7 @@

 渲染视口结构体，用于屏幕到归一化坐标的映射。

-**头文件：** `#include <XCEngine/Math/Rect.h>`
+**头文件：** `#include <XCEngine/Core/Math/Rect.h>`

 **命名空间：** `XCEngine::Math`

--- a/docs/api/memory/proxy-allocator/constructor.md
+++ b/docs/api/memory/proxy-allocator/constructor.md
@@ -0,0 +1,39 @@
+# ProxyAllocator::ProxyAllocator
+
+```cpp
+ProxyAllocator(IAllocator* underlying, const char* name);
+```
+
+构造一个代理分配器，包装底层分配器并记录分配统计。所有 `Allocate`、`Free`、`Reallocate` 调用都会被转发到底层分配器，同时记录统计信息。名称用于日志和报告。
+
+**参数：**
+- `underlying` - 被包装的底层分配器，不能为 `nullptr`
+- `name` - 代理分配器的名称字符串
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**线程安全：** ✅ (内部使用 mutex 保护统计数据)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+#include <XCEngine/Memory/ProxyAllocator.h>
+
+MemoryManager::Get().Initialize();
+
+// 使用系统分配器作为底层
+IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
+ProxyAllocator proxy(sysAlloc, "TempAllocations");
+
+// 通过代理分配
+void* ptr = proxy.Allocate(1024);
+proxy.Free(ptr);
+```
+
+## 相关文档
+
+- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览
+- [`~ProxyAllocator`](~proxy-allocator.md) - 析构函数
--- a/docs/api/resources/audio-loader/index.md
+++ b/docs/api/resources/audio-loader/index.md
@@ -22,7 +22,7 @@
 |------|--------|------|
 | [AudioLoader](constructor.md) | - | 构造函数 |
 | [~AudioLoader](destructor.md) | - | 析构函数 |
-| [GetResourceType](get-resource-type.md) | `ResourceType` | 返回资源类型 `AudioClip` |
+| [GetResourceType](../shader-loader/methods/get-resource-type.md) | `ResourceType` | 返回资源类型 `AudioClip` |
 | [GetSupportedExtensions](get-supported-extensions.md) | `Array<String>` | 获取支持的扩展名列表 |
 | [CanLoad](can-load.md) | `bool` | 检查是否能够加载指定路径的资源 |
 | [Load](load.md) | `LoadResult` | 加载音频资源 |
--- a/docs/api/resources/resources.md
+++ b/docs/api/resources/resources.md
@@ -21,7 +21,7 @@ Resources 模块提供了一套完整的资源管理解决方案，支持同步
 | [IResource](iresource/iresource.md) | `IResource.h` | 资源基类 |
 | [ResourceHandle](resourcehandle/resourcehandle.md) | `ResourceHandle.h` | 资源句柄模板 |
 | [IResourceLoader](iloader/iloader.md) | `IResourceLoader.h` | 资源加载器接口 |
-| [ShaderLoader](shaderloader/index.md) | `ShaderLoader.h` | 着色器加载器 |
+| [ShaderLoader](../rhi/d3d12/fence/index.md) | `ShaderLoader.h` | 着色器加载器 |
 | [ResourceManager](resourcemanager/resourcemanager.md) | `ResourceManager.h` | 资源管理器 |
 | [ResourceCache](resourcecache/resourcecache.md) | `ResourceCache.h` | 资源缓存 |
 | [AsyncLoader](asyncloader/asyncloader.md) | `AsyncLoader.h` | 异步加载器 |
--- a/docs/api/resources/texture-loader/index.md
+++ b/docs/api/resources/texture-loader/index.md
@@ -36,11 +36,11 @@
 |------|------|
 | [TextureLoader](constructor.md) | 构造函数 |
 | [~TextureLoader](destructor.md) | 析构函数 |
-| [GetResourceType](get-resource-type.md) | 返回 `ResourceType::Texture` |
-| [GetSupportedExtensions](get-supported-extensions.md) | 获取支持的扩展名列表 |
-| [CanLoad](can-load.md) | 检查是否支持加载指定路径的纹理 |
-| [Load](load.md) | 加载纹理资源 |
-| [GetDefaultSettings](get-default-settings.md) | 获取默认导入设置 |
+| [GetResourceType](../shader-loader/methods/get-resource-type.md) | 返回 `ResourceType::Texture` |
+| [GetSupportedExtensions](../audio-loader/get-supported-extensions.md) | 获取支持的扩展名列表 |
+| [CanLoad](../audio-loader/can-load.md) | 检查是否支持加载指定路径的纹理 |
+| [Load](../../scene/scene/load.md) | 加载纹理资源 |
+| [GetDefaultSettings](../audio-loader/get-default-settings.md) | 获取默认导入设置 |

 ### GetResourceType

--- a/docs/api/scene/scene-manager/scene-manager.md
+++ b/docs/api/scene/scene-manager/scene-manager.md
@@ -71,4 +71,4 @@ void SceneManagerExample() {
 ## 相关文档

 - [Scene 模块总览](../scene.md) - Scene 模块总览
- [Scene](scene/scene.md) - 场景类
+- [Scene](../scene.md) - 场景类
--- a/docs/api/scene/scene/create-game-object.md
+++ b/docs/api/scene/scene/create-game-object.md
@@ -1,35 +1,35 @@
-# CreateGameObject
+# Scene::CreateGameObject

-Create a new GameObject in this scene.
-
-## Syntax
+在场景中创建新的 GameObject。

 ```cpp
 GameObject* CreateGameObject(const std::string& name, GameObject* parent = nullptr);
 ```

-## Parameters
+创建一个具有指定名称的新 GameObject，并可选择设置其父对象。GameObject 由场景拥有，当场景被销毁时也会被销毁。

- `name` - The name of the new GameObject.
- `parent` - Optional parent GameObject (defaults to `nullptr`).
+**参数：**
+- `name` - 新 GameObject 的名称
+- `parent` - 可选的父 GameObject（默认为 `nullptr`）

-## Returns
+**返回：** `GameObject*` - 指向新创建的 GameObject 的指针

-Returns a pointer to the newly created `GameObject`.
+**线程安全：** ❌ (非线程安全，应在主线程调用)

-## Remarks
-
-Creates a new GameObject with the specified name and optionally sets its parent. The GameObject is owned by the scene and will be destroyed when the scene is destroyed.
-
-## See Also
-
- [DestroyGameObject](destroy-game-object)
-
-## Examples
+**示例：**

 ```cpp
+#include <XCEngine/Scene/Scene.h>
+
+using namespace XCEngine::Components;
+
 void Example(Scene* scene) {
    GameObject* player = scene->CreateGameObject("Player");
    GameObject* weapon = scene->CreateGameObject("Sword", player);
 }
 ```
+
+## 相关文档
+
+- [Scene 总览](scene.md) - 返回类总览
+- [DestroyGameObject](destroy-game-object.md) - 销毁 GameObject
--- a/docs/api/scene/scene/deserialize-from-string.md
+++ b/docs/api/scene/scene/deserialize-from-string.md
@@ -0,0 +1,40 @@
+# Scene::DeserializeFromString
+
+从字符串反序列化场景。
+
+```cpp
+void DeserializeFromString(const std::string& data);
+```
+
+从 JSON 格式的字符串数据恢复场景的完整状态，包括所有 GameObject、组件和层级结构。
+
+**参数：**
+- `data` - JSON 格式的序列化数据
+
+**线程安全：** ❌ (非线程安全，应在主线程调用)
+
+**注意：**
+- 此操作会清空当前场景的所有数据
+- 反序列化后的 GameObject 引用可能与原始引用不同
+
+**示例：**
+
+```cpp
+#include <XCEngine/Scene/Scene.h>
+
+using namespace XCEngine::Components;
+
+void Example(Scene* scene) {
+    std::string data = R"({
+        "name": "GameScene",
+        "gameObjects": [...]
+    })";
+    scene->DeserializeFromString(data);
+}
+```
+
+## 相关文档
+
+- [Scene 总览](scene.md) - 返回类总览
+- [Save](save.md) - 保存到文件
+- [SerializeToString](serialize-to-string.md) - 序列化为字符串
--- a/docs/api/scene/scene/find-by-id.md
+++ b/docs/api/scene/scene/find-by-id.md
@@ -0,0 +1,36 @@
+# Scene::FindByID
+
+按 ID 查找 GameObject。
+
+```cpp
+GameObject* FindByID(GameObjectID id) const;
+```
+
+通过游戏对象的唯一标识符查找 GameObject。
+
+**参数：**
+- `id` - GameObject 的唯一标识符
+
+**返回：** `GameObject*` - 指向找到的 GameObject 的指针，未找到则返回 `nullptr`
+
+**线程安全：** ✅ (只读操作)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Scene/Scene.h>
+
+using namespace XCEngine::Components;
+
+void Example(Scene* scene, GameObjectID id) {
+    GameObject* obj = scene->FindByID(id);
+    if (obj) {
+        printf("Found object: %s\n", obj->GetName().c_str());
+    }
+}
+```
+
+## 相关文档
+
+- [Scene 总览](scene.md) - 返回类总览
+- [Find](find.md) - 按名称查找
--- a/docs/api/scene/scene/find.md
+++ b/docs/api/scene/scene/find.md
@@ -1,36 +1,36 @@
-# Find
+# Scene::Find

-Find a GameObject by name.
-
-## Syntax
+按名称查找 GameObject。

 ```cpp
 GameObject* Find(const std::string& name) const;
 ```

-## Parameters
+在场景中搜索具有指定名称的 GameObject。搜索包括所有根对象及其子对象。

- `name` - The name of the GameObject to find.
+**参数：**
+- `name` - 要查找的 GameObject 名称

-## Returns
+**返回：** `GameObject*` - 指向找到的 GameObject 的指针，未找到则返回 `nullptr`

-Returns a pointer to the GameObject with the specified name, or `nullptr` if not found.
+**线程安全：** ✅ (只读操作)

-## Remarks
-
-Searches the scene for a GameObject with the specified name. The search includes all root GameObjects and their children.
-
-## See Also
-
- [FindGameObjectWithTag](find-game-object-with-tag)
-
-## Examples
+**示例：**

 ```cpp
+#include <XCEngine/Scene/Scene.h>
+
+using namespace XCEngine::Components;
+
 void Example(Scene* scene) {
    GameObject* player = scene->Find("Player");
    if (player) {
-        XC_LOG_INFO("Found player!");
+        printf("Found player!\n");
    }
 }
 ```
+
+## 相关文档
+
+- [Scene 总览](scene.md) - 返回类总览
+- [FindGameObjectWithTag](find-game-object-with-tag.md) - 按标签查找
--- a/docs/api/scene/scene/scene.md
+++ b/docs/api/scene/scene/scene.md
@@ -42,6 +42,7 @@ Scene 是 XCEngine 中的场景类，代表一个独立的游戏空间（如主
 | 方法 | 描述 |
 |------|------|
 | [`Find`](find.md) | 按名称查找 GameObject |
+| [`FindByID`](find-by-id.md) | 按 ID 查找 GameObject |
 | [`FindGameObjectWithTag`](find-game-object-with-tag.md) | 按标签查找 GameObject |
 | [`FindObjectOfType`](find-object-of-type.md) | 查找指定类型的组件 |
 | [`FindObjectsOfType`](find-objects-of-type.md) | 查找所有指定类型的组件 |
@@ -54,8 +55,10 @@ Scene 是 XCEngine 中的场景类，代表一个独立的游戏空间（如主
 | [`Update`](update.md) | 每帧更新场景 |
 | [`FixedUpdate`](fixed-update.md) | 固定频率更新 |
 | [`LateUpdate`](late-update.md) | 晚更新 |
-| [`Load`](load.md) | 加载场景 |
-| [`Save`](save.md) | 保存场景 |
+| [`Load`](load.md) | 从文件加载场景 |
+| [`Save`](save.md) | 保存场景到文件 |
+| [`SerializeToString`](serialize-to-string.md) | 序列化为字符串 |
+| [`DeserializeFromString`](deserialize-from-string.md) | 从字符串反序列化 |

 ### 事件

@@ -86,5 +89,5 @@ void SceneExample(Scene* scene) {
 ## 相关文档

 - [Scene 模块总览](../scene.md) - Scene 模块总览
- [SceneManager](scene-manager/scene-manager.md) - 场景管理器
- [GameObject](../components/game-object/game-object.md) - 游戏对象
+- [SceneManager](../scene-manager/scene-manager.md) - 场景管理器
+- [GameObject](../../components/game-object/game-object.md) - 游戏对象
--- a/docs/api/scene/scene/serialize-to-string.md
+++ b/docs/api/scene/scene/serialize-to-string.md
@@ -0,0 +1,33 @@
+# Scene::SerializeToString
+
+将场景序列化为字符串。
+
+```cpp
+std::string SerializeToString() const;
+```
+
+将场景的所有数据（包括所有 GameObject、组件和层级结构）序列化为 JSON 格式的字符串。
+
+**返回：** `std::string` - 序列化后的 JSON 字符串
+
+**线程安全：** ✅ (只读操作)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Scene/Scene.h>
+
+using namespace XCEngine::Components;
+
+void Example(Scene* scene) {
+    std::string serialized = scene->SerializeToString();
+    printf("Serialized scene (%zu bytes):\n%s\n", 
+        serialized.size(), serialized.c_str());
+}
+```
+
+## 相关文档
+
+- [Scene 总览](scene.md) - 返回类总览
+- [Load](load.md) - 从文件加载
+- [DeserializeFromString](deserialize-from-string.md) - 从字符串反序列化
--- a/docs/api/threading/task-system/task-system.md
+++ b/docs/api/threading/task-system/task-system.md
@@ -24,8 +24,6 @@

 | 方法 | 描述 |
 |------|------|
-| [`TaskSystem()`](task-system.md) | 私有构造函数（单例） |
-| [`~TaskSystem()`](task-system.md) | 析构函数 |
 | [`Initialize`](initialize.md) | 初始化任务系统 |
 | [`Shutdown`](shutdown.md) | 关闭任务系统 |
 | [`Submit(unique_ptr)`](submit.md) | 提交任务对象 |