MetaCore/docs/designs/metacore-current-architecture.md

MetaCore 当前架构与技术路线

更新时间：2026-05-20 状态：当前主线说明 读者：产品、架构、引擎、编辑器、渲染、工具链、交付

一句话定位

MetaCore 是一个以 EnTT ECS 为底层架构、Filament 为现代渲染核心、ImGui 为编辑器界面、RmlUi 为运行时 UI 的轻量级 Unity / Unreal Engine 对标型 3D 引擎与编辑器，采用编辑期 JSON、发布期二进制 Cook 的敏捷迭代路线，面向工业仿真、数字孪生、实时可视化和跨平台运行时交付。

当前技术选型

能力域	当前选择	定位
底层架构	EnTT	ECS 数据层，承载实体、组件和场景状态
编辑器对象语义	GameObject + Component	面向编辑器和用户工作流的 ECS 封装
编辑器 UI	Dear ImGui Docking	快速构建工具面板、Inspector、Hierarchy、Project、Console
3D 操控	ImGuizmo	编辑器视口中的移动、旋转、缩放工具
渲染核心	Google Filament	PBR、材质、灯光、glTF、跨图形 API 渲染后端
模型导入	glTF / GLB / gltfio	当前模型导入主线，后续扩展其他格式
运行时 UI	RmlUi	项目正式 UI，定位类似 Unity UGUI
编辑期资产	JSON / mcmeta / 可读项目文件	快速迭代、可 diff、可调试、可人工修复
发布期资产	Cooked binary / package	面向运行时性能、封装和交付稳定性
RuntimeData	TCP / 文件回放 / 数据绑定	外部仿真、遥测、业务数据驱动场景组件

渲染路线

MetaCore 已经从 Panda3D 迁移到 Filament 主线。Panda3D 相关代码只应被视为历史兼容层或待清理实现，不再作为新增能力的扩展方向。

Filament 作为主渲染核心，承担：

• PBR 材质与光照。
• glTF / GLB 加载与资源解释。
• 编辑器视口离屏渲染。
• 运行时 Player 场景渲染。
• Vulkan、OpenGL、DirectX 12、WebGPU 等后端能力的长期承接。

优先级建议：

1. Vulkan：首选高性能现代图形 API。
2. OpenGL：兼容和过渡。
3. DirectX 12：Windows 高性能运行时。
4. WebGPU：B/S 架构、浏览器嵌入和 Web 交付。

UI 路线

MetaCore 明确区分两套 UI：

编辑器 UI

编辑器 UI 使用 Dear ImGui。它服务于工具工作流：

• Hierarchy
• Scene
• Inspector
• Project
• Console
• RuntimeData 面板
• 导入、Cook、诊断等工具窗口

ImGui 不承担最终项目运行时 UI 的长期职责。

运行时 UI

运行时 UI 使用 RmlUi。它服务于项目交付：

• 标题栏、侧边栏、设备信息面板。
• 状态文本、告警提示、按钮、图片和图标。
• 与场景对象、RuntimeData 和业务状态绑定。
• 后续在编辑器中提供可视化编辑，再由 RmlUi 在 Player 中渲染。

这条路线类似 Unity 中“编辑器工具 UI”和“UGUI 项目 UI”的分工。

资产与序列化路线

当前阶段采用双阶段资产策略：

编辑期

编辑器阶段优先使用 JSON 和可读元数据：

• MetaCore.project.json
• .mcscene.json 或可读场景文档
• .mcmeta
• JSON 化材质、UI、导入描述和资源记录

目标是：

• 快速迭代。
• 便于 diff 和代码评审。
• 便于调试和人工修复。
• 降低早期功能演进的成本。

发布期

打包阶段再生成二进制运行时资产：

• cooked scene
• cooked mesh / material / texture
• runtime config
• CookManifest
• 可交付 Player 包

目标是：

• 提高加载性能。
• 减少运行时解析成本。
• 封装交付内容。
• 支持 C/S 和未来 B/S 发布形态。

平台与交付目标

编辑器平台

编辑器优先面向：

• Windows
• Linux
• 统信 UOS
• 麒麟 OS

第一阶段可以 Windows 先行，但平台抽象必须为国产化桌面环境保留边界。

运行时交付

运行时面向两种架构：

• C/S：第一阶段主要承诺，适合桌面端工业仿真、数字孪生、大屏和本地部署。
• B/S：后续产品化方向，适合 WebGPU、浏览器嵌入、第三方业务系统集成。

行业对标

MetaCore 对标 Unity 和 Unreal Engine，但不是第一阶段复制它们的全部功能广度。

对标 Unity：

• GameObject / Component 工作流。
• Scene / Hierarchy / Inspector / Project。
• Prefab。
• UGUI 类运行时 UI。
• 资产导入与可视化编辑体验。

对标 Unreal Engine：

• 高质量渲染目标。
• 材质和资源工程化。
• 大型项目交付、Cook、Package、运行时边界。

MetaCore 的差异化方向：

• 更轻量。
• 更容易国产化适配。
• 更适合工业仿真、数字孪生和业务系统嵌入。
• 更强调编辑期可读、运行期可交付的资产闭环。

开发方法

MetaCore 当前采用敏捷开发、快速迭代的方式：

• 先打通主链路，再逐步工程化。
• 先让编辑器可用，再逐步完善运行时性能。
• 先建立 JSON 可读资产闭环，再收敛 Cook 二进制发布链路。
• 先服务真实交付场景，再扩展通用引擎能力。

第一阶段的核心不是一次性做完整引擎，而是快速形成：

创建项目
  -> 导入模型
    -> 编辑场景
      -> 配置材质 / UI / 数据绑定
        -> 保存 JSON 编辑期资产
          -> Cook 运行时资产
            -> Player 运行
              -> 交付 C/S 应用

当前约束

• 新渲染能力默认走 Filament，不再沿 Panda3D 扩展。
• 编辑器工具 UI 默认走 ImGui。
• 项目运行时 UI 默认走 RmlUi。
• 模型导入优先完善 glTF / GLB / gltfio 闭环。
• 资产格式优先保证编辑期 JSON 可读性，再进入发布期二进制优化。
• 测试应区分“编辑期 JSON 资产链路”和“发布期 Cook 二进制链路”，避免用二进制产物是否存在来阻塞早期编辑器迭代。