152 lines
4.9 KiB
Markdown
152 lines
4.9 KiB
Markdown
# 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` 新编辑器主线从组件库走向完整宿主。
|
||
|