# MetaCore 打包与交付运行时工作流设计

生成时间：2026-03-28  
状态：草案  
范围：M4 UI、持久化与打包循环

## 目的

这份文档用于明确 MetaCore 第一阶段的打包、Cook、运行时交付工作流应该如何设计。

目标不是只做到“Player 能单独启动”，而是建立一条真正可交付的链路：

- 项目内容如何变成运行时可消费数据
- 场景、资源、UI、运行时配置如何被带出
- 打包后客户端如何在独立环境运行
- 哪些文件属于开发期，哪些属于交付期

## 结论先说

MetaCore 第一阶段应明确采用下面这条交付链：

```text
项目内容
  -> 资源与场景保存
    -> Cook
      -> 生成运行时所需输出
        -> 打包 Player + 项目内容
          -> 交付 Windows 独立客户端
```

这里必须把两件事分清楚：

1. **Editor 项目工作目录**
2. **交付运行时目录**

第一阶段不能再让 `Player` 长期依赖开发期目录的偶然结构或临时 fallback 才能运行。

## 当前代码基础

当前仓库里已经有较好的基础：

- `MetaCore.project.json`
- Scene 二进制 package 方向
- Package 服务
- Cook 服务
- `CookManifest`
- Player 能读取项目和启动场景
- RuntimeData 已有独立二进制文档和项目级 runtime 配置

这说明第一阶段不是没有打包基础，而是还缺一套清晰的“交付工作流定义”。

当前最需要解决的是：

- 什么内容属于交付包
- Cook 输出和源包之间的关系
- Player 在交付态下应该从哪里加载内容
- clean machine 验证应如何定义

## 第一阶段设计目标

第一阶段打包与交付工作流要满足：

- 开发者能从一个项目构建出独立 Windows 客户端
- 客户端不依赖 Editor 才能运行
- 启动场景正确加载
- 场景依赖资源正确带出
- UI 资源可带出
- Runtime 配置可带出
- clean machine 上可运行

## 第一阶段角色划分

### 1. 项目工作目录

这是开发期使用的目录，包含：

- `Assets`
- `Scenes`
- `Runtime`
- `Library`
- `MetaCore.project.json`

这部分是创作环境，不是最终交付目录。

### 2. Cook 输出目录

这是中间产物目录，用于：

- 存放 cooked 资源
- 存放 cooked scene
- 存放依赖清单

第一阶段建议继续使用：

- `Library/Cooked/Windows`

### 3. 打包输出目录

这是最终交付目录。

第一阶段建议显式区分出来，例如：

- `Build/Windows/<ProjectName>`

里面应包含：

- `MetaCorePlayer.exe`
- 运行时内容目录
- 项目 runtime 描述
- 必需依赖文件

## 第一阶段推荐交付目录结构

建议第一阶段打包后输出结构类似：

```text
Build/Windows/<ProjectName>/
  MetaCorePlayer.exe
  Content/
    Scenes/
    Assets/
    UI/
    Runtime/
  Project/
    MetaCore.runtimeproject
```

第一阶段名称可以调整，但结构职责必须清晰。

## 第一阶段必须打包的内容

### 1. 启动场景

必须带出项目定义的 `startup_scene` 对应的 cooked scene。

### 2. 场景依赖资源

至少要带出：

- Mesh 资源
- Material 资源
- Texture 资源
- Prefab 资源
- Scene 引用的 UI 资源

### 3. 运行时配置

如果项目使用 RuntimeData 或其他运行时配置，则应带出：

- `ProjectRuntime.mcruntimecfg`
- `DataSources.mcruntime`
- `Bindings.mcruntime`
- 后续 UI runtime 配置

### 4. 项目运行时描述

建议打包时生成一个“运行时项目描述”，用于告诉 `Player`：

- 启动场景在哪里
- 内容根目录在哪里
- runtime 配置在哪里
- UI 资源在哪里

这和开发期的 `MetaCore.project.json` 不必完全相同。

## 项目描述与运行时描述分离建议

这是第一阶段很关键的一个设计点。

### 开发期项目描述

例如：

- `MetaCore.project.json`

它更适合：

- 可读
- 面向编辑器
- 面向开发期目录

### 运行时项目描述

建议打包时生成一个更面向交付的二进制或轻量配置文件，例如：

- `MetaCore.runtimeproject`

它更适合：

- 面向 Player
- 面向 cooked/packaged 内容
- 不依赖开发目录结构

第一阶段不一定要把这层做得很复杂，但“开发期描述”和“交付期描述”最好现在就区分。

## Cook 的职责

