375 lines
8.5 KiB
Markdown
375 lines
8.5 KiB
Markdown
# 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 才算真正具备了“项目可交付”的引擎特征。
|