mcpField
U
unreal-packaging

unreal-packaging

github.com/gamedev-skills开发5.4k5.8k 次安装今天更新
代码仓库

关于 unreal-packaging

将 UE5 项目制作成可运行、可分发构建的工作流技能，面向 Unreal 开发者。内容涵盖构建配置、内容烹制、启动地图设置，以及通过编辑器或 `RunUAT BuildCookRun` 打包。

主要功能

  1. 01选择 Development 或 Shipping 配置
  2. 02设置打包版本的启动地图
  3. 03为目标平台烹制内容
  4. 04通过编辑器或命令行打包
  5. 05打包前验证资源

适用场景

  1. 01从 UE5 项目生成测试构建
  2. 02在 CI 中自动化重复构建
  3. 03排查构建中地图或资源缺失

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill unreal-packaging

安装后在 Claude Code 中输入/unreal-packaging确认已加载。

详细介绍

Unreal 打包与烹饪

将 UE5 项目转换为可运行、可分发的构建版本：选择合适的构建配置、烹饪内容、设置启动地图并进行打包——可在编辑器中或通过命令行完成。目标版本为 UE 5.8。

适用场景

  • 需要生成构建版本（测试版或发布版）、选择 Development 或 Shipping、烹饪内容、配置 Packaging / Maps & Modes 设置，或使用 RunUAT BuildCookRun 自动化 CI 构建时。
  • 项目包含 *.uproject 和 Config/Default*.ini，且目标是打包后的玩家版本，而非在编辑器中运行时。

不适用场景： 商店提交／发布流程 → steam-publish / itch-publish。编辑器中的游戏玩法开发／迭代不属于打包。

核心工作流

  1. 设置启动地图。 Project Settings → Maps & Modes → Game Default Map 决定打包后的构建版本首先加载哪个地图。此处设置错误或留空，是“打包后的游戏画面一片黑”的最常见原因。
  2. 选择构建配置： Development（默认；经过优化，但保留日志／统计信息／控制台，便于测试）或 Shipping（所有优化均已启用，并移除调试工具——用于发布）。DebugGame/Debug 用于调试引擎／游戏代码，不用于分发；仅含蓝图的项目无法使用 DebugGame。
  3. 了解烹饪与打包的区别。 烹饪会将资源转换为目标平台的格式，并打包到 .pak 文件中。打包会将编译后的可执行文件与烹饪后的内容捆绑成一组独立、可分发的文件。打包过程中会执行烹饪。
  4. 在编辑器中打包： Platforms 菜单 → 选择平台（例如 Windows）→ 设置 Binary Configuration → Package Project → 选择输出文件夹。
  5. 或者使用 Unreal Automation Tool（RunUAT BuildCookRun）从命令行构建，以便生成可重复的 CI 构建。
  6. 调整 Packaging 设置（Project Settings → Packaging）：选择要烹饪的地图／目录、是否完整重建、压缩方式，以及是否构建所有地图。
  7. 在 UnrealEditor-Cmd 可用时，于打包前验证资源。 运行 UnrealEditor-Cmd <Project>.uproject -run=DataValidation（Windows 上为 UnrealEditor-Cmd.exe），并在烹饪前修复所有报告的验证错误。
  8. 进行验证：实际运行打包后的构建版本，而不只是确认烹饪成功——启动可执行文件，并确认其加载了正确的地图且能正常运行。

常见模式

1. 在编辑器中打包（菜单路径）
Platforms (toolbar)
  -> Windows
     -> Binary Configuration -> Development | Shipping
     -> Content Management -> Package Project
  -> choose/confirm the staging output folder
2. 使用 UAT 从命令行构建（适合 CI）
# Cook + build + stage + pak + archive a Shipping Windows build.
RunUAT BuildCookRun \
  -project="C:/Path/MyGame.uproject" \
  -noP4 -platform=Win64 -clientconfig=Shipping \
  -cook -allmaps -build -stage -pak -archive \
  -archivedirectory="C:/Builds/MyGame"

RunUAT 位于 Engine/Build/BatchFiles/（Windows 上为 RunUAT.bat，macOS/Linux 上为 RunUAT.sh）。移除 -allmaps，并传入 -map=Map1+Map2，即可只烹饪部分地图。

3. 仅烹饪（不打包），例如用于刷新内容
RunUAT BuildCookRun -project="C:/Path/MyGame.uproject" -noP4 \
  -platform=Win64 -clientconfig=Development -cook -skipstage

常见问题

  • 打包后的构建版本加载黑屏／空白关卡——未设置 Game Default Map（或该地图未被烹饪）。在 Maps & Modes 中设置该选项，并确保该地图包含在烹饪内容中。
  • 发布了 Development 构建版本——Development 会保留日志／控制台／统计信息，且速度较慢；请发布 Shipping。反过来说，Shipping 会移除 UE_LOG/控制台，因此排查仅在 Shipping 中出现的问题时，需要使用 Development 或 Test。
  • 运行时缺少被引用的地图／资源——该内容未被烹饪。将其添加到 Packaging 设置中的待烹饪地图／目录，或烹饪所有地图。
  • 构建在目标平台上失败——未安装该平台的 SDK／工具链（Windows 构建工具、Android SDK/NDK、主机平台 SDK）。请安装该平台所需的先决条件。
  • 预期使用 Blueprint Nativization——该功能已在 UE5 中移除；不要依赖它来提升性能。请进行性能分析，并将热点逻辑移至 C++（unreal-cpp-gameplay）。
  • 首次烹饪非常慢——着色器和所有资源都需要从头开始烹饪；后续烹饪会采用增量方式。不要把首次烹饪缓慢误认为程序卡死。

参考资料

  • 主要文档：“Packaging Your Project” （https://dev.epicgames.com/documentation/en-us/unreal-engine/packaging-your-project），以及 Build Configurations / BuildCookRun 参考资料。

相关技能

  • steam-publish / itch-publish — 将打包后的构建版本分发到商店。
  • unreal-cpp-gameplay — BP 原生化已取消，现在可将热点逻辑迁移到 C++。

评论

支持 Markdown