# MetaCore 模型工作流 P0 任务卡

生成时间：2026-04-11  
状态：执行稿  
范围：Project 面板、资源拖拽、模型资源 Inspector、材质槽编辑、材质资源 Inspector

## 目的

这份文档把 [metacore-model-workflow-roadmap-vs-unity-ue.md](D:/MetaCore/docs/designs/metacore-model-workflow-roadmap-vs-unity-ue.md) 里的 `P0` 项，进一步拆成可直接进入实现的任务卡。

目标不是列愿望清单，而是把最小可用模型工作流落成：

```text
模型导入
  -> Project 面板中可见
    -> 选中后可查看信息
      -> 可拖入 Scene / Hierarchy
        -> 可在对象 Inspector 中调整资源引用
          -> 可编辑材质资源
```

## P0 总目标

当下面这几项都完成时，MetaCore 才算真正跨过“有模型导入能力”和“有模型编辑器工作流”之间的门槛：

- 有最小可用 `Project` 面板
- 模型 / Prefab / 材质可从资源面板拖拽
- 模型资源有最小 Inspector
- 对象可编辑材质槽引用
- 材质资源可编辑基础参数

---

## Task Card 01：Project 面板最小版

### 目标

做出一个真正能承载模型资源工作流的 `Project` 面板最小版，而不是只显示文件名。

### 用户结果

用户可以：

- 浏览 `Assets / Scenes / Runtime`
- 查看当前目录下资源
- 选中资源
- 看到资源类型
- 触发基础动作

### 建议代码落点

- [MetaCoreBuiltinEditorModule.cpp](/D:/MetaCore/Source/MetaCoreEditor/Private/MetaCoreBuiltinEditorModule.cpp)
- [MetaCoreEditorContext.h](/D:/MetaCore/Source/MetaCoreEditor/Public/MetaCoreEditor/MetaCoreEditorContext.h)
- [MetaCoreEditorServices.h](/D:/MetaCore/Source/MetaCoreEditor/Public/MetaCoreEditor/MetaCoreEditorServices.h)

### 需要的数据来源

- `MetaCoreIAssetDatabaseService::GetDirectoriesUnder(...)`
- `MetaCoreIAssetDatabaseService::GetAssetsUnder(...)`
- `MetaCoreIAssetDatabaseService::FindAssetByRelativePath(...)`

### 最小交互

- 左侧目录树
- 右侧资源列表
- 单击选中资源
- 资源项显示：
  - 名称
  - 类型
  - 来源类型（可选）

### 最小动作

- Refresh
- Reimport
- Create Folder
- Copy Relative Path

### UI 行为约束

- 目录树不显示 `Library` 作为主工作目录
- 资源列表默认按当前目录显示
- 场景、Prefab、模型、材质、纹理至少区分基础类型标签

### 验收标准

- 导入一个 `.gltf/.glb` 后，用户能在 `Project` 面板中找到对应资源
- 资源列表中能看见类型
- 选中资源后，Inspector 有响应
- 点击 Refresh 后资源列表更新
- 对单个资源执行 Reimport 后资源记录刷新

### 测试点

- 空目录显示
- 多层目录切换
- 导入后刷新
- 同目录多类型资源混合显示

---

## Task Card 02：模型 / Prefab 拖拽到 Scene / Hierarchy

### 目标

把当前已有的后端实例化服务，变成真正的编辑器拖拽工作流。

### 用户结果

用户可以：

- 从 `Project` 面板把模型拖进 `Scene`
- 从 `Project` 面板把模型拖进 `Hierarchy`
- 从 `Project` 面板把 Prefab 拖进场景

### 建议代码落点

- [MetaCoreBuiltinEditorModule.cpp](/D:/MetaCore/Source/MetaCoreEditor/Private/MetaCoreBuiltinEditorModule.cpp)
- [MetaCoreBuiltinCoreServicesModule.cpp](/D:/MetaCore/Source/MetaCoreEditor/Private/MetaCoreBuiltinCoreServicesModule.cpp)
- [MetaCoreEditorContext.h](/D:/MetaCore/Source/MetaCoreEditor/Public/MetaCoreEditor/MetaCoreEditorContext.h)

### 依赖服务

- `MetaCoreISceneEditingService::InstantiateModelAsset(...)`
- `MetaCoreIPrefabService::InstantiatePrefab(...)`

