xuanchi/XCEngine

Fork 0

Files

ssdfasd c866a7a39b refactor: close runtime rhi module boundary

2026-05-02 04:23:50 +08:00

22 KiB

Raw Blame History

XCEngine 目标架构总计划

1. 目标

这一轮重构直接朝长期结构收口，不再围绕历史目录做中间设计。

本计划现在是总 source of truth，后续子计划只能细化执行，不允许再反向改写这里已经确认的边界。

长期目标：

顶层主代码根收敛为 engine/ 和 editor/
engine/ 下面按 runtime、pipeline、managed 组织
runtime 明确表示打包给玩家时必须包含的引擎核心
pipeline 明确表示开发期引擎能力层，并且 runtime + pipeline 必须能组成包含引擎全部功能的无头模式
editor 明确表示桌面产品壳、窗口、面板、视口交互和工作流编排
物理目录统一按模块使用 include/ + src/
公共 C++ 头路径统一暴露为 XCEngine/...
每完成一个明确阶段，都重新编译 XCEditor 并执行 12 秒冒烟测试
每完成一个明确阶段并通过编译 / 冒烟，都提交并推送

2. 不可回退的规则

2.1 目录与命名规则

顶层域名固定使用小写：engine/runtime、engine/pipeline、engine/managed
域内模块名使用大写首字母：Rendering、Scene、Assets、Preview
物理模块统一使用 include/ + src/，不引入 Public/Private
禁止重新引入 Shared、Foundation、Common 这类无业务语义顶层目录
禁止把开发期能力继续塞回 runtime
禁止把桌面 editor 交互机制错误塞进 pipeline
禁止把引擎本体能力错误塞进 editor

2.2 include 规则

公共 include 一律走稳定 API 路径
runtime 公共头路径不暴露 runtime 这一层
pipeline 公共头路径保留 Pipeline 总域
禁止新增相对路径 public include

示例：

#include <XCEngine/Rendering/Execution/CameraRenderer.h>
#include <XCEngine/Scene/Scene.h>
#include <XCEngine/Pipeline/Assets/AssetDatabase.h>
#include <XCEngine/Pipeline/Preview/ModelPreviewRenderer.h>

2.3 模块边界规则

runtime 可以被 pipeline 和 editor 依赖
pipeline 可以依赖 runtime
editor 可以依赖 pipeline 和 runtime
runtime 禁止反向依赖 pipeline
pipeline 禁止依赖 editor
editor 负责 GUI 壳和交互编排，不负责拥有完整引擎功能本体

3. 顶层语义

3.1 runtime

runtime 的含义已经固定：

给玩家运行时带走的原生能力
运行游戏时必须存在的系统
不默认承载开发期专用离线编译、源文件导入、桌面视口交互机制

3.2 pipeline

pipeline 的含义已经固定：

开发期引擎能力层
不打包给玩家
与 runtime 组合后，必须能够构成包含引擎全部功能的无头模式
这里的“无头”含义是不依赖 editor GUI，不是要求保留所有桌面视口交互手段

因此，pipeline 承担的是：

可由代码 / API / 命令行驱动的开发期引擎功能
不是桌面窗口、鼠标拾取、gizmo handle 拖拽这类 GUI 交互机制

3.3 editor

editor 的含义已经固定：

桌面产品程序
UI 壳
工作流
窗口、面板、视口交互、快捷键、模式切换、Undo/Redo、状态同步

editor 不是引擎能力仓库，但它拥有桌面交互机制本身。

3.4 三层组合关系

这条关系现在明确写死：

runtime = Player Engine Core
runtime + pipeline = Full Headless Engine
runtime + pipeline + editor = Full GUI Editor Product

这里的 Full Headless Engine 指：

引擎完整功能可以被代码 / API / 命令行驱动
不依赖桌面 editor UI
但不要求保留桌面视口交互机制本身

4. 长期目录

