BuildPatch Tool (BPT)说明1.5.0

BuildPatch工具（BPT）是一款命令行工具，允许你将产品的二进制文件安全地上传到Dev 沙盒 中。然后你可以通过开发人员门户中的构建和二进制分段，将二进制文件指定给商品的正确构件，并进行测试。（对于部分组织，此分段可能名为 构建 。)通过发布管理流程，你可以提升流程，你可以在沙盒之间提升通过BuildPatch工具上传的二进制文件。

在你开始前，请阅读以下小节，收集准备使用BuildPatch工具所需的信息。

你可以在开发这门户的构件和二进制页面中下载BuildPatch工具（BPT）。

1. 在开发人员门户中，点击 我的产品 > Epic Games商城 > 构件和二进制文件 。
2. 右上角点击 下载工具 。
3. 下载完成后，在本地机器上安装工具。

你需要在开发人员门户中找到以下这些ID。

产品的Client ID和Client Secret 。

在你的组织中，所有属于Owner、Admin 或 Store 的角色，可以获取以下凭证：

1. 点击开发人员门户中的 产品 > 产品设置 。
2. 选择 通用 选项卡。
3. 找到Build Patch Tool凭证分段，保存客户端ID和密钥。

商品的构件名称和ID

1. 点击 我的产品 > Epic Games商城 > 构件和二进制文件 。
2. 在列表中，点击需要获取凭证的商品的名称。
3. 在管理构件页面，点击编辑细节面板右侧的 箭头图标 。
4. 保存构件名称和ID。
5. 为其他商品执行相同操作。

商品的商品ID

1. 点击 我的产品 > Epic Games商城 > 商品 。
2. 在列表中，点击需要获取凭证的商品的名称。
3. 在商品的详细信息界面，找到ID分段并保存商品ID。
4. 为其他商品执行相同操作。

由于命令提示符在命令行上对 \"（反斜杠直接后跟双引号）有独特的解释方式，所以在BuildPatchTool参数中指定路径时，要遵循以下至少一个指导意见：

• 目录名称不要附加尾部斜杠。
• 目录分隔符用正斜杠。
• 不要将路径括在引号内（如果路径包含一个或多个空格，这一点无法做到）。
• 使用另一个反斜杠仅对括在双引号内的尾部反斜杠转义（不推荐，因为容易出错）

有效路径语法示例

• -BuildRoot="D:/MyFolder/"
• -BuildRoot=D:\MyFolder\
• -BuildRoot=D:\MyFolder
• -BuildRoot=D:/MyFolder/
• -BuildRoot=D:/MyFolder
• -BuildRoot="D:\MyFolder\\"

无效路径语法

在命令行上定义路径时，以下语法 将无效 ：

-BuildRoot="D:\MyFolder\"

将BuildPatchTool ZIP文件的内容提取到可访问待上传二进制文件的机器。该机器还需要能够联网，以便与Epic后端通信。

身份验证是通过向BuildPatchTool提供 客户端ID 和 客户端密钥 来执行的。必须使用命令行参数为每个操作提供这些信息。 Epic将为你签发此ID和密钥，用作凭证。如需这些凭证，请前往开发人员门户，找到“我的产品（Your Product） > 产品设置（Product Settings） > 通用（General）选项卡 > Build Patch Tool凭证（Build Patch Tool Credentials）。

凡是与Epic的后端服务进行交互的操作，必须提供 ClientId 参数。客户端密钥必须使用 ClientSecret 或 ClientSecretEnvVar 参数提供。

如果使用 ClientSecret 参数，客户端密钥应该一字不差地作为参数值传递：

如果使用 ClientSecretEnvVar 参数，你需要传递包含客户端密钥的操作系统环境变量的名称：

**我们推荐尽可能使用 ClientSecretEnvVar 参数，因为这样可防止密钥值出现在系统日志和命令行历史记录。 **最好是将客户端密钥存储在密钥管理系统中（如Hashicorp Vault），并在每次运行期间将其安全地注入到你的构建机器的环境中。

找到 Engine/Binaries/Win64/ 目录。 从命令行以UploadBinary模式运行BuildPatchTool.exe，然后将其指向你的二进制文件（请参阅下面的CLI参数细节）。

这将处理你的二进制文件，将其上传到我们的云存储器，并将二进制文件注册到我们的后端：

