MetaCore/docs/designs/metacore-phase1-m1-m4-tasklist-and-acceptance.md

MetaCore 第一阶段 M1-M4 任务清单与验收标准

生成时间：2026-04-01
状态：草案
范围：第一阶段主干能力
读者：产品、架构、引擎、编辑器、工具链、测试

目的

这份文档把 MetaCore 第一阶段后续工作收敛成 4 个主里程碑：

• M1 项目与资源主干
• M2 模型、材质、场景制作闭环
• M3 Prefab 与 UI 基础
• M4 Player、打包、发布闭环

文档重点不是解释为什么这么分，而是直接给出：

• 每个里程碑要做哪些任务
• 每个里程碑完成时如何验收

这份文档可直接作为：

• 第一阶段执行总表
• 迭代排期基线
• 分工和验收对齐文档

与其他文档的关系

• metacore-engine-feature-baseline.md：定义引擎能力总版图
• metacore-phase1-implementation-plan.md：定义阶段性实施路线
• metacore-m1-m2-detailed-task-breakdown.md：已有的 M1-M2 细拆基础
• metacore-phase1-foundation-checklist-and-acceptance-matrix.md：第一阶段功能总清单

本文件是上述文档的执行版收敛结果。

里程碑总览

M1 项目与资源主干
  -> M2 模型、材质、场景制作闭环
    -> M3 Prefab 与 UI 基础
      -> M4 Player、打包、发布闭环

总体验收口径

第一阶段主干完成时，应满足下面这句话：

开发者可以基于一个正式项目，导入资源、组织场景、指派材质、复用 Prefab、编辑基础 UI，并最终打包出一个可独立运行的 Windows Player。

---

M1 项目与资源主干

目标

把 MetaCore 从“可以打开编辑器窗口”推进到“围绕项目和资源工作的引擎工具”。

任务清单

M1-A 项目创建与打开

• 定义标准项目目录结构
• 明确 MetaCore.project.json 的最小字段集合
• 实现项目创建流程
• 实现项目打开流程
• 明确样板项目与正式项目的边界

M1-B 项目路径与定位逻辑统一

• 统一 Editor / Player / Tool 的项目根定位逻辑
• 统一 startup scene 定位逻辑
• 统一 Runtime / Ui / Build 目录解析逻辑
• 统一命令行传项目路径的优先级规则

M1-C 项目描述文件读写稳定化

• 统一项目描述文件读写入口
• 明确字段缺失和坏格式报错
• 明确向后兼容策略
• 保证保存后再次读取结果一致

M1-D Project 面板基础资源浏览

• 显示项目目录树
• 显示资源列表
• 显示资源类型
• 能定位 Scene / Prefab / 资产文件
• 资源选择与 Inspector 联动

M1-E 资源数据库主干

• Asset Database 初始化流程稳定化
• GUID / meta / package 记录统一
• 相对路径与资源记录查询稳定化
• 刷新与扫描行为统一

M1-F 资源导入基础闭环

• 文件进入项目后进入 Asset Database
• 生成 .mcmeta
• 生成 .mcasset 或等价 package
• 在 Project 面板里可见
• 导入错误写入 Console

M1-G 资源重命名、移动、刷新基础行为

• 明确资源移动后的处理规则
• 明确资源重命名后的处理规则
• 明确刷新触发与重新扫描行为
• 保证基本引用不被无故打断

M1-H M1 测试与样板项目回归

• 项目创建/打开测试
• 项目描述文件读写测试
• 项目路径解析测试
• startup scene 读取测试
• Asset Database 初始化与刷新测试
• 样板项目回归测试

M1 验收标准

功能验收

• 用户可以创建并打开一个 MetaCore 项目
• Editor 和 Player 能围绕同一个项目根目录工作
• Project 面板能稳定显示项目资源
• 新加入的资源会进入 Asset Database
• meta / GUID / package 记录稳定生成

行为验收

• 从不同当前工作目录启动项目，结果一致
• MetaCore.project.json 保存后再打开，结果一致
• startup scene 缺失或损坏时，有明确错误和降级行为
• 资源刷新后，Project 面板状态与 Asset Database 一致

测试验收

• M1 对应 smoke / integration tests 全部通过
• 样板项目可在 Editor 中正常打开

M1 完成定义

当“项目入口 + 资源进入项目 + 资源在编辑器中可见”这条链成立时，M1 完成。

---

