fix: improve doc link navigation and tree display

- Fix link resolution with proper relative/absolute path handling
- Improve link styling with underline decoration
- Hide leaf nodes from tree, only show directories
- Fix log file path for packaged app

docs/api/math/aabb/aabb.md

@@ -0,0 +1,43 @@
+# AABB / OBB
+
+轴对齐包围盒 (AABB) 和有向包围盒 (OBB)。
+
+**头文件：** `#include <XCEngine/Math/AABB.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## AABB
+
+`AABB` 在 Math 库中通过 `Bounds` 类型实现，参见 [./bounds/bounds.md](../bounds/bounds.md)。
+
+## OBB - 有向包围盒
+
+OBB 是可以任意方向旋转的包围盒。
+
+```cpp
+struct OBB {
+    Vector3 center;
+    Vector3 extents;
+    Matrix4 transform;
+};
+```
+
+### 构造函数
+
+- `OBB()` - 默认构造
+- `OBB(const Vector3& center, const Vector3& extents)` - 从中心和半长构造
+
+### 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [GetAxis(index)](getaxis.md) | `Vector3` | 获取局部轴（index 必须是 0、1 或 2） |
+| [GetMin()](../box/getmin.md) | `Vector3` | 局部空间最小点 |
+| [GetMax()](../box/getmax.md) | `Vector3` | 局部空间最大点 |
+| [Contains(point)](../box/contains.md) | `bool` | 点是否在 OBB 内 |
+| [Intersects(OBB)](intersects-obb.md) | `bool` | 与另一个 OBB 相交 |
+| [Intersects(Sphere)](intersects-sphere.md) | `bool` | 与球体相交 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/aabb/getaxis.md

@@ -0,0 +1,23 @@
+# OBB::GetAxis
+
+```cpp
+Vector3 GetAxis(int index) const
+```
+
+获取 OBB 的局部坐标轴。
+
+**参数：**
+- `index` - 轴索引（0=X轴, 1=Y轴, 2=Z轴）
+
+**返回：** `Vector3` - 对应轴的方向向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+OBB obb = ...;
+Vector3 xAxis = obb.GetAxis(0);  // 局部 X 轴
+Vector3 yAxis = obb.GetAxis(1);  // 局部 Y 轴
+Vector3 zAxis = obb.GetAxis(2);  // 局部 Z 轴
+```

docs/api/math/aabb/intersects-obb.md

@@ -0,0 +1,24 @@
+# OBB::Intersects (OBB)
+
+```cpp
+bool Intersects(const OBB& other) const
+```
+
+检测两个 OBB 是否相交（使用 SAT 分离轴定理）。
+
+**参数：**
+- `other` - 另一个 OBB
+
+**返回：** `bool` - true 表示相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+OBB obbA = ...;
+OBB obbB = ...;
+if (obbA.Intersects(obbB)) {
+    // 两个有向包围盒相交
+}
+```

docs/api/math/aabb/intersects-sphere.md

@@ -0,0 +1,24 @@
+# OBB::Intersects (Sphere)
+
+```cpp
+bool Intersects(const Sphere& sphere) const
+```
+
+检测 OBB 是否与球体相交。
+
+**参数：**
+- `sphere` - 要检测的球体
+
+**返回：** `bool` - true 表示相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+OBB obb = ...;
+Sphere sphere = ...;
+if (obb.Intersects(sphere)) {
+    // OBB 与球体相交
+}
+```

docs/api/math/aabb/obb-contains.md

@@ -0,0 +1,20 @@
+# OBB::Contains
+
+```cpp
+bool Contains(const Vector3& point) const
+```
+
+检测点是否在 OBB 内。
+
+**参数：**
+- `point` - 要检测的点
+
+**返回：** `bool` - true 表示点在 OBB 内
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (obb.Contains(point)) { /* inside */ }
+```

docs/api/math/aabb/obb-getaxis.md

@@ -0,0 +1,20 @@
+# OBB::GetAxis
+
+```cpp
+Vector3 GetAxis(int index) const
+```
+
+获取 OBB 的局部轴。
+
+**参数：**
+- `index` - 轴索引 (0=X, 1=Y, 2=Z)
+
+**返回：** `Vector3` - 对应的局部轴
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 xAxis = obb.GetAxis(0);
+```

docs/api/math/aabb/obb-getmax.md

@@ -0,0 +1,17 @@
+# OBB::GetMax
+
+```cpp
+Vector3 GetMax() const
+```
+
+获取局部空间最大点。
+
+**返回：** `Vector3` - center + extents
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 max = obb.GetMax();
+```

docs/api/math/aabb/obb-getmin.md

@@ -0,0 +1,17 @@
+# OBB::GetMin
+
+```cpp
+Vector3 GetMin() const
+```
+
+获取局部空间最小点。
+
+**返回：** `Vector3` - center - extents
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 min = obb.GetMin();
+```

docs/api/math/aabb/obb-intersects-obb.md

@@ -0,0 +1,25 @@
+# OBB::Intersects(OBB)
+
+```cpp
+bool Intersects(const OBB& other) const;
+```
+
+判断两个 OBB 是否相交（SAT 分离轴定理）。
+
+**返回：** 两包围盒是否相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+OBB a(centerA, extentsA);
+OBB b(centerB, extentsB);
+if (a.Intersects(b)) {
+    // 两包围盒相交
+}
+```
+
+## 相关文档
+
+- [AABB 总览](aabb.md) - 返回 AABB 概览

docs/api/math/aabb/obb-intersects-sphere.md

@@ -0,0 +1,28 @@
+# OBB::Intersects(Sphere)
+
+```cpp
+bool Intersects(const Sphere& sphere) const;
+```
+
+判断 OBB 与球体是否相交。
+
+**参数：**
+- `sphere` - 球体
+
+**返回：** OBB 与球体是否相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+OBB obb(center, extents);
+Sphere s(sphereCenter, radius);
+if (obb.Intersects(s)) {
+    // OBB 与球体相交
+}
+```
+
+## 相关文档
+
+- [AABB 总览](aabb.md) - 返回 AABB 概览

docs/api/math/bounds/bounds.md

@@ -0,0 +1,40 @@
+# Bounds
+
+轴对齐包围盒 (AABB)，中心-范围表示。
+
+**头文件：** `#include <XCEngine/Math/Bounds.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 结构体定义
+
+```cpp
+struct Bounds {
+    Vector3 center = Vector3::Zero();
+    Vector3 extents = Vector3::Zero();
+};
+```
+
+## 构造函数
+
+- `Bounds()` - 默认构造
+- `Bounds(const Vector3& center, const Vector3& size)` - 从中心和大小构造
+
+## 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [GetMin()](getmin.md) | `Vector3` | 最小点 |
+| [GetMax()](getmax.md) | 最大点 |
+| [SetMinMax(min, max)](setminmax.md) | `void` | 从最小/最大点设置 |
+| [Contains(point)](contains.md) | `bool` | 点是否在盒内 |
+| [Intersects(other)](intersects.md) | `bool` | 与另一个 Bounds 相交 |
+| [Encapsulate(point)](encapsulate.md) | `void` | 扩展包含点 |
+| [Encapsulate(bounds)](encapsulate-bounds.md) | `void` | 扩展包含另一个 Bounds |
+| [Expand(amount)](expand.md) | `void` | 扩展包围盒 |
+| [GetClosestPoint(point)](getclosestpoint.md) | `Vector3` | 盒上最接近的点 |
+| [GetVolume()](getvolume.md) | `float` | 体积 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/bounds/contains.md

@@ -0,0 +1,20 @@
+# Bounds::Contains
+
+```cpp
+bool Contains(const Vector3& point) const
+```
+
+检测点是否在包围盒内。
+
+**参数：**
+- `point` - 要检测的点
+
+**返回：** `bool` - true 表示点在盒内
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (bounds.Contains(point)) { /* inside */ }
+```

