MetaCore/docs/designs/metacore-phase1-foundation-checklist-and-acceptance-matrix.md

MetaCore 第一阶段引擎基础功能总清单与验收矩阵

生成时间：2026-03-28
状态：草案
范围：第一阶段引擎基础主线

目的

这份文档用于把前面已经形成的多份设计文档，收敛成一份真正可执行的总表。

它要解决的问题很直接：

• 第一阶段到底有哪些基础功能块
• 哪些是 P0 / P1 / P2
• 每一项做到什么程度才算完成
• 每一项应该如何验收

这份文档不替代前面的专项设计，而是作为：

• 排期总表
• 阶段验收清单
• 团队对齐基线

使用方式

建议后续所有第一阶段推进，都以这份文档作为总入口：

• 想看为什么这样做：回到对应专项设计文档
• 想排开发顺序：看这里的优先级
• 想判断一项是否完成：看这里的 Definition of Done
• 想做测试和验收：看这里的“验证方式”

优先级定义

P0

第一阶段主线阻塞项。
不做完，MetaCore 还不能被视为“可用于开发项目的引擎”。

P1

紧随 P0 的高价值能力。
不一定是主线第一步，但缺了会明显影响生产力与交付质量。

P2

重要，但应建立在 P0/P1 成立之后。
典型是数字孪生增强、更多适配器、更多格式和更深能力。

总体完成标准

MetaCore 第一阶段只有在下面这句话成立时，才算真正完成：

开发者能够使用 MetaCore 完成一个 Windows 工业三维应用的项目创建、资源导入、场景搭建、材质与光照编辑、UI 配置、保存打开、打包交付，并在此基础上接入第一版 RuntimeData。

总清单与验收矩阵

1. 项目系统

优先级：P0

范围

• 项目创建/打开
• MetaCore.project.json
• 项目目录结构
• 启动场景
• Editor / Player 围绕项目工作

Definition of Done

• 能稳定定位项目根目录
• MetaCore.project.json 能被一致读取和保存
• 启动场景行为在 Editor 和 Player 中一致
• 样板项目目录结构固定可理解

验收方式

• 从不同工作目录启动仍能正确打开项目
• 修改启动场景后保存，再次打开结果一致
• 坏项目描述文件能给出明确报错

相关文档

• metacore-product-plan.md
• metacore-phase1-implementation-plan.md
• metacore-m1-m2-detailed-task-breakdown.md

2. 资源数据库与导入循环

优先级：P0

范围

• 资产元数据
• Asset Database
• Import Pipeline
• Reimport
• Package 基础

Definition of Done

• 导入后的资源进入 Asset Database
• 每个资源有稳定 GUID
• 资源能在 Project 面板中出现
• 资源能被重新导入而不破坏基础引用

验收方式

• 导入一个模型后能在资源列表中找到
• 删除/修改源文件时系统给出明确反馈
• 重导入后场景引用尽量保持稳定

相关文档

• metacore-m1-m2-detailed-task-breakdown.md
• metacore-project-panel-asset-browser-design.md

3. glTF/.glb 首批导入器

优先级：P0

范围

• .glb
• .gltf + 外部资源
• 节点层级
• 材质抽取
• 贴图抽取
• 导入结果文档

Definition of Done

• 导入一个 glTF/.glb 文件后，生成正式 Mesh / Material / Texture 资产
• 保留节点层级描述
• 可将模型资源拖入场景生成对象树
• 重导入默认尽量保持 GUID 稳定

验收方式

• 单网格、单材质样例导入成功
• 多材质、多层级样例导入成功
• 场景保存重开后模型实例仍有效

相关文档

• metacore-gltf-glb-importer-design.md

4. Project 面板与资源浏览

优先级：P0

范围

• 目录浏览
• 资源列表
• 资源详情 Inspector
• 资源拖拽
• 刷新 / 重导入 / 定位

Definition of Done

• 用户能看见项目资源结构
• 资源选择与 Inspector 联动
• 模型资源可拖入场景
• 材质资源可拖到对象材质槽
• 支持刷新和单资源重导入

验收方式

• 导入资源后在 Project 面板中可见
• 资源拖拽后场景对象或材质槽正确变化
• 重导入后面板内容与资源状态同步

相关文档

• metacore-project-panel-asset-browser-design.md

5. 场景编辑与层级工作流

优先级：P0

范围

• Hierarchy
• 创建 / 删除 / 复制 / 重命名
• 父子级
• 拖拽重挂接
• 多选
• 模型资源拖入场景

Definition of Done

• 用户能创建空对象和内置对象
• 模型资源拖入场景后生成对象树
• 支持复制、删除、重挂接、多选
• 层级保存/重开一致

验收方式

• 复杂对象树可以被正确组织
• 删除和复制对子树行为正确
• 重挂接后局部/世界变换行为符合约定

相关文档

• metacore-scene-hierarchy-workflow-design.md

6. Transform 与 Gizmo 工作流

优先级：P0

范围

• Move
• Rotate
• Scale
• Inspector 中 Position / Rotation / Scale
• Scene View 基础 Gizmo

Definition of Done

• 用户能在 Inspector 和视口中编辑 Transform
• 层级关系下局部变换与世界结果正确
• 多选基础编辑成立

验收方式

• 多对象摆放工作流顺畅
• 父对象移动后子对象行为正确
• 保存并重开后 Transform 一致

相关文档

• metacore-scene-hierarchy-workflow-design.md

