77 lines
4.6 KiB
Markdown
77 lines
4.6 KiB
Markdown
# GhostEngine 开发指南
|
||
|
||
欢迎参与 GhostEngine 项目。本文档旨在帮助你快速了解项目的当前状态、架构设计、开发规范及环境配置。
|
||
|
||
## 1. 开发环境要求 (Prerequisites)
|
||
|
||
在开始开发之前，请确保你的开发环境满足以下要求：
|
||
|
||
- **操作系统**: Windows 10 版本 1809 (17763) 或更高版本。
|
||
- **IDE**: Visual Studio 2022 (建议使用最新预览版以支持 .NET 10)。
|
||
- **.NET SDK**: .NET 10.0 SDK。
|
||
- **Windows App SDK**: 项目目前使用 Windows App SDK (WinUI 3) 版本 1.8.260101001。
|
||
- **显卡**: 支持 DirectX 12 (Feature Level 11.0+) 的显卡。
|
||
- **Visual Studio 工作负载**:
|
||
- .NET 桌面开发
|
||
- 使用 C++ 的桌面开发 (部分第三方库包装需要)
|
||
- 通用 Windows 平台开发 (用于 Windows App SDK 支持)
|
||
|
||
## 2. 项目结构 (Project Structure)
|
||
|
||
项目代码主要位于 `src` 目录下，按功能分为三个主要部分：
|
||
|
||
### 2.1 Runtime (引擎运行时)
|
||
- **Ghost.Graphics**: 图形渲染核心。包含 RHI (渲染硬件接口) 定义及其 D3D12 实现。集成了 Render Graph (渲染图) 模块用于管理复杂的渲染流水线。
|
||
- **Ghost.Entities**: 基于 Archetype (原型) 的高性能 ECS (实体组件系统) 实现。包含 `World`, `EntityManager`, `EntityQuery` 等核心组件。
|
||
- **Ghost.Engine**: 引擎基础逻辑。包含场景管理 (`Scene`)、基础组件 (如 `Hierarchy`, `LocalToWorld`) 及数学工具类。
|
||
|
||
### 2.2 Editor (编辑器)
|
||
- **Ghost.Editor**: 基于 WinUI 3 编写的桌面编辑器前端。采用 MVVM 架构。
|
||
- **Ghost.Editor.Core**: 编辑器框架层。包含资源管理 (`AssetRegistry`)、检查器服务 (`InspectorService`)、场景树管理 (`SceneGraph`) 等非 UI 逻辑。
|
||
- **Ghost.DSL**: 引擎自定义着色器语言 (GSL) 的编译器和解析器，用于处理着色器代码生成。
|
||
|
||
### 2.3 ThirdParty (第三方库)
|
||
- 包含对 FMOD (音频)、Nvtt (纹理压缩)、MeshOptimizer (模型优化) 等 C++ 库的 C# 包装。
|
||
|
||
## 3. 命名规范 (Naming Conventions)
|
||
|
||
项目严格遵守以下 C# 编程规范：
|
||
|
||
- **命名空间**: 以 `Ghost.` 开头，后跟模块名 (例如 `Ghost.Graphics.D3D12`)。
|
||
- **类与方法**: 使用 `PascalCase` (大驼峰命名法)。
|
||
- **私有字段**: 使用 `_camelCase` (下划线前缀的小驼峰命名法)。
|
||
- **接口**: 必须以 `I` 作为前缀 (例如 `IRenderDevice`)。
|
||
- **异步方法**: 必须以 `Async` 作为后缀 (例如 `LoadAssetAsync`)。
|
||
- **实现类**: 针对接口的具体实现应体现技术细节 (例如 `D3D12GraphicsEngine` 实现了 `IGraphicsEngine`)。
|
||
|
||
## 4. 架构设计与模式 (Architecture & Patterns)
|
||
|
||
### 4.1 ECS (Entity Component System)
|
||
运行时逻辑优先使用 ECS 模式以获得最佳的缓存命中率和并行性能：
|
||
- **Entity**: 纯 ID。
|
||
- **Component**: 纯数据结构 (Struct)。
|
||
- **System**: 处理特定组件组合的逻辑类。
|
||
|
||
### 4.2 RHI & Render Graph
|
||
- **RHI (Render Hardware Interface)**: 抽象了底层的图形 API。目前主要实现为 D3D12，通过 Vortice.Windows 进行绑定。
|
||
- **Render Graph**: 采用有向无环图 (DAG) 管理每一帧的渲染顺序、资源屏障 (Resource Barriers) 和资源复用，简化了 D3D12 的资源管理负担。
|
||
|
||
### 4.3 MVVM & Service Pattern (Editor)
|
||
编辑器部分遵循：
|
||
- **MVVM**: 分离 UI (`View`) 与业务逻辑 (`ViewModel`)。
|
||
- **Service/Contract**: 通过接口定义服务 (如 `IAssetRegistry`)，并利用依赖注入 (Dependency Injection) 进行解耦。
|
||
|
||
### 4.4 核心设计原则 (Core Design Principles)
|
||
- **Result over Exception (结果对象胜于异常)**: 在核心运行时中，避免使用 `throw` 处理预期错误，优先返回 `Ghost.Core.Result` 结构体，以提高性能和错误流的可控性。
|
||
- **Handle over Ptr/Reference (句柄胜于指针/引用)**: 资源引用（如实体、纹理、缓冲区）应优先使用 `Handle<T>`，避免持有直接的内存地址，以确保资源管理的安全性并支持高效序列化。
|
||
|
||
## 5. 核心逻辑当前状态
|
||
|
||
- **渲染系统**: 已具备基础的 D3D12 渲染器、Render Graph 编译器及简单的 Mesh 渲染 pass。支持自定义着色器加载。
|
||
- **实体系统**: 已实现 Archetype-based ECS，支持高性能的实体查询 (`EntityQuery`) 和作业系统迭代。
|
||
- **资源管理**: 编辑器端已实现初步的资产数据库 (`AssetRegistry`)，支持纹理和模型的导入流程。
|
||
- **场景管理**: 支持基础的层级结构 (`Hierarchy`) 和变换同步 (`LocalToWorld`)。
|
||
|
||
---
|
||
*注：关于后续的开发计划 (TODO) 及改进方向，我将直接通过会议或即时通讯工具进行沟通。*
|