docs/api/math/bounds/encapsulate-bounds.md

@@ -0,0 +1,18 @@
+# Bounds::Encapsulate (Bounds)
+
+```cpp
+void Encapsulate(const Bounds& bounds)
+```
+
+扩展包围盒以包含另一个 Bounds。
+
+**参数：**
+- `bounds` - 要包含的 Bounds
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+bounds.Encapsulate(otherBounds);
+```

docs/api/math/bounds/encapsulate.md

@@ -0,0 +1,21 @@
+# Bounds::Encapsulate
+
+```cpp
+void Encapsulate(const Vector3& point)
+void Encapsulate(const Bounds& bounds)
+```
+
+扩展包围盒以包含点或另一个 Bounds。
+
+**参数：**
+- `point` - 要包含的点
+- `bounds` - 要包含的 Bounds
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+bounds.Encapsulate(point);
+bounds.Encapsulate(otherBounds);
+```

docs/api/math/bounds/expand.md

@@ -0,0 +1,19 @@
+# Bounds::Expand
+
+```cpp
+void Expand(float amount)
+void Expand(const Vector3& amount)
+```
+
+扩展包围盒。
+
+**参数：**
+- `amount` - 扩展量（各方向或统一）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+bounds.Expand(1.0f);
+```

docs/api/math/bounds/getclosestpoint.md

@@ -0,0 +1,20 @@
+# Bounds::GetClosestPoint
+
+```cpp
+Vector3 GetClosestPoint(const Vector3& point) const
+```
+
+获取包围盒上最接近给定点的点。
+
+**参数：**
+- `point` - 参考点
+
+**返回：** `Vector3` - 盒上最接近的点
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 closest = bounds.GetClosestPoint(point);
+```

docs/api/math/bounds/getmax.md

@@ -0,0 +1,17 @@
+# Bounds::GetMax
+
+```cpp
+Vector3 GetMax() const
+```
+
+获取包围盒的最大点。
+
+**返回：** `Vector3` - center + extents
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 max = bounds.GetMax();
+```

docs/api/math/bounds/getmin.md

@@ -0,0 +1,17 @@
+# Bounds::GetMin
+
+```cpp
+Vector3 GetMin() const
+```
+
+获取包围盒的最小点。
+
+**返回：** `Vector3` - center - extents
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 min = bounds.GetMin();
+```

docs/api/math/bounds/getvolume.md

@@ -0,0 +1,17 @@
+# Bounds::GetVolume
+
+```cpp
+float GetVolume() const
+```
+
+计算包围盒的体积。
+
+**返回：** `float` - 体积
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+float vol = bounds.GetVolume();
+```

docs/api/math/bounds/intersects.md

@@ -0,0 +1,20 @@
+# Bounds::Intersects
+
+```cpp
+bool Intersects(const Bounds& other) const
+```
+
+检测两个 Bounds 是否相交。
+
+**参数：**
+- `other` - 另一个 Bounds
+
+**返回：** `bool` - true 表示相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (bounds.Intersects(other)) { /* collision */ }
+```

docs/api/math/bounds/setminmax.md

@@ -0,0 +1,19 @@
+# Bounds::SetMinMax
+
+```cpp
+void SetMinMax(const Vector3& min, const Vector3& max)
+```
+
+从最小/最大点设置包围盒。
+
+**参数：**
+- `min` - 最小点
+- `max` - 最大点
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+bounds.SetMinMax(minPoint, maxPoint);
+```

docs/api/math/box/box.md

@@ -0,0 +1,44 @@
+# Box
+
+带变换的包围盒结构体（支持 OBB 语义，取决于方法）。
+
+**头文件：** `#include <XCEngine/Math/Box.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 结构体定义
+
+```cpp
+struct Box {
+    Vector3 center = Vector3::Zero();
+    Vector3 extents = Vector3::Zero();
+    Matrix4x4 transform = Matrix4x4::Identity();
+};
+```
+
+**成员：**
+- `center` - 包围盒中心点
+- `extents` - 包围盒半长（各轴向的半径）
+- `transform` - 变换矩阵（用于 OBB 检测）
+
+**注意：** `Contains` 方法会使用 `transform` 进行真正的 OBB 检测。`Intersects(Box)` 目前使用 AABB 简化算法，未考虑旋转。
+
+## 构造函数
+
+- `Box()` - 默认构造
+- `Box(const Vector3& center, const Vector3& extents)` - 从中心和半长构造
+
+## 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [GetMin()](getmin.md) | `Vector3` | 局部空间最小点 |
+| [GetMax()](getmax.md) | `Vector3` | 局部空间最大点 |
+| [Contains(point)](contains.md) | `bool` | 点是否在盒内（使用 transform） |
+| [Intersects(Sphere)](intersects.md) | `bool` | 与球体相交 |
+| [Intersects(Box)](intersects-box.md) | `bool` | 与另一个盒相交（AABB 检测） |
+| [Intersects(Ray, t)](intersects-ray.md) | `bool` | 与射线相交 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/box/contains.md

@@ -0,0 +1,20 @@
+# Box::Contains
+
+```cpp
+bool Contains(const Vector3& point) const
+```
+
+检测点是否在盒内。
+
+**参数：**
+- `point` - 要检测的点
+
+**返回：** `bool` - true 表示点在盒内
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (box.Contains(point)) { /* inside */ }
+```

docs/api/math/box/getmax.md

@@ -0,0 +1,17 @@
+# Box::GetMax
+
+```cpp
+Vector3 GetMax() const
+```
+
+获取局部空间最大点。
+
+**返回：** `Vector3` - (+extents)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 max = box.GetMax();
+```

docs/api/math/box/getmin.md

@@ -0,0 +1,17 @@
+# Box::GetMin
+
+```cpp
+Vector3 GetMin() const
+```
+
+获取局部空间最小点。
+
+**返回：** `Vector3` - (-extents)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 min = box.GetMin();
+```

docs/api/math/box/intersects-box.md

@@ -0,0 +1,22 @@
+# Box::Intersects (Box)
+
+```cpp
+bool Intersects(const Box& other) const
+```
+
+检测两个盒是否相交（使用 AABB 简化算法，暂未考虑 transform 旋转）。
+
+**参数：**
+- `other` - 另一个盒
+
+**返回：** `bool` - true 表示相交
+
+**注意：** 当前实现为 AABB 检测，未使用 transform 进行真正的 OBB-SAT 检测。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (box.Intersects(otherBox)) { /* collision */ }
+```