7. 材质系统与 MeshRenderer 资源化

优先级：P0

范围

• Material Asset
• Mesh Asset
• Texture Asset 基础元信息
• MeshRenderer 从内嵌颜色演进到资源引用

Definition of Done

• Scene 中对象可以引用 Mesh Asset 和 Material Asset
• 材质资源具备第一阶段最小 PBR 字段
• MeshRenderer 不再只依赖 BuiltinMesh
• Scene / Prefab 保存的是资源引用

验收方式

• 导入模型后，材质资源可见且可被对象引用
• 更换材质资源后，运行时渲染结果变化正确
• 保存和重开后资源引用不丢失

相关文档

• metacore-material-render-pipeline-selection.md
• metacore-material-import-integration-design.md
• metacore-material-meshrenderer-data-structure-design.md

8. 基础 PBR 材质与光照

优先级：P0

范围

• 基于 panda3d-simplepbr 的第一版 PBR 后端
• Directional / Point / Spot Light
• 基础阴影或稳定照明
• 编辑器和 Player 尽量一致

Definition of Done

• 基础 PBR 材质在 Editor / Player 中可见
• 灯光可编辑且结果稳定
• simplepbr 只作为后端，不反向绑定材质资源结构

验收方式

• 导入模型的基础 PBR 参数能被正确显示
• 灯光颜色/强度调整结果可见
• 编辑器和 Player 画面不存在明显语义不一致

相关文档

• metacore-material-render-pipeline-selection.md

9. 场景保存与打开

优先级：P0

范围

• Scene 新建
• 保存
• 另存
• 打开
• 启动场景

Definition of Done

• Scene 中的层级、组件、资源引用都能稳定保存
• Scene 能被重新打开并恢复一致状态
• 启动场景机制稳定

验收方式

• 编辑场景后保存并关闭，再打开结果一致
• 改名或移动场景后，项目引用策略清晰

相关文档

• metacore-phase1-implementation-plan.md
• metacore-packaging-runtime-delivery-design.md

10. UI 编辑与运行时 UI

优先级：P1

范围

• UiDocument
• UiNode
• Panel / Text / Image / Button
• UI 层级树
• UI Inspector
• Player 运行时显示

Definition of Done

• 用户能创建和保存 UI 文档
• 用户能编辑基础 UI 节点与层级
• Scene 或项目可引用 UI 资源
• Player 能显示 UI

验收方式

• 典型数字孪生界面可完成基础搭建
• 保存并重开 UI 文档后结构一致
• 打包后 UI 能正常显示

相关文档

• metacore-ui-workflow-design.md

11. 打包与交付运行时

优先级：P0

范围

• Cook
• 打包输出目录
• 运行时项目描述
• Player 交付态加载
• clean machine 验证

Definition of Done

• 能从项目生成独立 Windows 输出目录
• 输出目录包含 Player 和项目必需内容
• Player 不依赖 Editor 即可运行
• 启动场景、资源、UI、runtime 配置可正确加载

验收方式

• 在独立目录启动打包产物成功
• clean machine 或近似隔离环境验证通过
• 缺失关键内容时给出明确日志

相关文档

• metacore-packaging-runtime-delivery-design.md

12. Prefab 基础复用

优先级：P1

范围

• 从对象树创建 Prefab
• Prefab 实例化
• 应用 / 还原基础行为

Definition of Done

• 可以将重复对象树提取为 Prefab
• Scene 中实例可复用资源和层级
• 对基础修改可以应用和还原

验收方式

• 重复设备对象可被抽成 Prefab 并实例化
• 保存重开后 Prefab 实例关系仍然可识别

相关文档

• metacore-phase1-implementation-plan.md

13. RuntimeData 数字孪生集成

优先级：P2

范围

• source / point / binding
• adapter
• runtime diagnostics
• Editor 侧配置

Definition of Done

• 打包后的运行时可接入至少一种 live source
• 数据变化能驱动场景或 UI 的第一批目标
• 故障、断连、损坏配置可见

验收方式

• mock / file_replay / tcp 至少一条真实链路可运行
• binding 故障不会导致运行时崩溃
• diagnostics 可定位问题

相关文档

• metacore-runtime-data-access-design.md
• metacore-runtime-data-usage.md

当前建议执行顺序

按这份总表，推荐的第一阶段主路径应是：

项目系统
  -> 资源数据库与 glTF/glb 导入
    -> Project 面板
      -> 场景编辑与层级
        -> Transform/Gizmo
          -> 材质资源化与基础 PBR
            -> 场景保存/打开
              -> UI 工作流
                -> 打包与交付运行时
                  -> RuntimeData 集成

当前不应抢占主线的内容

这些内容都重要，但当前不应抢占上面的主路径：

• 更多 live adapter
• 更复杂工业协议
• VR/XR 训练工作流
• B/S 产品化
• AI 辅助能力
• 更完整的后处理和高级渲染 feature

验收建议

后续每完成一个功能域，建议都按下面四步做验收：

1. 对照本表检查 Definition of Done
2. 对照专项设计文档确认没有走偏
3. 补对应 smoke / integration tests
4. 用样板项目做一次真实工作流回归

最终建议

第一阶段不要再被零散功能牵着走，而应按这份总表推进。

最关键的判断只有一个：

MetaCore 第一阶段不是“做出很多点状能力”，而是把一条完整的引擎基础生产力链做通。

只有这条链做通之后，数字孪生、VR、国产化适配和后续商业化方向才会真正站得住。