M2 模型、材质、场景制作闭环

目标

把 MetaCore 从“有项目和资源骨架”推进到“可以真实搭建 3D 场景”。

任务清单

M2-A 首批模型导入器定型

• 第一正式支持格式定为 glTF/.glb
• 明确 FBX 与 OBJ 的阶段位置
• 明确导入器接口边界
• 区分“识别格式”和“正式支持”

M2-B 模型资源数据结构

• 定义模型资产与源文件关系
• 定义 Mesh / Material / Texture 导入产物关系
• 定义模型节点层级存储方式
• 明确场景引用模型资产而非原始路径

M2-C glTF/.glb 最小生产闭环

• 导入 glTF/.glb
• 生成模型资产记录
• 生成 Mesh / Material / Texture 相关资源
• Project 面板可见
• 可实例化到场景

M2-D 导入归一化

• 保留节点层级
• 处理坐标系转换
• 处理缩放归一化
• 处理材质槽映射
• 明确空节点保留策略

M2-E Scene 层级工作流增强

• 模型拖入场景生成对象树
• 支持创建 / 删除 / 复制 / 重命名
• 支持父子级拖拽重挂接
• 支持多选和基础批量操作

M2-F Transform / Gizmo 打磨

• Move / Rotate / Scale 完整化
• Inspector 与 Scene View 操作一致
• 聚焦对象、相机围绕、基础吸附
• 局部/世界坐标模式清晰

M2-G 材质资源化

• Material 资源成为一等资源
• MeshRenderer 引用资源而非只依赖内嵌字段
• 纹理槽与基础 PBR 参数可编辑
• 材质可复用

M2-H 基础光照工作流

• Directional / Point / Spot Light 基础可用
• 灯光颜色、强度可编辑
• Editor / Player 结果尽量一致
• 保证基础照明不成为内容生产阻塞

M2-I 场景保存/打开稳定化

• 保存 Scene 中的层级、Transform、组件和资源引用
• 打开 Scene 时恢复一致状态
• 另存为与启动场景更新规则清晰

M2-J 重导入与引用保持

• 基于源变化触发重导入
• 重导入后尽量保持 GUID 稳定
• 场景中的模型/材质引用不被无故打断

M2-K M2 测试与样板场景回归

• 模型导入测试
• 模型实例化场景测试
• Scene 保存/重开测试
• 材质引用测试
• 重导入引用稳定性测试
• 样板场景制作回归

M2 验收标准

功能验收

• 用户可以导入至少一种正式支持的模型格式
• 模型资源可以放入场景并形成对象层级
• 用户可以编辑 Transform、材质和灯光
• 场景可以保存并重新打开
• 重导入后核心资源引用保持稳定

行为验收

• 单模型、分层模型、多材质模型都能完成基础闭环
• Scene 层级操作符合直觉
• 材质替换后渲染结果稳定变化
• 保存后重开，不依赖硬编码 demo 对象

测试验收

• M2 对应 smoke / integration tests 全部通过
• 至少一个正式样板场景可以从导入资源开始完整搭建

M2 完成定义

当“导入模型 -> 放入场景 -> 编辑材质与变换 -> 保存并重开”这条链成立时，M2 完成。

---

M3 Prefab 与 UI 基础

目标

把 MetaCore 从“能做静态场景”推进到“能做可复用内容和基础应用界面”。

任务清单

M3-A Prefab 基础工作流

• 从对象树创建 Prefab
• 从 Prefab 生成实例
• 建立 Prefab 与实例关系
• 保存 Prefab 资源

M3-B Prefab Apply / Revert

• 支持实例修改记录
• 支持基础 Apply
• 支持基础 Revert
• 保证保存和重开后仍可识别 Prefab 关系

M3-C Prefab 编辑器体验

• Project 面板识别 Prefab
• Inspector 显示 Prefab 来源
• Scene 中实例操作规则清晰
• 为后续 nested prefab/variant 预留结构

M3-D UI 文档与资源工作流

• 明确 UiDocument 作为正式资源
• Project 面板可创建/打开 UI 资源
• UI 文档保存/加载稳定

M3-E UI 节点与控件基础

• Panel
• Text
• Image
• Button
• UI 节点层级
• 基础属性编辑

M3-F UI 编辑器第一版

• UI 层级树
• UI Inspector
• 创建节点
• 删除节点
• 调整基础布局参数

M3-G UI 运行时渲染基础