docs/api/math/box/intersects-ray.md

@@ -0,0 +1,24 @@
+# Box::Intersects (Ray)
+
+```cpp
+bool Intersects(const Ray& ray, float& t) const
+```
+
+检测盒是否与射线相交。
+
+**参数：**
+- `ray` - 射线
+- `t` - 输出交点距离
+
+**返回：** `bool` - true 表示相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+float t;
+if (box.Intersects(ray, t)) {
+    Vector3 hit = ray.GetPoint(t);
+}
+```

docs/api/math/box/intersects.md

@@ -0,0 +1,20 @@
+# Box::Intersects
+
+```cpp
+bool Intersects(const Sphere& sphere) const
+```
+
+检测盒是否与球体相交。
+
+**参数：**
+- `sphere` - 球体
+
+**返回：** `bool` - true 表示相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (box.Intersects(sphere)) { /* collision */ }
+```

docs/api/math/color/black.md

@@ -0,0 +1,11 @@
+# Color::Black
+
+```cpp
+static Color Black()
+```
+
+返回黑色 (0, 0, 0, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Black();`

docs/api/math/color/blue.md

@@ -0,0 +1,11 @@
+# Color::Blue
+
+```cpp
+static Color Blue()
+```
+
+返回蓝色 (0, 0, 1, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Blue();`

docs/api/math/color/clear.md

@@ -0,0 +1,11 @@
+# Color::Clear
+
+```cpp
+static Color Clear()
+```
+
+返回透明黑色 (0, 0, 0, 0)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Clear();`

docs/api/math/color/color.md

@@ -0,0 +1,64 @@
+# Color
+
+颜色结构体，支持 RGBA 浮点分量。
+
+**头文件：** `#include <XCEngine/Math/Color.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 结构体定义
+
+```cpp
+struct Color {
+    float r = 1.0f;
+    float g = 1.0f;
+    float b = 1.0f;
+    float a = 1.0f;
+};
+```
+
+## 构造函数
+
+- `Color()` - 默认构造，初始化为白色 (1, 1, 1, 1)
+- `constexpr Color(float r, float g, float b, float a = 1.0f)` - 从 RGBA 分量构造
+
+## 静态工厂方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [White()](white.md) | `Color` | (1, 1, 1, 1) |
+| [Black()](black.md) | `Color` | (0, 0, 0, 1) |
+| [Red()](red.md) | `Color` | (1, 0, 0, 1) |
+| [Green()](green.md) | `Color` | (0, 1, 0, 1) |
+| [Blue()](blue.md) | `Color` | (0, 0, 1, 1) |
+| [Yellow()](yellow.md) | `Color` | (1, 1, 0, 1) |
+| [Cyan()](cyan.md) | `Color` | (0, 1, 1, 1) |
+| [Magenta()](magenta.md) | `Color` | (1, 0, 1, 1) |
+| [Clear()](clear.md) | `Color` | (0, 0, 0, 0)，透明黑 |
+
+## 静态方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Lerp(a, b, t)](lerp.md) | `Color` | 颜色线性插值 |
+
+## 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [ToRGBA()](torgba.md) | `uint32_t` | 转换为 32-bit RGBA (0xRRGGBBAA) |
+| [ToVector3()](tovector3.md) | `Vector3` | 转换为 RGB (丢弃 alpha) |
+| [ToVector4()](tovector4.md) | `Vector4` | 转换为 RGBA |
+
+## 运算符
+
+| 运算符 | 描述 |
+|--------|------|
+| `operator+(Color, Color)` | 颜色相加 |
+| `operator-(Color, Color)` | 颜色相减 |
+| `operator*(Color, float)` | 颜色乘以标量 |
+| `operator/(Color, float)` | 颜色除以标量 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/color/cyan.md

@@ -0,0 +1,11 @@
+# Color::Cyan
+
+```cpp
+static Color Cyan()
+```
+
+返回青色 (0, 1, 1, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Cyan();`

docs/api/math/color/green.md

@@ -0,0 +1,11 @@
+# Color::Green
+
+```cpp
+static Color Green()
+```
+
+返回绿色 (0, 1, 0, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Green();`

docs/api/math/color/lerp.md

@@ -0,0 +1,22 @@
+# Color::Lerp
+
+```cpp
+static Color Lerp(const Color& a, const Color& b, float t)
+```
+
+在两个颜色之间进行线性插值。
+
+**参数：**
+- `a` - 起始颜色
+- `b` - 结束颜色
+- `t` - 插值因子 (0-1)
+
+**返回：** `Color` - 插值结果
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color lerped = Color::Lerp(Color::Red(), Color::Blue(), 0.5f);
+```

docs/api/math/color/magenta.md

@@ -0,0 +1,11 @@
+# Color::Magenta
+
+```cpp
+static Color Magenta()
+```
+
+返回品红色 (1, 0, 1, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Magenta();`

docs/api/math/color/red.md

@@ -0,0 +1,11 @@
+# Color::Red
+
+```cpp
+static Color Red()
+```
+
+返回红色 (1, 0, 0, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Red();`

docs/api/math/color/torgba.md

@@ -0,0 +1,18 @@
+# Color::ToRGBA
+
+```cpp
+uint32_t ToRGBA() const
+```
+
+将颜色转换为 32-bit RGBA 整数格式。
+
+**返回：** `uint32_t` - RGBA 值 (0xRRGGBBAA)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color c(1.0f, 0.0f, 0.0f, 1.0f);
+uint32_t rgba = c.ToRGBA();
+```

docs/api/math/color/tovector3.md

@@ -0,0 +1,17 @@
+# Color::ToVector3
+
+```cpp
+Vector3 ToVector3() const
+```
+
+将颜色转换为 Vector3（丢弃 alpha）。
+
+**返回：** `Vector3` - RGB 值
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 rgb = Color::Red().ToVector3();
+```

docs/api/math/color/tovector4.md

@@ -0,0 +1,17 @@
+# Color::ToVector4
+
+```cpp
+Vector4 ToVector4() const
+```
+
+将颜色转换为 Vector4。
+
+**返回：** `Vector4` - RGBA 值
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector4 rgba = Color::Red().ToVector4();
+```

docs/api/math/color/white.md

@@ -0,0 +1,11 @@
+# Color::White
+
+```cpp
+static Color White()
+```
+
+返回白色 (1, 1, 1, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::White();`

docs/api/math/color/yellow.md

@@ -0,0 +1,11 @@
+# Color::Yellow
+
+```cpp
+static Color Yellow()
+```
+
+返回黄色 (1, 1, 0, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Yellow();`

docs/api/math/frustum/contains-bounds.md

@@ -0,0 +1,25 @@
+# Frustum::Contains (bounds)
+
+```cpp
+bool Contains(const Bounds& bounds) const
+```
+
+检测轴对齐包围盒是否完全在视锥体内。
+
+**参数：**
+- `bounds` - 要检测的轴对齐包围盒
+
+**返回：** `bool` - Bounds 完全在视锥内返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Frustum frustum = camera.CalculateFrustum();
+Bounds objectBounds = object.GetWorldBounds();
+if (frustum.Contains(objectBounds)) {
+    // 包围盒完全在视锥内，需要渲染
+    Render(object);
+}
+```

docs/api/math/frustum/contains-point.md

@@ -0,0 +1,24 @@
+# Frustum::Contains (point)
+
+```cpp
+bool Contains(const Vector3& point) const
+```
+
+检测点是否在视锥体内。
+
+**参数：**
+- `point` - 要检测的世界空间点
+
+**返回：** `bool` - 点在视锥内返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Frustum frustum = camera.CalculateFrustum();
+Vector3 point = object.GetPosition();
+if (frustum.Contains(point)) {
+    // 点在视锥内
+}
+```

docs/api/math/frustum/contains-sphere.md

@@ -0,0 +1,24 @@
+# Frustum::Contains (sphere)
+
+```cpp
+bool Contains(const Sphere& sphere) const
+```
+
+检测球体是否完全在视锥体内。
+
+**参数：**
+- `sphere` - 要检测的球体
+
+**返回：** `bool` - 球体完全在视锥内返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Frustum frustum = camera.CalculateFrustum();
+Sphere collider = object.GetBoundingSphere();
+if (frustum.Contains(collider)) {
+    // 球体完全在视锥内
+}
+```

docs/api/math/frustum/frustum.md

@@ -0,0 +1,45 @@
+# Frustum
+
+视锥体，用于视锥剔除。
+
+**头文件：** `#include <XCEngine/Math/Frustum.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 类定义
+
+```cpp
+class Frustum {
+public:
+    Plane planes[6];
+
+    enum class PlaneIndex {
+        Left = 0,
+        Right = 1,
+        Bottom = 2,
+        Top = 3,
+        Near = 4,
+        Far = 5
+    };
+
+    bool Contains(const Vector3& point) const;
+    bool Contains(const Sphere& sphere) const;
+    bool Contains(const Bounds& bounds) const;
+    bool Intersects(const Bounds& bounds) const;
+    bool Intersects(const Sphere& sphere) const;
+};
+```
+
+## 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Contains(point)](contains-point.md) | `bool` | 点是否在视锥内 |
+| [Contains(sphere)](contains-sphere.md) | `bool` | 球体是否完全在视锥内 |
+| [Contains(bounds)](contains-bounds.md) | `bool` | Bounds 是否完全在视锥内 |
+| [Intersects(bounds)](intersects-bounds.md) | `bool` | Bounds 是否与视锥相交 |
+| [Intersects(sphere)](intersects-sphere.md) | `bool` | 球体是否与视锥相交 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/frustum/intersects-bounds.md

@@ -0,0 +1,26 @@
+# Frustum::Intersects (bounds)
+
+```cpp
+bool Intersects(const Bounds& bounds) const
+```
+
+检测轴对齐包围盒是否与视锥体相交。
+
+**参数：**
+- `bounds` - 要检测的轴对齐包围盒
+
+**返回：** `bool` - 与视锥相交返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Frustum frustum = camera.CalculateFrustum();
+for (const auto& object : sceneObjects) {
+    if (frustum.Intersects(object.bounds)) {
+        // 物体与视锥相交，需要渲染
+        Render(object);
+    }
+}
+```

docs/api/math/frustum/intersects-sphere.md

@@ -0,0 +1,25 @@
+# Frustum::Intersects (sphere)
+
+```cpp
+bool Intersects(const Sphere& sphere) const
+```
+
+检测球体是否与视锥体相交。
+
+**参数：**
+- `sphere` - 要检测的球体
+
+**返回：** `bool` - 与视锥相交返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Frustum frustum = camera.CalculateFrustum();
+Sphere collider = object.GetBoundingSphere();
+if (frustum.Intersects(collider)) {
+    // 球体与视锥相交
+    Render(object);
+}
+```

docs/api/math/h/deg-to-rad.md

@@ -0,0 +1,20 @@
+# Math::DEG_TO_RAD
+
+```cpp
+constexpr float DEG_TO_RAD = Math::PI / 180.0f;
+```
+
+`DEG_TO_RAD` 是角度转弧度的转换系数。1 度等于 `PI / 180` 弧度，约等于 0.01745329251994329577。使用该常量将角度值乘以 `DEG_TO_RAD` 即可得到对应的弧度值。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float angleDegrees = 90.0f;
+float angleRadians = angleDegrees * Math::DEG_TO_RAD;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/degrees.md

@@ -0,0 +1,20 @@
+# Math::Degrees
+
+```cpp
+float Degrees(float radians);
+```
+
+`Degrees` 函数将弧度值转换为角度值。转换公式为：`角度 = 弧度 * (180 / PI)`。该函数是 `Radians` 函数的逆函数，常用于将三角函数的返回值或物理引擎中的弧度值转换为人机界面友好的角度值。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float radians = Math::HALF_PI;
+float degrees = Math::Degrees(radians);
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/epsilon.md

@@ -0,0 +1,23 @@
+# Math::EPSILON
+
+```cpp
+constexpr float EPSILON = 1e-6f;
+```
+
+`EPSILON` 是一个非常小的浮点数常量，值为 0.000001。该常量主要用于浮点数比较，由于浮点数精度问题，直接使用 `==` 比较浮点数可能产生错误结果，此时应使用 `EPSILON` 进行容差比较。例如判断两个浮点数是否相等，可以检查它们的差的绝对值是否小于 `EPSILON`。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float a = 0.1f + 0.2f;
+float b = 0.3f;
+if (Math::Abs(a - b) < Math::EPSILON) {
+    // a 和 b 可以视为相等
+}
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/float-max.md

@@ -0,0 +1,19 @@
+# Math::FLOAT_MAX
+
+```cpp
+constexpr float FLOAT_MAX = 3.402823466e+38f;
+```
+
+`FLOAT_MAX` 是 IEEE 754 单精度浮点数能表示的最大正有限值，约为 3.402823466e+38。该常量常用于初始化变量为最大值、在搜索算法中作为上界、或在需要表示"无穷大"但又不想引入 `INFINITY` 的场景中使用。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float maxDistance = Math::FLOAT_MAX;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/h.md

@@ -0,0 +1,54 @@
+# Math
+
+**命名空间**: `XCEngine::Math`
+
+**类型**: `header`
+
+**描述**: 数学库常量和辅助函数头文件。
+
+## 概述
+
+`Math.h` 提供了图形引擎常用的数学常量和辅助函数，包括圆周率、角度转换、浮点精度等基础常量，以及角度弧度转换等常用函数。
+
+## 常量
+
+| 常量 | 值 | 描述 |
+|------|-----|------|
+| [PI](pi.md) | 3.14159265358979323846f | 圆周率 |
+| [TWO_PI](two-pi.md) | 6.28318530717958647692f | 2π |
+| [HALF_PI](half-pi.md) | 1.57079632679489661923f | π/2 |
+| [DEG_TO_RAD](deg-to-rad.md) | PI / 180.0f | 度到弧度 |
+| [RAD_TO_DEG](rad-to-deg.md) | 180.0f / PI | 弧度到度 |
+| [EPSILON](epsilon.md) | 1e-6f | 浮点精度 |
+| [FLOAT_MAX](float-max.md) | 3.402823466e+38f | 浮点最大值 |
+
+## 辅助函数
+
+| 函数 | 描述 |
+|------|------|
+| [Radians](radians.md) | 度转弧度 |
+| [Degrees](degrees.md) | 弧度转度 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+using namespace XCEngine::Math;
+
+// 使用常量
+float angle = 90.0f * DEG_TO_RAD;  // 90度转弧度
+
+// 使用函数
+float rad = Radians(180.0f);        // 180度 -> π 弧度
+float deg = Degrees(Math::PI);      // π 弧度 -> 180度
+
+// 比较浮点数
+if (fabsf(a - b) < EPSILON) {
+    // 认为 a 和 b 相等
+}
+```
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/h/half-pi.md

@@ -0,0 +1,19 @@
+# Math::HALF_PI
+
+```cpp
+constexpr float HALF_PI = 1.57079632679489661923f;
+```
+
+`HALF_PI` 是圆周率除以 2，即 90 度对应的弧度值，约为 1.57079632679489661923。该常量常用于角度与弧度的转换、四分之一圆周计算等场景。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float ninetyDegreesRadians = Math::HALF_PI;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/pi.md

@@ -0,0 +1,22 @@
+# Math::PI
+
+```cpp
+constexpr float PI = 3.14159265358979323846f;
+```
+
+圆周率常量，精确到 float 能表示的最高精度。
+
+**用途：** 用于三角函数计算、弧度角度转换、圆形/弧度相关计算。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float circumference = 2.0f * Math::PI * radius;
+float area = Math::PI * radius * radius;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/rad-to-deg.md

@@ -0,0 +1,20 @@
+# Math::RAD_TO_DEG
+
+```cpp
+constexpr float RAD_TO_DEG = 180.0f / Math::PI;
+```
+
+`RAD_TO_DEG` 是弧度转角度的转换系数。1 弧度等于 `180 / PI` 度，约等于 57.29577951308232087685。使用该常量将弧度值乘以 `RAD_TO_DEG` 即可得到对应的角度值。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float radians = Math::HALF_PI;
+float degrees = radians * Math::RAD_TO_DEG;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/radians.md

@@ -0,0 +1,20 @@
+# Math::Radians
+
+```cpp
+float Radians(float degrees);
+```
+
+`Radians` 函数将角度值转换为弧度值。转换公式为：`弧度 = 角度 * (PI / 180)`。该函数是 `Degrees` 函数的逆函数，常用于将 UI 输入的角度值或游戏中的角度值转换为三角函数所需的弧度值。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float degrees = 90.0f;
+float radians = Math::Radians(degrees);
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/two-pi.md

@@ -0,0 +1,19 @@
+# Math::TWO_PI
+
+```cpp
+constexpr float TWO_PI = 6.28318530717958647692f;
+```
+
+`TWO_PI` 是圆周率的两倍，即完整的圆周长对应的弧度值，约为 6.28318530717958647692。该常量常用于需要完整圆周旋转的场景，例如角度归一化、三角函数周期计算、圆形运动等。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float fullCircleRadians = Math::TWO_PI;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/math.md

@@ -0,0 +1,100 @@
+# Math 模块概览
+
+**命名空间**: `XCEngine::Math`
+
+**类型**: `module`
+
+**描述**: XCEngine 的数学库模块，提供图形引擎常用的数学类型和函数。
+
+## 概述
+
+Math 模块提供了一套完整的图形数学库，包括向量、矩阵、四元数、变换和几何类型等。
+
+## 模块内容
+
+### 向量类型
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Vector2](vector2/vector2.md) | `Vector2.h` | 二维向量 |
+| [Vector3](vector3/vector3.md) | `Vector3.h` | 三维向量 |
+| [Vector4](vector4/vector4.md) | `Vector4.h` | 四维向量 |
+
+### 矩阵类型
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Matrix3](matrix3/matrix3.md) | `Matrix3.h` | 3x3 矩阵 |
+| [Matrix4](matrix4/matrix4.md) | `Matrix4.h` | 4x4 矩阵 |
+
+### 旋转/变换
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Quaternion](quaternion/quaternion.md) | `Quaternion.h` | 四元数 |
+| [Transform](transform/transform.md) | `Transform.h` | 变换组件 |
+
+### 几何类型
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Color](color/color.md) | `Color.h` | 颜色 |
+| [Ray](ray/ray.md) | `Ray.h` | 射线 |
+| [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` | 轴对齐包围盒 |
+| [Frustum](frustum/frustum.md) | `Frustum.h` | 视锥体 |
+| [Rect](rect/rect.md) | `Rect.h` | 二维矩形 |
+
+## 常量定义
+
+| 常量 | 值 | 描述 |
+|------|-----|------|
+| `PI` | 3.14159265358979323846f | 圆周率 |
+| `TWO_PI` | 6.28318530717958647692f | 2π |
+| `HALF_PI` | 1.57079632679489661923f | π/2 |
+| `DEG_TO_RAD` | PI / 180.0f | 度到弧度 |
+| `RAD_TO_DEG` | 180.0f / PI | 弧度到度 |
+| `EPSILON` | 1e-6f | 浮点精度 |
+| `FLOAT_MAX` | 3.402823466e+38f | 浮点最大值 |
+
+详细文档: [Math.h - 常量和辅助函数](h/h.md)
+
+## 辅助函数
+
+| 函数 | 描述 |
+|------|------|
+| `Radians(float degrees)` | 度转弧度 |
+| `Degrees(float radians)` | 弧度转度 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Math/Math.h>
+#include <XCEngine/Math/Vector3.h>
+#include <XCEngine/Math/Matrix4.h>
+#include <XCEngine/Math/Quaternion.h>
+
+using namespace XCEngine::Math;
+
+// 向量运算
+Vector3 a(1.0f, 0.0f, 0.0f);
+Vector3 b(0.0f, 1.0f, 0.0f);
+float dot = Vector3::Dot(a, b);
+Vector3 cross = Vector3::Cross(a, b);
+Vector3 normalized = Vector3::Normalize(a);
+
+// 矩阵运算
+Matrix4 model = Matrix4::TRS(position, rotation, scale);
+Matrix4 view = Matrix4::LookAt(eye, target, up);
+Matrix4 projection = Matrix4::Perspective(fov, aspect, near, far);
+Matrix4 mvp = projection * view * model;
+
+// 四元数运算
+Quaternion q1 = Quaternion::FromEulerAngles(0, 90 * DEG_TO_RAD, 0);
+Quaternion q2 = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(45.0f));
+Quaternion combined = q1 * q2;
+Vector3 rotated = q2 * Vector3::Forward();
+```

docs/api/math/matrix3/determinant.md

@@ -0,0 +1,18 @@
+# Matrix3::Determinant
+
+```cpp
+float Determinant() const
+```
+
+计算矩阵的行列式。
+
+**返回：** `float` - 行列式值
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 mat = ...;
+float det = mat.Determinant();
+```

docs/api/math/matrix3/identity.md

@@ -0,0 +1,17 @@
+# Matrix3::Identity
+
+```cpp
+static Matrix3 Identity()
+```
+
+返回 3x3 单位矩阵。
+
+**返回：** `Matrix3` - 单位矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 identity = Matrix3::Identity();
+```

docs/api/math/matrix3/inverse.md

@@ -0,0 +1,18 @@
+# Matrix3::Inverse
+
+```cpp
+Matrix3 Inverse() const
+```
+
+返回矩阵的逆矩阵。
+
+**返回：** `Matrix3` - 逆矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 mat = ...;
+Matrix3 inv = mat.Inverse();
+```

docs/api/math/matrix3/matrix3.md

@@ -0,0 +1,57 @@
+# Matrix3 / Matrix3x3
+
+3x3 矩阵结构体，用于表示 3D 旋转和缩放变换。
+
+**头文件：** `#include <XCEngine/Math/Matrix3.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 类型别名
+
+```cpp
+using Matrix3 = Matrix3x3;
+```
+
+## 存储方式
+
+行优先存储 (row-major)：
+```
+m[row][col]
+m[0][0] m[0][1] m[0][2]
+m[1][0] m[1][1] m[1][2]
+m[2][0] m[2][1] m[2][2]
+```
+
+## 构造函数
+
+- 默认构造函数初始化为零矩阵
+
+## 静态工厂方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Identity()](identity.md) | `Matrix3` | 单位矩阵 |
+| [Zero()](zero.md) | `Matrix3` | 零矩阵 |
+| [RotationX(radians)](rotationx.md) | `Matrix3` | X 轴旋转矩阵 |
+| [RotationY(radians)](rotationy.md) | `Matrix3` | Y 轴旋转矩阵 |
+| [RotationZ(radians)](rotationz.md) | `Matrix3` | Z 轴旋转矩阵 |
+| [Scale(scale)](scale.md) | `Matrix3` | 缩放矩阵 |
+
+## 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Transpose()](transpose.md) | `Matrix3` | 转置矩阵 |
+| [Inverse()](inverse.md) | `Matrix3` | 逆矩阵 |
+| [Determinant()](determinant.md) | `float` | 行列式 |
+
+## 运算符
+
+| 运算符 | 描述 |
+|--------|------|
+| `operator*(Matrix3, Matrix3)` | 矩阵乘法 |
+| `operator*(Matrix3, Vector3)` | 矩阵-向量乘法 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/matrix3/rotationx.md

@@ -0,0 +1,20 @@
+# Matrix3::RotationX
+
+```cpp
+static Matrix3 RotationX(float radians)
+```
+
+创建绕 X 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix3` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 rotX = Matrix3::RotationX(Math::HALF_PI);
+```

docs/api/math/matrix3/rotationy.md

@@ -0,0 +1,20 @@
+# Matrix3::RotationY
+
+```cpp
+static Matrix3 RotationY(float radians)
+```
+
+创建绕 Y 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix3` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 rotY = Matrix3::RotationY(Math::HALF_PI);
+```

docs/api/math/matrix3/rotationz.md

@@ -0,0 +1,20 @@
+# Matrix3::RotationZ
+
+```cpp
+static Matrix3 RotationZ(float radians)
+```
+
+创建绕 Z 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix3` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 rotZ = Matrix3::RotationZ(Math::HALF_PI);
+```

docs/api/math/matrix3/scale.md

@@ -0,0 +1,20 @@
+# Matrix3::Scale
+
+```cpp
+static Matrix3 Scale(const Vector3& scale)
+```
+
+创建缩放矩阵。
+
+**参数：**
+- `scale` - 各轴缩放因子
+
+**返回：** `Matrix3` - 缩放矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 scale = Matrix3::Scale(Vector3(2.0f, 2.0f, 2.0f));
+```

docs/api/math/matrix3/transpose.md

@@ -0,0 +1,18 @@
+# Matrix3::Transpose
+
+```cpp
+Matrix3 Transpose() const
+```
+
+返回矩阵的转置。
+
+**返回：** `Matrix3` - 转置矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 mat = ...;
+Matrix3 transposed = mat.Transpose();
+```

docs/api/math/matrix3/zero.md

@@ -0,0 +1,17 @@
+# Matrix3::Zero
+
+```cpp
+static Matrix3 Zero()
+```
+
+返回零矩阵。
+
+**返回：** `Matrix3` - 零矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 zero = Matrix3::Zero();
+```

docs/api/math/matrix4/decompose.md

@@ -0,0 +1,24 @@
+# Matrix4::Decompose
+
+```cpp
+void Decompose(Vector3& translation, Quaternion& rotation, Vector3& scale) const
+```
+
+将矩阵分解为平移、旋转和缩放分量。
+
+**参数：**
+- `translation` - 输出平移向量
+- `rotation` - 输出旋转四元数
+- `scale` - 输出缩放向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+Vector3 translation;
+Quaternion rotation;
+Vector3 scale;
+m.Decompose(translation, rotation, scale);
+```

docs/api/math/matrix4/determinant.md

@@ -0,0 +1,18 @@
+# Matrix4::Determinant
+
+```cpp
+float Determinant() const
+```
+
+计算矩阵的行列式。
+
+**返回：** `float` - 行列式值
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+float det = m.Determinant();
+```

docs/api/math/matrix4/getrotation.md

@@ -0,0 +1,18 @@
+# Matrix4::GetRotation
+
+```cpp
+Quaternion GetRotation() const
+```
+
+从矩阵中提取旋转分量。
+
+**返回：** `Quaternion` - 旋转四元数
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+Quaternion rotation = m.GetRotation();
+```

docs/api/math/matrix4/getscale.md

@@ -0,0 +1,18 @@
+# Matrix4::GetScale
+
+```cpp
+Vector3 GetScale() const
+```
+
+从矩阵中提取缩放分量。
+
+**返回：** `Vector3` - 缩放向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+Vector3 scale = m.GetScale();
+```

docs/api/math/matrix4/gettranslation.md

@@ -0,0 +1,18 @@
+# Matrix4::GetTranslation
+
+```cpp
+Vector3 GetTranslation() const
+```
+
+从矩阵中提取平移分量。
+
+**返回：** `Vector3` - 平移向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+Vector3 translation = m.GetTranslation();
+```

docs/api/math/matrix4/identity.md

@@ -0,0 +1,17 @@
+# Matrix4::Identity
+
+```cpp
+static Matrix4 Identity()
+```
+
+返回 4x4 单位矩阵。
+
+**返回：** `Matrix4` - 单位矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 identity = Matrix4::Identity();
+```

docs/api/math/matrix4/inverse.md

@@ -0,0 +1,18 @@
+# Matrix4::Inverse
+
+```cpp
+Matrix4 Inverse() const
+```
+
+返回矩阵的逆矩阵。
+
+**返回：** `Matrix4` - 逆矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+Matrix4 inv = m.Inverse();
+```

docs/api/math/matrix4/lookat.md

@@ -0,0 +1,22 @@
+# Matrix4::LookAt
+
+```cpp
+static Matrix4 LookAt(const Vector3& eye, const Vector3& target, const Vector3& up)
+```
+
+创建视图矩阵（观察矩阵）。
+
+**参数：**
+- `eye` - 相机位置
+- `target` - 观察目标点
+- `up` - 世界空间中的上方向
+
+**返回：** `Matrix4` - 视图矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 view = Matrix4::LookAt(cameraPos, target, Vector3::Up());
+```

docs/api/math/matrix4/matrix4.md

@@ -0,0 +1,79 @@
+# Matrix4 / Matrix4x4
+
+4x4 矩阵结构体，用于表示完整的 3D 变换（平移、旋转、缩放）、视图和投影变换。
+
+**头文件：** `#include <XCEngine/Math/Matrix4.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 类型别名
+
+```cpp
+using Matrix4 = Matrix4x4;
+```
+
+## 存储方式
+
+行优先存储 (row-major)：
+```
+m[0][0] m[0][1] m[0][2] m[0][3]
+m[1][0] m[1][1] m[1][2] m[1][3]
+m[2][0] m[2][1] m[2][2] m[2][3]
+m[3][0] m[3][1] m[3][2] m[3][3]
+```
+
+## 静态工厂方法
+
+### 基础变换
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Identity()](identity.md) | `Matrix4` | 单位矩阵 |
+| [Zero()](zero.md) | `Matrix4` | 零矩阵 |
+| [Translation(v)](translation.md) | `Matrix4` | 平移矩阵 |
+| [Scale(v)](scale.md) | `Matrix4` | 缩放矩阵 |
+| [Rotation(q)](rotation.md) | `Matrix4` | 旋转矩阵（四元数） |
+| [TRS(translation, rotation, scale)](trs.md) | `Matrix4` | 完整变换 |
+
+### 旋转
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [RotationX(radians)](rotationx.md) | `Matrix4` | X 轴旋转 |
+| [RotationY(radians)](rotationy.md) | `Matrix4` | Y 轴旋转 |
+| [RotationZ(radians)](rotationz.md) | `Matrix4` | Z 轴旋转 |
+
+### 相机变换
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [LookAt(eye, target, up)](lookat.md) | `Matrix4` | 视图矩阵 |
+| [Perspective(fov, aspect, near, far)](perspective.md) | `Matrix4` | 透视投影 |
+| [Orthographic(left, right, bottom, top, near, far)](orthographic.md) | `Matrix4` | 正交投影 |
+
+## 实例方法
+
+### 乘法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| `operator*(Matrix4, Matrix4)` | `Matrix4` | 矩阵乘法 |
+| `operator*(Matrix4, Vector4)` | `Vector4` | 矩阵-向量乘法 |
+| [MultiplyPoint(v)](multiplypoint.md) | `Vector3` | 点变换（带平移） |
+| [MultiplyVector(v)](multiplyvector.md) | `Vector3` | 方向变换（不带平移） |
+
+### 分解
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Transpose()](transpose.md) | `Matrix4` | 转置矩阵 |
+| [Inverse()](inverse.md) | `Matrix4` | 逆矩阵 |
+| [Determinant()](determinant.md) | `float` | 行列式 |
+| [GetTranslation()](gettranslation.md) | `Vector3` | 获取平移分量 |
+| [GetRotation()](getrotation.md) | `Quaternion` | 获取旋转分量 |
+| [GetScale()](getscale.md) | `Vector3` | 获取缩放分量 |
+| [Decompose(translation, rotation, scale)](decompose.md) | `void` | 分解所有分量 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/matrix4/multiplypoint.md

@@ -0,0 +1,21 @@
+# Matrix4::MultiplyPoint
+
+```cpp
+Vector3 MultiplyPoint(const Vector3& v) const
+```
+
+使用矩阵变换点（包含平移）。
+
+**参数：**
+- `v` - 要变换的点
+
+**返回：** `Vector3` - 变换后的点
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 model = Matrix4::TRS(pos, rot, scale);
+Vector3 worldPos = model.MultiplyPoint(localPos);
+```

docs/api/math/matrix4/multiplyvector.md

@@ -0,0 +1,21 @@
+# Matrix4::MultiplyVector
+
+```cpp
+Vector3 MultiplyVector(const Vector3& v) const
+```
+
+使用矩阵变换方向向量（不包含平移）。
+
+**参数：**
+- `v` - 要变换的方向向量
+
+**返回：** `Vector3` - 变换后的方向
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 model = Matrix4::TRS(pos, rot, scale);
+Vector3 worldDir = model.MultiplyVector(localDir);
+```

docs/api/math/matrix4/orthographic.md

@@ -0,0 +1,25 @@
+# Matrix4::Orthographic
+
+```cpp
+static Matrix4 Orthographic(float left, float right, float bottom, float top, float near, float far)
+```
+
+创建正交投影矩阵。
+
+**参数：**
+- `left` - 左裁剪面
+- `right` - 右裁剪面
+- `bottom` - 下裁剪面
+- `top` - 上裁剪面
+- `near` - 近裁剪面距离
+- `far` - 远裁剪面距离
+
+**返回：** `Matrix4` - 正交投影矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 ortho = Matrix4::Orthographic(-aspect, aspect, -1.0f, 1.0f, 0.1f, 100.0f);
+```

docs/api/math/matrix4/perspective.md

@@ -0,0 +1,23 @@
+# Matrix4::Perspective
+
+```cpp
+static Matrix4 Perspective(float fov, float aspect, float near, float far)
+```
+
+创建透视投影矩阵。
+
+**参数：**
+- `fov` - 垂直视野角度（弧度）
+- `aspect` - 宽高比
+- `near` - 近裁剪面距离
+- `far` - 远裁剪面距离
+
+**返回：** `Matrix4` - 透视投影矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 proj = Matrix4::Perspective(45.0f * DEG_TO_RAD, aspect, 0.1f, 100.0f);
+```

docs/api/math/matrix4/rotation.md

@@ -0,0 +1,21 @@
+# Matrix4::Rotation
+
+```cpp
+static Matrix4 Rotation(const Quaternion& q)
+```
+
+从四元数创建旋转矩阵。
+
+**参数：**
+- `q` - 四元数
+
+**返回：** `Matrix4` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f);
+Matrix4 rotation = Matrix4::Rotation(rot);
+```

docs/api/math/matrix4/rotationx.md

@@ -0,0 +1,20 @@
+# Matrix4::RotationX
+
+```cpp
+static Matrix4 RotationX(float radians)
+```
+
+创建绕 X 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix4` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 rotX = Matrix4::RotationX(Math::HALF_PI);
+```

docs/api/math/matrix4/rotationy.md

@@ -0,0 +1,20 @@
+# Matrix4::RotationY
+
+```cpp
+static Matrix4 RotationY(float radians)
+```
+
+创建绕 Y 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix4` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 rotY = Matrix4::RotationY(Math::HALF_PI);
+```

docs/api/math/matrix4/rotationz.md

@@ -0,0 +1,20 @@
+# Matrix4::RotationZ
+
+```cpp
+static Matrix4 RotationZ(float radians)
+```
+
+创建绕 Z 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix4` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 rotZ = Matrix4::RotationZ(Math::HALF_PI);
+```

docs/api/math/matrix4/scale.md

@@ -0,0 +1,20 @@
+# Matrix4::Scale
+
+```cpp
+static Matrix4 Scale(const Vector3& v)
+```
+
+创建缩放矩阵。
+
+**参数：**
+- `v` - 各轴缩放因子
+
+**返回：** `Matrix4` - 缩放矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 scale = Matrix4::Scale(Vector3(2.0f, 2.0f, 2.0f));
+```

docs/api/math/matrix4/translation.md

@@ -0,0 +1,20 @@
+# Matrix4::Translation
+
+```cpp
+static Matrix4 Translation(const Vector3& v)
+```
+
+创建平移矩阵。
+
+**参数：**
+- `v` - 平移向量
+
+**返回：** `Matrix4` - 平移矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 translation = Matrix4::Translation(Vector3(1.0f, 2.0f, 3.0f));
+```

docs/api/math/matrix4/transpose.md

@@ -0,0 +1,18 @@
+# Matrix4::Transpose
+
+```cpp
+Matrix4 Transpose() const
+```
+
+返回矩阵的转置。
+
+**返回：** `Matrix4` - 转置矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+Matrix4 transposed = m.Transpose();
+```

docs/api/math/matrix4/trs.md

@@ -0,0 +1,22 @@
+# Matrix4::TRS
+
+```cpp
+static Matrix4 TRS(const Vector3& translation, const Quaternion& rotation, const Vector3& scale)
+```
+
+创建完整的 TRS（平移、旋转、缩放）变换矩阵。
+
+**参数：**
+- `translation` - 平移向量
+- `rotation` - 旋转四元数
+- `scale` - 缩放向量
+
+**返回：** `Matrix4` - 组合变换矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 transform = Matrix4::TRS(position, rotation, Vector3::One());
+```

docs/api/math/matrix4/zero.md

@@ -0,0 +1,17 @@
+# Matrix4::Zero
+
+```cpp
+static Matrix4 Zero()
+```
+
+返回零矩阵。
+
+**返回：** `Matrix4` - 零矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 zero = Matrix4::Zero();
+```

docs/api/math/plane/frompoints.md

@@ -0,0 +1,22 @@
+# Plane::FromPoints
+
+```cpp
+static Plane FromPoints(const Vector3& a, const Vector3& b, const Vector3& c)
+```
+
+从三个不共线点创建平面。
+
+**参数：**
+- `a` - 第一个点
+- `b` - 第二个点
+- `c` - 第三个点
+
+**返回：** `Plane` - 由三点定义的平面
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Plane plane = Plane::FromPoints(p0, p1, p2);
+```

docs/api/math/plane/getclosestpoint.md

@@ -0,0 +1,20 @@
+# Plane::GetClosestPoint
+
+```cpp
+Vector3 GetClosestPoint(const Vector3& point) const
+```
+
+计算平面上最接近给定点的点。
+
+**参数：**
+- `point` - 参考点
+
+**返回：** `Vector3` - 平面上最接近的点
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 closest = plane.GetClosestPoint(point);
+```

docs/api/math/plane/getdistancetopoint.md

@@ -0,0 +1,20 @@
+# Plane::GetDistanceToPoint
+
+```cpp
+float GetDistanceToPoint(const Vector3& point) const
+```
+
+计算点到平面的有符号距离。
+
+**参数：**
+- `point` - 要计算的点
+
+**返回：** `float` - 有符号距离
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+float dist = plane.GetDistanceToPoint(point);
+```

docs/api/math/plane/getside.md

@@ -0,0 +1,20 @@
+# Plane::GetSide
+
+```cpp
+bool GetSide(const Vector3& point) const
+```
+
+判断点在平面的哪一侧。
+
+**参数：**
+- `point` - 要测试的点
+
+**返回：** `bool` - true 表示点在法线方向一侧
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (plane.GetSide(point)) { /* point is on normal side */ }
+```

docs/api/math/plane/intersects.md

@@ -0,0 +1,20 @@
+# Plane::Intersects
+
+```cpp
+bool Intersects(const Sphere& sphere) const
+```
+
+检测平面是否与球体相交。
+
+**参数：**
+- `sphere` - 要检测的球体
+
+**返回：** `bool` - true 表示相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (plane.Intersects(sphere)) { /* collision */ }
+```

docs/api/math/plane/plane.md

@@ -0,0 +1,40 @@
+# Plane
+
+3D 平面结构体，由法线和距离表示。
+
+**头文件：** `#include <XCEngine/Math/Plane.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 结构体定义
+
+```cpp
+struct Plane {
+    Vector3 normal = Vector3::Up();
+    float distance = 0.0f;
+};
+```
+
+## 构造函数
+
+- `Plane()` - 默认构造 (y=0 平面)
+- `Plane(const Vector3& normal, float distance)` - 从法线和距离构造
+
+## 静态工厂方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [FromPoints(a, b, c)](frompoints.md) | `Plane` | 从三个不共线点创建 |
+
+## 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [GetDistanceToPoint(point)](getdistancetopoint.md) | `float` | 点到平面的有符号距离 |
+| [GetClosestPoint(point)](getclosestpoint.md) | `Vector3` | 平面上最接近给定点的点 |
+| [GetSide(point)](getside.md) | `bool` | 点在平面的哪一侧 |
+| [Intersects(sphere)](intersects.md) | `bool` | 与球体相交 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/quaternion/dot.md

@@ -0,0 +1,20 @@
+# Quaternion::Dot
+
+```cpp
+float Dot(const Quaternion& other) const
+```
+
+计算两个四元数的点积。
+
+**参数：**
+- `other` - 另一个四元数
+
+**返回：** `float` - 点积结果
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+float dot = quat1.Dot(quat2);
+```

docs/api/math/quaternion/fromaxisangle.md

@@ -0,0 +1,21 @@
+# Quaternion::FromAxisAngle
+
+```cpp
+static Quaternion FromAxisAngle(const Vector3& axis, float radians)
+```
+
+从轴角创建四元数。
+
+**参数：**
+- `axis` - 旋转轴（应为单位向量）
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Quaternion` - 表示旋转的四元数
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Quaternion rot = Quaternion::FromAxisAngle(Vector3::Up(), 90.0f * DEG_TO_RAD);
+```

docs/api/math/quaternion/fromeulerangles.md

@@ -0,0 +1,25 @@
+# Quaternion::FromEulerAngles
+
+```cpp
+static Quaternion FromEulerAngles(float pitch, float yaw, float roll)
+static Quaternion FromEulerAngles(const Vector3& euler)
+```
+
+从欧拉角创建四元数。角度以弧度为单位。
+
+**参数：**
+- `pitch` - 俯仰角（X 轴旋转）
+- `yaw` - 偏航角（Y 轴旋转）
+- `roll` - 翻滚角（Z 轴旋转）
+- `euler` - 欧拉角向量 (pitch, yaw, roll)
+
+**返回：** `Quaternion` - 表示旋转的四元数
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f);
+Quaternion rot2 = Quaternion::FromEulerAngles(Vector3(0.0f, 90.0f * DEG_TO_RAD, 0.0f));
+```