XCEngine/
  engine/
    assets/
      builtin/
    managed/
      ScriptCore/
      RenderPipelines/
        Universal/
      GameScripts/
    pipeline/
      Assets/
        include/
          XCEngine/
            Pipeline/
              Assets/
        src/
      Shaders/
        include/
          XCEngine/
            Pipeline/
              Shaders/
        src/
      Preview/
        include/
          XCEngine/
            Pipeline/
              Preview/
        src/
      Baking/
        include/
          XCEngine/
            Pipeline/
              Baking/
        src/
      Build/
        include/
          XCEngine/
            Pipeline/
              Build/
        src/
      Cook/
        include/
          XCEngine/
            Pipeline/
              Cook/
        src/
      Packaging/
        include/
          XCEngine/
            Pipeline/
              Packaging/
        src/
    runtime/
      Asset/
        include/
          XCEngine/
            Core/
              Asset/
            Core/
              IO/
        src/
      Core/
        include/
          XCEngine/
            Core/
        src/
      Debug/
        include/
          XCEngine/
            Debug/
        src/
      Memory/
        include/
          XCEngine/
            Memory/
        src/
      Threading/
        include/
          XCEngine/
            Threading/
        src/
      Platform/
        include/
          XCEngine/
            Platform/
              Windows/
        src/
          Windows/
      Input/
        include/
          XCEngine/
            Input/
        src/
      Audio/
        include/
          XCEngine/
            Audio/
        src/
      Physics/
        include/
          XCEngine/
            Physics/
        src/
          PhysX/
      Scene/
        include/
          XCEngine/
            Scene/
            Components/
        src/
          Components/
      Resources/
        include/
          XCEngine/
            Resources/
        src/
      UI/
        include/
          XCEngine/
            UI/
              Core/
              Input/
              Layout/
              Runtime/
              Style/
              Text/
              Widgets/
        src/
          Core/
          Input/
          Layout/
          Runtime/
          Style/
          Text/
          Widgets/
      RHI/
        include/
          XCEngine/
            RHI/
        src/
      Rendering/
        include/
          XCEngine/
            Rendering/
              Builtin/
              Caches/
              Execution/
              Extraction/
              Features/
              FrameData/
              Graph/
              Materials/
              Passes/
              Pipelines/
              Planning/
              Shadow/
        src/
          Builtin/
          Caches/
          Execution/
          Extraction/
          Features/
          FrameData/
          Graph/
          Materials/
          Passes/
          Pipelines/
          Planning/
          Shadow/
      Scripting/
        include/
          XCEngine/
            Scripting/
        src/
    third_party/
    tools/
    CMakeLists.txt
  editor/
  project/
  tests/
  docs/
  tools/
  third_party/

说明：

runtime/Rendering/Pipelines 指运行时渲染管线，不等于顶层 engine/pipeline
engine/pipeline/Preview 指可无头调用的开发期预览能力
engine/pipeline/Baking 指可无头调用的开发期烘焙能力
桌面视口交互机制长期不进入顶层 engine/pipeline

5. 公共头路径

5.1 runtime

runtime 的公共头路径直接按领域暴露，不把 runtime 这一层写进 API 路径。

示例：

#include <XCEngine/Core/Asset/ResourceManager.h>
#include <XCEngine/Rendering/FrameData/RenderSceneData.h>
#include <XCEngine/Scene/Scene.h>
#include <XCEngine/Resources/Material/Material.h>
#include <XCEngine/Scripting/Mono/MonoScriptRuntime.h>

5.2 pipeline

pipeline 的公共头路径保留 Pipeline 总域，并按业务域暴露。

示例：

#include <XCEngine/Pipeline/Assets/AssetDatabase.h>
#include <XCEngine/Pipeline/Shaders/ShaderCompiler.h>
#include <XCEngine/Pipeline/Preview/ModelPreviewRenderer.h>
#include <XCEngine/Pipeline/Baking/LightingBakeService.h>

5.3 include 的意义

include/ 只表示模块公开头根目录。

代码里的 #include 不带 include 这一层。

6. 模块设计

6.1 runtime

runtime 按玩家运行时领域拆模块：

Asset
Core
Debug
Memory
Threading
Platform
Input
Audio
Physics
Scene
Resources
UI
RHI
Rendering
Scripting