• Player 可加载 UI 资源
• UI 能显示在运行时
• 分辨率变化下保持基础可用

M3-H UI 与项目/场景引用关系

• Scene 或项目可以引用 UI 资源
• 启动时能加载默认 UI
• 资源引用保存和重开不丢失

M3-I M3 测试与样板回归

• Prefab 创建/实例化测试
• Prefab Apply / Revert 测试
• UI 文档保存/重开测试
• Player UI 显示测试
• 样板项目 UI 回归

M3 验收标准

功能验收

• 用户可以把重复对象树提取为 Prefab 并实例化
• Prefab 的基础 Apply / Revert 可用
• 用户可以创建和编辑 UI 文档
• Player 可以显示基础 UI

行为验收

• 重复对象不再依赖手工复制粘贴维护
• UI 文档在保存和重开后保持一致
• Prefab 实例在场景里仍然是可识别、可管理的

测试验收

• M3 对应 smoke / integration tests 全部通过
• 样板项目中至少有一组 Prefab 和一套基础 UI 跑通

M3 完成定义

当“可复用对象模板 + 可编辑基础 UI”两条链都成立时，M3 完成。

---

M4 Player、打包、发布闭环

目标

把 MetaCore 从“编辑器里能工作”推进到“产物可以独立交付和运行”。

任务清单

M4-A Player 启动链稳定化

• Player 项目根解析统一
• 启动场景加载稳定
• 资源路径解析稳定
• UI 资源和运行时配置加载统一

M4-B Cook 与构建输出规范

• 明确构建输出目录结构
• 明确 Player 产物、资源产物、配置产物摆放规则
• 统一 cook 输出命名和路径约定

M4-C 打包流程固定化

• 从项目生成独立输出目录
• 包含场景、资源、UI、运行时配置
• 明确失败时的诊断输出

M4-D 发布目录与移交规范

• 定义可交付目录结构
• 定义最小运行所需内容
• 定义缺失关键文件时的报错规则

M4-E clean machine 验证

• 在隔离环境中运行打包产物
• 验证不依赖 Editor
• 验证不依赖源工程目录

M4-F 运行时日志与诊断

• 启动日志
• 资源缺失日志
• Scene / UI / Runtime 配置加载错误日志
• 核心失败路径可定位

M4-G 发布回归测试

• 打包输出检查测试
• Player 独立运行测试
• clean machine 或近似隔离验证
• 样板项目发布回归

M4 验收标准

功能验收

• 用户可以从正式项目生成独立 Windows 输出目录
• 输出目录包含运行所需的最小内容
• Player 在脱离 Editor 的情况下可启动并运行项目

行为验收

• 启动场景、模型、材质、UI 都能在打包产物中正确加载
• 缺少关键内容时，Player 有明确日志
• 打包目录结构清晰，可移交给交付团队

测试验收

• M4 对应打包和发布回归全部通过
• 样板项目可以成功打包并在独立目录运行

M4 完成定义

当“编辑器里的项目内容可以被打包成独立 Player 并脱离工程运行”这条链成立时，M4 完成。

---

推荐执行顺序

M1 项目与资源主干
  -> M2 模型、材质、场景制作闭环
    -> M3 Prefab 与 UI 基础
      -> M4 Player、打包、发布闭环

里程碑之间允许少量交叉推进，但不应颠倒主依赖关系：

• 没有 M1，不应大规模扩展资源类型
• 没有 M2，不应把重点转向复杂应用层
• 没有 M3，应用构建效率会明显不足
• 没有 M4，第一阶段不能算交付闭环

建议的里程碑退出条件

M1 退出条件

• 项目和资源主干稳定
• 所有人都围绕统一项目目录与资源规则工作

M2 退出条件

• 内容团队能从导入模型开始搭一个基础场景

M3 退出条件

• 内容复用和基础 UI 能支撑真实样板应用

M4 退出条件

• 样板项目可以脱离开发环境独立运行并交付

结论

MetaCore 第一阶段后续工作不应再以“零散能力补丁”的方式推进，而应围绕这 4 个里程碑持续收敛。

最重要的判断标准不是做了多少功能，而是下面这四条链是否依次成立：

1. 项目和资源进入引擎
2. 内容在引擎中可被制作
3. 内容和 UI 可被复用组织
4. 最终项目可被独立发布运行

只要这四条链成立，MetaCore 第一阶段的引擎主干就是健康的。