请见下方说明，了解你必须指定的各个参数。你还可以在任意模式之后添加 "-help" 选项（例如， "BuildPatchTool.exe -mode=PatchGeneration -help" ），以获取有关必需参数的信息。

你可以将可选的 -FileAttributeList 参数与PatchGeneration模式搭配使用，将特殊属性应用于二进制文件中的文件，如可执行文件，或文件的标签组。请注意，启动应用程序（由 -AppLaunch 参数指定）会自动标记为可执行文件，不需要显式包含在此配置文件中。如果不需要设置特殊属性，可以忽略 -FileAttributeList 参数。

你的自定义 FileAttributeList 文件必须是文本文件，文件中包含一个或多个以换行符分隔的条目。每行必须包含用引号括起的（相对于BuildRoot的）文件路径，后跟要应用于所引用文件的一个或多个以空格分隔的属性：

"<QuotedRelativePathToFile>" <list of attributes>

"Relative/Path/To/My/file.bin" executable tag:my_tag "Second/Path/To/A/file.txt" tag:txt_files

支持以下文件属性标记：

• executable
• tag:my_tag

文件标记用于为Epic Games启动程序的选择性下载功能提供输入，公开在安装选项屏幕中。如果你觉得需要使用此功能，请联系Epic Games代表，因为该功能仍处于测试阶段。

默认情况下，桌面快捷方式图标将设置为AppLaunch参数指示的应用程序可执行文件的图标。有两种方法可以更新此图标：

• 更新应用程序可执行文件中嵌入的图标
• 添加与应用程序可执行文件同名的单独.ico文件（例如：如果可执行文件是launch.exe，应使用launch.ico）

分块和上传过程完成后，你必须将标签应用到二进制文件，才可以从Epic Games启动程序访问它。将标签应用于二进制文件会将标签名称（例如“Live”）和平台（例如“Win32”）与单个二进制版本关联。你可以将多个标签分配给同一个二进制文件。

EpicGamesLauncher客户端将只查询与其当前运行的平台相关联的二进制文件。例如，Win32启动程序客户端只会使用Win32平台查询，因此它永远不会收到标有Windows或Mac的二进制文件。Windows x64客户端将仅查询使用Windows平台的二进制文件，依此类推。如果你确实有一个能与多个平台兼容的二进制文件（例如，兼容Windows和Win32），那么你可以将两个标签（每个平台一个）应用于同一个二进制文件，使其可用于两个平台，无需重新上传。

注意： 当你把二进制文件所有标签删除时，该二进制文件会在七天后自动删除。如果你想阻止这种删除，请在 不活跃的二进制文件（Inactive binaries） 部分中找到该二进制文件，并为其添加至少一个标签。

要删除先前设置的标签，你可以使用 UnlabelBinary 模式和用于 LabelBinary 模式的相同参数：

你还可以查询后端，使用 ListBinaries 模式检索你已注册的二进制文件列表：

如要删除一个二进制文件，请删除二进制文件的所有标签。二进制文件将在七天后自动删除。

CopyBinary 模式允许你在不同构件之间复制二进制文件，而无需重新上传二进制文件。如果你想要将最终二进制文件从Staging构件移至Live构件，此功能很有用。

DiffBinaries 工具模式将计算已上传的两个二进制文件之间的差异，并输出用于在它们之间应用更新的统计数据。

需要v1.4.0和更高版本

BuildPatchTool将通用补丁系统用于使用 UploadBinary 模式上传的所有二进制文件。系统允许Epic Games商城将用户机器上二进制文件的任意版本更新为任意其他版本，从而最大限度降低下载大小。

BinaryDeltaOptimise 模式旨在获取已上传到Epic服务的两个二进制文件，并为在这两个特定版本之间更新的用户生成更小的下载。我们将其称为A到B补丁。运行此命令是可选的步骤，鉴于大部分玩家都是使用特定的二进制版本（二进制“A”），发布比平常更大的补丁时，可以执行此步骤来改善用户体验。

下面是用于改善两个二进制版本之间的增量补丁的命令行示例：

在 BinaryDeltaOptimise 模式下运行时，BuildPatchTool将从我们的云网络流送现有二进制数据，进行重新分析，然后上传新的A到B特定补丁数据。如果 BuildVersionA 和 BuildVersionB 之间的原始下载大小很大，此过程耗时可能超过标准PatchGeneration模式。

