XCEngine/docs/blueprint.md

# 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"
      - "实现脚本组件"
      - "支持热重载"
```

---