gengjiayuan/MetaCore

Fork 0

ayuan9957 9a33e9f243 Advance editor workflows and add UI and simplepbr foundations

2026-03-30 08:30:28 +08:00

8.5 KiB

Raw Blame History

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

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

目的

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

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

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

结论先说

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

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

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

第一阶段不能再让 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 描述
必需依赖文件

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

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

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、拼装最终产物

打包流程建议

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

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

第一阶段 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 配置缺失
运行时项目描述损坏

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

第一阶段至少应做到：

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

第一阶段 Definition of Done

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

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

与整体路线的关系

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

M4 UI、持久化与打包循环

它的位置必须在：

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

之后。

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

最终建议

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

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

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

8.5 KiB Raw Blame History Unescape Escape