XCEngine/docs/plan/第一阶段计划.md

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	日志级别	过滤、分类、格式化

执行命令

# 编译并运行所有单元测试
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)