1021 lines
27 KiB
Markdown
1021 lines
27 KiB
Markdown
# XCEngine 蓝图
|
||
|
||
---
|
||
|
||
# SYSTEM_META
|
||
|
||
```yaml
|
||
name: XCEngine
|
||
version: 0.1.0
|
||
type: game-engine
|
||
description: "模块化的 C++17 游戏引擎，支持 D3D12 和 OpenGL 双图形后端"
|
||
target_runtime: C++17
|
||
```
|
||
|
||
---
|
||
|
||
# SYSTEM_STRUCTURE
|
||
|
||
```yaml
|
||
root: XCEngine
|
||
|
||
subsystems:
|
||
- name: Core
|
||
responsibilities:
|
||
- "提供基础类型别名和断言机制"
|
||
- "实现引用计数智能指针"
|
||
- "提供线程安全的事件发布/订阅系统"
|
||
- "提供文件写入 RAII 封装"
|
||
provides: [RefCounted, Event, FileWriter, SmartPtr]
|
||
depends_on: []
|
||
boundary:
|
||
inputs: []
|
||
outputs: [类型系统]
|
||
|
||
- name: Math
|
||
responsibilities:
|
||
- "实现向量、矩阵、四元数数学运算"
|
||
- "提供变换（Transform）层次组合"
|
||
- "实现几何基元（平面、球体、盒子、射线、视锥体）"
|
||
provides: [Vector, Matrix, Quaternion, Transform, Geometry]
|
||
depends_on: [Core]
|
||
boundary:
|
||
inputs: [Core 类型]
|
||
outputs: [数学计算结果]
|
||
|
||
- name: Containers
|
||
responsibilities:
|
||
- "提供动态数组模板"
|
||
- "提供字符串处理功能"
|
||
- "提供基于开放寻址的哈希表"
|
||
provides: [Array, String, HashMap]
|
||
depends_on: [Core, Memory]
|
||
boundary:
|
||
inputs: [Core 类型]
|
||
outputs: [容器实例]
|
||
|
||
- name: Memory
|
||
responsibilities:
|
||
- "定义内存分配器抽象接口"
|
||
- "实现线性分配器（栈式）"
|
||
- "实现池分配器（固定大小块）"
|
||
- "提供代理分配器（统计追踪）"
|
||
- "管理全局内存系统"
|
||
provides: [IAllocator, LinearAllocator, PoolAllocator, ProxyAllocator, MemoryManager]
|
||
depends_on: [Core]
|
||
boundary:
|
||
inputs: [分配请求]
|
||
outputs: [内存块]
|
||
|
||
- name: Threading
|
||
responsibilities:
|
||
- "封装线程 RAII 管理"
|
||
- "提供互斥锁、自旋锁、读写锁"
|
||
- "实现任务系统和线程池"
|
||
- "支持任务依赖和优先级调度"
|
||
provides: [Thread, Mutex, TaskSystem, TaskGroup]
|
||
depends_on: [Core, Containers]
|
||
boundary:
|
||
inputs: [任务函数]
|
||
outputs: [执行结果]
|
||
|
||
- name: Debug
|
||
responsibilities:
|
||
- "提供多层级分类日志系统"
|
||
- "支持多种日志输出目标（控制台、文件）"
|
||
- "实现性能分析器和 Chrome 追踪导出"
|
||
provides: [Logger, Profiler, ILogSink]
|
||
depends_on: [Core, Containers, Threading]
|
||
boundary:
|
||
inputs: [日志消息]
|
||
outputs: [日志输出]
|
||
|
||
- name: Resources
|
||
responsibilities:
|
||
- "管理所有游戏资源的生命周期"
|
||
- "实现资源加载器框架和多种格式支持"
|
||
- "提供 LRU 缓存和内存预算控制"
|
||
- "支持异步加载和依赖图管理"
|
||
- "管理资源文件系统路径和资源包"
|
||
provides: [IResource, ResourceManager, ResourceHandle, AsyncLoader]
|
||
depends_on: [Core, Containers, Memory, Threading, Math, Debug]
|
||
boundary:
|
||
inputs: [资源路径]
|
||
outputs: [资源对象]
|
||
|
||
- name: RHI
|
||
responsibilities:
|
||
- "抽象渲染硬件接口，统一不同图形 API"
|
||
- "封装 GPU 资源（缓冲区、纹理、着色器）"
|
||
- "提供命令列表录制和提交机制"
|
||
- "管理描述符堆和管线状态"
|
||
provides: [RHIDevice, RHIBuffer, RHITexture, RHIShader, RHICommandList]
|
||
depends_on: [Core]
|
||
boundary:
|
||
inputs: [渲染命令]
|
||
outputs: [GPU 调用]
|
||
|
||
- name: RHI_D3D12
|
||
responsibilities:
|
||
- "实现 DirectX 12 后端"
|
||
- "封装 D3D12 设备和资源"
|
||
- "管理描述符堆和根签名"
|
||
provides: [D3D12Device, D3D12Buffer, D3D12Texture]
|
||
depends_on: [Core, RHI]
|
||
boundary:
|
||
inputs: [RHI 调用]
|
||
outputs: [D3D12 API]
|
||
|
||
- name: RHI_OpenGL
|
||
responsibilities:
|
||
- "实现 OpenGL 4.6+ 后端"
|
||
- "封装 OpenGL 设备和资源"
|
||
- "管理 VAO 和采样器状态"
|
||
provides: [OpenGLDevice, OpenGLBuffer, OpenGLTexture]
|
||
depends_on: [Core, RHI]
|
||
boundary:
|
||
inputs: [RHI 调用]
|
||
outputs: [OpenGL API]
|
||
|
||
modules:
|
||
- name: CoreTypes
|
||
parent_subsystem: Core
|
||
responsibility: "定义基础类型别名（int8、uint32 等）和断言宏"
|
||
public_api:
|
||
- fn: Assert
|
||
params:
|
||
- name: condition
|
||
type: bool
|
||
- name: message
|
||
type: const char*
|
||
returns: type: void
|
||
|
||
- name: CoreSmartPtr
|
||
parent_subsystem: Core
|
||
responsibility: "实现引用计数智能指针 Ref<T> 和 UniqueRef<T>"
|
||
public_api:
|
||
- fn: MakeRef
|
||
params:
|
||
- name: args
|
||
type: Args...
|
||
returns: type: Ref<T>
|
||
- fn: MakeUnique
|
||
params:
|
||
- name: args
|
||
type: Args...
|
||
returns: type: UniqueRef<T>
|
||
|
||
- name: CoreEvent
|
||
parent_subsystem: Core
|
||
responsibility: "提供线程安全的事件发布/订阅系统"
|
||
public_api:
|
||
- fn: Subscribe
|
||
params:
|
||
- name: callback
|
||
type: std::function<void(Args...)>
|
||
returns: type: uint32
|
||
- fn: Unsubscribe
|
||
params:
|
||
- name: id
|
||
type: uint32
|
||
returns: type: void
|
||
- fn: Invoke
|
||
params:
|
||
- name: args
|
||
type: Args...
|
||
returns: type: void
|
||
|
||
- name: MathVector
|
||
parent_subsystem: Math
|
||
responsibility: "实现 Vector2、Vector3、Vector4 及其运算"
|
||
public_api:
|
||
- fn: Dot
|
||
params:
|
||
- name: a
|
||
type: const Vector3&
|
||
- name: b
|
||
type: const Vector3&
|
||
returns: type: float
|
||
- fn: Cross
|
||
params:
|
||
- name: a
|
||
type: const Vector3&
|
||
- name: b
|
||
type: const Vector3&
|
||
returns: type: Vector3
|
||
- fn: Normalize
|
||
params:
|
||
- name: v
|
||
type: const Vector3&
|
||
returns: type: Vector3
|
||
- fn: Lerp
|
||
params:
|
||
- name: a
|
||
type: const Vector3&
|
||
- name: b
|
||
type: const Vector3&
|
||
- name: t
|
||
type: float
|
||
returns: type: Vector3
|
||
|
||
- name: MathMatrix
|
||
parent_subsystem: Math
|
||
responsibility: "实现 Matrix3x3、Matrix4x4 及其运算"
|
||
public_api:
|
||
- fn: Perspective
|
||
params:
|
||
- name: fov
|
||
type: float
|
||
- name: aspect
|
||
type: float
|
||
- name: near
|
||
type: float
|
||
- name: far
|
||
type: float
|
||
returns: type: Matrix4x4
|
||
- fn: LookAt
|
||
params:
|
||
- name: eye
|
||
type: const Vector3&
|
||
- name: target
|
||
type: const Vector3&
|
||
- name: up
|
||
type: const Vector3&
|
||
returns: type: Matrix4x4
|
||
- fn: Inverse
|
||
params:
|
||
- name: m
|
||
type: const Matrix4x4&
|
||
returns: type: Matrix4x4
|
||
|
||
- name: MathQuaternion
|
||
parent_subsystem: Math
|
||
responsibility: "实现四元数和旋转变换"
|
||
public_api:
|
||
- fn: FromAxisAngle
|
||
params:
|
||
- name: axis
|
||
type: const Vector3&
|
||
- name: angle
|
||
type: float
|
||
returns: type: Quaternion
|
||
- fn: FromEulerAngles
|
||
params:
|
||
- name: pitch
|
||
type: float
|
||
- name: yaw
|
||
type: float
|
||
- name: roll
|
||
type: float
|
||
returns: type: Quaternion
|
||
- fn: Slerp
|
||
params:
|
||
- name: a
|
||
type: const Quaternion&
|
||
- name: b
|
||
type: const Quaternion&
|
||
- name: t
|
||
type: float
|
||
returns: type: Quaternion
|
||
|
||
- name: MathTransform
|
||
parent_subsystem: Math
|
||
responsibility: "实现位置/旋转/缩放变换层次"
|
||
public_api:
|
||
- fn: Translate
|
||
params:
|
||
- name: position
|
||
type: const Vector3&
|
||
returns: type: Transform&
|
||
- fn: Rotate
|
||
params:
|
||
- name: rotation
|
||
type: const Quaternion&
|
||
returns: type: Transform&
|
||
- fn: Scale
|
||
params:
|
||
- name: scale
|
||
type: const Vector3&
|
||
returns: type: Transform&
|
||
- fn: ToMatrix
|
||
returns: type: Matrix4x4
|
||
|
||
- name: MathGeometry
|
||
parent_subsystem: Math
|
||
responsibility: "实现几何基元（Plane、Sphere、Box、Ray、Frustum、AABB、OBB）"
|
||
public_api:
|
||
- fn: Intersects
|
||
params:
|
||
- name: ray
|
||
type: const Ray&
|
||
- name: sphere
|
||
type: const Sphere&
|
||
returns: type: bool
|
||
- fn: Contains
|
||
params:
|
||
- name: frustum
|
||
type: const Frustum&
|
||
- name: point
|
||
type: const Vector3&
|
||
returns: type: bool
|
||
|
||
- name: ContainersArray
|
||
parent_subsystem: Containers
|
||
responsibility: "提供模板动态数组"
|
||
public_api:
|
||
- fn: push
|
||
params:
|
||
- name: value
|
||
type: const T&
|
||
returns: type: void
|
||
- fn: emplace
|
||
params:
|
||
- name: args
|
||
type: Args...
|
||
returns: type: T&
|
||
- fn: Size
|
||
returns: type: uint32
|
||
|
||
- name: ContainersString
|
||
parent_subsystem: Containers
|
||
responsibility: "提供字符串处理功能"
|
||
public_api:
|
||
- fn: Substring
|
||
params:
|
||
- name: start
|
||
type: uint32
|
||
- name: length
|
||
type: uint32
|
||
returns: type: String
|
||
- fn: Trim
|
||
returns: type: String
|
||
- fn: Find
|
||
params:
|
||
- name: str
|
||
type: const String&
|
||
returns: type: int32
|
||
|
||
- name: ContainersHashMap
|
||
parent_subsystem: Containers
|
||
responsibility: "提供基于开放寻址的哈希表"
|
||
public_api:
|
||
- fn: Insert
|
||
params:
|
||
- name: key
|
||
type: const K&
|
||
- name: value
|
||
type: const V&
|
||
returns: type: bool
|
||
- fn: Find
|
||
params:
|
||
- name: key
|
||
type: const K&
|
||
returns: type: Iterator
|
||
- fn: Remove
|
||
params:
|
||
- name: key
|
||
type: const K&
|
||
returns: type: bool
|
||
|
||
- name: MemoryAllocators
|
||
parent_subsystem: Memory
|
||
responsibility: "实现线性分配器、池分配器、代理分配器"
|
||
public_api:
|
||
- fn: Allocate
|
||
params:
|
||
- name: size
|
||
type: size_t
|
||
returns: type: void*
|
||
- fn: Free
|
||
params:
|
||
- name: ptr
|
||
type: void*
|
||
returns: type: void
|
||
- fn: Clear
|
||
returns: type: void
|
||
|
||
- name: MemoryManager
|
||
parent_subsystem: Memory
|
||
responsibility: "管理全局内存分配器和追踪统计"
|
||
public_api:
|
||
- fn: Get
|
||
returns: type: MemoryManager&
|
||
- fn: CreateLinearAllocator
|
||
params:
|
||
- name: size
|
||
type: size_t
|
||
returns: type: LinearAllocator
|
||
- fn: CreatePoolAllocator
|
||
params:
|
||
- name: blockSize
|
||
type: size_t
|
||
- name: blockCount
|
||
type: uint32
|
||
returns: type: PoolAllocator
|
||
|
||
- name: ThreadingPrimitives
|
||
parent_subsystem: Threading
|
||
responsibility: "提供线程、互斥锁、自旋锁、读写锁"
|
||
public_api:
|
||
- fn: Thread
|
||
params:
|
||
- name: func
|
||
type: std::function<void()>
|
||
returns: type: void
|
||
- fn: Lock
|
||
returns: type: void
|
||
- fn: Unlock
|
||
returns: type: void
|
||
|
||
- name: ThreadingTaskSystem
|
||
parent_subsystem: Threading
|
||
responsibility: "实现任务调度和线程池"
|
||
public_api:
|
||
- fn: Get
|
||
returns: type: TaskSystem&
|
||
- fn: ParallelFor
|
||
params:
|
||
- name: begin
|
||
type: uint32
|
||
- name: end
|
||
type: uint32
|
||
- name: func
|
||
type: std::function<void(uint32)>
|
||
returns: type: void
|
||
- fn: Submit
|
||
params:
|
||
- name: task
|
||
type: ITask*
|
||
returns: type: void
|
||
- fn: Wait
|
||
returns: type: void
|
||
|
||
- name: DebugLogger
|
||
parent_subsystem: Debug
|
||
responsibility: "提供多层级分类日志系统"
|
||
public_api:
|
||
- fn: Get
|
||
returns: type: Logger&
|
||
- fn: Log
|
||
params:
|
||
- name: category
|
||
type: const char*
|
||
- name: level
|
||
type: LogLevel
|
||
- name: message
|
||
type: const char*
|
||
returns: type: void
|
||
|
||
- name: DebugProfiler
|
||
parent_subsystem: Debug
|
||
responsibility: "实现性能分析器"
|
||
public_api:
|
||
- fn: Get
|
||
returns: type: Profiler&
|
||
- fn: BeginSession
|
||
params:
|
||
- name: name
|
||
type: const char*
|
||
returns: type: void
|
||
- fn: EndSession
|
||
returns: type: void
|
||
- fn: ExportChromeTracing
|
||
params:
|
||
- name: path
|
||
type: const char*
|
||
returns: type: void
|
||
|
||
- name: ResourcesIResource
|
||
parent_subsystem: Resources
|
||
responsibility: "定义资源基接口"
|
||
public_api:
|
||
- fn: GetType
|
||
returns: type: ResourceType
|
||
- fn: GetName
|
||
returns: type: const String&
|
||
- fn: GetPath
|
||
returns: type: const String&
|
||
- fn: GetGUID
|
||
returns: type: const ResourceGUID&
|
||
|
||
- name: ResourcesManager
|
||
parent_subsystem: Resources
|
||
responsibility: "管理资源生命周期、加载、卸载"
|
||
public_api:
|
||
- fn: Get
|
||
returns: type: ResourceManager&
|
||
- fn: Load
|
||
params:
|
||
- name: path
|
||
type: const String&
|
||
returns: type: LoadResult
|
||
- fn: LoadAsync
|
||
params:
|
||
- name: path
|
||
type: const String&
|
||
- name: callback
|
||
type: std::function<void(ResourceHandle<IResource>)>
|
||
returns: type: void
|
||
- fn: Unload
|
||
params:
|
||
- name: guid
|
||
type: const ResourceGUID&
|
||
returns: type: void
|
||
|
||
- name: ResourcesLoaders
|
||
parent_subsystem: Resources
|
||
responsibility: "实现各类资源加载器"
|
||
public_api:
|
||
- fn: Load
|
||
params:
|
||
- name: path
|
||
type: const String&
|
||
returns: type: IResource*
|
||
- fn: GetSupportedExtensions
|
||
returns: type: Array<String>
|
||
- fn: CanLoad
|
||
params:
|
||
- name: path
|
||
type: const String&
|
||
returns: type: bool
|
||
|
||
- name: ResourcesFileSystem
|
||
parent_subsystem: Resources
|
||
responsibility: "管理资源路径和资源包"
|
||
public_api:
|
||
- fn: Get
|
||
returns: type: ResourceFileSystem&
|
||
- fn: RegisterLoader
|
||
params:
|
||
- name: loader
|
||
type: IResourceLoader*
|
||
returns: type: void
|
||
- fn: LoadPackage
|
||
params:
|
||
- name: path
|
||
type: const String&
|
||
returns: type: bool
|
||
|
||
- name: RHIDevice
|
||
parent_subsystem: RHI
|
||
responsibility: "创建和管理 RHI 设备及资源"
|
||
public_api:
|
||
- fn: CreateBuffer
|
||
params:
|
||
- name: desc
|
||
type: const RHIBufferDesc&
|
||
returns: type: RHIBuffer*
|
||
- fn: CreateTexture
|
||
params:
|
||
- name: desc
|
||
type: const RHITextureDesc&
|
||
returns: type: RHITexture*
|
||
- fn: CreateShader
|
||
params:
|
||
- name: desc
|
||
type: const RHIShaderDesc&
|
||
returns: type: RHIShader*
|
||
- fn: CreateCommandList
|
||
returns: type: RHICommandList*
|
||
- fn: GetCapabilities
|
||
returns: type: const RHICapabilities&
|
||
|
||
- name: RHICommandList
|
||
parent_subsystem: RHI
|
||
responsibility: "录制和提交图形命令"
|
||
public_api:
|
||
- fn: Draw
|
||
params:
|
||
- name: vertexCount
|
||
type: uint32
|
||
- name: instanceCount
|
||
type: uint32
|
||
returns: type: void
|
||
- fn: DrawIndexed
|
||
params:
|
||
- name: indexCount
|
||
type: uint32
|
||
- name: instanceCount
|
||
type: uint32
|
||
returns: type: void
|
||
- fn: Dispatch
|
||
params:
|
||
- name: x
|
||
type: uint32
|
||
- name: y
|
||
type: uint32
|
||
- name: z
|
||
type: uint32
|
||
returns: type: void
|
||
- fn: SetPipelineState
|
||
params:
|
||
- name: state
|
||
type: RHIPipelineState*
|
||
returns: type: void
|
||
|
||
- name: RHIFactory
|
||
parent_subsystem: RHI
|
||
responsibility: "静态工厂创建后端设备"
|
||
public_api:
|
||
- fn: CreateRHIDevice
|
||
params:
|
||
- name: type
|
||
type: RHIDeviceType
|
||
returns: type: RHIDevice*
|
||
|
||
- name: RHIBuffer
|
||
parent_subsystem: RHI
|
||
responsibility: "封装 GPU 缓冲区"
|
||
public_api:
|
||
- fn: Map
|
||
params:
|
||
- name: offset
|
||
type: size_t
|
||
- name: size
|
||
type: size_t
|
||
returns: type: void*
|
||
- fn: Unmap
|
||
returns: type: void
|
||
|
||
- name: RHITexture
|
||
parent_subsystem: RHI
|
||
responsibility: "封装 GPU 纹理"
|
||
public_api:
|
||
- fn: GetWidth
|
||
returns: type: uint32
|
||
- fn: GetHeight
|
||
returns: type: uint32
|
||
- fn: GetFormat
|
||
returns: type: PixelFormat
|
||
```
|
||
|
||
---
|
||
|
||
# EVOLUTION_MODE
|
||
|
||
```yaml
|
||
mode: build
|
||
description: "XCEngine 处于早期构建阶段，核心基础设施正在逐步完善"
|
||
context: |
|
||
XCEngine 是一个正在开发中的游戏引擎项目，当前版本 0.1.0 专注于建立核心基础设施。
|
||
核心模块（Core、Math、Containers、Memory）已基本完成，提供了游戏引擎所需的基础构建块。
|
||
|
||
渲染系统（RHI）已完成双后端支持（D3D12 和 OpenGL），但高级渲染特性（如光线追踪、
|
||
网格着色器）尚未实现。
|
||
|
||
资源管理系统（Resources）已具备完整的加载框架，支持异步加载、缓存和依赖管理，
|
||
但仅支持基础格式（纹理、网格、着色器）。
|
||
|
||
缺少的子系统：物理系统、脚本系统、实体组件系统（ECS）、音频系统、UI 系统。
|
||
这些将在后续迭代中逐步添加。
|
||
```
|
||
|
||
---
|
||
|
||
# REQUIREMENTS
|
||
|
||
- id: REQ-001
|
||
title: "核心数学库完善"
|
||
description: "扩展数学库以支持 SIMD 优化，提供更高效的向量/矩阵运算"
|
||
source: user
|
||
type: non-functional
|
||
acceptance_criteria:
|
||
- "向量运算支持 SSE/AVX 加速"
|
||
- "矩阵运算支持 SIMD 优化"
|
||
- "性能基准测试显示 2x 以上的性能提升"
|
||
priority: P1
|
||
|
||
- id: REQ-002
|
||
title: "资源系统扩展"
|
||
description: "增加更多资源格式支持，包括音频、动画、骨骼网格"
|
||
source: user
|
||
type: functional
|
||
acceptance_criteria:
|
||
- "支持 WAV 音频加载"
|
||
- "支持 glTF 格式模型导入"
|
||
- "支持骨骼动画数据"
|
||
priority: P1
|
||
|
||
- id: REQ-003
|
||
title: "异步任务系统增强"
|
||
description: "支持任务优先级、任务亲和性、任务追踪"
|
||
source: user
|
||
type: functional
|
||
acceptance_criteria:
|
||
- "支持高/中/低三档任务优先级"
|
||
- "支持将任务分配到特定线程"
|
||
- "提供任务执行状态查询接口"
|
||
priority: P2
|
||
|
||
- id: REQ-004
|
||
title: "内存追踪和泄漏检测"
|
||
description: "增强内存管理器，提供分配追踪和泄漏检测功能"
|
||
source: user
|
||
type: non-functional
|
||
acceptance_criteria:
|
||
- "记录每次分配的调用栈"
|
||
- "检测并报告内存泄漏"
|
||
- "生成内存使用报告"
|
||
priority: P1
|
||
|
||
- id: REQ-005
|
||
title: "渲染管线扩展"
|
||
description: "增加 Compute Shader 支持、GPU 驱动的剔除、延迟渲染管线"
|
||
source: user
|
||
type: functional
|
||
acceptance_criteria:
|
||
- "支持 Compute Shader 执行"
|
||
- "实现视锥体剔除"
|
||
- "提供延迟渲染模板"
|
||
priority: P2
|
||
|
||
- id: REQ-006
|
||
title: "日志系统国际化"
|
||
description: "支持多语言日志输出"
|
||
source: user
|
||
type: functional
|
||
acceptance_criteria:
|
||
- "支持日志消息参数化"
|
||
- "支持格式化字符串"
|
||
- "提供本地化接口"
|
||
priority: P2
|
||
|
||
---
|
||
|
||
# MVS_DEFINITION
|
||
|
||
```yaml
|
||
mvs_solutions:
|
||
- id: MVS-001
|
||
name: "SIMD 数学优化"
|
||
goal: "为数学库添加 SIMD 加速，提升渲染和物理计算性能"
|
||
verification_criteria:
|
||
- "矩阵乘法性能提升 2x 以上"
|
||
- "向量点积/叉积性能提升 2x 以上"
|
||
- "不破坏现有 API 兼容性"
|
||
scope:
|
||
- subsystem: Math
|
||
components: [Vector, Matrix, Quaternion]
|
||
- external: [SSE4.2, AVX2]
|
||
code_structure:
|
||
- file: "engine/include/XCEngine/Math/Vector3.inl"
|
||
purpose: "SIMD 向量实现"
|
||
contains:
|
||
- "SSE/AVX 向量运算内联函数"
|
||
- "跨平台 SIMD 选择宏"
|
||
standalone: true
|
||
- file: "engine/include/XCEngine/Math/Matrix4x4.inl"
|
||
purpose: "SIMD 矩阵实现"
|
||
contains:
|
||
- "SSE/AVX 矩阵乘法"
|
||
- "SIMD 矩阵求逆"
|
||
standalone: true
|
||
integration_plan:
|
||
- step: "定义 SIMD 抽象层选择宏（XC_USE_SSE/AVX）"
|
||
- step: "在 Vector3.h 中引入条件编译的 SIMD 实现"
|
||
- step: "在 Matrix4x4.h 中引入 SIMD 乘法实现"
|
||
- step: "添加性能基准测试"
|
||
status: pending
|
||
|
||
- id: MVS-002
|
||
name: "音频资源加载器"
|
||
goal: "实现 WAV 格式音频加载，为后续音频系统打基础"
|
||
verification_criteria:
|
||
- "成功加载标准 WAV 文件"
|
||
- "正确解析音频参数（采样率、声道、位深）"
|
||
- "提供 AudioClip 资源对象"
|
||
scope:
|
||
- subsystem: Resources
|
||
components: [AudioLoader, AudioClip]
|
||
- external: [stb_vorbis, libwav]
|
||
code_structure:
|
||
- file: "engine/include/XCEngine/Resources/AudioClip.h"
|
||
purpose: "音频数据资源"
|
||
contains:
|
||
- "AudioClip 类定义"
|
||
- "音频格式枚举"
|
||
standalone: true
|
||
- file: "engine/src/Resources/AudioLoader.cpp"
|
||
purpose: "WAV 加载器实现"
|
||
contains:
|
||
- "WAV 文件解析"
|
||
- "音频数据解码"
|
||
standalone: false
|
||
integration_plan:
|
||
- step: "创建 AudioClip 资源类"
|
||
- step: "实现 WAV 解析器"
|
||
- step: "注册 AudioLoader 到 ResourceManager"
|
||
- step: "添加单元测试"
|
||
status: pending
|
||
|
||
- id: MVS-003
|
||
name: "内存泄漏检测器"
|
||
goal: "为 Memory 模块添加分配追踪和泄漏报告功能"
|
||
verification_criteria:
|
||
- "记录所有分配操作和调用栈"
|
||
- "在程序结束时输出泄漏报告"
|
||
- "支持泄漏检测白名单"
|
||
scope:
|
||
- subsystem: Memory
|
||
components: [AllocationTracker, MemoryReport]
|
||
- external: [DbgHelp.dll, walkmacros]
|
||
code_structure:
|
||
- file: "engine/include/XCEngine/Memory/AllocationTracker.h"
|
||
purpose: "分配追踪器"
|
||
contains:
|
||
- "AllocationTracker 单例"
|
||
- "调用栈记录器"
|
||
standalone: true
|
||
- file: "engine/src/Memory/AllocationTracker.cpp"
|
||
purpose: "追踪器实现"
|
||
contains:
|
||
- "DbgHelp 调用栈捕获"
|
||
- "泄漏检测算法"
|
||
standalone: false
|
||
integration_plan:
|
||
- step: "创建 AllocationTracker 类"
|
||
- step: "修改 ProxyAllocator 集成追踪器"
|
||
- step: "实现泄漏报告生成器"
|
||
- step: "在程序退出时自动输出报告"
|
||
status: pending
|
||
```
|
||
|
||
---
|
||
|
||
# DATA_MODELS
|
||
|
||
```yaml
|
||
- name: ResourceHandle
|
||
description: "类型安全的资源智能指针，自动引用计数"
|
||
fields:
|
||
- name: m_resource
|
||
type: T*
|
||
default: nullptr
|
||
constraints: optional
|
||
- name: m_refCount
|
||
type: uint32*
|
||
default: nullptr
|
||
constraints: optional
|
||
|
||
- name: ResourceGUID
|
||
description: "资源的全局唯一标识符，由路径哈希生成"
|
||
fields:
|
||
- name: m_hash
|
||
type: uint64
|
||
default: 0
|
||
constraints: required
|
||
|
||
- name: LoadResult
|
||
description: "资源加载结果"
|
||
fields:
|
||
- name: success
|
||
type: bool
|
||
default: false
|
||
constraints: required
|
||
- name: resource
|
||
type: IResource*
|
||
default: nullptr
|
||
constraints: optional
|
||
- name: errorMessage
|
||
type: String
|
||
default: ""
|
||
constraints: optional
|
||
|
||
- name: RHICapabilities
|
||
description: "GPU 硬件能力查询"
|
||
fields:
|
||
- name: raytracing
|
||
type: bool
|
||
default: false
|
||
constraints: optional
|
||
- name: meshShaders
|
||
type: bool
|
||
default: false
|
||
constraints: optional
|
||
- name: tessellation
|
||
type: bool
|
||
default: false
|
||
constraints: optional
|
||
- name: maxTextureSize
|
||
type: uint32
|
||
default: 4096
|
||
constraints: optional
|
||
|
||
- name: Transform
|
||
description: "位置、旋转、缩放的三维变换"
|
||
fields:
|
||
- name: m_position
|
||
type: Vector3
|
||
default: (0,0,0)
|
||
constraints: required
|
||
- name: m_rotation
|
||
type: Quaternion
|
||
default: identity
|
||
constraints: required
|
||
- name: m_scale
|
||
type: Vector3
|
||
default: (1,1,1)
|
||
constraints: required
|
||
|
||
- name: Frustum
|
||
description: "视锥体，用于裁剪检测"
|
||
fields:
|
||
- name: m_planes
|
||
type: Array<Plane, 6>
|
||
default: []
|
||
constraints: required
|
||
- name: m_corners
|
||
type: Array<Vector3, 8>
|
||
default: []
|
||
constraints: required
|
||
|
||
- name: IResource
|
||
description: "所有资源的基接口"
|
||
fields:
|
||
- name: m_type
|
||
type: ResourceType
|
||
constraints: required
|
||
- name: m_name
|
||
type: String
|
||
constraints: required
|
||
- name: m_path
|
||
type: String
|
||
constraints: required
|
||
- name: m_guid
|
||
type: ResourceGUID
|
||
constraints: required
|
||
```
|
||
|
||
---
|
||
|
||
# EVOLUTION_PLAN
|
||
|
||
```yaml
|
||
fix_plan:
|
||
- issue_id: BUG-001
|
||
description: "LinearAllocator Clear 后重新分配时可能返回重叠内存"
|
||
root_cause: "Clear 仅重置指针，未清理旧内存映射"
|
||
minimal_change:
|
||
- file: "engine/src/Memory/LinearAllocator.cpp"
|
||
verification: "连续 Clear 和分配，检查内存区域不重叠"
|
||
|
||
- issue_id: BUG-002
|
||
description: "Event 在多线程同时订阅/取消订阅时存在竞态条件"
|
||
root_cause: "订阅列表操作未加锁保护"
|
||
minimal_change:
|
||
- file: "engine/include/XCEngine/Core/Event.h"
|
||
verification: "压力测试多线程订阅场景，无崩溃和数据错误"
|
||
|
||
refactor_plan:
|
||
- target: "统一内存分配接口"
|
||
constraints:
|
||
- "保持向后兼容"
|
||
- "不引入运行时开销"
|
||
steps:
|
||
- "提取 IAllocator 接口的最小子集"
|
||
- "将 MakeRef/MakeUnique 重构为使用分配器参数"
|
||
- "添加便捷宏 XE_NEW/T_XE_DELETE"
|
||
|
||
- target: "RHI 资源状态转换自动化"
|
||
constraints:
|
||
- "保持性能"
|
||
- "兼容现有渲染器"
|
||
steps:
|
||
- "引入资源状态跟踪器"
|
||
- "自动插入转换 barriers"
|
||
- "暴露手动控制接口"
|
||
|
||
feature_plan:
|
||
- feature_id: FEAT-001
|
||
name: "实体组件系统（ECS）"
|
||
addition: "实现高性能 ECS 架构，支持 archetypes 和 query"
|
||
integration_point: "Engine 层，位于 Resources 和 Gameplay 之间"
|
||
steps:
|
||
- "定义 Component、Entity、World 接口"
|
||
- "实现 Archetype 存储"
|
||
- "实现 Query 系统"
|
||
- "集成到引擎主循环"
|
||
|
||
- feature_id: FEAT-002
|
||
name: "物理子系统"
|
||
addition: "集成物理引擎，支持刚体、碰撞体"
|
||
integration_point: "Core 层下方，独立子系统"
|
||
steps:
|
||
- "评估物理引擎集成（Bullet/PhysX）"
|
||
- "封装物理世界接口"
|
||
- "实现碰撞检测和响应"
|
||
- "集成到渲染管线"
|
||
|
||
- feature_id: FEAT-003
|
||
name: "脚本系统"
|
||
addition: "支持 Lua 脚本和自定义脚本语言绑定"
|
||
integration_point: "Core 层上方，独立子系统"
|
||
steps:
|
||
- "集成 Lua 虚拟机"
|
||
- "绑定核心引擎 API"
|
||
- "实现脚本组件"
|
||
- "支持热重载"
|
||
```
|
||
|
||
---
|