# XCEngine 游戏引擎 - 第一阶段计划

> **目标**: 构建核心基础层，为上层渲染系统提供底层依赖
> **版本**: 1.0
> **日期**: 2026-03-13

---

## 阶段目标

第一阶段聚焦于引擎底层基础设施的建设，确保后续渲染系统开发有稳定的基础。

---

## 模块规划

### 1.1 数学库 (Math Library)

| 项目 | 内容 |
|------|------|
| **优先级** | P0 |
| **预计工作量** | 5天 |
| **包含类型** | `Vector2`, `Vector3`, `Vector4`, `Matrix3x3`, `Matrix4x4`, `Quaternion`, `Transform`, `Color`, `Rect`, `RectInt`, `Viewport`, `Ray`, `Sphere`, `Box`, `Plane`, `Frustum`, `Bounds`, `AABB`, `OBB` |
| **功能要求** | 向量运算、矩阵变换、四元数、欧拉角转换、视锥体剔除基础 |

### 1.2 Core 基础类型

| 项目 | 内容 |
|------|------|
| **优先级** | P0 |
| **预计工作量** | 2天 |
| **包含类型** | 基础类型别名 (`int8`, `uint8`, `int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`, `byte`)、`RefCounted`、`Ref<T>`、`UniqueRef<T>`、`Event<T>` |
| **功能要求** | 基础类型别名、引用计数、智能指针、事件系统 |
| **依赖** | 无 |

### 1.3 线程系统 (Threading)

| 项目 | 内容 |
|------|------|
| **优先级** | P0 |
| **预计工作量** | 4天 |
| **包含类型** | `ITask`, `LambdaTask`, `TaskGroup`, `TaskSystem`, `TaskSystemConfig`, `Mutex`, `SpinLock`, `ReadWriteLock`, `Thread` |
| **功能要求** | 任务调度、依赖管理、并行计算、同步原语 |
| **依赖** | Core基础类型 |

### 1.4 内存管理 (Memory Management)

| 项目 | 内容 |
|------|------|
| **优先级** | P0 |
| **预计工作量** | 3天 |
| **包含类型** | `IAllocator`, `LinearAllocator`, `PoolAllocator`, `ProxyAllocator`, `MemoryManager` |
| **功能要求** | 内存分配、追踪、泄漏检测、线性/池化分配策略 |
| **依赖** | 线程系统（ProxyAllocator需要Mutex） |

### 1.5 容器库 (Containers)

| 项目 | 内容 |
|------|------|
| **优先级** | P0 |
| **预计工作量** | 3天 |
| **包含类型** | `Array<T>`, `String`, `String::npos`, `HashMap<K,V>` |
| **功能要求** | 动态数组、字符串操作（含npos常量）、哈希映射 |
| **依赖** | Core基础类型, 内存管理 |

### 1.6 日志与调试系统

| 项目 | 内容 |
|------|------|
| **优先级** | P1 |
| **预计工作量** | 2天 |
| **包含类型** | `Logger`, `ConsoleLogSink`, `FileLogSink`, `FileWriter`, `Profiler`, `Assert` |
| **功能要求** | 分级日志、分类输出、文件写入、性能分析、断言 |
| **依赖** | Core基础类型, 容器库(String) |

---

## 时间安排

| 周次 | 内容 |
|------|------|
| 第1周 | 数学库 + Core基础类型 |
| 第2周 | 线程系统 + 内存管理 |
| 第3周 | 容器库 + 日志系统 |

> 注：内存管理依赖线程系统完成（ProxyAllocator需要Mutex），因此调整顺序

---

## 测试方案

### 测试框架
- **推荐**: Google Test (gtest) 或 Doctest

### 测试用例设计

| 模块 | 测试类别 | 测试用例示例 |
|------|---------|-------------|
| **Math** | 向量运算 | `Vector3::Dot`, `Cross`, `Normalize`, `Lerp` 精度测试 |
| **Math** | 矩阵运算 | `Matrix4x4::TRS`, `LookAt`, `Perspective` 结果正确性 |
| **Math** | 四元数 | `FromEulerAngles`, `Slerp`, `ToMatrix4x4` 精度验证 |
| **Core** | 引用计数 | `RefCounted` 多线程安全释放 |
| **Core** | 事件系统 | 订阅/取消订阅、线程安全调用 |
| **Threading** | 任务系统 | 依赖链、优先级、并行For、TaskSystemConfig |
| **Threading** | 同步原语 | 锁竞争、死锁检测 |
| **Memory** | 分配器 | 边界检查、碎片率、线性分配器回滚测试 |
| **Memory** | 泄漏检测 | 分配/释放计数、峰值追踪 |
| **Containers** | Array | 边界访问、迭代器、内存增长策略 |
| **Containers** | String | 子串、查找、大小写转换 |
| **Containers** | HashMap | 冲突处理、负载因子重分布 |
| **Logger** | 日志级别 | 过滤、分类、格式化 |

### 执行命令

```bash
# 编译并运行所有单元测试
cmake --build build --target xcengine_tests
./build/tests/xcengine_tests.exe

# 性能基准测试
./build/tests/xcengine_tests.exe --benchmark
```

---

## 验收标准

- [ ] 数学库通过全部运算正确性测试
- [ ] Core基础类型（引用计数、智能指针）工作正常
- [ ] 线程系统在高并发下稳定运行
- [ ] 内存分配器无内存泄漏
- [ ] 容器操作边界安全
- [ ] 日志系统输出格式正确

---

## 依赖关系

```
Math Library (无依赖)
    │
    ├──▶ Core 基础类型 (无依赖)
    │         │
    │         ├──▶ Threading (依赖 Core)
    │         │
    │         ├──▶ Memory Management (依赖 Threading)
    │         │         │
    │         │         └──▶ Containers (依赖 Memory, Core)
    │         │
    │         └──▶ Logging & Debug (依赖 Core, Containers)
```