一般建议在运行 BinaryDeltaOptimise 模式时，将当前Live二进制文件用作 BuildVersionA，将你接下来要发布的二进制文件用作 BuildVersionB 。理想情况下，应规划在发布的几天前完成此过程，以防运行工具时发生问题，如断网。

要检查当前Live二进制文件版本，你可以利用ListBinaries模式。 如果已在两个提供的BuildVersion值之间运行了 BinaryDeltaOptimise ，该过程会成功将操作短路，如输出中所示。

完成处理后，输出将显示实现的改进情况。

• "最终未知压缩字节数，加上元 [Bytes]"
  • 这指的是针对 BuildVersionA 和 BuildVersionB 之间的补丁实现的新下载大小。
• "原始未知压缩字节数 [Bytes]"
  • 这指的是运行优化之前， BuildVersionA 和 BuildVersionB 之间的补丁的下载大小。
• "改进：[Percentage]"
  • 这将显示实现的改进情况。该百分比指的是缩减幅度，越大越好。

Epic Games商城提供了对可下载内容(DLC)的全面支持。对于DLC，BuildPatchTool的操作完全相同，因为它适用于整个游戏，以下是额外注意事项：

DLC的每个项目都将拥有自己唯一的构件ID。相应地，DLC的每个项目都需要各自的补丁生成过程，才能通过指定的合适构件ID执行。由于每个项目会单独生成，在为DLC项目执行补丁生成时，应务必确保基础游戏及所有其他DLC项目不同时出现在补丁生成过程中BuildRoot参数指定的文件夹中。或者，如果BuildRoot文件夹确实包含主游戏或其他DLC项目，则可以在BuildPatchTool命令行上指定-FileIgnoreList参数，在生成的二进制文件中将其排除（有关更多细节，请参阅“如何上传二进制文件”）。

安装在最终用户的机器上时，主游戏和相关DLC的所有项目将安装到同一个目录。这将造成如下限制：主游戏或DLC的所有项目中不得有文件使用相同的文件路径。BuildPatchTool将检查此情况，并且在有文件违反此规则时阻止补丁生成过程发生。这意味着，基础游戏必须能够按相对于安装位置的路径找到安装的DLC。

在短期内，DLC项目的构件ID将由Epic分配给你，并且主游戏和DLC项目之间的关联将作为该过程的一部分提供。从长远来看，我们考虑将此配置合并到开发人员门户上的自助服务操作中。

在排查故障时，请先检查是否有以下潜在错误：

• 检查路径语法 - BuildRoot="D:\MyFolder\" - WILL NOT WORK
• 确保在所有参数之间添加了空格。
• 版本中包含的文件受Windows MAX_PATH限制（限制为260个字符）；如果上传过程意外失败，请确保所有文件路径位置不超过此限制。
• 大多数BuildPatchTool参数通常作为绝对路径或工作目录相对路径提供，但AppLaunch参数必须仅相对于BuildRoot位置提供。
• 随着在同一台机器上处理更多版本，CloudDir内容会随着时间的推移而增加。但是，你可以随时清除此文件夹，而且不会产生负面影响。

使用BPT时，请确保你的命令行是精确的。如果你使用的命令不精确，你将收到一条特定的错误消息。

请注意，这些只是常见错误。

含义 你所使用的客户端凭证并未授权上传到指定的构件。这可能是由于凭证或其他参数中有拼写错误，或者授予客户端的权限有问题。

含义 BPT未检测到上面所列的一个或多个参数。这可能就是因为缺少这些参数，或者未正确添加这些参数。

含义 BPT未检测到上面所列的一个或多个参数。这可能就是因为缺少这些参数，或者未正确添加这些参数。

含义 你所使用的客户端凭证与我们的记录不匹配。这可能是由于凭证或其他参数中有拼写错误，或者授予客户端的权限有问题。

含义 你所使用的客户端凭证无权访问你指定的构件。这通常是因为授予客户端的权限发生了问题，服务交付团队可以解决这个问题。

• 使用的客户端ID和客户端密钥由Epic提供，专供BuildPatchTool使用；EOS客户端ID（通常以xyza开头）不能与BuildPatchTool一起使用
• 提供了所有需要的参数
• 参数没有拼写错误，包括不正确的首字母大小写或空格问题
• 包含空格的参数缺少引号