docs: rewrite README around engine capabilities

2026-04-09 23:35:30 +08:00
parent 7e60bc568a
commit 84db2e951d
1 changed files with 134 additions and 87 deletions
--- a/README.md
+++ b/README.md
@@ -1,123 +1,179 @@
 # XCEngine

-`XCEngine` 是一个 Windows-first、editor-first 的 C++20 游戏引擎工作区。当前主线围绕 `RHI -> Rendering -> Editor -> Asset Pipeline -> Mono Scripting` 演进，目标不是堆 sample，而是把可运行的引擎与编辑器主链持续收口成型。
+`XCEngine` 是一个基于 `C++20` 的游戏引擎。当前代码中已经包含 `RHI`、`Rendering`、`Scene`、`Resources`、`Editor`、`Mono C# Scripting` 和 `XCUI` 相关模块；本 README 只描述当前已经实现或已经接入的能力。

-## 项目定位
+## 核心特性

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

- `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 体系。
+### 场景与运行时

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

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

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

-当前推荐在 Windows 上构建和运行。
+### 脚本系统
+
+- 可选启用基于 `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
- 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 依赖，可以先关闭脚本运行时：
+如果当前不需要 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 新编辑器
+如需构建 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
 ```

@@ -128,24 +184,15 @@ 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
 ```

-更细的测试组织与约定见 [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` 新编辑器主线从组件库走向完整宿主。
-
+- `docs/api/main.md`
+- `editor/README.md`
+- `tests/TEST_SPEC.md`
+- `docs/plan/Editor架构说明.md`
+- `docs/plan/XCUI_NewEditor主线重建计划_2026-04-07.md`