其中 Rendering 是完整玩家运行时渲染模块，内部按子域组织：

Builtin
Caches
Execution
Extraction
Features
FrameData
Graph
Materials
Passes
Pipelines
Planning
Shadow

长期禁止继续把以下内容留在 runtime：

source import
source compile
离线 shader build
桌面 editor 视口交互专用 pass
ObjectId picking
gizmo handle 交互

6.2 pipeline

pipeline 按可无头调用的开发期能力域拆模块：

Assets
Shaders
Preview
Baking
Build
Cook
Packaging

这里的 pipeline 不再狭义限制为“离线内容管线”，但也不再承载桌面 editor 视口交互机制。

6.2.1 Assets

engine/pipeline/Assets 负责：

资产数据库
导入
源文件到 artifact 的转换
项目资产索引
项目资产服务

6.2.2 Shaders

engine/pipeline/Shaders 负责：

shader authoring 源文件解析
shader source 依赖收集
shader variant 展开
离线编译、transpile、build cache
shader artifact 生成

6.2.3 Preview

engine/pipeline/Preview 负责：

模型预览
材质预览
资源缩略图
离屏工具渲染

这类能力可以无头调用，因此属于 pipeline。

6.2.4 Baking

engine/pipeline/Baking 负责未来烘焙能力：

光照烘焙
其他离线场景烘焙

6.2.5 Build / Cook / Packaging

这几个域保持不变，仍属于可无头调用的开发期能力：

Build
Cook
Packaging

6.3 editor

editor 负责桌面产品逻辑和桌面交互机制。

editor 应保留：

当前工具模式
快捷键与命令路由
local/world 模式切换
undo / redo
scene selection 状态同步
outliner / inspector / viewport 的工作流联动
panel、workspace、windowing、shell
视口鼠标交互
视口拾取机制
gizmo handle 可视化与拖拽交互
grid / selection outline / selected helpers 这类 editor 视口辅助渲染

7. ObjectId 与 Gizmo 的最终边界

7.1 ObjectId

在当前最终定义下，ObjectId 不再属于 pipeline。

结论已经固定：

不放 runtime
不放 pipeline
放 editor

原因：

它不是玩家运行时能力
它也不是无头模式必须具备的能力
它是桌面视口交互机制的一部分

长期归属：

ObjectIdCodec
RenderObjectIdRegistry
BuiltinObjectIdPass
viewport picking readback
object-id shader 的 editor 视口消费链路

7.2 Gizmo

在当前最终定义下，Gizmo 也不再作为 pipeline 能力存在。

结论已经固定：

不放 runtime
不放 pipeline
放 editor

原因：

无头模式只需要通过 API 操作对象，不需要桌面 handle 拖拽机制
gizmo 的 handle render / pick / drag 属于 editor 视口交互

需要保留在 editor 的内容包括：

gizmo render
gizmo pick
gizmo drag solve
constraint
snap
mode 切换
W / E / R
local / world
pivot mode
选中对象同步
undo / redo

8. runtime 中仍待回收的 pipeline 内容

runtime 的物理目录虽然已经基本收口，但仍混有一批应属于 pipeline 的开发期职责。

8.1 应抽到 pipeline/Shaders

shader authoring 源文件解析
shader source 依赖收集
shader variant 展开与后端编译
SPIR-V / GLSL 等离线编译与编译缓存
shader artifact 生成

当前混入位置包括：

ShaderLoader 的 .shader authoring 路径
ShaderAuthoringLoader*
ShaderAuthoringParser*
ShaderRuntimeBuildUtils
ShaderCompilationCache
RHI/ShaderCompiler/SpirvShaderCompiler

8.2 应抽到 pipeline/Assets

UI document compile / validate / artifact write
mesh / model / gaussian splat 的 source importer
import-settings-driven 的 source conversion

当前混入位置包括：

UIDocumentCompiler
UIDocumentLoaders 的 source compile 分支
MeshLoader 中 Assimp 导入路径
AssimpModelImporter
GaussianSplatPlyImporter

