XCEngine/README.md

# XCEngine

`XCEngine` 是一个 Windows-first、editor-first 的 C++20 游戏引擎工作区。当前主线围绕 `RHI -> Rendering -> Editor -> Asset Pipeline -> Mono Scripting` 演进，目标不是堆 sample，而是把可运行的引擎与编辑器主链持续收口成型。

## 项目定位

- `engine/` 提供核心静态库 `XCEngine`，包含 `RHI`、`Rendering`、`Resources`、`Scene`、`Input`、`Audio`、`Scripting` 等模块。
- `editor/` 是当前正式桌面编辑器，宿主基于 Win32 + D3D12，编辑器 target 名为 `XCEditor`，输出文件名为 `XCEngine.exe`。
- `new_editor/` 是基于 `XCUI` 的新编辑器主线，当前仍在并行演进。
- `project/` 是随仓库维护的示例工程，已经采用 `Assets + .meta + Library` 布局。
- `tests/` 覆盖 Engine、Rendering、RHI、Editor、Scripting、UI 等主线模块。

## 当前能力

- `RHI` 当前维护 `D3D12 / OpenGL / Vulkan` 三个后端。
- `Rendering` 已形成 `SceneRenderer -> CameraRenderer -> RenderPipeline` 主链。
- Scene View 已接通 object-id picking、selection outline、grid、overlay 与 gizmo 渲染。
- 资源系统已采用 `AssetDatabase + Artifact + Library` 工作流，而不是简单文件直读。
- `Material / Shader / Texture / Mesh` 已接入正式资源导入与运行时加载链路。
- 编辑器已支持项目加载、Scene/Game viewport、Inspector、Hierarchy、Project 面板等基础闭环。
- Mono C# 脚本运行时与项目脚本程序集构建链路已接入当前工作区。
- `new_editor/` 正在推进 `XCUI` 宿主、控件与 shell 体系。

## 仓库结构

- `engine/`：引擎核心实现与公共头文件。
- `editor/`：当前正式编辑器与 viewport 接线。
- `new_editor/`：XCUI 新编辑器主线。
- `managed/`：`XCEngine.ScriptCore` 与示例托管程序集。
- `project/`：示例工程与随仓库维护的资产。
- `tests/`：单元测试、集成测试与阶段性回归入口。
- `docs/`：架构说明、API 文档、计划与历史归档。
- `mvs/`：原型、实验工程与外部参考材料。

## 环境要求

当前推荐在 Windows 上构建和运行。

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

脚本运行时启用时，还需要：

- 可用的 Mono 依赖，默认路径来自 `参考/Fermion/Fermion/external/mono`

补充说明：

- 当前根 CMake 配置里，`Vulkan SDK` 仍是硬依赖。
- NanoVDB 头文件是可选能力，仅影响 `.nvdb` 体积资源支持。
- 如果仓库里的大资源依赖 Git LFS，请先执行 `git lfs pull`。

## 快速开始

### 1. 配置

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

如果本地暂时没有 Mono 依赖，可以先关闭脚本运行时：

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

### 2. 构建当前编辑器

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

编辑器产物路径：

- `editor/bin/Debug/XCEngine.exe`

### 3. 运行编辑器

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

显式指定工程目录：

```powershell
.\editor\bin\Debug\XCEngine.exe --project D:\Path\To\Project
```

### 4. 构建项目脚本程序集

如果你要验证 `ScriptComponent`、脚本类发现或 Inspector 字段编辑，先构建：

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

### 5. 可选构建 XCUI 新编辑器

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

产物路径通常为：

- `new_editor/bin/Debug/XCUIEditor.exe`

## 测试

列出测试：

```powershell
ctest --test-dir build -N -C Debug
```

运行测试：

```powershell
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
```

更细的测试组织与约定见 [tests/TEST_SPEC.md](tests/TEST_SPEC.md)。

## 文档入口

- 编辑器说明：[editor/README.md](editor/README.md)
- API 文档入口：[docs/api/main.md](docs/api/main.md)
- 架构蓝图：[docs/blueprint.md](docs/blueprint.md)
- Editor 架构说明：[docs/plan/Editor架构说明.md](docs/plan/Editor架构说明.md)
- 测试规范：[tests/TEST_SPEC.md](tests/TEST_SPEC.md)
- 协作约定：[AGENT.md](AGENT.md)

## 当前状态

`XCEngine` 仍处于高频迭代阶段，但当前仓库已经不是“零散原型集合”，而是一个以编辑器工作流为中心持续收口的引擎工作区。接口、目录和构建细节仍可能调整，但主线方向已经比较明确：

- 稳定 `RHI / Rendering / Asset Pipeline / Editor` 主链。
- 继续推进 `Mono Scripting` 与项目脚本工作流。
- 推进 `XCUI` 新编辑器主线从组件库走向完整宿主。