### 拖拽规则

#### 模型资源 -> Scene

结果：

- 根据模型节点文档实例化 `GameObject` 树
- 默认挂到根或当前活动对象之下

#### 模型资源 -> Hierarchy 节点

结果：

- 以目标节点为父对象实例化模型树

#### Prefab -> Scene / Hierarchy

结果：

- 实例化 Prefab

### 最小 UI 行为

- 拖拽开始时显示资源名提示
- 允许 Scene 区域接收 drop
- 允许 Hierarchy 节点接收 drop
- drop 成功后自动选中新创建根对象

### 暂不要求

- 精确 3D 落点
- 复杂 hover preview
- 材质拖到具体 submesh

### 验收标准

- 模型拖到 Scene 后生成对象树
- 模型拖到 Hierarchy 某节点后，生成对象树并挂到目标父节点
- Prefab 拖入场景后成功实例化
- 创建后的根对象自动选中

### 测试点

- 单节点模型
- 多节点模型
- Hierarchy 拖到根
- Hierarchy 拖到已有对象
- Prefab 拖拽

---

## Task Card 03：模型资源 Inspector 最小版

### 目标

让“选中模型资源”这件事真正有信息价值，而不是只有一条路径。

### 用户结果

用户在 `Project` 面板中选中模型资源后，可以看到：

- 源文件路径
- 导入器
- 模型格式
- Mesh / Material / Texture / Node 数量
- 基本结构摘要

### 建议代码落点

- [MetaCoreBuiltinEditorModule.cpp](/D:/MetaCore/Source/MetaCoreEditor/Private/MetaCoreBuiltinEditorModule.cpp)
- [MetaCoreAssetTypes.h](/D:/MetaCore/Source/MetaCoreFoundation/Public/MetaCoreFoundation/MetaCoreAssetTypes.h)
- [MetaCoreEditorAssetTypes.h](/D:/MetaCore/Source/MetaCoreEditor/Public/MetaCoreEditor/MetaCoreEditorAssetTypes.h)

### 数据来源

- `MetaCoreAssetRecord`
- `MetaCoreModelAssetDocument`
- `MetaCoreMeshAssetDocument`
- `MetaCoreMaterialAssetDocument`
- `MetaCoreTextureAssetDocument`

### 最小展示字段

- 资源名称
- 相对路径
- `ImporterId`
- `SourceFormat`
- `SourceHash`
- Mesh 数量
- Material 数量
- Texture 数量
- Node 数量

### 建议展示摘要

- Mesh 列表：
  - 名称
  - PrimitiveCount
- Material 列表：
  - 名称
- Texture 列表：
  - 路径

### 最小动作

- Reimport
- Copy Relative Path

### 验收标准

- 在 `Project` 面板选中模型资源时，Inspector 能展示模型资产摘要
- glTF / glb / generic model 都能正确显示
- Reimport 操作可用

### 测试点

- 单 mesh 模型
- 多 mesh 模型
- 外部贴图 glTF
- fallback generic model

---

## Task Card 04：对象 Inspector 中的材质槽编辑

### 目标

让场景中的模型对象能够真正改材质引用，而不是只能看导入结果。

### 用户结果

用户选中带 `MeshRenderer` 的对象后，可以：

- 查看当前 `MeshAssetGuid`
- 查看当前材质槽引用
- 替换材质资源

### 建议代码落点

- [MetaCoreBuiltinCoreServicesModule.cpp](/D:/MetaCore/Source/MetaCoreEditor/Private/MetaCoreBuiltinCoreServicesModule.cpp)
- [MetaCoreComponents.h](/D:/MetaCore/Source/MetaCoreScene/Public/MetaCoreScene/MetaCoreComponents.h)

### 数据基础

当前已有：

- `MeshRenderer.MeshAssetGuid`
- `MeshRenderer.MaterialAssetGuids`

### 最小交互

- 在对象 Inspector 里列出材质槽
- 每个槽显示当前材质资源名
- 可从下拉框选择其他材质

### 拖拽增强

允许：

- 从 `Project` 面板把材质拖到 Inspector 材质槽

### 暂不要求

- 多 submesh 复杂编辑器
- 材质实例系统
- 多槽批量替换

### 验收标准

- 用户可替换对象材质槽引用
- 修改后场景对象正确保存引用
- 重新选中对象时能看到替换结果