第一阶段 Cook 应明确负责：

- 把源 package 复制或转换为运行时可消费输出
- 建立 `CookManifest`
- 确定资源 GUID 与 cooked 路径关系
- 为打包阶段提供可收集依赖的基础

### Cook 不是最终打包

这两层要分开：

- Cook：生成内容
- Package/Build：组织交付目录、复制 Player、拼装最终产物

## 打包流程建议

第一阶段推荐下面这条顺序：

1. 解析项目描述
2. 确定启动场景
3. Cook 启动场景
4. 递归收集依赖资源并 Cook
5. Cook UI 资源
6. 收集 Runtime 配置
7. 生成运行时项目描述
8. 复制 `MetaCorePlayer.exe`
9. 组装交付目录
10. 运行最小验证

## 第一阶段 Player 行为建议

打包后的 `Player` 不应默认去猜开发期路径。

建议优先行为：

- 读取与自身同目录或指定参数下的运行时项目描述
- 根据运行时项目描述找到：
  - 启动场景
  - 内容根目录
  - Runtime 配置
  - UI 资源

### 仅在开发态允许 fallback

例如：

- 直接运行仓库里的 `TestProject`
- 自动猜测 `MetaCore.project.json`

这类行为可以保留给开发便利，但不应成为交付态主路径。

## 场景与资源的打包策略

第一阶段建议：

- Scene 以 cooked scene 文件形式带出
- 资源以 cooked asset 文件形式带出
- Scene 中只保存 GUID/引用关系
- Player 运行时通过 runtime 内容索引解析资源

不要让交付态仍然需要访问源文件或编辑器期 package 路径推断逻辑。

## UI 的打包策略

如果第一阶段引入正式 UI 资源工作流，则打包时应同样带出：

- UI 文档
- UI 引用图片资源
- 必要字体资源

Scene 或运行时项目描述应能定位到这些 UI 内容。

## RuntimeData 的打包策略

RuntimeData 在第一阶段不再是主线，但如果项目启用它，打包时必须作为正式交付内容处理：

- runtime project 配置
- source / binding 配置
- 必要的 replay 文件或外部连接参数

注意：

- 开发态的调试 fallback 不应进入正式交付流程

## clean machine 验证

这是第一阶段打包能力是否成立的真正验收标准。

### 验证目标

在没有源码、没有编辑器、没有开发期目录结构假设的机器上，最终产物应能：

- 启动
- 读取运行时项目描述
- 加载启动场景
- 正确加载资源
- 正确显示 UI
- 如果配置了 RuntimeData，则能正确加载相关配置

### 最低验证方式

第一阶段至少要有一条明确流程：

- 将打包目录复制到 clean machine 或近似隔离环境
- 启动 `MetaCorePlayer.exe`
- 验证项目主界面和主场景

## 错误与诊断

交付态必须能对这些问题给出明确提示：

- 启动场景缺失
- cooked 资源缺失
- UI 文档缺失
- runtime 配置缺失
- 运行时项目描述损坏

错误不应只表现为黑屏或静默失败。

第一阶段至少应做到：

- 日志输出
- 控制台/日志文件
- 基础错误分类

## 推荐实现顺序

建议按下面顺序推进：

1. 固定运行时项目描述结构
2. 固定交付目录结构
3. 打通 Scene 与资源依赖收集
4. 打通 UI 资源带出
5. 打通 Runtime 配置带出
6. 复制 Player 和组装交付目录
7. 做 clean machine 验证
8. 再补增量构建与更细的诊断

## 第一阶段 Definition of Done

下面这些成立时，才能认为第一阶段打包与交付工作流真正成立：

- 从项目可以生成独立 Windows 输出目录
- 输出目录包含 Player 和项目必需内容
- Player 不依赖 Editor 即可运行
- 启动场景能正确加载
- 资源和 UI 能正确显示
- Runtime 配置能正确读取
- clean machine 验证通过

## 与整体路线的关系

这份文档对应第一阶段中的：

- `M4 UI、持久化与打包循环`

它的位置必须在：

- 项目系统
- 资源导入
- 场景编辑
- 材质与光照
- UI 资源工作流

之后。

只有这些内容工作流成立后，打包才有意义。

## 最终建议

第一阶段不要把“能运行 Player”误认为“完成打包”。

真正的打包与交付能力，应当是：

**能把一个项目稳定转换成独立运行的 Windows 客户端，并在脱离编辑器和源码环境后仍能正确加载场景、资源、UI 和运行时配置。**

这一步做实之后，MetaCore 才算真正具备了“项目可交付”的引擎特征。