XCEngine/README.md

# XCEngine

`XCEngine` 是一个基于 `C++20` 的游戏引擎。当前代码中已经包含 `RHI`、`Rendering`、`Scene`、`Resources`、`Editor`、`Mono C# Scripting` 和 `XCUI` 相关模块；本 README 只描述当前已经实现或已经接入的能力。

## 核心特性

### 渲染

- 内置跨后端 `RHI` 抽象层，当前支持 `D3D12`、`OpenGL`、`Vulkan`
- 当前主渲染链为 `SceneRenderer -> CameraRenderer -> BuiltinForwardPipeline`
- 已接入前向渲染主路径、透明路径和 skybox 路径
- 已具备方向光阴影通路
- 已具备 `object-id` pass，可用于编辑器拾取
- 已具备选中描边、最终颜色合成和颜色缩放后处理 pass
- 已具备无限网格 pass，可用于 Scene View
- 已接入 `NanoVDB` 体积渲染 pass
- `RenderSurface` 允许同一条渲染链服务于窗口输出、编辑器视口和离屏目标

### 场景与运行时

- 采用 `Scene / GameObject / Component` 结构
- 已具备场景更新、运行时驱动和场景序列化能力
- 内置常用组件，包括：
  - `TransformComponent`
  - `CameraComponent`
  - `LightComponent`
  - `MeshFilterComponent`
  - `MeshRendererComponent`
  - `VolumeRendererComponent`
  - `AudioSourceComponent`
  - `AudioListenerComponent`
  - `ScriptComponent`

### 资源系统

- 资源主线不是简单文件直读，而是 `AssetDatabase + Artifact + Library` 工作流
- 已具备项目资产索引、导入、重导入和缓存维护链路
- 已接入的资源类型包括：
  - `Mesh`
  - `Texture`
  - `Shader`
  - `Material`
  - `AudioClip`
  - `VolumeField`
  - `UI Document`
- 内置 `builtin://` 资源入口，可直接使用基础 mesh、材质等内置资源

### 脚本系统

- 可选启用基于 `Mono` 的 `C#` 脚本运行时
- 托管程序集分为：
  - `XCEngine.ScriptCore`
  - `GameScripts`
- 脚本组件由 `ScriptComponent` 承载
- 引擎当前支持脚本类发现、字段元数据读取、默认值读取和字段存储
- 支持脚本字段 override 持久化与运行时同步
- 编辑器已接入项目脚本程序集重建与脚本运行时重载

### 编辑器

- 当前正式编辑器是基于 `Win32 + D3D12 + ImGui` 的桌面编辑器
- 当前已具备以下基础工作流：
  - `Hierarchy`
  - `Inspector`
  - `Project`
  - `Console`
  - `Scene View`
  - `Game View`
- `Scene View` 已接入：
  - object-id picking
  - selection outline
  - overlay
  - transform gizmo
  - infinite grid
- `Inspector` 已能处理常规组件检查，也已接入 `ScriptComponent` 与材质资源检查路径
- 编辑器能够识别项目目录、加载项目资源、接通 `Library/ScriptAssemblies` 中的脚本程序集

### UI 与 XCUI

- 引擎内部包含 retained-mode UI 基础设施
- 已具备：
  - 布局系统
  - 样式系统
  - 焦点控制
  - 输入分发
  - 快捷键分发
  - 文本输入编辑
  - 选择模型
  - 拖拽交互模型
- 运行时 UI 主链包括：
  - `UIScreenDocumentHost`
  - `UIScreenPlayer`
  - `UISystem`
- 新编辑器路线基于 `XCUIEditorLib` 推进，当前已经包含树视图、列表视图、菜单、标签条、属性网格、字段控件、workspace / dock / viewport shell 等基础组件

### 音频

- 已具备 `AudioSystem`
- 已接入 `AudioSourceComponent` 与 `AudioListenerComponent`
- 当前代码中已包含 `AudioMixer` 和多种效果器/分析器实现入口：
  - `Equalizer`
  - `FFTFilter`
  - `Reverbation`
  - `HRTF`

### 测试

- 引擎不是“只靠手工点点看”的状态，当前已具备大规模测试树
- 覆盖范围包括：
  - Engine 基础模块
  - Rendering
  - RHI
  - Editor
  - Scripting
  - UI
- `RHI` 集成测试使用统一基准图做 golden-image 对比
- `XCUI` 当前也有独立的 unit / integration 验证链路

## 当前实现范围

- 当前正式编辑器为基于 `Win32 + D3D12 + ImGui` 的桌面编辑器
- 当前 `RHI` 后端为 `D3D12`、`OpenGL`、`Vulkan`
- 当前项目资产工作流已经接入 `AssetDatabase + Artifact + Library`
- 当前 `Mono C#` 脚本程序集与运行时链路已经接入
- 当前 `XCUI` 新编辑器路线仍在继续实现中

## 快速开始

推荐环境：

- Windows 10/11
- Visual Studio 2022 / MSVC v143
- CMake 3.15+
- Vulkan SDK
- .NET SDK

配置工程：

```powershell
cmake -S . -B build -A x64
```

如果当前不需要 Mono 脚本运行时：

```powershell
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
```

构建当前正式编辑器：

```powershell
cmake --build build --config Debug --target XCEditor
```

运行：

```powershell
.\editor\bin\Debug\XCEngine.exe
```

如需构建项目脚本程序集：

```powershell
cmake --build build --config Debug --target xcengine_project_managed_assemblies
```

如需构建 XCUI 新编辑器宿主：

```powershell
cmake --build build --config Debug --target XCUIEditorApp
```

## 测试入口

```powershell
ctest --test-dir build -N -C Debug
ctest --test-dir build -C Debug --output-on-failure
```

常用目标：

```powershell
cmake --build build --config Debug --target editor_tests
cmake --build build --config Debug --target rendering_all_tests
cmake --build build --config Debug --target rhi_all_tests
cmake --build build --config Debug --target scripting_tests
cmake --build build --config Debug --target core_ui_all_tests
cmake --build build --config Debug --target editor_ui_all_tests
cmake --build build --config Debug --target runtime_ui_all_tests
```

## 文档入口

- `docs/api/main.md`
- `editor/README.md`
- `tests/TEST_SPEC.md`
- `docs/plan/Editor架构说明.md`
- `docs/plan/XCUI_NewEditor主线重建计划_2026-04-07.md`