# MetaCore 第一阶段 M1-M4 任务清单与验收标准 生成时间：2026-04-01 状态：草案 范围：第一阶段主干能力 读者：产品、架构、引擎、编辑器、工具链、测试 ## 目的 这份文档把 MetaCore 第一阶段后续工作收敛成 4 个主里程碑： - M1 项目与资源主干 - M2 模型、材质、场景制作闭环 - M3 Prefab 与 UI 基础 - M4 Player、打包、发布闭环 文档重点不是解释为什么这么分，而是直接给出： - 每个里程碑要做哪些任务 - 每个里程碑完成时如何验收 这份文档可直接作为： - 第一阶段执行总表 - 迭代排期基线 - 分工和验收对齐文档 ## 与其他文档的关系 - [metacore-engine-feature-baseline.md](D:/MetaCore/docs/designs/metacore-engine-feature-baseline.md)：定义引擎能力总版图 - [metacore-phase1-implementation-plan.md](D:/MetaCore/docs/designs/metacore-phase1-implementation-plan.md)：定义阶段性实施路线 - [metacore-m1-m2-detailed-task-breakdown.md](D:/MetaCore/docs/designs/metacore-m1-m2-detailed-task-breakdown.md)：已有的 M1-M2 细拆基础 - [metacore-phase1-foundation-checklist-and-acceptance-matrix.md](D:/MetaCore/docs/designs/metacore-phase1-foundation-checklist-and-acceptance-matrix.md)：第一阶段功能总清单 本文件是上述文档的执行版收敛结果。 ## 里程碑总览 ```text 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 完成。 --- ## 推荐执行顺序 ```text M1 项目与资源主干 -> M2 模型、材质、场景制作闭环 -> M3 Prefab 与 UI 基础 -> M4 Player、打包、发布闭环 ``` 里程碑之间允许少量交叉推进，但不应颠倒主依赖关系： - 没有 M1，不应大规模扩展资源类型 - 没有 M2，不应把重点转向复杂应用层 - 没有 M3，应用构建效率会明显不足 - 没有 M4，第一阶段不能算交付闭环 ## 建议的里程碑退出条件 ### M1 退出条件 - 项目和资源主干稳定 - 所有人都围绕统一项目目录与资源规则工作 ### M2 退出条件 - 内容团队能从导入模型开始搭一个基础场景 ### M3 退出条件 - 内容复用和基础 UI 能支撑真实样板应用 ### M4 退出条件 - 样板项目可以脱离开发环境独立运行并交付 ## 结论 MetaCore 第一阶段后续工作不应再以“零散能力补丁”的方式推进，而应围绕这 4 个里程碑持续收敛。 最重要的判断标准不是做了多少功能，而是下面这四条链是否依次成立： 1. 项目和资源进入引擎 2. 内容在引擎中可被制作 3. 内容和 UI 可被复用组织 4. 最终项目可被独立发布运行 只要这四条链成立，MetaCore 第一阶段的引擎主干就是健康的。