### 测试点

- 单材质模型
- 多材质模型
- 拖拽赋材质
- 下拉切换材质

---

## Task Card 05：材质资源 Inspector 最小版

### 目标

把已经存在的 `MetaCoreMaterialAssetDocument` 真正变成可以编辑的资源。

### 用户结果

用户选中材质资源后，可以编辑：

- BaseColor
- BaseColorTexture
- NormalTexture
- Metallic
- Roughness
- EmissiveColor
- AlphaMode
- AlphaCutoff
- DoubleSided

### 建议代码落点

- [MetaCoreBuiltinEditorModule.cpp](/D:/MetaCore/Source/MetaCoreEditor/Private/MetaCoreBuiltinEditorModule.cpp)
- [MetaCoreAssetTypes.h](/D:/MetaCore/Source/MetaCoreFoundation/Public/MetaCoreFoundation/MetaCoreAssetTypes.h)
- [MetaCoreBuiltinCoreServicesModule.cpp](/D:/MetaCore/Source/MetaCoreEditor/Private/MetaCoreBuiltinCoreServicesModule.cpp)

### 最小动作

- 修改材质参数
- 保存材质资源

### 联动要求

- 修改材质资源后：
  - 若场景对象引用该材质，视口显示应更新
  - 至少编辑器内状态应保持一致

### 暂不要求

- 材质节点编辑器
- ShaderGraph
- 材质实例继承

### 验收标准

- 选中材质资源时 Inspector 可显示材质参数
- 修改参数后可写回材质资源
- 场景中引用该材质的对象可反映修改结果

### 测试点

- 修改颜色
- 修改金属度/粗糙度
- 替换贴图引用
- 开关双面/透明模式

---

## Task Card 06：Project -> Inspector 资源选择状态统一

### 目标

补足前面几张卡之间的状态桥，让资源选择、对象选择、Inspector 内容切换更加一致。

### 用户结果

用户会感觉：

- 在 `Project` 选中的是“资源”
- 在 `Hierarchy` 选中的是“对象”
- Inspector 会根据当前上下文切换

### 建议代码落点

- [MetaCoreEditorContext.h](/D:/MetaCore/Source/MetaCoreEditor/Public/MetaCoreEditor/MetaCoreEditorContext.h)
- [MetaCoreBuiltinEditorModule.cpp](/D:/MetaCore/Source/MetaCoreEditor/Private/MetaCoreBuiltinEditorModule.cpp)
- [MetaCoreEditorServices.h](/D:/MetaCore/Source/MetaCoreEditor/Public/MetaCoreEditor/MetaCoreEditorServices.h)

### 建议新增状态

最小可以考虑增加：

- 当前选中资源路径或 GUID
- 当前选中资源类型

不要把资源选择和对象选择混成同一状态。

### 验收标准

- 选中对象时，Inspector 显示对象
- 选中资源时，Inspector 显示资源
- 二者切换行为清楚，不互相覆盖造成混乱

---

## 实现顺序建议

建议按这个顺序做：

1. Task 06：资源选择状态统一
2. Task 01：Project 面板最小版
3. Task 03：模型资源 Inspector 最小版
4. Task 02：模型 / Prefab 拖拽到 Scene / Hierarchy
5. Task 04：对象材质槽编辑
6. Task 05：材质资源 Inspector 最小版

原因：

- 没有统一状态，Project 和 Inspector 会互相打架
- 没有 Project 面板，后面的拖拽和资源 Inspector 不成立
- 没有模型资源 Inspector，Project 选中资源几乎没有意义
- 没有材质槽编辑和材质资源 Inspector，模型编辑链就断在对象级

---

## P0 完成定义

当下面这些都成立时，可以认为模型工作流的 P0 已完成：

- 有最小可用 `Project` 面板
- 资源选择和对象选择状态清晰分离
- 模型资源在 Inspector 中有最小可读信息
- 模型和 Prefab 可以从资源面板拖到 `Scene / Hierarchy`
- 场景对象可以替换材质槽
- 材质资源可以编辑基础参数

---

## 最终建议

P0 阶段不建议继续扩格式、扩渲染特性、扩高级导入选项。

当前最应该做的是：

**把已经存在的模型资源能力，变成一条真正让用户摸得到、拖得动、看得懂、改得了的编辑器工作流。**