ssdfasd
2b007739ce
关键节点: - 当前阶段项目侧目录收敛为 Assets / Settings / Library - 移除 Content 相关落地表述 - 重构顺序调整为先 target/API 边界，再做目录迁移 - 每阶段验收统一为 XCEditor 编译 + 12 秒冒烟测试
414 lines
8.6 KiB
Markdown
414 lines
8.6 KiB
Markdown
# XCEngine 重构计划
|
||
|
||
## 1. 目标
|
||
|
||
这份计划用于定义 XCEngine 当前一轮重构的执行顺序和架构边界。
|
||
|
||
本轮重构的目标是：
|
||
|
||
- 在代码和构建层面拆开 runtime、pipeline、shared 三类职责
|
||
- 在拆分过程中保持 editor 日常迭代路径稳定
|
||
- 先理顺依赖和 API，再做物理目录调整
|
||
- 每个阶段结束后都执行一次 `XCEditor` 编译和 12 秒冒烟测试
|
||
|
||
## 2. 本轮范围
|
||
|
||
这份计划描述的是当前引擎重构阶段，不是最终交付产物布局。
|
||
|
||
当前阶段的项目侧数据根目录是：
|
||
|
||
- `project/Assets`
|
||
- `project/Settings`
|
||
- `project/Library`
|
||
|
||
当前阶段的基本要求是：
|
||
|
||
- editor 日常迭代继续基于现有项目工作流
|
||
- import、cache、rebuild 等职责逐步从 runtime 侧 API 中拆出去
|
||
- 顶层 `editor` 目录结构在前几个阶段保持稳定
|
||
- 物理目录调整放到依赖边界稳定之后再做
|
||
|
||
打包输出路径和产物布局放到单独的交付阶段再定义。
|
||
|
||
## 3. 架构规则
|
||
|
||
### 3.1 阶段划分
|
||
|
||
代码库按执行阶段拆分为：
|
||
|
||
- `engine/foundation`：基础设施层
|
||
- `engine/shared`：跨阶段稳定契约层
|
||
- `engine/runtime`：运行时系统
|
||
- `pipeline`：导入、构建、烘焙系统
|
||
- `editor`：当前编辑器应用树
|
||
- `programs`：各类可执行入口
|
||
|
||
### 3.2 依赖方向
|
||
|
||
目标依赖关系收敛为：
|
||
|
||
```text
|
||
foundation
|
||
^
|
||
|
|
||
shared
|
||
^ ^
|
||
| |
|
||
runtime pipeline
|
||
^ ^
|
||
| |
|
||
+--------editor
|
||
|
||
programs -> runtime / pipeline
|
||
```
|
||
|
||
约束如下：
|
||
|
||
- `runtime` 只向下依赖 `foundation` 和 `shared`
|
||
- `pipeline` 只向下依赖 `foundation` 和 `shared`
|
||
- `editor` 负责编排 runtime 和 pipeline
|
||
- `shared` 只保留稳定数据契约
|
||
|
||
### 3.3 项目数据职责
|
||
|
||
当前阶段的项目侧数据职责为：
|
||
|
||
- `project/Assets`：源资源
|
||
- `project/Settings`：项目配置
|
||
- `project/Library`：导入缓存、中间产物、索引、日志、脚本编译输出
|
||
|
||
`Library` 归 pipeline 侧职责管理。
|
||
runtime 可以消费现有工作流准备好的资源数据，但 import 和 build 编排必须继续往 pipeline 侧收拢。
|
||
|
||
## 4. 目标目录结构
|
||
|
||
```text
|
||
XCEngine/
|
||
CMakeLists.txt
|
||
cmake/
|
||
engine/
|
||
foundation/
|
||
base/
|
||
containers/
|
||
memory/
|
||
threading/
|
||
diagnostics/
|
||
filesystem/
|
||
math/
|
||
serialization/
|
||
shared/
|
||
asset/
|
||
AssetRef/
|
||
LocalID/
|
||
ResourceType/
|
||
CatalogFormat/
|
||
PackageFormat/
|
||
cooked/
|
||
CompiledTexture/
|
||
CompiledMaterial/
|
||
CompiledShader/
|
||
CompiledModel/
|
||
CompiledUIDocument/
|
||
CompiledVolume/
|
||
CompiledGaussianSplat/
|
||
runtime/
|
||
platform/
|
||
asset/
|
||
AssetManager/
|
||
ResourceStore/
|
||
AsyncLoad/
|
||
Catalog/
|
||
Package/
|
||
CookedReaders/
|
||
resources/
|
||
Texture/
|
||
Mesh/
|
||
Material/
|
||
Shader/
|
||
Model/
|
||
UI/
|
||
Volume/
|
||
GaussianSplat/
|
||
scene/
|
||
rendering/
|
||
core/
|
||
passes/
|
||
pipelines/
|
||
frame_graph/
|
||
gpu_cache/
|
||
audio/
|
||
physics/
|
||
scripting/
|
||
pipeline/
|
||
core/
|
||
SourceAssetDB/
|
||
ArtifactDB/
|
||
SourceIndex/
|
||
DependencyGraph/
|
||
BuildCache/
|
||
BuildGraph/
|
||
ImportService/
|
||
importers/
|
||
TextureImporter/
|
||
MaterialImporter/
|
||
ShaderImporter/
|
||
ModelImporter/
|
||
UIDocumentImporter/
|
||
VolumeImporter/
|
||
GaussianSplatImporter/
|
||
compilers/
|
||
ShaderCompiler/
|
||
UIDocumentCompiler/
|
||
writers/
|
||
ArtifactWriter/
|
||
CatalogWriter/
|
||
PackageWriter/
|
||
cook/
|
||
tools/
|
||
editor/
|
||
programs/
|
||
xcgame/
|
||
xcassetbuild/
|
||
xccook/
|
||
xcshadercook/
|
||
managed/
|
||
runtime/
|
||
editor/
|
||
project/
|
||
Assets/
|
||
Settings/
|
||
Library/
|
||
SourceDB/
|
||
ArtifactDB/
|
||
Artifacts/
|
||
ImportLogs/
|
||
ScriptAssemblies/
|
||
tests/
|
||
foundation/
|
||
shared/
|
||
runtime/
|
||
pipeline/
|
||
editor/
|
||
e2e/
|
||
docs/
|
||
tools/
|
||
third_party/
|
||
```
|
||
|
||
## 5. 各层职责
|
||
|
||
### 5.1 `engine/foundation`
|
||
|
||
基础设施层承载全仓通用能力：
|
||
|
||
- 基础类型
|
||
- 日志与诊断
|
||
- 字符串和容器
|
||
- 数学库
|
||
- 线程和同步
|
||
- 内存管理
|
||
- 序列化
|
||
- 文件系统封装
|
||
|
||
### 5.2 `engine/shared`
|
||
|
||
共享契约层承载跨阶段稳定数据结构：
|
||
|
||
- 资源标识
|
||
- 本地标识
|
||
- 资源类型枚举
|
||
- catalog / package 描述结构
|
||
- 各类 cooked payload 结构
|
||
- 版本常量
|
||
|
||
这一层只放数据契约，不放 manager、loader、cache、importer、orchestrator。
|
||
|
||
### 5.3 `engine/runtime`
|
||
|
||
运行时层负责：
|
||
|
||
- 资源加载与解析
|
||
- 运行时对象缓存
|
||
- 异步加载调度
|
||
- scene 系统
|
||
- rendering
|
||
- audio
|
||
- physics
|
||
- scripting
|
||
|
||
runtime 侧收敛原则：
|
||
|
||
- 面向运行时消费资源
|
||
- 不承载源资源导入
|
||
- 不承载构建缓存管理
|
||
- 不直接持有 pipeline 服务实现
|
||
|
||
### 5.4 `pipeline`
|
||
|
||
pipeline 层负责：
|
||
|
||
- 源资源数据库
|
||
- 中间产物数据库
|
||
- 源资源索引
|
||
- 依赖关系图
|
||
- 构建缓存
|
||
- 构建图
|
||
- import service
|
||
- 各类 importer 和 compiler
|
||
- 中间产物写入和后续打包写入
|
||
|
||
`project/Library` 下的导入和构建状态由这一层统一负责。
|
||
|
||
### 5.5 `editor`
|
||
|
||
当前阶段保留现有顶层 `editor` 应用树，职责包括：
|
||
|
||
- workspace / project 相关交互
|
||
- runtime 与 pipeline 的编排
|
||
- editor 场景和工具工作流
|
||
|
||
editor 内部目录重组不属于第一阶段工作。
|
||
|
||
### 5.6 `programs`
|
||
|
||
各类可执行入口统一放在这里，例如：
|
||
|
||
- 游戏程序
|
||
- 资源构建工具
|
||
- 烘焙工具
|
||
- shader 工具
|
||
|
||
## 6. 当前系统到目标结构的映射
|
||
|
||
当前主要系统映射如下：
|
||
|
||
- `ResourceManager` -> `engine/runtime/asset/AssetManager`
|
||
- `ResourceCache` -> `engine/runtime/asset/ResourceStore`
|
||
- `AsyncLoader` -> `engine/runtime/asset/AsyncLoad`
|
||
- `ProjectAssetIndex` -> `pipeline/core/SourceIndex`
|
||
- `AssetImportService` -> `pipeline/core/ImportService`
|
||
- `AssetDatabase` -> `pipeline/core/SourceAssetDB` + `pipeline/core/ArtifactDB`
|
||
- `RenderResourceCache` -> `engine/runtime/rendering/gpu_cache`
|
||
|
||
重构过程中，editor 迭代路径先保持在现有项目工作流上，再逐步完成职责分拆。
|
||
|
||
## 7. 构建目标规划
|
||
|
||
建议的目标族如下：
|
||
|
||
```text
|
||
xc_foundation
|
||
xc_shared_asset
|
||
xc_shared_cooked
|
||
|
||
xc_runtime_platform
|
||
xc_runtime_asset
|
||
xc_runtime_resources
|
||
xc_runtime_scene
|
||
xc_runtime_rendering
|
||
xc_runtime_audio
|
||
xc_runtime_physics
|
||
xc_runtime_scripting
|
||
xc_runtime
|
||
|
||
xc_pipeline_core
|
||
xc_pipeline_importers
|
||
xc_pipeline_compilers
|
||
xc_pipeline_writers
|
||
xc_pipeline_cook
|
||
xc_pipeline
|
||
|
||
xcgame
|
||
xcassetbuild
|
||
xccook
|
||
xcshadercook
|
||
```
|
||
|
||
构建侧落地原则：
|
||
|
||
- 运行时可执行程序链接 `xc_runtime`
|
||
- 资源工具链接 `xc_pipeline`
|
||
- editor 入口结构在前几个阶段保持现状
|
||
|
||
## 8. 分阶段执行计划
|
||
|
||
### 阶段一：构建边界拆分
|
||
|
||
目标：
|
||
|
||
- 先把现有代码拆成 foundation、shared、runtime、pipeline 四类目标
|
||
- 这一阶段尽量少动物理文件位置
|
||
|
||
工作项：
|
||
|
||
- 拆分 CMake target
|
||
- 收敛公共头文件暴露面
|
||
- 消除 target 级别的 runtime / pipeline 混杂依赖
|
||
|
||
阶段验收：
|
||
|
||
1. 编译 `XCEditor`
|
||
2. 执行 12 秒 editor 冒烟测试
|
||
|
||
### 阶段二：API 边界拆分
|
||
|
||
目标：
|
||
|
||
- 把 runtime 侧资源访问接口和 pipeline 侧导入/构建职责拆开
|
||
|
||
工作项：
|
||
|
||
- 将 import / build 逻辑收拢到 pipeline 服务
|
||
- 将 runtime manager 收窄到 load / resolve / cache 范围
|
||
- 保持 editor 当前迭代工作流稳定
|
||
|
||
阶段验收：
|
||
|
||
1. 编译 `XCEditor`
|
||
2. 执行 12 秒 editor 冒烟测试
|
||
|
||
### 阶段三：物理目录迁移
|
||
|
||
目标：
|
||
|
||
- 让磁盘目录结构和依赖边界对齐
|
||
|
||
工作项：
|
||
|
||
- 把文件迁移到 `engine/foundation`、`engine/shared`、`engine/runtime`、`pipeline`
|
||
- 更新 include、CMake 和测试
|
||
- 除非前置拆分强依赖，否则不在这一阶段重组 editor 内部树
|
||
|
||
阶段验收：
|
||
|
||
1. 编译 `XCEditor`
|
||
2. 执行 12 秒 editor 冒烟测试
|
||
|
||
### 阶段四：交付与打包阶段
|
||
|
||
目标：
|
||
|
||
- 在 runtime、pipeline、editor 职责已经清晰之后，再引入独立交付流程
|
||
|
||
工作项：
|
||
|
||
- 增加专用 cook / build 可执行工具
|
||
- 明确交付产物格式和输出路径
|
||
- 将交付流程与 editor 日常迭代流程分离
|
||
|
||
阶段验收：
|
||
|
||
1. 编译 `XCEditor`
|
||
2. 执行 12 秒 editor 冒烟测试
|
||
|
||
## 9. 硬性规则
|
||
|
||
整个重构过程都遵守以下规则：
|
||
|
||
1. `Library` 是 pipeline 侧的缓存和中间状态。
|
||
2. runtime API 只收敛到运行时资源访问职责。
|
||
3. 大规模文件迁移必须排在 target 和 API 边界稳定之后。
|
||
4. shared 层只保留稳定数据契约。
|
||
5. phases 1 到 3 期间，editor 日常迭代路径保持连续可用。
|
||
6. 每个阶段完成后都要先编译 `XCEditor`，再执行 12 秒冒烟测试。
|