8.3 应继续留在 editor，而不是进入 pipeline

以下内容不再视为 pipeline 回收对象，而应直接收口到 editor：

ObjectIdCodec
RenderObjectIdRegistry
BuiltinObjectIdPass
editor scene viewport 专用 render targets
ViewportObjectIdPicker
grid / selection outline / selected helpers 的底层 pass
gizmo 的底层 render / pick / solve

当前混入位置包括：

engine/runtime/Rendering/include/XCEngine/Rendering/Picking/*
engine/runtime/Rendering/include/XCEngine/Rendering/Passes/BuiltinObjectIdPass.h
engine/runtime/Rendering/src/Picking/*
engine/runtime/Rendering/src/Passes/BuiltinObjectIdPass*
editor/src/Product/Rendering/Viewport/ViewportRenderTargets*
editor/src/Product/Rendering/Viewport/ViewportRenderTargetUtils*
editor/src/Product/Rendering/Viewport/ViewportObjectIdPicker*
editor/src/Product/Rendering/Viewport/Passes/SceneViewportGridPass*
editor/src/Product/Rendering/Viewport/Passes/SceneViewportSelectionOutlinePass*
editor/src/Product/Rendering/Viewport/Passes/SceneViewportSelectedHelpersPass*
editor/src/Product/Features/Workspace/Scene/SceneViewportTransformGizmo*

8.4 应继续留在 runtime

runtime resource objects
纯 artifact reader / loader
artifact container / artifact schema
runtime RHI backend
runtime Rendering 的玩家渲染链
纯玩家运行时 UI / Rendering 消费路径

9. editor 中需要收口和回归的内容

当前 editor 里以下内容长期应该明确收口为 editor 领域，而不是再抽到 pipeline：

9.1 Viewport 渲染与交互能力

editor/src/Product/Rendering/Viewport/ViewportRenderTargets.*
editor/src/Product/Rendering/Viewport/ViewportRenderTargetUtils.*
editor/src/Product/Rendering/Viewport/ViewportObjectIdPicker.*
editor/src/Product/Rendering/Viewport/SceneViewportRenderPassBundle.*
editor/src/Product/Rendering/Viewport/Passes/SceneViewportGridPass.*
editor/src/Product/Rendering/Viewport/Passes/SceneViewportSelectionOutlinePass.*
editor/src/Product/Rendering/Viewport/Passes/SceneViewportSelectedHelpersPass.*

9.2 Gizmo 与桌面工具交互

editor/src/Product/Features/Workspace/Scene/SceneViewportTransformGizmo.*
editor/src/Product/Features/Workspace/Scene/SceneViewportTransformGizmoSupport.*
SceneViewportController
SceneViewportSession
SceneEditCommandRoute

9.3 产品工作流层

SceneViewportFeature
SceneViewportController
SceneViewportSession
SceneViewportToolOverlay
SceneViewportSceneOverlay

10. CMake 与 native lib 规划

10.1 基本规则

每个模块自己暴露自己的公开头与私有实现目录。

示例：

target_include_directories(XCRuntimeRendering
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/engine/runtime/Rendering/include
  PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/engine/runtime/Rendering/src
)

target_include_directories(XCPipelineAssets
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/engine/pipeline/Assets/include
  PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/engine/pipeline/Assets/src
)

10.2 长期 native libs

长期建议的 native libs：

XCRuntimeCore
XCRuntimeDebug
XCRuntimeMemory
XCRuntimeThreading
XCRuntimePlatform
XCRuntimeInput
XCRuntimeAudio
XCRuntimePhysics
XCRuntimeAsset
XCRuntimeResources
XCRuntimeScene
XCRuntimeScripting
XCRuntimeUI
XCRuntimeRHI
XCRuntimeRendering
XCPipelineAssets
XCPipelineShaders
XCPipelinePreview
XCPipelineBaking
XCPipelineBuild
XCPipelineCook
XCPipelinePackaging

10.3 当前已存在或半存在的产物

XCRuntimeAsset
XCPipelineAssets
XCEngineUI
XCEngineRenderingEditorSupport

长期调整方向：

XCEngineUI 收口到 XCRuntimeUI
XCEngineRenderingEditorSupport 保持 editor-support 语义，不再规划成 XCPipelineViewport
XCEngine 逐步退化为薄聚合 target，或者最终被显式模块依赖替代

10.4 依赖方向

长期依赖方向收敛为：

Core / Debug / Memory / Threading / Platform 作为底层
Input / Audio / Physics 作为中层运行时能力
Asset / Resources / Scene / Scripting / UI 作为系统层
RHI 作为渲染抽象层
Rendering 依赖 RHI + Scene + Resources
Pipeline 依赖 runtime
Editor 依赖 pipeline + runtime

明确约束：

保持 XCPipelineAssets -> XCRuntimeAsset
禁止 XCRuntime* -> XCPipeline*
避免把 Rendering 的子目录继续拆成大量碎小 libs

11. 执行优先级

P0：总 plan 收口与根残留清理

目标：

用本计划替代旧的 pipeline/Viewport 语义
清理 engine/CMakeLists.txt 中对已删除根目录 engine/include、engine/src 的历史引用
把总 plan 作为后续阶段唯一边界依据

验收：

XCEditor 编译通过
12 秒冒烟通过
提交并推送

P1：RHI 阶段闭环

目标：

完成 engine/runtime/RHI 的 CMake、依赖面与构建闭环
让 RHI 从目录迁移完成，进入真实 module 边界

状态：

已完成：XCRuntimeRHI 已建立，RHI backend / factory / screenshot / backend 第三方依赖已从 XCEngine 主 target 中拆出并完成独立构建闭环

验收：

XCEditor 编译通过
12 秒冒烟通过
提交并推送

P2：runtime -> pipeline 内容回收

这是当前最高优先级的结构阶段。

目标：

把 Shaders / UI / Model-Mesh-GaussianSplat 中仍混在 runtime 的开发期职责回收到 pipeline

执行顺序：

Shaders
UI
Model / Mesh / GaussianSplat

验收：

pipeline 可以独立完成 source -> artifact
runtime 默认路径不再隐式承担 source compile / source import
XCEditor 编译通过
12 秒冒烟通过
提交并推送

P3：editor-support 收口

目标：

把 ObjectId 相关能力彻底从 runtime 中抽出，收口为 editor-support
把 editor 视口专用 render targets、picking、grid、selection outline、selected helpers、gizmo 明确收口到 editor 语义

执行顺序：

ObjectIdCodec / RenderObjectIdRegistry / BuiltinObjectIdPass
ViewportRenderTargets / ViewportRenderTargetUtils / ViewportObjectIdPicker
SceneViewportGridPass / SceneViewportSelectionOutlinePass / SceneViewportSelectedHelpersPass
SceneViewportTransformGizmo / SceneViewportTransformGizmoSupport

验收：

runtime 不再承载 editor 视口交互机制
editor-support 语义明确
XCEditor 编译通过
12 秒冒烟通过
提交并推送

P4：native lib 收口

目标：

把当前仍集中在 XCEngine 中的实现逐步拆到长期 module / lib
让 XCEngine 退化为薄聚合 target

优先顺序：

XCRuntimeRHI
XCRuntimeUI
XCRuntimeRendering
XCPipelineShaders
其余 runtime / pipeline modules

验收：

每完成一个明确 module 拆分都重新编译 XCEditor
每完成一个明确 module 拆分都执行 12 秒冒烟
每完成一个明确 module 拆分都提交并推送

P5：尾部清理

目标：

删除确认废弃且不再被引用的残留
删除项目根目录 .dog 文件，但只能在整个计划彻底收口后执行

验收：

全量编译通过
12 秒冒烟通过
提交并推送

12. 当前状态

截至 2026-05-02：

engine/pipeline/Assets 已完成长期域名落地并通过编译 / 冒烟
engine/pipeline/、engine/managed/ 已完成根结构收口并通过编译 / 冒烟
engine/runtime 已完成真实根路径收口并通过编译 / 冒烟
engine/runtime/Asset 已完成 include|src 物理落地并通过编译 / 冒烟
engine/runtime/Core 已完成物理收口并通过编译 / 冒烟
engine/runtime/Debug 已完成物理收口并通过编译 / 冒烟
engine/runtime/Memory 已完成物理收口并通过编译 / 冒烟
engine/runtime/Threading 已完成物理收口并通过编译 / 冒烟
engine/runtime/Platform 已完成物理收口并通过编译 / 冒烟
engine/runtime/Input 已完成物理落地并通过编译 / 冒烟
engine/runtime/Audio 已完成物理落地并通过编译 / 冒烟
engine/runtime/Physics 已完成物理落地并通过编译 / 冒烟
engine/runtime/Scene 已完成物理落地并通过编译 / 冒烟
engine/runtime/Resources 已完成主要物理落地并通过编译 / 冒烟
engine/runtime/UI 已完成物理落地并通过编译 / 冒烟
engine/runtime/Scripting 已完成物理落地并通过编译 / 冒烟
engine/runtime/Rendering 已完成主要物理落地并通过编译 / 冒烟
engine/runtime/RHI 已完成真实 module / lib 收口，XCRuntimeRHI 已建立并通过编译 / 冒烟
engine/Shared 已完成删除，资产基础类型已并入 engine/runtime/Asset
根级 engine/include 与 engine/src 已不再作为物理代码目录存在，相关 CMake 历史引用也已清理
XCPipelineAssets -> XCRuntimeAsset 的单向依赖已经建立
ObjectId 相关底层能力仍暂时散落在 runtime/Rendering 与 XCEngineRenderingEditorSupport
editor 中仍有一批 viewport 交互与辅助渲染能力需要继续收口

13. 当前剩余工作

按优先级排序，当前剩余工作为：

继续执行 Shaders / UI / Model-Mesh-GaussianSplat 的 runtime -> pipeline 回收
把 ObjectId / gizmo / viewport helper passes 从 runtime 中抽出并收口到 editor-support
推进 native lib 总收口
全计划闭环后再删除根目录 .dog

14. 验收节奏

后续执行严格按下面节奏推进：

完成一个明确阶段
编译 XCEditor
运行 12 秒 editor smoke
通过后提交并推送
再进入下一阶段

这个节奏对所有后续阶段都生效。

22 KiB Raw Blame History Unescape Escape

XCEngine 目标架构总计划

1. 目标

2. 不可回退的规则

2.1 目录与命名规则

2.2 include 规则

2.3 模块边界规则

3. 顶层语义

3.1 runtime

3.2 pipeline

3.3 editor

3.4 三层组合关系

4. 长期目录

5. 公共头路径

5.1 runtime

5.2 pipeline

5.3 include 的意义

6. 模块设计

6.1 runtime

6.2 pipeline

6.2.1 Assets

6.2.2 Shaders

6.2.3 Preview

6.2.4 Baking

6.2.5 Build / Cook / Packaging

6.3 editor

7. ObjectId 与 Gizmo 的最终边界

7.1 ObjectId

7.2 Gizmo

8. runtime 中仍待回收的 pipeline 内容

8.1 应抽到 pipeline/Shaders

8.2 应抽到 pipeline/Assets

8.3 应继续留在 editor，而不是进入 pipeline

8.4 应继续留在 runtime

9. editor 中需要收口和回归的内容

9.1 Viewport 渲染与交互能力

9.2 Gizmo 与桌面工具交互

9.3 产品工作流层

10. CMake 与 native lib 规划

10.1 基本规则

10.2 长期 native libs

10.3 当前已存在或半存在的产物

10.4 依赖方向

11. 执行优先级

P0：总 plan 收口与根残留清理

P1：RHI 阶段闭环

P2：runtime -> pipeline 内容回收

P3：editor-support 收口

P4：native lib 收口

P5：尾部清理

12. 当前状态

13. 当前剩余工作

14. 验收节奏

22 KiB

Raw Blame History