XCEngine/docs/plan/target-architecture.md

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 依赖方向

目标依赖关系收敛为：

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. 目标目录结构

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. 构建目标规划

建议的目标族如下：

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 秒冒烟测试。